dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-plan/references/intake.md

@@ -0,0 +1,158 @@
+# Plan Intake
+
+Phase 0.2 through 0.7 of `ce-plan`. Read this before resolving the upstream product source. The principles and quality bar below govern every phase from here on.
+
+## Core Principles
+
+1. **Use the Product Contract as the source of truth** - If `ce-brainstorm` produced a requirements-only unified plan, planning should enrich it in place rather than re-inventing behavior or creating a second artifact.
+2. **Decisions, not code** - Capture approach, boundaries, files, dependencies, risks, and test scenarios. Do not pre-write implementation code or shell command choreography. Pseudo-code sketches or DSL grammars that communicate high-level technical design are welcome when they help a reviewer validate direction — but they must be explicitly framed as directional guidance, not implementation specification.
+3. **Research before structuring** - Explore the codebase, institutional learnings, and external guidance when warranted before finalizing the plan.
+4. **Right-size the artifact** - Small work gets a compact plan. Large work gets more structure. The philosophy stays the same at every depth.
+5. **Separate planning from execution discovery** - Resolve planning-time questions here. Explicitly defer execution-time unknowns to implementation.
+6. **Keep the plan portable** - The plan should work as a living document, review artifact, or issue body without embedding tool-specific executor instructions.
+7. **Carry execution direction lightly when it matters** - If the request, origin document, or repo context clearly implies test-first proof, characterization coverage, smoke-first verification, or another non-default execution direction, reflect that in the plan as a lightweight natural-language signal. Do not encode it as a finite enum or turn the plan into step-by-step execution choreography.
+8. **Honor user-named resources** - When the user names a specific resource — a CLI, MCP server, URL, file, doc link, or prior artifact — treat it as authoritative input, not a suggestion. Discover it if unknown (`command -v`, fetch, read) before assuming it's unavailable. Use it in place of generic alternatives. If it fails or doesn't exist, say so explicitly rather than silently substituting.
+
+## Plan Quality Bar
+
+Every plan should contain:
+- A clear problem frame and scope boundary
+- Concrete requirements traceability back to the request or origin document
+- Repo-relative file paths for the work being proposed (never absolute paths — see Planning Rules)
+- Explicit test file paths for feature-bearing implementation units
+- Decisions with rationale, not just tasks
+- Existing patterns or code references to follow
+- Enumerated test scenarios for each feature-bearing unit, specific enough that an implementer knows exactly what to test without inventing coverage themselves
+- Clear dependencies and sequencing
+
+A plan is ready when its contents give an implementer sufficient direction and no launch-blocking question remains. Verify material claims about existing code and fixtures against the repository; distinguish these prerequisites from additions the plan proposes to build. Record any unresolved prerequisite that prevents implementation as a blocker.
+
+#### 0.2 Find Upstream Product Contract
+
+Before asking planning questions, resolve the upstream product source in this order:
+
+1. **Explicit path from the user.** Read its contents. If a unified plan has a Product Contract but needs implementation planning, this run enriches that same file in place. If it already contains implementation planning, treat it as a resume/deepening target and resolve any gaps there. If it is a legacy `docs/brainstorms/*-requirements.{md,html}` file, use it as a legacy origin and write a new unified plan in `<root>/plans/`.
+2. **Recent Product Contracts needing planning.** Search `<root>/plans/*.{md,html}` for unified plans from `product_contract_source: ce-brainstorm`, and inspect their contents. Follow an explicit supersession notice to its canonical path only when the linked document's contents establish that it represents the same requested work; otherwise stop for clarification. If same-basename Markdown and HTML copies exist without a clear canonical path, ask which to use; neither format nor a readiness label establishes precedence.
+3. **Legacy requirements docs.** Search `docs/brainstorms/` for files matching `*-requirements.md` or `*-requirements.html`. These remain readable historical inputs; do not migrate or rewrite them.
+
+**Relevance criteria:** A Product Contract source is relevant if:
+- The topic semantically matches the feature description
+- It was created within the last 30 days (use judgment to override if the document is clearly still relevant or clearly stale)
+- It appears to cover the same user problem or scope
+
+If multiple source documents match, ask which one to use using the platform's blocking question tool when available (see Interaction Method). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+**Session-settled decisions are an input tier alongside the document sources above.** Decisions already examined-and-chosen in the invoking conversation — or carried in a distilled brief passed as invocation input, from the user or a calling skill — enter planning as settled constraints, not open questions. Read `references/settled-decisions.md` before classifying decisions carried in from the conversation; it defines the settlement test, the two provenance classes, the annotation shape, the capture rules, and what a brief entry must include. Classifying without it risks labeling unexamined assertions as settled, or re-asking decisions the user already closed.
+
+#### 0.3 Use the Product Contract as Primary Input
+
+If a relevant requirements-only unified plan exists:
+1. Read metadata, Goal Capsule, Product Contract, Open Questions, and Sources (scan headings to locate them; don't read long appendices unless referenced).
+2. Announce that `ce-plan` will add the implementation planning to that same file.
+3. Preserve the Product Contract's **meaning and stable R/A/F/AE IDs** unless planning discovers a direct conflict. Conflicts become explicit assumptions or questions; do not silently rewrite product scope.
+   - Preservation protects decisions, not bytes. **Meaning-preserving restructuring is sanctioned without a conflict:** splitting an overloaded requirement (the original R-ID keeps the original core intent; split-out parts take next unused numbers), moving a rule's full statement onto the R that governs it while slimming the Key Decision to label + annotation + `Governs R…` links, and deleting unlinked duplicate restatement. When an R is split, or a rule moves to a different R, re-point every affected `Governs R…`, `Covers R…`, and inline `per R…` citation to the IDs that now govern it; the preservation map records the change but does not replace those live links. Restructuring must not weaken a qualifier, drop an edge case, or reclassify a product constraint as an implementation preference — those are scope changes, not restructures.
+   - Because enrichment edits the same file that holds the user's product decisions, record a one-line **Product Contract preservation** note in the enriched plan: "Product Contract unchanged", "restructured, no scope change: \<old-ID → new-IDs map\>", or "changed: \<R-IDs\> — \<why\>". This keeps the WHAT/HOW review boundary visible to reviewers (`ce-doc-review`, PR review) when there is no separate brainstorm file to diff against. For a *substantive* product-scope change (not a clarification or restructure), pause and confirm with the user before writing implementation units.
+4. Carry forward all applicable Product Contract sections listed below.
+5. Use the Product Contract as the primary input to planning and research.
+6. Do not create a duplicate plan unless an explicit `output:` conversion or pipeline override requires a new canonical path; when conversion happens, report old path and new canonical path.
+
+If a relevant legacy requirements document exists:
+1. Read it thoroughly
+2. Announce that it will serve as the origin document for planning
+3. Carry forward all of the following:
+   - Problem frame
+   - Actors (A-IDs), Key Flows (F-IDs), and Acceptance Examples (AE-IDs) when present — preserve these as constraints that implementation units must honor
+   - Requirements and success criteria
+   - Scope boundaries (including "Deferred for later" and "Outside this product's identity" subsections when present)
+   - Key decisions and rationale
+   - Dependencies or assumptions
+   - Outstanding questions, preserving whether they are blocking or deferred
+4. Use the source document as the primary input to planning and research
+5. Reference important carried-forward decisions in the plan with `(see origin: <source-path>)`
+6. Do not silently omit source content — if the origin document discussed it, the plan must address it even if briefly. Before finalizing, scan each section of the origin document to verify nothing was dropped.
+
+If no relevant Product Contract source exists, planning may proceed from the user's request directly and will create a complete unified plan with `product_contract_source: ce-plan-bootstrap`.
+
+**Settled decisions get the same preservation discipline as origin Product Contract decisions.** Session-settled decisions (from the conversation or a passed brief) are augmented by research, never re-asked, and never silently rewritten. Handle contradiction evidence by its severity. Nothing found: proceed silently. Suboptimal but workable: proceed as settled, and attach a conflict call-out to the labeled KTD when the plan is written (Phase 5.2). Invalidating: stop as blocked, as the Phase 5.2 pipeline contract describes.
+
+#### 0.4 Planning Bootstrap (No Requirements Doc or Unclear Input)
+
+If no relevant requirements document exists, or the input needs more structure:
+- Assess whether the request is already clear enough for direct technical planning — "clear enough" means the bootstrap exit condition below already holds, so confirm the problem frame, scope boundaries, and success signals are known or recorded as assumptions, then continue to Phase 0.5
+- If the ambiguity is mainly product framing, user behavior, or scope definition, recommend `ce-brainstorm` as a suggestion — but always offer to continue planning here as well
+- If the user signals they lack working knowledge of the problem domain itself, recommend `ce-brainstorm` — its blindspot pass maps the decisions the territory will force before requirements are extracted — but honor their choice to continue here; Phase 2 (Resolve Planning Questions) then applies its unfamiliar-territory scaffolding
+- If the user wants to continue here (or was already explicit about wanting a plan), run the planning bootstrap below
+
+The planning bootstrap should establish:
+- Problem frame
+- Intended behavior
+- Scope boundaries and obvious non-goals
+- Success criteria
+- Blocking questions or assumptions
+
+Keep this bootstrap brief. It exists to preserve direct-entry convenience, not to replace a full brainstorm.
+
+**Exit condition:** Exit the bootstrap when each of these holds, OR the user explicitly wants to proceed: the problem frame is stated; the in-scope and out-of-scope boundaries that matter are known; success criteria or acceptance signals are known or recorded as assumptions. Recording an item as an assumption satisfies the boundaries and success-signal clauses. That is what lets the check pass in headless mode and on a `SKIP_SCOPING_CONFIRM` run, where no synchronous user exists to answer. The problem-frame clause is the exception: it must be **stated**, because the plan's required sections always include `Problem Frame`, and an assumed frame would either leave a mandatory section empty or promote an unvalidated guess into product scope. When the prompt does not supply one, or supplies only an approach with no outcome, derive the outcome from the request's own motivation rather than assuming it, or stop and ask; when that motivation is itself a component-level fact (a platform limit, a cost, a failure mode inside the system), follow it to what it costs the people the system serves — the approach becomes the Goal Capsule's Means, not its Objective. That derived Objective is the holdable goal, not a catalog of what the plan will cover; those assumptions go to `### Assumptions` at Phase 5.2 (Write Plan File), following the existing rule. A session-settled decision counts as already-established for every clause it covers — never re-ask it. This exit condition covers the bootstrap only; it adds no check to Phase 2's planning questions or the brainstorm-sourced Phase 5.1.5 path.
+
+If the bootstrap uncovers major unresolved product questions:
+- Recommend `ce-brainstorm` again
+- If the user still wants to continue, require explicit assumptions before proceeding
+
+If the bootstrap reveals that a different workflow would serve the user better:
+
+- **Bug-shaped prompt** (user describes broken behavior — "fix the bug where X", error message, regression, "doesn't work"). Offer `ce-debug` as an alternative alongside continuing with `ce-plan` whenever the code with the bug is reachable (in cwd OR in a named repo found at another local path). Stay in `ce-plan` silently when the named code can't be found anywhere local — paper-planning is the only useful output when the code cannot be reached.
+
+  **When the bug is at another local path (not cwd):**
+  - Announce the target explicitly **before** any cross-repo investigation: which path will be read AND where plan outputs will land (default: target repo's `<root>/plans/`, not cwd's).
+  - Default: proceed from the target repo for both investigation and plan-write. The user can interrupt to redirect (switch context, paper-plan, abandon, etc.). No location menu — the announcement makes the cross-repo nature visible, and the user can speak up if they want something unusual.
+  - **After** announcing and proceeding, present the standard ce-debug routing menu (continue with `ce-plan` vs switch to `ce-debug`) — same shape as the in-cwd case. Cross-repo location and ce-debug skill routing are separate decisions; do not merge them into a single question.
+
+  Reading code at another path is fine in principle — that's just file access. The harm to avoid is silent operation on the wrong repo, especially writing the plan doc somewhere it won't be discovered (a busyblock plan landing in `cli-printing-press/<root>/plans/` is a discoverability disaster). The announcement requirement makes the target visible; defaulting to the target repo for both investigation and outputs respects the user's stated intent (they named that repo); the orthogonal ce-debug menu keeps the skill-choice question clean.
+
+  The accessibility classification is conservative and may under-suggest in monorepos, dependency bugs, or after renames. Users can always invoke `ce-debug` manually.
+
+  **Headless mode**: skip the `ce-debug` suggestion menu entirely; default to continuing with `ce-plan` (the user's explicit invocation). There is no synchronous user to choose between skills, and switching to `ce-debug` automatically would change the skill mid-run without authorization.
+
+- **Clear task ready to execute** (known root cause, obvious fix, no architectural decisions) — no routing question; the Output Contract gate in SKILL.md resolves it at Phase 0.6 (Assess Plan Depth), and the user can redirect at any point.
+
+#### 0.5 Classify Outstanding Questions Before Planning
+
+If the origin document contains `Resolve Before Planning` or similar blocking questions:
+- Review each one before proceeding
+- Reclassify it into planning-owned work **only if** it is actually a technical, architectural, or research question
+- Keep it as a blocker if it would change product behavior, scope, or success criteria
+
+If true product blockers remain:
+- State them clearly
+- Ask the user, using the platform's blocking question tool when available (see Interaction Method), whether to:
+  1. Resume `ce-brainstorm` to resolve them
+  2. Convert them into explicit assumptions or decisions and continue
+- Do not continue planning while true blockers remain unresolved
+
+#### 0.6 Assess Plan Depth
+
+First resolve the Output Contract gate that SKILL.md states. A Direct or Chat brief selection exits intake to `references/output-contracts.md` without classifying depth; only Durable continues here.
+
+Classify the work into one of these plan depths:
+
+- **Lightweight** - small, well-bounded, low ambiguity
+- **Standard** - normal feature or bounded refactor with some technical decisions to document
+- **Deep** - cross-cutting, strategic, high-risk, or highly ambiguous implementation work
+
+If depth is unclear, ask one targeted question and then continue.
+
+For a material Durable run, use the host's task-tracking capability when available to show route-level outcomes and meaningful transitions. If unavailable, continue without simulating it in chat.
+
+#### 0.7 Solo-Mode Scoping Synthesis
+
+Show the user the call-outs — the specific forks in scope or approach where user input materially changes the plan — so scope can be corrected **before Phase 1 research is spent**. Sub-agent dispatch (repo-research-analyst, learnings-researcher, etc.) is the expensive next step; this phase exists so that effort is not spent on the wrong scope.
+
+Runs **only in solo invocation** — when Phase 0.2 found no upstream Product Contract source (no requirements-only unified plan and no legacy `*-requirements` doc; `product_contract_source: ce-plan-bootstrap`) AND Phase 0.4 stayed in ce-plan (did not route to ce-debug, ce-work, or universal-planning) AND Phase 0.5 cleared (no unresolved blockers) AND not on Phase 0.1 fast paths (resume normal, deepen-intent) AND Phase 0.6's Output Contract gate selected Durable. Each of these is an explicit condition. Skip Phase 0.7 entirely when any of them fails — upstream-sourced invocations (unified-plan enrichment or legacy brainstorm) defer to Phase 5.1.5 instead.
+
+**Read `references/synthesis-summary.md` before composing the scoping synthesis.** It defines what the user sees, the confirmation and auto-proceed lines, the revision loop, soft-cut, self-redirect, headless routing, and where the internal draft lands in the plan.
+
+**Required output of this step — do not skip; silent proceeding is not allowed.** Compose an internal three-bucket scope draft (Stated / Inferred / Out of scope — internal thinking that feeds where content goes in the plan body at Phase 5.2, not the chat output). Derive call-outs (specific forks where user input materially changes the plan), then emit the **solo-variant** synthesis and **wait for user confirmation before continuing to Phase 1.** It states the problem as you understand it, then a scope claim — what the plan will target, what it will not, at affirm-or-redirect level — never an enumeration of Implementation Units, file paths, or PR/sequencing shape (the plan-write step decides those, and they are not knowable yet). Use the confirmation or auto-proceed lines in `references/synthesis-summary.md` (loaded above) rather than reconstructing them here.
+
+**Blocking decision:** auto-proceed — send the user the auto-proceed announcement in chat, then continue without waiting — only when plan depth is **Lightweight AND zero call-outs survive**. Standard and Deep always present the confirmation and wait for it, even with zero call-outs.
+
+**Headless / opt-in skip:** in headless mode, or when `SKIP_SCOPING_CONFIRM` resolved to skip in Phase 0.0, do not block — compose the internal draft, skip the chat-time confirmation, and write Inferred bets into a `## Assumptions` section when the plan is written (Phase 5.2). The skip covers only this scoping confirmation; Phase 0.4 routing, Phase 0.5 blockers, Phase 2 questions, source-doc disambiguation, and the Phase 5.4 menu still happen. Announcement wording and full routing: `references/synthesis-summary.md` ("Headless mode", "When to skip the blocking confirmation").

package/skills/ce-plan/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-plan/references/output-contracts.md

@@ -0,0 +1,29 @@
+# Direct and Chat Brief Output Contracts
+
+Read this when the Output Contract gate in SKILL.md selects Direct or Chat brief. SKILL.md states the gate itself: its condition, the safe direction, the Durable pins, and the point where it resolves. This file defines what the two chat-tier results contain, how each hands off, and when each is done. A Durable run never reads this file.
+
+## What both tiers share
+
+- The result is delivered in chat, in plain sentences, and nothing is written under `<root>/plans/` unless the user asks for a file.
+- No subagent runs, no confidence check, no document review, and no Phase 5.4 menu. The result closes the run on its own.
+- `ce-plan` still never implements. A Direct result describes the change; the implementation belongs to `ce-work` or the user.
+
+## Direct
+
+Say what changes, where, and how it is verified, in a few sentences. Then offer the handoff in one line: hand it to `ce-work` or the user makes the change. Invoke `ce-work` with that statement as its prompt only when the user accepts, or when the invocation already carried implementation intent from an orchestrator; `ce-plan` never makes the edit itself, and a planning invocation is not execution authority. A Direct result is complete when the statement and the offer are in chat.
+
+## Chat brief
+
+Deliver, in chat:
+
+- a summary of what changes and why, in a few sentences;
+- the implementation units, each with its files and its test expectations;
+- one decisions line when the request or a brainstorm summary settled a choice the implementer must honor, otherwise none.
+
+Close with one line offering to save the brief to a file or hand it to `ce-work`. A Chat brief is complete when the brief and that offer are in chat. "Proceed" after a Chat brief hands the brief to `ce-work` as its prompt; `ce-work`'s session-carried resolution accepts an in-conversation brief as that prompt.
+
+A brainstorm summary that carries a settled decision the implementer must honor selects Chat brief at minimum, so the decision has a line to live on.
+
+## Saving a Chat brief
+
+A save request for anything the file described here cannot be (another renderer, or the full plan floor) is a Durable request whenever it arrives. Re-invoke `ce-plan` on the brief; the Durable path then chooses the renderer and writes the artifact. Otherwise, naming markdown or not, write the brief as a plain markdown file under `<root>/plans/` with the same filename shape as a plan, with frontmatter `title`, `type`, and `date`, and `execution: code` for a code deliverable. Reserve the path with exclusive creation; on collision retry with the smallest available numeric suffix before the extension, never overwriting an existing file. Do not set `artifact_contract`: a saved brief does not carry the unified-plan floor. `ce-work` treats a saved brief as a legacy plan (no contract field, normal code lifecycle).

package/skills/ce-plan/references/output-mode.md

@@ -0,0 +1,45 @@
+# Output Mode and Artifact Root
+
+Read this before interpreting any planning phase. It defines how prompt tokens are parsed, which configuration layer wins, how the renderer is selected, and how the artifact root is resolved. Parse immediate prompt and contextual signals now. Defer every repository-backed fallback until resume and domain routing establish that this run will compose a rooted path or artifact; an answer-seeking run or a run with an explicit plan path may never need repository discovery.
+
+## Artifact Root
+
+**Every file reference inside the plan document is repo-relative** (`src/models/user.rb`), never absolute — unit file lists, pattern references, origin links, and prose mentions alike. Absolute paths break portability across machines, worktrees, and teammates. Paths printed to the user in chat are the exception and stay absolute so they are clickable.
+
+This skill writes plans under `<root>/plans/` and reads learnings under `<root>/solutions/`. Resolve `<root>` when you first compose a `<root>/` path, never before you need it. A write to `<root>/...` and a read of `<root>/solutions/` both count, so either one triggers resolution; only a run that touches no `<root>/` path at all — a scratch-only or no-repo flow — skips it. Pass the resolved path to any subagent, not the config.
+
+<!-- ce-docs-root:start -->
+**Resolve the CE artifact root `<root>` before composing any artifact path.**
+
+- **Read** `docs_root` from `<repo-root>/.compound-engineering/config.yaml` only (`<repo-root>` = `git rev-parse --show-toplevel`). Do not read it from `config.local.yaml`. Unset -> `<root>` is `docs`, exactly as before.
+- **Validate** a set value: a repo-relative directory whose real, symlink-resolved path stays inside the repo and is neither the repo root nor under `.git/`. Otherwise stop with an error naming `docs_root` and the value -- never fall back to `docs`.
+- **Use** `<root>` as the sole artifact location: create it if absent, compose each path as `<root>/<subdir>` with this skill's own subdirectory, and never also read `docs`.
+<!-- ce-docs-root:end -->
+
+## 0.0 Resolve Output Mode
+
+Output mode is **exclusive** — a plan is written as either markdown (`.md`) OR HTML (`.html`), never both. Its precedence is in-prompt request > user-stated preference > config > default (`md`). There is no pipeline override: a headless or non-interactive run resolves the format by the same steps. Before routing, resolve any tier that needs no repository. If those tiers do not settle the format, keep config/default resolution pending until an artifact-producing route is known; settle it before selecting a renderer or composing the artifact path. A terminal no-artifact route never probes config merely to resolve an unused format.
+
+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 ("make the plan a webpage"). Match an explicit format case-insensitively to `md`/`html`, and ignore the `output:` token when reading the rest of the prompt as the feature description. Distinguish a request about the document's format from a format named as subject matter: "add an HTML export feature" is the work, not a doc-format request.
+   - `output:` alone (no value) → no-op, fall through to step 2.
+   - `output:<unknown>` (e.g., `output:pdf`) → drop the token, fall through, and emit a one-line note above the post-generation menu after final resolution: `Ignored unknown output: value '<value>' — using <resolved_format> instead.` Do not hardcode `md` in the note — that misleads users when config has set HTML.
+2. **User-stated preference.** If this prompt holds no format request, honor an output-format preference the user established earlier that is already in your context, matching `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.
+3. **Config.** Once an artifact-producing route is known, apply the ordinary-key rule below: the first **active (non-commented)** `plan_output:` matching `md` or `html` (case-insensitively) wins. Missing, invalid, or commented values continue to the next layer, then step 4. The shipped template's commented examples are not settings.
+4. **Default.** Otherwise `OUTPUT_FORMAT=md`. If `<repo-root>` cannot be resolved so the config cannot be read, fall through to this default rather than failing.
+5. **Pipeline mode and model elevation.** Pipeline mode skips interactive questions but does **not** disable model elevation — `plan_model` config (and a `plan_model:<alias>` token passed by the caller) is still honored (see the model-elevation sub-step below and `references/reasoning-elevation.md`). It does not change the output format.
+
+**Token-parsing convention:** only literal-prefix flag tokens (`output:`, `mode:`, the exact `confirm:auto`/`confirm:ask` forms, `plan_model:<alias>`, `delegate:` where applicable) are consumed and stripped. Other `<word>:<word>` tokens — including commit prefixes like `feat:` and any unrecognized `confirm:<value>` — pass through verbatim into the feature description. A stripped `plan_model:<alias>` token is kept for the Phase 5.2 model-elevation step.
+
+**For an artifact-producing route, load the format-rendering reference only after the value settles:** `references/markdown-rendering.md` when `OUTPUT_FORMAT=md`, `references/html-rendering.md` when `OUTPUT_FORMAT=html`. Section content is the same either way; presentation differs. Both are paired with `references/plan-sections.md`.
+
+<!-- ce-config-layers:start -->
+**Resolve ordinary CE yaml keys from the two repo files.**
+
+- **Read** `<repo-root>/.compound-engineering/config.local.yaml`, then `config.yaml` (`<repo-root>` = `git rev-parse --show-toplevel`). Missing files are skipped. Gitignore does not change resolution.
+- **Win** with the first active (non-commented) value. For scalars, empty is unset; an invalid value continues to the next layer, then the skill default. For lists and maps, a present key — including an empty list or map — replaces the whole key.
+- **Do not** use this rule for `docs_root` — that key is `config.yaml` only.
+<!-- ce-config-layers:end -->
+
+Also resolve the immediate `SKIP_SCOPING_CONFIRM` signals here. `confirm:auto` skips the scoping-synthesis confirmation for this run and `confirm:ask` forces it on; honor an equivalent plain-language instruction the same way ("just write it, don't ask me to confirm" skips; "ask me before writing the plan" asks). Only those two literal values are consumed as a flag — any other `confirm:<value>` stays verbatim in the feature description. Then use a preference already in your context. If neither settles the value, defer the first **active (non-commented)** `plan_skip_scoping_confirm:` matching `true` or `false`, then the default of asking, until `references/intake.md` reaches the scoping-confirmation step where the value matters. A route that never reaches that step does not probe config for it.
+
+**Model-elevation visibility.** Treat a stripped `plan_model:<alias>` token, or a `plan_model` config value you have found, as a pending Phase 5.2 input, not a resolved choice. Phase 5.2 resolves the choice from the current conversation, that token, and config immediately before authoring, so later user intent cannot be lost.