dsh-compound-engineering 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,116 @@
+# Plan Handoff
+
+This file contains post-plan-writing instructions for the Durable path: document review, post-generation options, and issue creation. Load it after the plan file has been written and the confidence check (5.3.1-5.3.7) is complete. Direct and Chat brief results never reach it.
+
+## 5.3.8 Document Review
+
+Invoke the `ce-doc-review` skill with arguments `mode:non-interactive <plan-path>` using the host's normal skill-invocation mechanism. Do not substitute a generic Task, Agent, or subagent; those are delegation mechanisms, not skill invocation. This phase runs for both markdown and HTML; `ce-doc-review` applies fixes in the artifact's native format. It is mandatory — do not skip it because the confidence check already ran. The two workflows catch different classes of issues.
+
+While authoring or revising a draft within the user's planning request, carry that permission to edit into the review: "Apply corrections to this draft's implementation and verification sections needed to satisfy its established Product Contract. Preserve that contract, existing constraints, and user-reserved or session-settled decisions." Supply the document path and the actual contract; the skill name or non-interactive mode alone does not grant permission. If the request does not authorize revising the document, grant no permission to edit. `ce-doc-review` decides whether a fix is applied and enforces its restriction on fixes that only another model found; do not apply a returned proposal merely to bypass that restriction.
+
+If `ce-doc-review` cannot be invoked, record a stand-in structured review result (the shape `ce-doc-review` would normally return) with these values and proceed to Final Checks:
+- `fixes_applied = 0`
+- `proposed_fixes_count = 0`, `decisions_count = 0`, `fyi_count = 0`
+- `skipped_reason: skill_unreachable`
+- `skipped_detail: <why the host's normal skill-invocation mechanism could not start ce-doc-review>`
+
+The review never started: say that `ce-doc-review` did not run. Report a review error or timeout only after the `ce-doc-review` workflow actually begins.
+
+Non-interactive is the default at this phase because most users want to start work after planning, not adjudicate every reviewer concern up front. Non-interactive returns structured findings without blocking prompts. Its applied list includes corrections covered by the permission to edit you supplied; proposals still needing approval and unresolved user decisions remain separate. The post-generation menu (see 5.4) offers `Decide on the review's open items` as a first-class option so users can opt into the full interactive walkthrough when they want it.
+
+The confidence check and ce-doc-review are complementary:
+- The confidence check strengthens rationale, sequencing, risk treatment, and grounding
+- Document-review checks coherence, feasibility, scope alignment, and surfaces role-specific issues
+
+**Take responsibility for the completed plan.** Before applying or presenting review results, save a resolved review alongside the original evidence. Each claim has a disposition and its reason. A retained claim needs project evidence of a practical consequence if the plan stays unchanged, plus an explanation of why the existing plan and settled decisions do not already address it. A retained claim that would add a mechanism must also pass `references/structure.md` 3.8; one that fails it goes to the considered-and-not-built list instead. Review can also claim that a committed mechanism fails 3.8, or that something on the considered-and-not-built list passes it. Retain such a claim when its reasoning holds under 3.8, and make the removal or restoration yourself, since the review does not apply those changes. A reviewer label, recommendation, or request for more detail does not satisfy that condition. Dismiss claims that do not meet it, including advisory observations.
+
+Your result is a plan the user can act on, with only worthwhile unresolved choices. Investigate factual uncertainty and choose technical corrections within the planning request. Leave an already adequate plan unchanged. A user decision remains only when progress requires essential information you cannot obtain or a consequential choice that the request and constraints do not settle. Record what remains for the user to decide and why you cannot settle it from that context.
+
+For a retained correction, invoke `ce-doc-review` with the resolved review, evidence, and the existing permission to edit. It applies the correction and reuses completed review results. Do not apply returned proposals yourself or treat your agreement as permission to bypass its application restrictions.
+
+Save actual edits and the reviewed document's identity with the resolved review. Only its remaining findings supply the handoff and menu counts; original counts stay in the saved evidence. Dismissed and completed items must not reappear as FYIs or deferred questions. Proceed to Final Checks when the resolved review and any authorized corrections are complete.
+
+**Pipeline mode:** Invoke `ce-doc-review` with `mode:non-interactive` and the plan path — non-interactive mode is identical to the interactive default at this phase. No further routing is offered in pipeline mode; the caller decides what to do with the returned findings. Address any P0/P1 findings before returning control to the caller. If the review could not start and ce-plan recorded the `skill_unreachable` stand-in result, return that result explicitly so the caller does not treat review as complete.
+
+## 5.3.9 Final Checks and Cleanup
+
+Before proceeding to post-generation options:
+- Confirm the plan is stronger in specific ways, not merely longer
+- Confirm the planning boundary is intact
+- Confirm origin decisions were preserved when an origin document exists
+
+If artifact-backed mode was used:
+- Clean up the temporary scratch directory after the plan is safely updated
+- If cleanup is not practical on the current platform, note where the artifacts were left
+
+**Format-specific composition.** When `OUTPUT_FORMAT=html` (resolved in SKILL.md Phase 0.0), the plan is written as a single self-contained `.html` file — there is no markdown sibling. Read `references/html-rendering.md` for composition rules: invariants, precedence stack, format principles, agent-consumability rules, and the post-compose audit. The `.html` file is the artifact downstream consumers (`ce-doc-review`, `ce-work`, human readers) read and update directly.
+
+When `OUTPUT_FORMAT=md`, write the markdown directly per `references/markdown-rendering.md`. No HTML is composed.
+
+After all mutations in this run have settled (initial write, deepening synthesis, and `ce-doc-review` fixes in the artifact's native format), the artifact at its single path reflects the final state.
+
+## 5.4 Post-Generation Options
+
+**Already-authorized next action:** If the request already authorizes what happens after the plan (implement, create an issue, stop), fire that action. Do not present the menu to re-ask. Pipeline mode still returns to the caller.
+
+**Execution handoff:** After review and any corrections, assess the final plan against its implementation contract and repository evidence. Do not offer execution while a material prerequisite is unverified or a launch-blocking question or finding remains. Name the blocker in the plan and handoff; in pipeline mode return `status: blocked` with the artifact path, blocker, and recovery path. A skipped review is not a pass; establish the needed evidence within the planning request or report the gap. Deferred details and explicitly planned new files do not prevent handoff.
+
+**Pipeline mode:** No interactive menu. The result below is the last thing this skill writes. It ends this skill, not the turn. The caller runs in this same session, and its next step follows the result. If document review started but did not complete, return the skill's `status: blocked` result with `phase`, `blocker`, `recovery_path`, and the preserved `artifact_path`. Otherwise return the resolved structured review result from completion, or the `skill_unreachable` stand-in recorded when the review never started.
+
+**Path format:** Use absolute paths for chat-output file references — relative paths are not auto-linked as clickable in most terminals.
+
+**Summary line above the menu (always):** Print a single concise line summarizing the resolved review state — e.g., `Doc review applied 3 fixes. 2 decisions, 1 proposed fix, 4 FYI observations remain (1 at P1).` When no fixes were applied and no findings remain, print `Doc review clean — no fixes needed.` When the structured review result carries `skipped_reason: skill_unreachable`, print `Doc review skipped — ce-doc-review could not be invoked (<skipped_detail>); it did not run.` If a review that actually began failed, print `Doc review failed after starting — <actual error>; the plan was not fully reviewed.` This line establishes what the autofix pass did (or didn't) so the user has the context to choose between the menu options below. Never describe a harness or delegation failure that kept the review from starting as a downstream skill timeout.
+
+**Render only the findings that still need the reader.** Preserve the decision-first structure (Recommendation / Consequence if unchanged / Change / Basis) for retained actionable findings. Do not re-narrate them into dense paragraphs or unexplained identifiers. Explain any changed disposition in the saved review evidence; do not copy dismissed findings into the handoff. The summary reports changes actually made and items still unresolved after your judgment.
+
+**Question:** "Plan ready at `<absolute path to plan>`. What would you like to do next?"
+
+**Options:**
+1. **Start `ce-work`** - Build and ship the plan in this session, with verification, simplification, code review, and commits. Show only when the plan contents support implementation and no launch-blocking question or finding remains; universal-planning, answer-seeking, approach-plan, and requirements-only artifacts keep their own handoff/checkpoint behavior.
+
+**Recommended marker:** render option 1 as **Start `ce-work`** *(recommended)*. No other option carries the marker.
+2. **Decide on the review's open items** - Confirm or skip the suggested edits, and settle the judgment calls the auto-pass left for you. (Authorized corrections were already applied; you can also defer items into Open Questions.) Hide this option when **Prototype a remaining feel-question** is shown.
+2. **Prototype a remaining feel-question** - Invoke `ce-prototype` on a named remaining question that is expensive to unravel and that neither talk nor a cheap sketch can settle. A question turning on finish or motion is already past the sketch tier; a cheap-to-reverse decision does not qualify however visual it is. Shown only when such a question remains. A visual-probe question that already settled fails this predicate. The option description names the proposed slice. When this option is shown, omit **Decide on the review's open items** from the same menu.
+3. **Create Issue** - Create a tracked issue from this plan in your configured issue tracker (e.g., GitHub Issues, Linear, Jira)
+4. **Open in browser** - Open the HTML plan file locally for review and sharing. **Render only when `OUTPUT_FORMAT=html`.**
+
+There is no "done" / "pause" option — the blocking question already waits, and the user ends the turn by dismissing it (Esc) or just not picking anything. The plan file is already saved.
+
+**HTML browser option.** Only one output format is ever in effect, so the plan exists as exactly one artifact — `.md` or `.html`, never both. Render **Open in browser** only for HTML runs. Implementation handoff (option 1) remains available in both modes only when the artifact is implementation-ready code; `ce-work` reads either format.
+
+**Menu rendering:** The menu has up to 4 options (option 1 renders only for implementation-ready code; option 2 is the exclusive review-or-prototype slot — see below; Open in browser is HTML-only). Account for each platform's blocking-question option cap rather than trimming choices: Claude Code `AskUserQuestion` supports up to 4 explicit options, Codex `request_user_input` supports only 2-3 explicit options, and DeepSeek Harness `ask_user_question` has no hard option cap, so the full menu always fits. When the visible menu exceeds the current platform's cap, render it as a numbered list in chat with the hint "Pick a number or describe what you want." When the visible menu fits the cap, use the platform's blocking tool and renumber the visible options 1-N. When no matching tool is in the current list or a real question call errors, fall back to the same numbered-list-in-chat rendering. Never silently skip the question.
+
+**Show `Decide on the review's open items` (option 2) only when the resolved review state has `proposed_fixes_count + decisions_count > 0` and no `skipped_reason: skill_unreachable`.** FYIs alone do not offer a decision to make. Keep their retained count in the summary even when this option is hidden. Renumber the visible menu options after applying this condition. `ce-doc-review` defines how a selected review resumes and returns.
+
+**Cross-skill invocation rule:** Invoke `ce-work`, `ce-doc-review`, and `ce-prototype` using the host's normal skill-invocation mechanism. Do not substitute a generic Task, Agent, or subagent; the invoked skill may still dispatch its own subagents according to its protocol.
+
+Before acting on any selection received after a user turn, reload this file. Then act on the selection; rendering the menu or announcing the route is not the routed action:
+- **Start `ce-work`** -> Classify the artifact first. If the plan contents do not support code implementation or a launch blocker remains, do not execute it; route requirements-only artifacts back to `ce-plan` enrichment and non-code artifacts to their own workflow. If it is executable, invoke the `ce-work` skill under the cross-skill invocation rule, passing the plan path as the skill argument; `ce-work` then chooses how to execute and carries the implementation through verification and shipping. If `ce-work` cannot be invoked, print the existing `ce-work` fallback prompt for the user to run; in that prompt, tell the executor to read Goal Capsule, Verification Contract, Definition of Done, and active U-IDs (scanning headings to find them) rather than the whole document first. Do not merely tell the user to type an invocation when the host can invoke it directly.
+- **Decide on the review's open items** -> Invoke the `ce-doc-review` skill again under the cross-skill invocation rule, passing the plan path **without** `mode:non-interactive` so the interactive routing question and walkthrough run. The non-interactive pass already applied `safe_auto` fixes and recorded its findings in the session, so the interactive pass reuses that prior `safe_auto` / R29 decision state (its R29 suppression rule prevents prior-round Skipped/Deferred entries from re-raising) — "picks up where non-interactive stopped" means that state reuse, **not** skipping Phase 4 presentation or jumping straight to routing with a count. `ce-doc-review`'s walkthrough enforces the same-turn presentation-before-routing rule on this re-entry; a structured review result shown in an earlier turn beside this menu does not satisfy it. If the skill cannot be invoked, say that it did not run and return to the menu. After it returns, re-render this menu with the refreshed counts so the user can pick what to do next.
+- **Create Issue** -> Follow the Issue Creation section below through an available connector, MCP, API, or documented CLI; no `linear` CLI is guaranteed, and one missing binary is not proof that the tracker is unavailable.
+- **Prototype a remaining feel-question** -> Invoke the `ce-prototype` skill under the cross-skill invocation rule, passing the plan path as the skill argument. Do not build a prototype in this skill. If it cannot be invoked, say that it did not run and return to the menu. After it returns, re-render this menu from the artifact's current contents — a plan it wrote back to needs implementation planning again, so the execution options drop out on their own; when it returned decisions instead of writing them, say so, since the plan still describes the pre-prototype behavior.
+- **Open in browser** -> Display the absolute path to the `.html` plan file so the user can open it locally. Where the platform exposes a browser-opening primitive (e.g., `open` on macOS, `xdg-open` on Linux, `start` on Windows), the agent may invoke it directly; otherwise print the absolute path and let the user open it. After the path is displayed (or the browser is opened), return to the post-generation options so the user can pick a follow-up action.
+- **Free-form prompts that target the findings** (e.g., the user types "review", "walk through", "deep review" instead of picking a numbered option) -> route as if they had picked `Decide on the review's open items`. Do not loop back to the menu without running the review. When the structured review result carries `skipped_reason: skill_unreachable`, say that `ce-doc-review` could not be invoked and loop back without misreporting a review failure.
+- **Other free-form input** -> Accept revisions to the plan and loop back to options.
+
+## Issue Creation
+
+When the user selects "Create Issue":
+
+1. **Identify the project's issue tracker from the active instructions and conventions already in your context** — the issue / project-management tool the project uses (e.g., GitHub Issues, Linear, Jira). Don't open or name specific instruction files to do this; the project's instructions are already available to you. Look for an explicit `project_tracker:` declaration (`github`, `linear`, …) or any documented tracker convention. Only if your context doesn't already carry the project's instructions (e.g., you're a fresh subagent) or they're silent, consult supplementary signals: `README.md`, `CONTRIBUTING.md`, PR templates under `.github/`, or visible tracker URLs.
+
+2. **Create the issue through whatever interface that tracker actually exposes in this environment** — a platform connector/MCP tool, documented API/GraphQL credentials, or a documented CLI. First actively discover what's available: use the platform's tool-discovery primitive (e.g., `ToolSearch` in Claude Code) to look for a tracker connector or MCP tool before assuming none exists — lazy-loaded connectors and credentials stored outside the shell won't surface in a passive check. Do not assume a tracker means a particular CLI, and do not treat a missing binary, env var, or unloaded MCP server as proof the tracker is unavailable — those are false negatives when access comes through a connector or a raw API with credentials stored outside the shell. When using a direct API, never print secret values; read the plan body from disk and send it as the issue's markdown/description per the API contract. Worked examples for the common cases:
+   - **GitHub** — `gh issue create --title "<type>: <title>" --body-file <plan_path>`
+   - **Linear** (no guaranteed first-party CLI) — prefer, in order: a Linear connector or MCP tool that can create issues → documented direct API/GraphQL credentials and endpoint → a documented local Linear CLI, only when the project or user explicitly states it is installed and authenticated.
+
+3. If no tracker is configured, ask the user which tracker they use with the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to asking on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip. Offer three explicit options — `GitHub`, `Linear`, `Skip` — and let the user name a different tracker (Jira, etc.) through the tool's built-in free-form / "Other" input. Don't add an explicit fourth `Other` option — that's redundant where the tool already offers free-form and can exceed a 2–3 explicit-option cap. When the tool exposes no free-form path, capture the other-tracker name via the chat fallback. Then:
+   - Proceed with the chosen tracker's creation path above
+   - If the user names a different tracker through the free-form path, ask for its reachable interface if they didn't say, then create the issue via the capability path in step 2
+   - Offer to persist the choice by adding a `project_tracker: <value>` declaration to the project's root agent-instructions file (e.g., `AGENTS.md`; if it `@`-includes another file, write to the substantive one). Use the lowercase tracker key (`github`, `linear`, `jira`, …) — not the display label — so future runs match step 1 and skip this prompt
+   - If `Skip`, return to the options without creating an issue
+
+4. If the detected tracker has no reachable interface after actively discovering available connector/MCP tools and following its documented access method — no working connector, MCP tool, CLI, or API path — report a clear error (e.g., "`gh` CLI not found or not authenticated for GitHub Issues"; "Linear is documented for this project, but no connector, MCP tool, or API credentials were found") and return to the options. Do not silently fall back to a local issue-plan document unless the user explicitly asks for a local-only artifact.
+
+After issue creation:
+- Display the issue URL
+- Ask whether to proceed with `ce-work` using the host's blocking question tool already in the current tool list

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

@@ -0,0 +1,489 @@
+# Plan Sections
+
+This reference describes what makes a great implementation plan. It does NOT
+prescribe how the plan looks on the page — rendering is handled by the
+format-specific references (`markdown-rendering.md`, `html-rendering.md`).
+
+## The outcome
+
+A great plan enables three audiences to act:
+
+- **The implementing agent** (`ce-work` or a human) starts from an informed
+  baseline — the decisions everything else rests on are named, research breadcrumbs orient
+  their own investigation, unit boundaries are clear. The plan gives the
+  implementer a starting point, not a substitute for their own investigation.
+- **The reviewer** identifies the decisions everything else rests on and the boundaries
+  of what's being changed in one pass.
+- **The future reader** (anyone returning months later) traces why the work
+  was done, what shaped it, and where the artifacts live.
+
+A section belongs only when it serves one of these audiences. Omit padding.
+
+## Unified plan artifact contract
+
+`ce-plan` writes the canonical compound-engineering plan artifact. The same
+artifact may begin as a requirements-only skeleton from `ce-brainstorm` and
+later be enriched by `ce-plan`; it is still one plan file moving through
+planning stages, not a requirements doc plus a separate implementation doc.
+
+When the artifact is meant to be consumed by implementation agents, use:
+
+- **`artifact_contract: ce-unified-plan/v1`** — declares this contract.
+- **`product_contract_source`** — where the Product Contract came from:
+  `ce-brainstorm`, `ce-plan-bootstrap`, `legacy-requirements`, or another
+  explicit source string when a repo has a specialized producer.
+- **`execution`** — `code` for implementation plans, `knowledge-work` for
+  non-code deliverables. Absence remains legacy-compatible and means `code`
+  only for older plans without `artifact_contract`.
+
+Determine whether a plan can be executed from its contents. The Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done must give the executor enough direction, with no launch-blocking question remaining. Mark open questions as blocking or deferred; deferred implementation details do not prevent work. A Product Contract without sufficient planning needs enrichment.
+
+Do not write a readiness or execution-status field. When updating an older artifact, remove `artifact_readiness` from its frontmatter or visible HTML metadata. An old readiness label does not establish completeness or override a blocker. Plans carry no `status` field and no mutable execution lifecycle.
+
+Approach-plans, answer-seeking outputs, and universal-planning outputs remain outside this software implementation contract unless they contain the full contract above. Route non-code deliverables by their contents and `execution: knowledge-work`.
+
+## Section ID Registry
+
+Unified artifacts use these stable logical sections. Markdown uses the
+heading text; HTML uses matching visible headings and anchor IDs. Downstream
+skills grep or anchor-scan for these names before reading large bodies.
+
+| Logical section | Markdown heading | HTML id | Reader use |
+|---|---|---|---|
+| Goal Capsule | `## Goal Capsule` | `goal-capsule` | Objective (outcome), Means (chosen approach), authority hierarchy, and stop conditions |
+| Product Contract | `## Product Contract` | `product-contract` | Requirements, actors, flows, acceptance examples, product scope |
+| Product Requirements | `### Requirements` under Product Contract | `product-requirements` | Requirement extraction for review and implementation trace |
+| Planning Contract | `## Planning Contract` | `planning-contract` | KTDs, technical design, assumptions, sequencing |
+| Implementation Units | `## Implementation Units` | `implementation-units` | U-ID work packets for execution |
+| Verification Contract | `## Verification Contract` | `verification-contract` | Repo-specific test commands and quality gates |
+| Definition of Done | `## Definition of Done` | `definition-of-done` | Global and per-unit completion criteria |
+| Appendix | `## Appendix` | `appendix` | Long research, raw notes, or supporting detail |
+
+Requirements-only artifacts are kept light: a Goal Capsule and the Product
+Contract. They must not point implementers at absent Planning Contract,
+Implementation Units, Verification Contract, or Definition of Done sections.
+`ce-plan` adds those implementation sections when it enriches to
+implementation-ready. Implementation-ready artifacts include the full registry
+above, except Appendix remains optional.
+
+### Wayfinding: map before reading (size-aware)
+
+The document does not carry a reading guide; consuming skills own the reading
+algorithm. A **short** plan — a lightweight or requirements-only artifact that
+fits in a screen or two — can just be read in full; that is cheaper and simpler
+than scanning and ranging. But an implementation-ready unified plan is often
+long, and HTML output (also supported) is more verbose still, so for anything
+beyond short, do **not** load the entire artifact to find your way around.
+Build a section map first, then read only the ranges the task needs:
+
+- **Markdown:** scan headings to get the section and unit map — e.g.
+  `rg -n '^#{1,3} ' <plan>` (top-level sections plus `### U<N>.` units).
+- **HTML:** scan the heading elements (`<h1>`–`<h3>`) and their anchor ids;
+  match on the section name and ignore the wrapper tags.
+
+In both formats the section **names and anchor ids are the stable contract**
+from the Section ID Registry above (`Goal Capsule`/`goal-capsule`,
+`Verification Contract`/`verification-contract`, `### U<N>.` units, …). Wayfind
+against those registry names, not a brittle tag/format pattern, so the
+instruction survives rendering changes. After mapping, read metadata, then only
+the sections the task needs — e.g. Goal Capsule, the active U-ID plus its cited
+R/F/AE/KTD, Verification Contract, and Definition of Done. Read the Appendix or
+unrelated units only when a section you are already reading cites them.
+
+## Whether a plan file is warranted
+
+SKILL.md's Output Contract gate decides this at intake, before any research: Direct and Chat brief results stay in chat (`references/output-contracts.md`); a Durable run writes the file this reference describes.
+
+## Implementation-ready hard floor
+
+When an implementation-ready software plan is warranted, these sections are
+present. They carry the contracts downstream consumers depend on.
+
+- **Goal Capsule** — objective, means (only when an approach is fixed),
+  authority hierarchy, stop conditions, execution profile, and who
+  finishes and ships the work. This is the fastest way for an executor to avoid drifting from
+  the plan. A reader who has not read the rest of the plan must be able to
+  hold the Objective as the goal. Remaining-true constraints live on their
+  owning R-IDs (the R-IDs that state them), not as extra Objective clauses — user-checkable is not a
+  license to pack them onto the Objective. An Objective that is only
+  understandable after later sections is not yet the Objective, even when a
+  user could check the outcome and a different implementation would still
+  serve it. The **Objective** is always the outcome: what is true for users
+  or operators afterwards, phrased so it would still read as the goal under
+  a different implementation. It sits outside the component being changed,
+  which is a question of who can check it rather than of which nouns it
+  uses: an outcome someone outside that component can verify without knowing
+  its internals is an Objective even when that component is what changed,
+  and one only its internals can settle is not the Objective however
+  outcome-shaped its wording; the registry above decides where it does
+  belong. The usual failure is an objective about the component's own
+  execution — the wall-clock it no longer holds, the runtime it no longer
+  consumes, what stays isolated inside it — which only its internals settle.
+  Infrastructure and refactor work has such an objective too: the reason
+  that component's behavior mattered to someone. The chosen approach is the
+  **Means**, its own line whenever the request or the plan has fixed one —
+  never invented for outcome-only work. It is a linked projection under the
+  one-owner rule below: one line naming the approach and citing the KTD or
+  Key Decision that owns it (`Means: … (KTD2)`), never a restatement of that
+  owner's mechanism. Test: if the implementation changed, would the
+  Objective still be the goal, and could a reader who does not know the
+  changed component's internals tell whether it was met? No to the first
+  makes it a Means. No to the second means it is stated at the component's
+  level, and the Objective is whatever depended on that component. When a
+  request supplies only its approach ("move X out of A into B"), that is the
+  Means; the Objective is the outcome it serves, derived from the request's
+  motivation, the project's stated problem, or asked for — never the approach
+  restated.
+- **Product Contract** — product scope and behavior. Contains Summary, Problem
+  Frame, Requirements with stable R-IDs, and any material Actors, Flows,
+  Acceptance Examples, Success Criteria, Scope Boundaries, Dependencies,
+  Outstanding Questions, and Sources. This replaces the separate requirements
+  artifact in new brainstorm-to-plan flows.
+- **Planning Contract** — the implementation-facing decisions: Key Technical
+  Decisions, high-level design, assumptions, implementation constraints,
+  sequencing, and research that shapes how the Product Contract will be built.
+- **Implementation Units** (with stable U-IDs) — discrete work packets sized so
+  each is independently executable. Each unit names Goal, Requirements,
+  Files, Approach, Test Scenarios, and Verification. `ce-work` and other
+  executors consume these units.
+  - **Unit Index (large plans only, ~10+ units).** When the plan has roughly
+    ten or more units, open the section with a compact navigation table — one
+    row per unit: **U-ID · one-line title · files touched · depends-on**. It
+    lets an executor map units to files and resolve dependency order without
+    scanning every unit body. It is a **navigation aid only**: the unit bodies
+    stay authoritative, it carries nothing beyond those four fields (no
+    approach, tests, or rationale), and `files touched` is the key/primary
+    paths, not an exhaustive restatement. **Omit it below ~10 units** — there
+    the per-unit `Dependencies`/`Files` (and any sequencing or dependency
+    diagram) already suffice, and an index would be ceremony.
+- **Verification Contract** — repo-specific commands and quality gates,
+  including which tests prove the plan, when `release:validate` applies, and
+  what behavioral skill evaluation is required. Avoid generic "run tests"
+  language when the repo has concrete commands. When the goal is
+  optimization-shaped (build time, latency, coverage, bundle size), express a
+  measurable threshold as the exit criterion (e.g., "p95 latency < 200ms",
+  "build time reduced 30%") and consider routing to `ce-optimize` — a metric
+  target is a sharper done signal for a long-running goal than a boolean check.
+- **Definition of Done** — global and per-unit done criteria. This is the
+  completion contract an executor checks before declaring the work done. Include
+  a cleanup criterion: a long autonomous run accumulates dead-end and
+  experimental code from approaches that did not pan out; declaring done
+  requires that abandoned-attempt code is removed, not left in the diff.
+
+## Include when material
+
+These sections are present when they carry information that isn't covered
+elsewhere. The test is not "is this a substantial plan?" — it is
+*"does this specific plan have content this section would surface?"* Filling
+a section with placeholder prose is worse than omitting it.
+
+The first five entries below carry the Product Contract's product framing —
+what is being built and why. Later entries mix Product Contract subsections
+(Scope Boundaries, Open Questions, Acceptance Examples, Sources) with
+Planning Contract ones; the hard floor above remains authoritative for which
+section sits under which contract. Problem Frame is unconditional; each of the other four is included when its own test says so. A plan
+that skips all four conditional framing entries has usually inherited its
+framing from an upstream Product Contract — check before concluding none of
+them apply.
+
+- **Problem Frame** — the hard floor above contains it unconditionally, so
+  this entry governs its depth, never whether to include it. Give it
+  paragraphs when motivation isn't obvious from Summary alone; keep it to a
+  line or two when the motivation was settled upstream and more would only
+  echo the origin document. Backward-looking / situational. Does NOT restate
+  the proposal; the remedy lives in Summary.
+
+- **Key Decisions** — include when the plan carries product-level choices
+  that constrain the Requirements below, whether made during planning (scope
+  narrowings, defaults chosen against a real alternative, framing the user
+  picked) or inherited from an upstream Product Contract, which Phase 0.3
+  requires carrying forward with its rationale. Each entry is a provenance
+  index entry, not a second statement of the rule: the decision in bold, at
+  most one line of rationale, and exact `Governs R5, R7` links when it
+  constrains specific requirements. The normative text lives on the governed
+  Rs. Session-settled annotations follow the rules under "ID and content
+  rules" below. Distinct from Planning Contract's Key Technical Decisions,
+  which record how-level choices; a product decision belongs here, and a KTD
+  cites it rather than mirroring it. Skip only when no such
+  choice exists on any side: every requirement follows directly from the
+  request, any upstream Product Contract weighed no alternatives, and the
+  session settled none. A `session-settled:` decision always keeps the
+  section — plan-write and the routing table both require its labeled entry
+  to live here.
+
+- **Success Criteria** — include when there are quality / metric / handoff
+  signals that Requirements don't already carry: quantitative metrics ("p95
+  latency under 200ms"), qualitative criteria ("the agent's output reads as
+  one voice"), process / handoff quality ("ce-doc-review can act on this
+  without follow-ups"). Skip when Requirements ARE the success criteria
+  (every R is "done when the R is true"). Requirements that describe an
+  approach rather than an outcome are not success criteria; then include at
+  least one criterion that would show the Goal Capsule Objective was reached.
+
+- **Actors** — include when the work has multi-party behavior (multiple
+  humans, agents, or systems meaningfully involved) that the units must
+  honor. Skip for single-actor work and for plans whose change is internal
+  to one component — most implementation plans skip this.
+
+- **Key Flows** — include when the work has multi-step behavior whose
+  sequencing the units must preserve. Skip when the change is not
+  flow-shaped, or when Requirements and Acceptance Examples together already
+  prevent downstream invention of paths — again, most implementation plans
+  skip this.
+
+- **High-Level Technical Design** — include when the technical approach has
+  shape that prose alone doesn't carry well: architecture across components,
+  sequencing across processes, state machines, branching gates.
+  Visualizations (component topology, sequence, swim lane, flowchart,
+  data-flow) typically live here. Skip when the approach is a one-paragraph
+  pattern application that the prose itself conveys.
+
+- **Scope Boundaries** — include when scope is contested, when there are
+  tempting non-goals worth naming explicitly, or when "deferred for later"
+  needs distinguishing from "outside the product's identity." Skip when scope
+  is obvious from Requirements alone.
+
+- **Open Questions** — include when there are genuinely unresolved items that
+  block planning or implementation. Skip when the plan is complete; an empty
+  "Open Questions: none" section signals false uncertainty.
+
+- **System-Wide Impact** — include when the change affects cross-cutting
+  concerns (data lifecycles, auth boundaries, performance characteristics, cardinal
+  rules, shared infrastructure, agent/tool parity, prompt context, shared
+  workspaces). Skip for changes localized to one component where the impact is
+  self-evident.
+
+- **Risks & Dependencies** — include when there are real risks worth flagging
+  (external service changes, version pins under churn, behavioral assumptions
+  worth highlighting) or material upstream dependencies. Skip for low-risk
+  localized work.
+
+- **Acceptance Examples** — include when any requirement has a state-dependent
+  or conditional shape ("When X, Y") where the prose alone leaves ambiguity
+  about edge cases. Skip when all requirements are unconditional and
+  unambiguous.
+
+- **Documentation / Operational Notes** — include when documentation,
+  monitoring, runbooks, or rollout steps need explicit notes. Skip when the
+  work is purely internal and uses existing operational scaffolding without
+  modification.
+
+- **Sources / Research** — include the research that orients the implementer
+  or justifies the choices the plan rests on. The test: *"if I were the implementer
+  reading this cold, would this breadcrumb help me make better choices?"*
+  Yes → include (code locations like `services/convex/reports.ts:174-176`,
+  external docs, RFCs, constraints, prior plans — the category is inclusive,
+  not enumerated). A record of the planning process itself (reading the
+  user's prompt, glancing at obvious entry points, restating prose) → omit. Put it inline next to the
+  KTD or unit it justifies, or in a dedicated section — both shapes work.
+  A constraint adopted from a Compound Pack file is cited inline as
+  `(pack: <id>, <path within the pack>)` after the requirement, KTD, constraint,
+  or risk it shaped. The path is relative to the pack's own directory, so it
+  is stable for path- and git-sourced packs alike. Cite the pack text; do not
+  restate it. That marker is reserved for pack files; `<root>/solutions/`
+  learnings keep the ordinary path citation, so a reader can tell a
+  prescriptive pack rule from a retrospective learning.
+
+## Agent agency
+
+The catalog is a floor, not a ceiling. When the plan's content doesn't fit
+any catalog section, introduce a new one — don't force the content into a
+section it doesn't belong in. Content drives section choices, not vice
+versa.
+
+The agent also picks per artifact:
+
+- Whether Problem Frame merges into Summary — legacy and non-unified plans
+  only. Any `ce-unified-plan/v1` artifact keeps both headings regardless of
+  plan depth: the hard floor names them separately and downstream consumers
+  anchor on them. (Scoped by artifact contract, not by depth — a `Lightweight`
+  plan can still be implementation-ready.)
+- Sub-groupings (Requirements by capability, KTDs by component, Units phased
+  into milestones)
+- How much detail each section carries
+- Whether HTD has one diagram, several, or none — and whether visualizations
+  live in HTD or embedded in other sections
+
+## Prose economy
+
+"Include when material" sizes *which* sections appear; this sizes *how the kept
+prose reads*. A section can be material and still be written loosely — the
+failure mode is a material section padded into a wall of text where
+contradictions hide and the implementing agent loses the thread. A deep plan
+earns length through coverage (more units, more traced requirements, real
+risks), never through wordiness around that coverage.
+
+Write every kept section through the `ce-noslop` skill.
+
+Hold every kept section to these:
+
+- **Lead with the decision or outcome.** Put the conclusion first, then the
+  reason, then background; keep one claim plus its support per paragraph. Don't
+  bury a Key Technical Decision, the chosen scope, an open blocker, or a unit
+  goal beneath its rationale. This does not override section roles — Summary
+  stays proposal-only, Problem Frame stays motivation-only and never restates
+  the remedy.
+- **A Summary is a handful of sentences**, not one sentence with five
+  semicolons and four parentheticals. A KTD's rationale is the reason that
+  decided it, not every reason.
+- **A requirement or unit is one sentence of intent plus at most one
+  qualifier.** When it would specify two outcomes ("either A or B, the
+  implementer decides"), state the intent and send the fork to Open Questions —
+  don't write both arms in full inside the item.
+
+Precision is not padding: keep file paths, IDs, dates, domain terms,
+conditionals, and exact thresholds verbatim; when a concrete anchor is knowable
+from the work already done, use it instead of a vague abstraction. Economy
+targets the connective tissue around precision, never the precision itself.
+
+**Resolve in place; don't stratify.** When deepening, a doc-review pass, or a
+later decision supersedes earlier text, rewrite or remove the original — don't
+leave it standing as strikethrough or stack a separate "resolutions" layer on
+top of it. Version control holds the history. Stacked strata double the reading
+surface and hide which text is live.
+
+**One owner per rule; cite, don't restate.** A normative rule — a gate, cap,
+threshold, protocol, or output contract — is stated in full at exactly one
+owning entry: product behavior on its R-ID; an implementation choice on its
+KTD. Every other layer cites the owning ID and adds only what is local to
+it — a unit's Approach carries unit-local deltas (files, sequencing,
+patterns), never a re-derivation of the protocol its cited Rs and KTDs own.
+Linked projections are allowed (an AE restating behavior under
+`Covers R…`, a Flow citing the Rs it sequences). **Unlinked sibling
+restatement** — the same rule written out again in a KTD, Scope bullet, or
+Approach with no ID link — is the defect: each copy drifts independently.
+When linked layers disagree, authority is typed: the **R wins on product
+behavior**; the **KTD wins on implementation mechanism** within its cited R
+constraints; a unit overrides neither; AEs and Flows illustrate and
+sequence, never amend.
+
+**Bind external authorities; don't summarize them.** When a requirement,
+KTD, or unit adopts an external document (a field guide, spec, standard),
+state the commitment, cite the path, and record only this work's deltas. A
+multi-sentence summary of the cited document is restatement of an owner that
+lives outside the doc.
+
+**Named test, run before the plan is declared written:** could the implementer
+find a contradiction in each section in one pass? Could a colleague who was
+not in the session say what this work is after the Objective alone? A sentence
+carrying more than one parenthetical, a sentence chaining more than two
+semicolons, an item specifying two outcomes, or a rule stated in full in more than one section
+fails the test — split it (a semicolon chain becomes a list), defer it, or
+replace the duplicate with its owning ID.
+
+## Plan metadata fields
+
+Every plan carries a small set of stable metadata fields that downstream
+tooling depends on. The contract is format-independent: in markdown these
+fields appear as YAML frontmatter at the top of the file; in HTML they
+appear as visible header text (typically a `<dl>` of `<dt>`/`<dd>` pairs or
+a stats strip). Field names and semantics are the same across both formats
+so consumers can locate them without knowing which format produced the
+plan.
+
+### Required
+
+- **`title`** — the plan's descriptive name with a ` - Plan` suffix
+  (e.g., `Highlighter Tool - Plan`), matching the H1 (markdown) or document
+  `<h1>` (HTML) so file metadata and visible heading don't drift. Stable
+  across planning stages (it is a plan at every stage). Do not put a
+  conventional-commit prefix (`feat:`/`fix:`) in the title — the `type` field
+  carries that classification.
+- **`type`** — conventional-commit-prefix-aligned classification (`feat`,
+  `fix`, `refactor`, `chore`, `docs`, `perf`, `test`, etc.). Carries the
+  intent the eventual commit message should reflect.
+- **`date`** — creation date in ISO 8601 (`YYYY-MM-DD`), ASCII digits only.
+
+Plans carry **no `status` field** — a plan is a decision artifact, not a
+tracked work item. `ce-work` does not mutate the plan at ship time;
+whether a plan shipped is derived from git, not stored in the doc. Do not
+add a `status` field or an `active → completed` lifecycle.
+
+### Optional but well-known
+
+These fields are not required, but when set they have fixed names and
+semantics so downstream tooling can rely on them:
+
+- **`origin`** — repo-relative path to an upstream brainstorm requirements
+  doc (e.g., `docs/brainstorms/2026-05-12-pagination-requirements.md`).
+  Set when planning from an upstream brainstorm; carried for traceability
+  and re-resolved when `ce-plan` re-deepens.
+- **`deepened`** — ISO 8601 date marking the first time the confidence
+  check substantively strengthened the plan. Presence affects Phase 0.1
+  resume fast-path logic (see `references/deepening-workflow.md`).
+- **`execution`** — execution domain for downstream routing: `code`
+  (the default when absent) or `knowledge-work`. `ce-work`'s input triage
+  reads this: a plan marked `execution: knowledge-work` routes to the
+  non-code carve-out (read sources, synthesize, produce a deliverable —
+  skipping the branch/test/commit/CI lifecycle); absent or `code` routes
+  to the normal code path. Written by `ce-plan`'s approach-altitude flow
+  (`references/approach-altitude.md`) when a non-code deliverable is
+  persisted for execution.
+
+Field names are stable across plan revisions — never rename a field or
+repurpose its semantics. Agents composing new plans MUST use these exact
+names; adding new fields is fine, but renaming `origin` to `source` or
+`date` to `created` breaks the downstream consumers above.
+
+## ID and content rules
+
+These apply regardless of rendering format.
+
+- **Stable IDs.** R-IDs (Requirements), U-IDs (Implementation Units),
+  KTD-IDs (Key Technical Decisions, implementation-ready plans), A-IDs
+  (if the plan has Actors), F-IDs (if it has Flows), AE-IDs (if it has
+  Acceptance Examples). IDs are stable across plan revisions — never renumber to "clean
+  up gaps."
+- **Plain prefix.** `R1.`, `U1.`, `KTD1.` as bullet prefixes. Do not bold;
+  the prefix is visually distinctive on its own.
+- **KTD-IDs on implementation-ready plans.** Number Key Technical Decisions
+  (`KTD1.`, next unused number, same never-renumber rule as U-IDs) in newly
+  authored implementation-ready plans, and in an existing plan whenever a
+  KTD is added, split, or first cited by a unit. Untouched unnumbered KTDs
+  in legacy plans stay as they are — readable by label, no mass renumbering.
+- **Repo-relative paths.** Always. Never absolute paths in plan content;
+  they break portability across machines, worktrees, teammates.
+- **No record of the planning process.** No "captured at Phase X" notes, no `## Next Steps`
+  pointing to the next skill, no italic provenance lines. Engineering process
+  metadata belongs in commit messages and tool output, not the artifact.
+- **Session-settled annotations on KTDs.** A Key Technical Decision that
+  records a decision settled in the invoking conversation carries an inline
+  annotation on its entry:
+  `(session-settled: user-directed — chosen over <alternative>: <one-line reason>)`.
+  Exactly two classes: `user-directed` (the user chose against or between
+  surfaced options) and `user-approved` (the agent proposed with the tradeoff
+  surfaced; the user assented). An agent never labels its own unexamined
+  proposal. A KTD that makes the how-level choice instantiating a labeled
+  Product Contract Key Decision inherits the label and cites the decision's
+  governed R-IDs. Do **not** create a KTD that merely mirrors a Product Key
+  Decision with no new technical choice — the Key Decision plus its
+  `Governs R…` links already own that content. The annotation is
+  self-contained — decision, rejected alternative, and one-line reason
+  readable without the conversation — and lives inline on the entry: no
+  sidecar files, no frontmatter registry, no numeric weights, no lifecycle
+  field. Like a `(see origin: <path>)` citation, it is decision provenance,
+  not a record of the planning process — review passes must not strip it. A consumer that
+  does not recognize the annotation treats the entry as a normal KTD.
+- **Group Requirements by concern when they span distinct logical areas.**
+  The trigger is distinct concerns, not item count — even four requirements
+  benefit from grouping if they cover three different topics. Skip grouping
+  only when all requirements are genuinely about the same thing; a long flat
+  list is a smell that subgroups were missed. Group by capability (e.g.,
+  "Packaging", "Migration and compatibility", "Contributor workflow"), not by
+  the order requirements were discussed. R-IDs stay continuous across groups
+  (R1, R2 in the first group; R3, R4 in the second; never restart at R1 per
+  group).
+
+## Rendering
+
+The format-specific references describe how to render these sections in each
+output format:
+
+- **Markdown rendering:** `references/markdown-rendering.md`
+- **HTML rendering:** `references/html-rendering.md`
+
+This reference (`plan-sections.md`) is about WHAT the plan contains;
+rendering references are about HOW each format presents it. The plan is
+written in one format — markdown OR HTML, never both — based on the
+resolved output mode. The section catalog is the same regardless of
+format.