npm - @runfusion/fusion - Versions diffs - 0.73.0-beta.2 → 0.73.0-beta.4 - Mend

@runfusion/fusion 0.73.0-beta.2 → 0.73.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (291) hide show

package/dist/plugins/.fusion-ce-skills/ce-plan/references/html-rendering.md ADDED Viewed

@@ -0,0 +1,668 @@
+# HTML Rendering
+This is a format-rendering reference — it describes how to render any
+artifact in HTML, 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* HTML specifically presents it. The same
+content rendered by different skills shares the same HTML principles.
+The HTML artifact is the *only* artifact the skill produces for that run —
+output mode is exclusive (markdown OR HTML, never both). Downstream
+consumers that read HTML today (`ce-work`, `ce-doc-review` DOM-safe-or-report-only mode,
+human readers) do so directly; the agent-consumability rules below make that
+work. `ce-doc-review` may apply only parse5-backed DOM-safe helper mutations; markdown autofix and
+markdown Append-to-Open-Questions write-back remain disabled for `.html` artifacts, and any helper refusal falls back to report-only.
+## Hard invariants
+These hold regardless of which skill produced the artifact.
+- **Single self-contained HTML5 file.** No companion `.css`, `.js`, or
+  `.svg` files. CSS lives in `<style>`. SVG lives inline. Images are
+  base64 data URIs or inline SVG. The one permitted exception is a
+  `<link rel="stylesheet">` to a CDN webfont CSS endpoint (Google Fonts,
+  Bunny Fonts, etc.), paired with an offline-readable fallback font stack
+  so the doc remains readable if the CDN is unreachable.
+- **All metadata appears as visible text — single source of truth.**
+  The artifact's metadata (title, type, date, etc. — exact
+  fields per-skill, defined in the section contract) renders as visible
+  HTML elements that downstream agents and humans read. No hidden
+  machine-readable copy in any form: no `<script type="application/json">`
+  frontmatter block, no `data-*` attribute mirror, and no
+  `<meta name="created">` / `<meta name="origin">`
+  in `<head>` duplicating the same values that appear in the visible
+  header. One representation for each value — drift across two copies is
+  the failure this rule prevents.
+  The text-and-attribute redundancy in `<time datetime="2026-05-12">2026-05-12</time>`
+  is acceptable because the attribute is a parser hint, not a hidden copy.
+- **Stable IDs as anchor IDs AND visible text.** Every ID-bearing item
+  (R-IDs, U-IDs, A-IDs, F-IDs, AE-IDs, KTDs) gets `id="r1"` on its
+  element AND appears as visible text inside the element (e.g., the
+  text "R1." inside the table cell or heading). Downstream agents find
+  the ID in source the same way they find it in markdown.
+- **Source / composition signal.** A visible footer at the bottom of
+  the doc names the composition timestamp and the source identifier
+  (the user prompt context, the upstream brainstorm doc when one
+  exists, or just the composing skill name when there's no external
+  source). Example shape:
+  `<footer class="composition-signal">Composed 2026-05-17T14:23Z by ce-plan from <code>docs/brainstorms/...-requirements.md</code></footer>`.
+  Under exclusive output mode this signal is the artifact's own
+  provenance — there's no markdown sibling to reference. Omitting it
+  leaves readers unable to tell how stale the rendering is.
+- **ASCII identifiers.** Class names, element IDs, data attribute names
+  are ASCII-only.
+- **Unified plan navigation.** Unified plan artifacts include a visible
+  navigation region near the top of the document. It links to stable section
+  anchors for `goal-capsule`,
+  `product-contract`, `planning-contract`, `implementation-units`,
+  `verification-contract`, `definition-of-done`, and `appendix` when those
+  sections exist. Requirements-only artifacts omit links to absent
+  implementation sections.
+- **Visible readiness metadata.** If the artifact has `artifact_contract`,
+  `artifact_readiness`, `product_contract_source`, or `execution`, render
+  those values in the visible header metadata. Do not hide a duplicate copy in
+  JSON, `data-*`, or `<meta>` tags.
+## Precedence stack for style preferences
+Honor user style preferences in this order (highest to lowest):
+1. **In-session conversation** — explicit direction the user gave this run.
+2. **Preferred stylesheet reference** named in loaded agent-instruction
+   context (typically `AGENTS.md` / `CLAUDE.md`, but scan loaded context;
+   don't enumerate locations). The reference may be a file path
+   (`docs/style.css`), a URL, a named library ("Tailwind"), or a style
+   brand ("Stripe docs"). Agent-instruction files carry deliberate
+   agent-aware preferences, so this tier sits above DESIGN.md.
+3. **DESIGN.md** discovered on the filesystem (see "DESIGN.md discovery"
+   below).
+4. **Fallback default** — the opinionated palette / typography choices the
+   agent makes when no preference exists.
+### Active-recall at compose time
+Before writing the CSS, scan loaded context for any stylesheet reference
+the user has indicated for documents like this. If found and inlinable
+(short local file, fetchable URL within budget), inline it into `<style>`.
+If found but not inlinable (large framework, paywalled stylesheet, named
+system without a fetchable source), compose CSS in its spirit — typography,
+color, density cues drawn from the named system. Only fall back to the
+default style when no preference signal exists.
+The single-file invariant is preserved either way. External
+`<link rel="stylesheet">` is permitted only for CDN webfont CSS (with the
+offline fallback font stack); never link to an external stylesheet
+carrying layout, color, or typography rules the doc cannot read offline.
+### DESIGN.md discovery
+When tier 3 of the precedence stack applies, look for a DESIGN.md file in
+these locations, first match wins:
+1. Worktree root (resolve via `git rev-parse --show-toplevel`).
+2. `docs/DESIGN.md`.
+3. `.compound-engineering/DESIGN.md`.
+Read once at compose time. Absent → fall through to the fallback default.
+Worktree-root only — do not fall through to a main checkout. Users
+working from a worktree who want HTML defaults can add DESIGN.md to the
+worktree.
+**DESIGN.md is a partial override, not all-or-nothing.** Real DESIGN.md
+files vary widely: some are token tables, some are CSS variables, some are
+prose; most are authored for a *product or marketing surface*, not a
+long-form doc. The governing split: **take the brand's scale-independent
+identity literally, own the scale-dependent layout values yourself, and
+skip decoration.**
+- **Take literally (scale-independent identity):** the color palette
+  (under the contrast rule), font *weight* and *style*, OpenType features,
+  and radius *character* (sharp vs rounded). These carry the brand and are
+  safe at any size.
+- **Own it yourself (scale-dependent layout):** the **type size scale**
+  and **spacing magnitudes**. DESIGN.md values are almost always
+  product/marketing-scaled (display headings at 48-80px, airy ~96px
+  section gaps); read them only as *hierarchy*, then set doc-appropriate
+  values (body ~14-16px, headings ~1.2-1.6× body, comfortable paragraph
+  spacing).
+- **Skip decoration:** decorative or atmospheric brand voltage with no
+  content to attach to in a doc — gradient orbs, full-bleed hero
+  photography, motion. Take the palette and feel; do not reproduce the
+  decoration.
+Specific cases:
+- **Fonts: load only open webfonts; never attempt a proprietary brand
+  face.** A self-contained doc can only load an open webfont (Google Fonts
+  or an open CDN) via the permitted webfont `<link>` plus an offline
+  fallback stack. **Assume a bespoke brand face is proprietary and do not
+  attempt to load it** — Airbnb Cereal, Coinbase Display/Sans, BMW Type,
+  Waldenburg, Circular and the like will not render in a single file;
+  trying just produces a broken fallback. Use the DESIGN.md's own fallback
+  chain, or a family-matched system stack (serif↔serif, sans↔sans,
+  mono↔mono). Load a named face *only* when it is a known open webfont
+  (Inter, Geist, Cal Sans, Roboto…); when unsure whether a face is open,
+  do not try. Honor the DESIGN.md's declared roles (`body` / `display` /
+  `mono`) and never promote a display/decorative face into a body or
+  small-text role. Net: reproduce the brand's serif-vs-sans structure and
+  weight voice, not necessarily its exact faces.
+- **Typography-scale mismatch.** DESIGN.md typography tokens are usually
+  sized for product UI — marketing pages, app screens, hero sections —
+  with display headings at 48-80px. A long-form doc needs body at ~14-16px
+  and headings at ~1.2-1.6× body. When the size scale looks
+  product-scaled (the common case), use the **family**, **weight**, and
+  **OpenType feature** assignments (these carry the design language) and
+  pick the agent's own size scale for the doc surface. Apply DESIGN.md
+  sizes literally only when they are clearly doc-scaled — body 14-16px,
+  headings under ~32px.
+- **Scope mismatch (product UI vs doc surface).** A DESIGN.md aimed at
+  product marketing or app UI may name button states, input borders, or
+  hero backgrounds tied to *that* surface, not a generic doc. The page
+  surface is the case to judge: a **reading canvas** — white, off-white,
+  or a legible dark — transfers **literally** and should be the doc
+  background; a bright product/marketing-hero surface
+  (`--surface: #c0f0fb`) does not — extract the principle (the design
+  language uses a tinted surface) rather than the literal value when the
+  token is product-UI-scoped.
+- **Partial coverage.** When DESIGN.md defines some categories but not
+  others (colors but no spacing scale, typography but no elevation), use
+  it for what it covers and the fallback default for the rest. Do not
+  require DESIGN.md to be complete before honoring it.
+## Format principles
+These shape what "good" HTML looks like; the agent applies them per
+artifact based on content.
+### Readable measure, not full bleed
+Long-form text is unreadable at full viewport width — past ~80 characters
+per line the eye loses the return sweep and scanning slows. As a
+fallback-default (precedence tier 4, overridden by in-session direction or
+DESIGN.md), center the document in a content container and hold prose to a
+comfortable measure.
+- **Page container.** A centered column with a max-width in the ~820-960px
+  band (`margin-inline: auto`) keeps the doc off the far edges of wide
+  monitors while leaving room for the format's richer shapes.
+- **Prose measure.** Hold running paragraphs to roughly 65-80 characters
+  (`max-width: ~70ch` on text blocks). The named test: read a paragraph at
+  full window width on a wide display — if the return sweep to the next
+  line is effortful, the measure is too wide.
+- **Let wide content break out.** Tables, diagrams, and side-by-side
+  columns may use the full container width (or wider) when the content
+  needs it — the measure constraint is for prose, not for everything.
+Express the constraint in `ch`/`rem` rather than a single hardcoded pixel
+value so it survives font-size and DESIGN.md overrides. DESIGN.md or an
+in-session instruction overrides these values; this is the fallback when no
+layout preference exists.
+### Markdown source is content, not design
+When markdown (or markdown-shaped chat context) is part of the input, use
+it for semantic content — what the doc is about, what sections exist,
+what facts each section establishes. Do NOT treat its bullet-vs-table
+presentation choices as authoritative; re-choose the rendering per
+content shape in HTML's richer affordance space. If the markdown rendered
+13 requirements as a bulleted list, that does NOT mean HTML must render
+them as a list — ask whether 13 items sharing `ID + body` shape deserve
+a table.
+### Prose is authoritative
+When a visualization disagrees with the surrounding prose, the prose
+governs. If they diverge, the visualization is wrong.
+### Hyperlink the reference index
+When the doc has a Sources & References (or equivalent reference-index)
+section, hyperlink each entry to its canonical destination so readers
+can open it directly. A long bare-text list of paths and ticket IDs is
+the format's biggest unforced UX miss — the reader has to copy-paste
+every entry into a browser or IDE.
+Resolve the repo's GitHub URL once at compose time:
+```bash
+git remote get-url origin
+```
+Apply linking to three reference shapes:
+- **Repo-relative code/doc paths** (`services/foo.ts`,
+  `docs/solutions/bar.md`) → `<repo-url>/blob/main/<path>`.
+- **Named GitHub PRs/issues** (`PR #636`, `issue #1048`) →
+  `<repo-url>/pull/636` or `<repo-url>/issues/1048`.
+- **Named external trackers** (Linear `ESP-1705`, Jira `PROJ-123`) →
+  link only when the workspace URL is established in loaded context
+  (e.g., a `linear.app/<workspace>/...` URL appeared earlier in the
+  session or in `AGENTS.md`); otherwise leave as text.
+**Do not invent URLs.** If `origin` isn't a GitHub URL (GitLab,
+Bitbucket, internal host) and the equivalent main-tree URL pattern
+isn't obvious, leave entries as `<code>` text. If the external
+tracker workspace isn't established, leave as text. A broken or
+guessed link is worse than no link.
+**Scope: reference index only, not inline prose.** Inline `<code>`
+mentions of paths or PRs inside paragraph prose stay as code or text.
+Linking every mention would clutter; readers expect clickable jumps
+where the doc presents itself as a reference index.
+### Stable section anchors for unified plans
+<!--
+FNXC:CompoundEngineering 2026-06-27-22:35:
+FN-7149 keeps HTML plans as pinned single-file snapshots while allowing only parse5-backed DOM-safe ce-doc-review mutations. Stable section IDs remain the only anchors for in-place fixes; any ambiguity or parser instability must fall back to report-only instead of fabricating sections.
+-->
+When rendering a unified plan, every major logical section gets a stable
+anchor ID and visible heading text:
+| Logical section | Required id |
+|---|---|
+| Goal Capsule | `goal-capsule` |
+| Product Contract | `product-contract` |
+| Product Requirements | `product-requirements` |
+| Planning Contract | `planning-contract` |
+| Implementation Units | `implementation-units` |
+| Verification Contract | `verification-contract` |
+| Definition of Done | `definition-of-done` |
+| Appendix | `appendix` |
+Long HTML plans are agent-consumed as source text as often as they are read in
+a browser. Keep the heading text visible and adjacent to the `id`; do not rely
+on a nav link alone to carry the section name.
+### Text contrast is local
+Every text-on-background pairing must hold up on its own. A color that
+works for prose on the page background does not automatically work for
+a small label inside a tinted container. The most common violation:
+applying a generic "muted" text variable (calibrated for prose-on-bg) to
+secondary text inside an accent-soft / warn-soft / info-soft container.
+Test by reading each filled shape's labels at the rendered scale. If the
+subtitle or secondary text feels washed-out against the fill, the choice
+is wrong for that local context — pick a color from the same family as
+the fill (accent-text for accent-soft, etc.) or drop the muting entirely
+and rely on font-size and weight for hierarchy.
+### Body bold not colored by default
+Reserve accent text color for status chips, ID chips, links, and section
+borders. Do NOT color `<strong>` in body content by default. Bold weight
+already carries emphasis; applying accent color to every `<strong>` in a
+long list overwhelms the eye, especially in dark mode. CSS should leave
+`strong` at `color: inherit` unless a specific surface (status pill, ID
+chip) is being styled.
+### Chips and pills: uniform shape, no one-sided accent
+Status chips, ID chips, and metric pills in the same row share one shape
+— same border-radius, border weight, and fill treatment. Differentiate
+categories only by the chip's overall fill/text color (applied to the
+whole pill, like a soft-tint badge), never by an accent on one edge. A
+colored stripe or arc on a single side of a pill reads as broken and
+asymmetric — as if a border half-failed to render — so avoid it. The same
+holds for any element, not just chips: differentiate by a full tint, not
+a colored stripe on one edge. If an ID chip should stand out from metric
+chips, vary its fill/text color uniformly, not its edge treatment, and
+keep every chip in the row a visual set.
+### No JS framework runtimes
+A small inline `<script>` for active-section TOC tracking or anchor-
+permalink behavior is acceptable. React, Vue, Svelte, or any framework
+runtime is not. The single-file invariant doesn't permit framework
+bundles, and the artifact's longevity doesn't warrant a build dependency.
+## Section anatomy
+How section types commonly render in HTML. These are patterns, not
+contracts — the agent picks shapes that fit the content.
+- **Summary / Problem Frame** — semantic `<section>` with prose
+  paragraphs. Optionally precede with an eyebrow label (small-caps tag
+  above the title) for editorial polish.
+- **Requirements** — `<table>` is the default at 5+ uniform items;
+  bullets at smaller counts. Concern-grouping takes precedence over the
+  flat-table default: when requirements span distinct concerns, group them
+  under bold inline headers (or per-group sections) first, then apply the
+  5+ table default *within* each group rather than flattening the whole
+  section into one table. Each row has the R-ID as visible text in
+  its own column. Consider adding a "covered by" column for reverse
+  traceability when ID-anchored items have downstream references in
+  the same doc.
+- **Implementation Units** — repeating `<article>` cards with a stable
+  ID chip (visible "U1" text), a metadata strip (`<dl>` with field
+  labels and values for Goal, Files, Dependencies), and secondary
+  content (Approach, Test Scenarios, Verification, Patterns to Follow)
+  inside `<details>` collapsibles, **default-closed**. At 3+ units the
+  default-closed rule is load-bearing — rendering all units fully
+  expanded turns the doc into one continuous scroll where the reader
+  can't see the unit list at a glance. The metadata strip is the
+  primary always-visible surface; subsection labels (`<summary>`) are
+  clickable affordances for readers to expand on demand. A single unit
+  with no secondary content can skip `<details>` entirely; the rule
+  fires when content exists to hide. The `<dl>` strip is for *descriptive*
+  fields (Goal, Files, Dependencies). A *directive* field — `Execution
+  note` is the canonical case, carrying a procedural instruction the
+  implementer must act on (e.g. "start with a failing integration test") —
+  does not belong in the strip, where it renders as a passive pair styled
+  like a date and gets skimmed past. Render it as an advisory callout (see
+  Tinted callout cards) so its visual weight matches its actionability. The
+  test: descriptive value -> metadata pair; something the reader must act
+  on -> callout.
+- **Key Technical Decisions** — repeating cards with the decision ID,
+  bold decision title (often with inline code for technical
+  identifiers), and prose rationale. Flat cards (not collapsibles) —
+  these are reference material readers scan, not drill into.
+- **Risks** — cards with a color-coded status eyebrow (e.g., "RISK ·
+  MITIGATED" / "OPEN · DEFERRED FOLLOW-UP") and prose body. Communicate
+  status through the eyebrow's color plus an optional subtle full-card
+  tint — not a colored stripe on one edge (see "Chips and pills").
+- **Scope Boundaries** — callout cards distinguished (in-scope vs deferred
+  vs outside) by a colored eyebrow/label plus a subtle full-card tint when
+  the distinction is meaningful — not a one-edge colored stripe.
+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, quantitative
+comparison), HTML renders it as **inline SVG**. The agent picks the
+shape that conveys the content fastest — there is no fixed catalog of
+"approved" diagram types. If the content is quantitative comparison
+across categories, a bar chart is the right shape; if it's component
+relationships, a topology diagram; if it's process flow across
+participants, a swim lane; etc.
+**Conceptual diagrams are not wireframes.** The wireframe affordance below
+is scoped to *UI-shaped requirements* and is excluded for non-visual
+systems. That exclusion is about wireframes only —
+a brainstorm about a data model, schema, agent workflow, or migration is
+still free to use a conceptual diagram (a before/after field map, a
+source-of-truth fan-out, a state diagram). Don't let the wireframe
+exclusion suppress a conceptual diagram the content warrants.
+**Diagrams complement prose; they never replace it.** A diagram is an
+accelerant placed next to the prose it illustrates, not a substitute. The
+IDed prose stays complete and standalone — a reader who ignores every
+diagram still gets the full content in text, and a text-reading downstream
+agent (which does not parse SVG geometry) is never left with a relationship
+that exists only in the picture. This extends the prose-is-authoritative
+rule above: prose governs not only on disagreement but on completeness, so
+adding a diagram is not license to thin the prose it depicts.
+### Layout legibility for hand-authored SVG
+The agent designs SVG coordinates without rendering — layouts that look
+fine in source can collide in practice. Before emitting, trace each
+labeled arrow, each shape edge, and each text label:
+- **No stroke — arrow *or* shape edge/border — passes through a text
+  label.** If an arrow line/curve, or the border of a box, parallelogram,
+  or other shape, crosses a label's bounding box, the text reads as
+  struck-through and the stroke reads as terminating at the wrong element.
+  Fix by re-routing the arrow, moving the label clear of every edge, or
+  applying `paint-order: stroke fill` with a stroke color matching the
+  diagram background to halo the label. The halo width is a judgment call:
+  narrow enough not to bleed into glyph strokes (a halo whose width
+  approaches the glyph's own stroke width muddies the text color), wide
+  enough to mask the underlying stroke (at least its stroke width
+  plus a hairline). Verify by inspecting rendered text at the target
+  font size — if glyphs look thicker or more colored-toward-halo than
+  the same text outside the diagram, the halo is too wide.
+- **Labels inside skewed or rotated shapes sit in the shape's true
+  interior, not its bounding box.** A parallelogram, isometric face, or
+  rotated rect has an interior offset from its bounding box, so a
+  box-aligned (e.g. left-aligned) label spills past the slanted edge.
+  Inset the label to fall inside the actual shape — account for the
+  skew/rotation offset at the label's vertical position — or place it
+  outside the shape with a short leader. This is the usual failure in the
+  **stacked-layers idiom** (offset parallelograms implying z-order), where
+  per-layer labels left-aligned to the container both overflow the lower
+  layers and get crossed by the neighbouring layer's edge. Prefer
+  labelling each layer in its own un-overlapped region, or to the side of
+  the stack.
+- **Arrow labels sit adjacent to the arrow's midpoint** (typically
+  within ~10-15px above or beside the line they describe). A label
+  floating at the diagram's edge that readers have to trace back to an
+  arrow is broken — readers will misread.
+- **Avoid long curves that traverse the diagram** to connect a
+  component on one side to one on the other. If A and D need a labeled
+  connection across a multi-component layout, prefer reordering boxes
+  so A and D are adjacent, numbered step badges next to each
+  participant that the caption ties together, or a short
+  labeled-channel notation — rather than one curve crossing multiple
+  unrelated elements.
+- **Differentiate diagram shapes by geometry first, by fill semantics
+  second.** Geometry (diamond = decision, rect = step, oval =
+  start/end, parallelogram = data) carries the role unambiguously.
+  Fill semantics (accent-soft for highlighted path, warn-soft for
+  fallthrough) carry meaning. Resist introducing additional neutral-tint
+  tiers (a slightly-lighter grey to mark "decision shapes are different
+  from boxes") — when geometry already differentiates, an additional
+  luminance tier adds no information and creates fragility: small RGB
+  deltas survive native browser rendering but can be flattened or
+  inverted inconsistently by dark-mode extensions, accessibility
+  plugins, or printing.
+### Plan architecture diagrams are not directional sketches
+Do not add hedging captions or section preambles to plan SVG diagrams —
+phrases like "directional guidance for review, not implementation
+specification" do not belong on plan diagrams or on unit-card
+technical-design subsections. Plan diagrams render the same authoritative
+content as the surrounding prose; the prose-is-authoritative rule
+already governs disagreement. Hedging language is reserved for the
+wireframe affordance below, which carries a *required* directional
+caption because the wireframe is explicitly NOT a spec.
+## Wireframe mockups (requirements docs only)
+When a brainstorm requirement describes a user-facing visual surface (UI
+feature, screen layout, screen flow, component placement), the HTML
+rendering may include a wireframe mockup. The trigger is the
+**requirement**, not the document: any requirement (or requirements group)
+with a UI/layout shape can carry a wireframe, whether or not the brainstorm
+as a whole is "a visual product" — a backend-heavy brainstorm with one
+screen change still earns a wireframe for that requirement. It still applies
+to brainstorm **requirements** output — the requirements-only unified plan
+`ce-brainstorm` writes (now under `docs/plans/`), not an implementation-ready
+plan (`ce-plan`'s enriched output) — and only to UI-shaped requirements — a
+non-visual requirement (API design, data model, agent workflow,
+infrastructure) takes a conceptual diagram instead, not a
+wireframe.
+When a wireframe is included:
+- **Fidelity ceiling: wireframe, not mockup.** Gray boxes for layout
+  regions, text labels for content placeholders, intentional placeholder
+  copy (`[Product name]`, `[CTA label]`, `[user avatar]`). No
+  pixel-perfect colors, no exact typography choices, no specific
+  component-library references. The wireframe communicates spatial
+  arrangement and structure, not visual style.
+- **Static only.** Inline SVG or simple HTML/CSS for layout. No JS
+  interaction, no working form fields, no state changes, no live data.
+- **Anti-padding.** One wireframe per distinct visual concept.
+- **Mandatory directional caption.** Every wireframe carries an explicit
+  "directional, not the spec" note adjacent to it. Required wording (or
+  close paraphrase): *"Directional only — illustrates the intended
+  user-facing shape. Exact colors, spacing, copy, and component choices
+  are placeholders for review, not requirements."*
+Without this caption the wireframe risks being read as a binding visual
+spec, which the affordance is explicitly designed to avoid.
+## Affordance idioms
+Common HTML affordances the agent can reach for when content benefits.
+These are examples, not requirements — the agent picks what each
+artifact's content warrants. Other affordances not listed here are
+fine when the content suggests them.
+- **Sticky TOC sidebar with active-section indicator** — available when
+  the agent judges navigation will materially help and the
+  implementation is reliable: two-column layout on desktop, collapsed
+  to top-of-page on mobile, paired with a small inline
+  `IntersectionObserver` script that toggles `.active` on the matching
+  nav anchor. Trade-off: a broken sticky TOC (layout collisions,
+  active-section state drift, dark-mode CSS issues) is worse than a
+  static top-of-doc TOC. For most long docs, default-closed `<details>`
+  on repeating cards (see Implementation Units anatomy) already cuts
+  the visible scroll length enough that a static TOC works — reach for
+  sticky only when collapsibles alone don't solve the navigation
+  problem.
+- **Within-section sub-nav** for sections containing 6+ repeating cards
+  (Implementation Units, KTDs, Risks at large counts). A short list of
+  card-anchor links (`<ul>` of `<a href="#u1">U1. ...</a>`) rendered at
+  the top of the section gives readers a jump table — no JS needed.
+  Lower-complexity alternative to the sticky TOC for the specific case
+  of long card sections.
+- **Eyebrow labels** (small-caps tag above section titles) for
+  editorial polish, especially when section titles are narrative
+  rather than literal.
+- **Stats strip** at the top of the doc when the artifact has 3+
+  quantifiable signals worth surfacing at a glance.
+- **`<details>` + `<summary>`** for collapsible secondary content
+  inside repeating cards. All collapsibles start closed — `open`
+  attribute should not appear on any `<details>` inside repeating
+  cards by default.
+- **Side-by-side columns** for parallel content (Request / Response,
+  Before / After, Two alternatives).
+- **Tinted callout cards** for content that is "different in kind"
+  (Deferred, Open Questions, advisory notes, unit-level execution notes)
+  — a subtle full-card background tint plus a colored eyebrow/label
+  communicates kind at a glance. Avoid a colored stripe on one edge; tint
+  the whole card instead.
+## Agent-consumability rules
+Downstream agents that read HTML today (`ce-work`, `ce-doc-review` in
+DOM-safe-or-report-only mode, a skill re-reading its own prior artifact on a resume run,
+future consumers) reason over the HTML as text — the way they reason over
+markdown, not via DOM extraction or a script-style parse. `ce-doc-review`
+uses this consumable structure to produce findings and may mutate only through the FN-7149 DOM-safe helper (see
+opening note).
+These rules are why such a consumer can locate one item (a single
+requirement, unit, idea, or other ID-bearing entry) and reason over it from
+source alone — its title, every labeled field, and any diagram's meaning —
+with no hidden machine-readable copy to fall back on. The semantic structure
+*is* the extraction contract: it is what makes the single-source-of-truth
+invariant (no `data-*` or JSON metadata mirror) safe rather than lossy.
+Weakening it — `<article>` item boundaries collapsed into `<div>` soup, a
+field label demoted to an attribute, one item's content scattered across
+distant parts of the doc — breaks that reasoning even when the rendered page
+looks identical. Compose so semantic understanding is reachable in source:
+- **Use semantic HTML over `<div>` soup.** `<article>` per unit card,
+  `<dl>` for metadata pairs, `<table>` for tabular content, `<details>`
+  / `<summary>` for collapsibles, `<section>` for top-level doc
+  sections. Structure markers carry meaning to a text-reading agent.
+- **Render field labels as visible text, not as attributes.** Emit
+  `<dt>GOAL</dt><dd>...</dd>`, not `<dd data-field="goal">...</dd>`.
+  The label is the semantic anchor.
+- **Keep U-IDs, R-IDs, and similar as visible text** in headings and
+  table cells, not only as `id=""` attributes. The agent finds "U1." in
+  source the same way it finds "U1." in markdown.
+- **Match section heading vocabulary to what the section contract
+  defines.** When the section contract says "Implementation Units," the
+  HTML heading is "Implementation Units" — not "How we'll build it,"
+  even if the narrative version reads better. Section heading
+  vocabulary is the contract downstream consumers grep for. (Editorial
+  re-titles can appear as eyebrow labels, sub-headings, or visual
+  framing — but the load-bearing section heading matches the contract
+  name.)
+- **All semantic content lives in actual HTML text.** No CSS `::before
+  { content: "..." }` carrying meaning, no background images as
+  content, no semantic info that only renders. Whatever the agent sees
+  in source is what it knows.
+- **Stable structure is the public API.** Element types, the ID and
+  label scheme, and the field-label vocabulary do not break across
+  versions. Visual styling can change freely.
+### Canonical checklist representation
+<!--
+FNXC:CompoundEngineering 2026-06-28-08:30:
+FN-7159 defines one stable HTML checklist shape so ce-doc-review can DOM-safely repair malformed checklist markup instead of leaving all HTML checklist hygiene report-only. The checked state must be visible text, not an attribute-only fact, because downstream CE consumers read source text as the public API.
+-->
+Use exactly this shape for checklist content in CE HTML artifacts:
+```html
+<ul class="ce-checklist" aria-label="Checklist">
+  <li class="ce-checklist-item"><span class="ce-checklist-state">[ ]</span> <span class="ce-checklist-label">Unchecked item label</span></li>
+  <li class="ce-checklist-item"><span class="ce-checklist-state">[x]</span> <span class="ce-checklist-label">Checked item label</span></li>
+</ul>
+```
+- The container is a `<ul class="ce-checklist" aria-label="Checklist">`. An empty checklist is this same container with zero `<li>` children; do not invent an alternate empty-state wrapper.
+- Each item is exactly one direct `<li class="ce-checklist-item">` child containing exactly two visible spans in order: `<span class="ce-checklist-state">[ ]</span>` or `<span class="ce-checklist-state">[x]</span>`, then one ASCII space text node, then `<span class="ce-checklist-label">…</span>`.
+- The checked state is the visible text `[ ]` for unchecked or `[x]` for checked. Attribute-only state (`checked`, `aria-checked`, `data-checked`, CSS-generated checkmarks, icon-only checkmarks) is not canonical because semantic state must be readable in source text.
+- The label span contains the item label as visible text. Do not move label meaning into `title`, `aria-label`, `data-*`, SVG, or CSS. Inline semantic text markup inside the label is allowed only when it preserves the same visible words and does not carry checklist state.
+- Mixed-state checklists are represented by mixing `[ ]` and `[x]` item state spans. The item order is document order and is stable.
+- Already-canonical checklists are not rewritten. This exact element/class/state vocabulary is the public API for downstream consumers and DOM-safe repair; visual CSS may style it, but structure and visible state markers must remain stable across versions.
+For `ce-doc-review` DOM-safe repair, a checklist is **provable** only when the existing HTML is already this canonical shape or one of these unambiguous malformed variants whose canonical form can be derived without judgment:
+- Raw markdown checklist lines left as visible HTML body text, using `- [ ] label`, `- [x] label`, or `- [X] label` on one or more consecutive lines.
+- A `<ul>` or `<ol>` whose every direct `<li>` begins with visible `[ ]`, `[x]`, or `[X]` text followed by the item label.
+- A `<ul>` or `<ol>` whose every direct `<li>` has an `<input type="checkbox">` as its first non-whitespace child, with `checked` preserving checked state and the remaining visible text preserving the label.
+Anything else is malformed-or-ambiguous and stays report-only: ordinary lists, partial checklist lists, icon-only state, labels split across unrelated DOM regions, mixed checklist/non-checklist children, missing labels, duplicate hidden state copies that disagree with visible state, or content whose parse/serialize round trip is unstable. Repair may normalize only structure and visible state markers; it must not add, drop, reorder, or reword items.
+## Post-compose audit
+Before returning the artifact, scan it for common slips:
+- **Single self-contained file.** No companion `.css` / `.js` / `.svg`.
+- **No hidden machine-readable metadata copy.** No
+  `<script type="application/json">` frontmatter block, no `data-*`
+  attributes mirroring visible values, **no `<meta name="created">` /
+  `<meta name="origin">` etc. in `<head>`
+  duplicating the visible header**. Metadata lives in visible text;
+  one source of truth per value.
+- **All stable IDs** appear as both `id=""` and visible text.
+- **Section heading vocabulary** matches the section contract names
+  (downstream agents grep these).
+- **Source / composition signal** is present as a visible footer at
+  the bottom of the doc (composition timestamp + source identifier).
+- **Repeating cards with 3+ instances put secondary content inside
+  default-closed `<details>`.** Fully-expanded unit cards in a long
+  Implementation Units section is a failure mode — the reader can't see
+  the unit list at a glance. Verify by skimming the rendered units:
+  each `<article>` should render as its ID + title + metadata strip
+  with collapsibles below, not as one long block.
+- **Within-section sub-nav** is present for sections with 6+ repeating
+  cards.
+- **Body `<strong>`** is not colored with accent palette.
+- **No one-edge colored accent** (a colored stripe/arc on a single side)
+  on chips, pills, or callout cards — differentiate by uniform fill +
+  colored eyebrow/label instead. A one-sided stripe reads as
+  broken/unintentional; chips in a row must be a uniform visual set.
+- **`<details>`** inside repeating cards have no `open` attribute.
+- **Diagram labels** are legible — no arrow paths crossing text,
+  halo width appropriate for font size.
+- **Diagrams complement prose, not replace it.** Every relationship a
+  diagram conveys is also present in the surrounding IDed prose; no
+  content lives only in an SVG.
+- **No JS framework runtimes** included. Small inline `<script>` for
+  active-section TOC tracking or anchor-permalink behavior is the only
+  acceptable JS.
+- **Each heading level** is visually distinct from others and from
+  inline bold.
+- **No template placeholders** (`{skill}`, `<value>`, `[plan title]`)
+  leaked into output.
+- **No process exhaust** callouts in the artifact.