- Make markdown-rendering.md status-flip rule per-contract (P2,
PRRT_kwDOP_gZVc6ESE1q): the prior unconditional "`status` is
editable -- downstream skills flip it (`active → completed`)" rule
contradicted brainstorm-sections.md's just-landed no-status-lifecycle
semantic. Rewrote the bullet to condition on whether the section
contract defines a status field with a lifecycle: plans do (ce-work
flips active → completed); brainstorms don't (no flip, referenced via
the plan's origin:). Synced byte-identical to the ce-plan copy per
the cross-skill drift convention.
- Fix HTML plan resume deepening (P1, PRRT_kwDOP_gZVc6CuitN): Phase 0.1
in ce-plan/SKILL.md now routes by extension first. `.html` plans always
short-circuit to Phase 5.3 (software fast path) since the html-rendering
invariant forbids YAML and the visible header carries equivalent
metadata; `.md` plans retain the frontmatter-based split.
- Define plan frontmatter schema in section contract (P2,
PRRT_kwDOP_gZVc6DDjiV): plan-sections.md adds a "Plan metadata fields"
subsection naming required (title/type/status/date) and optional but
well-known (origin/deepened) fields with their downstream semantics
(resume fast-path, ce-work status flip, deepening tracking, HITL
origin tracing).
- Make brainstorm closing-summary path format-aware (P2,
PRRT_kwDOP_gZVc6DnLL6): handoff.md Phase 4.3 templates now use
`<absolute path to requirements doc>` placeholder matching Phase 4.1,
with a substitution note covering both md and html extensions.
- Resolve HTML review contradiction (P2, PRRT_kwDOP_gZVc6DnLMA):
plan-handoff.md early prose rewritten to align with the later stance
-- HTML free-form review is declined with a "switch to output:md"
prompt. Whole file presents one stance now.
- Define brainstorm frontmatter schema in section contract (P2,
PRRT_kwDOP_gZVc6Dn8vZ): brainstorm-sections.md adds a "Brainstorm
metadata fields" subsection naming required (date, topic) fields with
filename and resume-detection semantics, plus an explicit
status-flip-does-not-apply call-out to head off conflation with the
plan-side mechanic.
Three new tests pin the contracts.
A real nugget-demographics plan HTML rendered its Sources & References
section as 9 bare code paths, 4 doc paths, 2 GitHub PR mentions, and a
Linear ticket — none hyperlinked. The reader has to copy-paste every
entry into a browser or IDE to use it. Bare text references are the
HTML format's biggest unforced UX miss: a doc reading like a reference
index loses the format's main affordance over markdown.
New Format-principles rule: hyperlink the reference index. Resolves the
repo's GitHub URL once at compose time from `git remote get-url origin`
and applies linking to three reference shapes:
- Repo-relative code/doc paths → `<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, Jira) → linked only when the
workspace URL is established in loaded context; otherwise text
Two constraints prevent the rule from going crazy:
- Do not invent URLs. If origin isn't GitHub or the tracker workspace
isn't established, leave entries as text. A broken or guessed link
is worse than no link.
- Scope: reference index only. Inline <code> mentions of paths or PRs
in paragraph prose stay as code — linking every mention clutters.
One new test pins the principle with five assertions: rule presence,
the `git remote get-url origin` resolution, the `blob/main` URL shape,
the URL-invention prohibition, and the reference-index-only scope.
A realistic Dembrandt-extracted DESIGN.md (every.to, Google design-token
spec with YAML frontmatter) carried 53 typography tokens sized 12-52px —
marketing-page scale. A naive agent reading the spec would pick text-1
(52px Signifier) for headings and text-19 (20px) for body, producing a
plan doc with text 25-150% larger than comfortable doc-reading size.
The existing scope-mismatch rule covers product-UI colors and components
but not typography sizes. This adds the parallel rule on the size axis:
use DESIGN.md's family / weight / OpenType feature assignments (these
carry the design language) and pick the agent's own size scale
appropriate to long-form doc reading (body ~14-16px, headings ~1.2-1.6x
body). Apply DESIGN.md sizes literally only when the tokens are
clearly doc-scaled.
Category-level guidance, no key enumeration — the agent navigates the
DESIGN.md schema with its own semantic understanding. Test added.
Reviewing a real product DESIGN.md (every.to brand tokens) exposed three
failure modes the current binary present/absent rule doesn't cover:
1. **Scope mismatch.** A DESIGN.md aimed at marketing-site product UI
names page-surface colors (e.g., #c0f0fb brand cyan), button states,
and input borders that are tied to *that* product surface, not to a
generic doc. A naive agent could apply the product surface color as
every plan-doc's page background. Failure mode: every plan looks like
it's on the marketing site.
2. **Partial coverage.** Real DESIGN.md files cover a subset (colors but
no spacing; typography but no elevation). The binary present/absent
rule implies the agent needs a complete file before honoring any of
it. In practice, agent should use what's there and fall through for
what isn't.
3. **Named fonts without fetchable source.** "Signifier", "Every", and
other brand fonts have no CDN endpoint. The existing webfont-fallback
rule only covers CDN cases. Agent should treat the name as a hint
about design intent (serif vs sans vs mono, weight) and emit a
system-font stack — not link to an external stylesheet (breaking the
single-file invariant) and not ignore the hint entirely.
New DESIGN.md discovery subsection: "DESIGN.md is a partial override,
not all-or-nothing." Three named failure modes with explicit guidance
on what to extract (principle) vs what to skip (literal product-UI
value), how to handle partial coverage, and how to fall back on
unfetchable named fonts.
Three new tests pin each principle.
Reverting the previous commit's promotion of sticky TOC from "affordance
idiom" to "expected for substantial docs." A sticky TOC is the highest-
complexity affordance in the reference — IntersectionObserver, two-column
layout, mobile collapse, active-section state — and a broken
implementation is materially worse than a working static TOC. Promoting
it to load-bearing creates pressure to ship even when the agent can't
get all the pieces right.
The default-closed <details> rule (kept) does most of the navigation work
the sticky TOC was meant to address. With units collapsed, an 8-unit
section renders as ~20 lines rather than ~400, so a static top-of-doc
TOC actually works at that scale.
What stays:
- Within-section sub-nav for sections with 6+ repeating cards (no JS, no
layout complexity — just <ul> of anchor links).
- Default-closed <details> on repeating cards at 3+ instances.
- Status as <span class="status">, no <meta> tag duplication, source/
composition footer, all other audit checks.
What changes:
- Sticky TOC bullet rewritten as an available affordance with explicit
trade-off framing (broken sticky > working static, reach for it only
when collapsibles alone don't solve the problem).
- Post-compose audit drops the sticky-TOC-when-substantial check.
- The matching test is removed; the audit-checks test stops asserting
the sticky-TOC line.
The 2026-05-17 supply-chain hardening HTML plan exposed five gaps where
soft "convention" / "affordance idiom" guidance failed to fire:
- Status rendered as `<dd>active</dd>` inside the header `<dl>`, breaking
ce-work's selector-based flip mechanic.
- `<meta name="status">` / `<meta name="created">` / `<meta name="origin">`
tags duplicated the visible header values — a hidden-metadata form the
prior rule didn't explicitly name.
- 8 Implementation Units rendered fully expanded with no `<details>`
collapsibles, turning the unit section into one long scroll.
- 823-line doc with 11 top-level sections rendered a static top-of-doc TOC
that disappeared on scroll.
- Sources & Research closed the doc with no staleness footer.
- No within-section sub-nav for the 8-unit Implementation Units section.
Promotes these from soft to load-bearing:
- Editable status: split into its own hard invariant, names the
`<span class="status">{value}</span>` shape as the contract and the
failure modes it prevents (header `<dl>`, `<meta>`, plain visible text).
- Hidden metadata ban: explicitly enumerates `<meta name="...">` alongside
the existing `<script type="application/json">` and `data-*` forms.
- Implementation Units anatomy: default-closed `<details>` is now load-
bearing at 3+ units, with rationale (can't see unit list at a glance).
- Sticky TOC + active-section indicator: promoted from "affordance idiom"
to "expected for substantial docs (5+ sections OR ~400+ lines), not
optional."
- Within-section sub-nav: new affordance for sections with 6+ repeating
cards.
- Source / composition signal: invariant now includes a concrete
`<footer class="composition-signal">` example shape so the agent knows
what to emit.
Post-compose audit grows six checks matching each new load-bearing rule.
Tests pin every new rule with a regex against the reference; byte-parity
across ce-plan and ce-brainstorm copies is unchanged.
- Gate ce-doc-review option for brainstorm HTML mode (P1, PRRT_kwDOP_gZVc6CgO1O):
Mirror the ce-plan-side gating onto ce-brainstorm/references/handoff.md.
Option 2 ("Agent review of requirements doc with ce-doc-review") is hidden
when OUTPUT_FORMAT=html with a one-line note explaining the limitation, the
Phase 4 option-count guidance enumerates the new hide condition, and the
post-review nudge is suppressed in HTML mode so it can't point at a missing
action.
- Update output:html user-facing docs for exclusive artifact mode (P2,
PRRT_kwDOP_gZVc6CgDS5): plugins/compound-engineering/README.md skill
rows for ce-brainstorm/ce-plan, plus docs/skills/ce-plan.md and
docs/skills/ce-brainstorm.md argument tables. Replace "alongside the
markdown" with the actual behavior — md OR html, never both — and
surface the pipeline-mode override.
- Pipeline mode wins over resume format preservation (P2, PRRT_kwDOP_gZVc6Cf8ZB):
Phase 0.1's "resume preserves existing artifact format" rule now defers to
Phase 0.0's pipeline override. Headless resumes of an .html plan force
OUTPUT_FORMAT=md so downstream automation gets markdown as expected. Same
clarification on ce-brainstorm's resume rule.
- Gate Phase 5.3.8 ce-doc-review behind OUTPUT_FORMAT=md (P1, PRRT_kwDOP_gZVc6CdWU9): ce-doc-review's walkthrough applies markdown-only mutations (## heading inserts, single-file md edits), so routing HTML plans through it would corrupt the artifact. HTML runs now emit a skipped envelope, surface a clear "ce-doc-review is markdown-only today" line above the menu, and hide the "Run deeper doc review" option.
- Extend ce-plan upstream-brainstorm discovery to match both *-requirements.md and *-requirements.html (P2, PRRT_kwDOP_gZVc6CdWVB) so brainstorm_output: html artifacts are auto-discovered at Phase 0.2 and referenced at Phase 5.1.5.
- Rewrite config-template.yaml output-format comments for exclusive mode (P2, PRRT_kwDOP_gZVc6CfVZj): no sibling, pipeline forces md.
- Sync byte-duplicated html-rendering.md across ce-plan and ce-brainstorm.
Adds an `output:html` / `output:md` argument to ce-plan and ce-brainstorm so
the agent emits the artifact as a single self-contained HTML file when the
user wants a rendered surface (TOC, diagrams, collapsibles) instead of
markdown. Output mode is exclusive — the skill writes either `.md` OR
`.html`, never both. Pipeline mode forces markdown so automated downstream
consumers always get a stable text shape.
Replaces the prescriptive template files with a two-layer reference
architecture:
- **Section contract per skill** (`plan-sections.md`, `brainstorm-sections.md`)
describes WHAT the artifact contains: outcome statements, a decide-whether-
warranted off-ramp, hard floor of required sections, an include-when-
material catalog (Key Decisions placed early as framing choices), agent
agency above the floor, and ID/content rules (continuous R-IDs across
groups, repo-relative paths, ASCII identifiers).
- **Format-rendering ref per format** (`markdown-rendering.md`,
`html-rendering.md`, byte-duplicated across ce-plan and ce-brainstorm)
describes HOW to render the contract in that format: hard invariants,
precedence stack for style preferences, format principles, affordance
idioms, agent-consumability rules, and a post-compose audit.
The HTML reference teaches failure-mode defenses as principles, not pinned
values: local text contrast (defends against muted-on-tinted washout),
body `<strong>` uncolored by default, no JS framework runtimes, paint-order
halo on diagram labels (width is a judgment call), geometry-first shape
differentiation, plan diagrams are not directional sketches, and a
single-source-of-truth rule (no hidden `<script type="application/json">`
metadata copy — metadata is visible text only). Stable IDs appear as both
anchor IDs and visible text so downstream agents (ce-work, ce-doc-review)
can scan an HTML plan the same way they scan markdown.
ce-work is updated to glob both formats, flip status visibly in HTML
(`<span class="status">active</span>` → `completed`) alongside the markdown
frontmatter convention, and tolerate HTML wrapper noise when locating
section regions by their contract name.
Tests pin the architecture: byte-parity across the two rendering refs,
exclusivity of output mode (no `OUTPUT_FORMAT_SOURCE`, format-keyed option 4
in the post-generation menu), and the failure-mode defenses in
html-rendering.md.
Trevin Chow