feat(ce-plan,ce-brainstorm): add output:html mode#826
Open
tmchow wants to merge 6 commits into
Open
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f95c05a338
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
added a commit
that referenced
this pull request
May 12, 2026
Two findings from the Codex review on #826. P1 — html-output.md said "Escape `<` as `<`", which is a no-op. The intended guidance is to escape `<` as `<` (the HTML entity) inside the JSON payload embedded in `<script type="application/json">`, so any frontmatter value containing the literal substring `</script>` cannot terminate the script tag. Browsers unescape when reading the script element's text content, so downstream JSON parsers see clean characters. The invariant test was loose enough to pass on either `<` or the word "escape"; tightened to require the literal entity AND require it to sit near a `<script>` reference. P2 — HTML composition in Phase 5.3.9 (ce-plan) and Phase 3 (ce-brainstorm) recomposed whenever an `.html` sibling was marked for re-render in Phase 0.1, even when pipeline mode forced `OUTPUT_FORMAT=md`. In automated contexts (LFG) that resume an existing plan with an HTML sibling, this would emit HTML, violating the explicit md-only pipeline rule and the ce-work consumption guarantee. The composition gate is now two conditions: (a) HTML wanted via CLI/config/sibling-re-render AND (b) not in pipeline mode. Both must hold. Same gate applies to mid-run re-renders triggered by HITL Proof resync. The plan body was also updated to match the corrected escape rule. Refs: #826
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a898b3eeff
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
added a commit
that referenced
this pull request
May 12, 2026
…after Proof pull Two follow-up findings from the Codex re-review of #826. P2 — Sibling-rerender suppression on explicit output:md. The prior fix gated HTML composition on (HTML wanted OR sibling marked) AND not-in-pipeline, but the sibling-marked branch still fired even when a user explicitly passed output:md on resume. That made it impossible to disable HTML emission once a plan had an .html sibling without manually deleting the sibling file, which contradicted the documented CLI arg > config > default precedence. Phase 0.0 now tracks OUTPUT_FORMAT_SOURCE alongside OUTPUT_FORMAT, with values cli / config / default / pipeline-forced. Phase 0.1 only marks the sibling for re-render when SOURCE=default — when neither an explicit CLI arg nor a config preference resolved. An explicit md choice (CLI or config) now beats sibling presence; users can drop back to markdown-only on resume without filesystem surgery. P2 — Recompose HTML after Proof pull. The localSynced:false and done_for_now branches in plan-handoff.md and ce-brainstorm/handoff.md offered a Pull workflow that updated the local markdown and re-ran ce-doc-review, but they didn't re-apply the HTML composition rule. The .html sibling could be stale in the same run after a successful pull, contradicting the recompose-after-markdown-mutations contract. Both branches now re-apply the HTML composition rule (gated by its two conditions) after the pull before re-rendering the menu, matching the localSynced:true branch behavior. Refs: #826
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9e565de2db
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
added a commit
that referenced
this pull request
May 12, 2026
… Proof in HTML mode Proof operates on markdown plans/requirements docs and cannot ingest HTML. The previous menu rendering presented option 4 (ce-plan) and option 3 (ce-brainstorm) as a single bullet containing both "Open in Proof" and "Open in browser" labels with an inline italic conditional. An agent reading that bullet could render both labels visibly, leaving an HTML-mode user with the option of picking Proof and getting markdown loaded in the editor unexpectedly. Splitting the conditional bullet into two separate option-N lines — each tagged with its `OUTPUT_FORMAT` precondition — gives the agent an unambiguous instruction: render exactly one. The mutual exclusion stays intact and the menu cap is still honored. Adds explicit "Proof operates on markdown" rationale to the prose so the why is reachable without skill redesign. Refs: #826
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 26e814ce25
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8b521043b1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
added a commit
that referenced
this pull request
May 12, 2026
… resolve webfont contradiction Two findings from the Codex re-review of #826. P2 — Menu gate / composition gate mismatch. The "Open in browser" menu option gated on OUTPUT_FORMAT=html, but the HTML composition step (Phase 5.3.9 in ce-plan, Phase 3 in ce-brainstorm) fires under a broader predicate: OUTPUT_FORMAT=html OR Phase 0.1 marked an existing .html sibling for re-render. The OUTPUT_FORMAT_SOURCE machinery added in the previous round preserved the explicit-md-beats-sibling rule but exposed this latent gap. A resume run with a .html sibling but OUTPUT_FORMAT=md (default-source) regenerated the HTML in Phase 3/5.3.9 — but the menu still surfaced "Open in Proof" and hid the fresh HTML the user just implicitly requested via sibling re-render. The menu gate now uses the same predicate as the composition gate (HTML wanted OR sibling-marked re-render), so resume runs surface the artifact they just produced. P2 — Webfont link contradiction in reference. The active-recall block said "Never emit a <link rel='stylesheet'> to an external sheet" while the Fallback default style section showed exactly that — a <link rel="stylesheet"> pointing to Google Fonts CSS. Both could not be right. The documented webfont exception ("CDN webfonts permitted only with offline-readable fallback stack") is the intended rule; the absolute prohibition was the bug. Qualified the rule to scope the prohibition to layout/typography stylesheets the doc cannot read offline, while explicitly permitting <link rel="stylesheet"> for CDN webfont CSS with the fallback condition stated nearby. Three new invariant tests pin both fixes — menu-gate-matches-composition-gate on both skills, and no-absolute-stylesheet-prohibition in the reference. Byte-for-byte parity preserved across ce-plan and ce-brainstorm html-output.md. Refs: #826
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a464837eae
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
added a commit
that referenced
this pull request
May 12, 2026
… </script> injection Two findings from the Codex re-review of #826. P1 — Wrong escape was shipped across two prior rounds. The reference said "escape `<` as ` & lt; `" and claimed browsers unescape it when reading the script tag's text content. That claim is factually incorrect: <script type="application/json"> is HTML raw-text content where HTML entities are NOT decoded. .textContent returns the literal four-character string '<', not '<', so any frontmatter value containing '<' is corrupted instead of round-tripping. The correct escape is the JSON Unicode escape `<`, which JSON parsers natively decode back to '<'. Replaced the escape rule with explicit literal-six-character `<` guidance, added an explicit warning against the HTML-entity approach naming the round-trip failure mode, and tightened the invariant test to require the literal `<` AND forbid future regression to `<`. P2 — Hard-invariant bullet still ambiguous on `<link rel="stylesheet">`. Line 22 said "No companion .css, .js, or .svg files" and an agent could reasonably read that as banning ALL `<link rel="stylesheet">`, even though the webfont exception was documented in the next bullet. Folded the exception into line 22 so an agent reading the no-companion-files rule cannot miss the webfont carve-out and the explicit boundary on what kinds of external stylesheets are permitted (CDN webfont CSS only — never layout, color, or design-system stylesheets). Refs: #826
tmchow
added a commit
that referenced
this pull request
May 12, 2026
…enu-rendering predicate Codex caught a real follow-on bug from the previous round. Menu rendering now uses the broader HTML-emitted predicate (OUTPUT_FORMAT=html OR Phase 0.1 marked a sibling for re-render), but the routing block was still gated on OUTPUT_FORMAT=html only. So a resume run that surfaces "Open in browser" via the sibling-rerender branch would fail to actually open the file when the user picked it — the routing's condition is false even though the menu showed the option. Aligned all three Open-in-browser routing surfaces (ce-plan SKILL.md inline, plan-handoff.md elaborate, ce-brainstorm handoff.md) to the same HTML-emitted predicate the menu uses. Same predicate as the composition gate. All three surfaces now consistent. Refs: #826
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0c8de465db
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 69c7be2b40
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b1187a56b9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
added a commit
that referenced
this pull request
May 14, 2026
…e prose Codex review (PR #826) flagged two precision bugs in the Phase 0.0 output-mode spec: 1. Step 2 said "if YAML contains `plan_output: md |html`", which would match commented examples like `# plan_output: html` shipped in the config template — silently flipping users into HTML on every run. Now the spec requires an ACTIVE (non-commented) key, names the shipped-template failure mode inline, and says comments must be ignored. 2. The unknown-output-value note hardcoded "defaulting to md", but step 1's drop-and-fall-through still lets step 2 (config) resolve to html or step 4 (pipeline) force md. The note now reflects the actual final resolved mode after steps 2-4, not a hardcoded value. Same fix on both ce-plan (plan_output) and ce-brainstorm (brainstorm_output) for parity. Tests pin the principle's presence (active-key requirement, final-mode-reflection) rather than specific phrasings.
tmchow
added a commit
that referenced
this pull request
May 14, 2026
Two findings from the Codex review on #826. P1 — html-output.md said "Escape `<` as `<`", which is a no-op. The intended guidance is to escape `<` as `<` (the HTML entity) inside the JSON payload embedded in `<script type="application/json">`, so any frontmatter value containing the literal substring `</script>` cannot terminate the script tag. Browsers unescape when reading the script element's text content, so downstream JSON parsers see clean characters. The invariant test was loose enough to pass on either `<` or the word "escape"; tightened to require the literal entity AND require it to sit near a `<script>` reference. P2 — HTML composition in Phase 5.3.9 (ce-plan) and Phase 3 (ce-brainstorm) recomposed whenever an `.html` sibling was marked for re-render in Phase 0.1, even when pipeline mode forced `OUTPUT_FORMAT=md`. In automated contexts (LFG) that resume an existing plan with an HTML sibling, this would emit HTML, violating the explicit md-only pipeline rule and the ce-work consumption guarantee. The composition gate is now two conditions: (a) HTML wanted via CLI/config/sibling-re-render AND (b) not in pipeline mode. Both must hold. Same gate applies to mid-run re-renders triggered by HITL Proof resync. The plan body was also updated to match the corrected escape rule. Refs: #826
tmchow
added a commit
that referenced
this pull request
May 14, 2026
…after Proof pull Two follow-up findings from the Codex re-review of #826. P2 — Sibling-rerender suppression on explicit output:md. The prior fix gated HTML composition on (HTML wanted OR sibling marked) AND not-in-pipeline, but the sibling-marked branch still fired even when a user explicitly passed output:md on resume. That made it impossible to disable HTML emission once a plan had an .html sibling without manually deleting the sibling file, which contradicted the documented CLI arg > config > default precedence. Phase 0.0 now tracks OUTPUT_FORMAT_SOURCE alongside OUTPUT_FORMAT, with values cli / config / default / pipeline-forced. Phase 0.1 only marks the sibling for re-render when SOURCE=default — when neither an explicit CLI arg nor a config preference resolved. An explicit md choice (CLI or config) now beats sibling presence; users can drop back to markdown-only on resume without filesystem surgery. P2 — Recompose HTML after Proof pull. The localSynced:false and done_for_now branches in plan-handoff.md and ce-brainstorm/handoff.md offered a Pull workflow that updated the local markdown and re-ran ce-doc-review, but they didn't re-apply the HTML composition rule. The .html sibling could be stale in the same run after a successful pull, contradicting the recompose-after-markdown-mutations contract. Both branches now re-apply the HTML composition rule (gated by its two conditions) after the pull before re-rendering the menu, matching the localSynced:true branch behavior. Refs: #826
tmchow
added a commit
that referenced
this pull request
May 14, 2026
… Proof in HTML mode Proof operates on markdown plans/requirements docs and cannot ingest HTML. The previous menu rendering presented option 4 (ce-plan) and option 3 (ce-brainstorm) as a single bullet containing both "Open in Proof" and "Open in browser" labels with an inline italic conditional. An agent reading that bullet could render both labels visibly, leaving an HTML-mode user with the option of picking Proof and getting markdown loaded in the editor unexpectedly. Splitting the conditional bullet into two separate option-N lines — each tagged with its `OUTPUT_FORMAT` precondition — gives the agent an unambiguous instruction: render exactly one. The mutual exclusion stays intact and the menu cap is still honored. Adds explicit "Proof operates on markdown" rationale to the prose so the why is reachable without skill redesign. Refs: #826
tmchow
force-pushed
the
tmchow/ce-plan-html-output
branch
from
ab81216 to
5ff5fcc
Compare
tmchow
added a commit
that referenced
this pull request
May 14, 2026
… resolve webfont contradiction Two findings from the Codex re-review of #826. P2 — Menu gate / composition gate mismatch. The "Open in browser" menu option gated on OUTPUT_FORMAT=html, but the HTML composition step (Phase 5.3.9 in ce-plan, Phase 3 in ce-brainstorm) fires under a broader predicate: OUTPUT_FORMAT=html OR Phase 0.1 marked an existing .html sibling for re-render. The OUTPUT_FORMAT_SOURCE machinery added in the previous round preserved the explicit-md-beats-sibling rule but exposed this latent gap. A resume run with a .html sibling but OUTPUT_FORMAT=md (default-source) regenerated the HTML in Phase 3/5.3.9 — but the menu still surfaced "Open in Proof" and hid the fresh HTML the user just implicitly requested via sibling re-render. The menu gate now uses the same predicate as the composition gate (HTML wanted OR sibling-marked re-render), so resume runs surface the artifact they just produced. P2 — Webfont link contradiction in reference. The active-recall block said "Never emit a <link rel='stylesheet'> to an external sheet" while the Fallback default style section showed exactly that — a <link rel="stylesheet"> pointing to Google Fonts CSS. Both could not be right. The documented webfont exception ("CDN webfonts permitted only with offline-readable fallback stack") is the intended rule; the absolute prohibition was the bug. Qualified the rule to scope the prohibition to layout/typography stylesheets the doc cannot read offline, while explicitly permitting <link rel="stylesheet"> for CDN webfont CSS with the fallback condition stated nearby. Three new invariant tests pin both fixes — menu-gate-matches-composition-gate on both skills, and no-absolute-stylesheet-prohibition in the reference. Byte-for-byte parity preserved across ce-plan and ce-brainstorm html-output.md. Refs: #826
tmchow
added a commit
that referenced
this pull request
May 14, 2026
… </script> injection Two findings from the Codex re-review of #826. P1 — Wrong escape was shipped across two prior rounds. The reference said "escape `<` as ` & lt; `" and claimed browsers unescape it when reading the script tag's text content. That claim is factually incorrect: <script type="application/json"> is HTML raw-text content where HTML entities are NOT decoded. .textContent returns the literal four-character string '<', not '<', so any frontmatter value containing '<' is corrupted instead of round-tripping. The correct escape is the JSON Unicode escape `<`, which JSON parsers natively decode back to '<'. Replaced the escape rule with explicit literal-six-character `<` guidance, added an explicit warning against the HTML-entity approach naming the round-trip failure mode, and tightened the invariant test to require the literal `<` AND forbid future regression to `<`. P2 — Hard-invariant bullet still ambiguous on `<link rel="stylesheet">`. Line 22 said "No companion .css, .js, or .svg files" and an agent could reasonably read that as banning ALL `<link rel="stylesheet">`, even though the webfont exception was documented in the next bullet. Folded the exception into line 22 so an agent reading the no-companion-files rule cannot miss the webfont carve-out and the explicit boundary on what kinds of external stylesheets are permitted (CDN webfont CSS only — never layout, color, or design-system stylesheets). Refs: #826
tmchow
added a commit
that referenced
this pull request
May 14, 2026
…enu-rendering predicate Codex caught a real follow-on bug from the previous round. Menu rendering now uses the broader HTML-emitted predicate (OUTPUT_FORMAT=html OR Phase 0.1 marked a sibling for re-render), but the routing block was still gated on OUTPUT_FORMAT=html only. So a resume run that surfaces "Open in browser" via the sibling-rerender branch would fail to actually open the file when the user picked it — the routing's condition is false even though the menu showed the option. Aligned all three Open-in-browser routing surfaces (ce-plan SKILL.md inline, plan-handoff.md elaborate, ce-brainstorm handoff.md) to the same HTML-emitted predicate the menu uses. Same predicate as the composition gate. All three surfaces now consistent. Refs: #826
tmchow
added a commit
that referenced
this pull request
May 14, 2026
…e prose Codex review (PR #826) flagged two precision bugs in the Phase 0.0 output-mode spec: 1. Step 2 said "if YAML contains `plan_output: md |html`", which would match commented examples like `# plan_output: html` shipped in the config template — silently flipping users into HTML on every run. Now the spec requires an ACTIVE (non-commented) key, names the shipped-template failure mode inline, and says comments must be ignored. 2. The unknown-output-value note hardcoded "defaulting to md", but step 1's drop-and-fall-through still lets step 2 (config) resolve to html or step 4 (pipeline) force md. The note now reflects the actual final resolved mode after steps 2-4, not a hardcoded value. Same fix on both ce-plan (plan_output) and ce-brainstorm (brainstorm_output) for parity. Tests pin the principle's presence (active-key requirement, final-mode-reflection) rather than specific phrasings.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5ff5fcca34
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
force-pushed
the
tmchow/ce-plan-html-output
branch
from
5ff5fcc to
540d40b
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 540d40ba99
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
force-pushed
the
tmchow/ce-plan-html-output
branch
from
d3099e3 to
83b8a5f
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 83b8a5ff78
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…format ref split 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.
tmchow
force-pushed
the
tmchow/ce-plan-html-output
branch
from
83b8a5f to
d35807c
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d35807c332
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- 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.
- 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.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 23d7d5775c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- 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.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9e98cf3b4e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- 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.
…ain plan dogfood
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.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f78736a820
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| If the plan already has a `deepened: YYYY-MM-DD` frontmatter field and there is no explicit user request to re-deepen, the fast path still applies the same confidence-gap evaluation — it does not force deepening. | ||
|
|
||
| **Resume preserves the existing artifact's format, except pipeline mode.** When resuming an existing plan, the resume run writes back in whatever format the existing artifact uses — markdown if the existing file is `.md`, HTML if it is `.html` — so a resume doesn't silently change the artifact shape. Explicit `output:` arguments on this run override (e.g., resuming an `.html` plan with `output:md` switches the artifact to markdown). Pipeline mode (LFG, any `disable-model-invocation` context) always wins per Phase 0.0: even when resuming an existing `.html` plan, pipeline runs force `OUTPUT_FORMAT=md` so downstream automation receives the markdown shape it expects. The resume rewrites the markdown file at the parallel path (`<plan-basename>.md`) and the original `.html` is left in place untouched. |
There was a problem hiding this comment.
The new resume rule allows .html plans to be resumed, but Phase 0.1 still treats “no YAML frontmatter” as a non-software signal and routes to references/universal-planning.md instead of the software fast path. Because HTML output intentionally has no YAML frontmatter, a resumed HTML software plan can be misclassified and skip Phase 5.3 confidence/deepening behavior (including the interactive deepen flow users explicitly request). This breaks core /ce-plan deepen ... behavior specifically for plans created with output:html.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
output:html/output:mdto 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). Output mode is exclusive — the skill writes either.mdOR.html, never both. Pipeline mode (LFG, anydisable-model-invocationcontext) forces markdown so automated downstream consumers always get a stable text shape.The PR also restructures the underlying references. The prescriptive
plan-template.md/requirements-capture.md/html-output.mdtrio is replaced with a two-layer architecture that separates WHAT the artifact contains from HOW it is rendered.What changed
Section contracts (WHAT).
plan-sections.mdandbrainstorm-sections.mddescribe outcome statements, a decide-whether-warranted off-ramp, a 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 logical groups, repo-relative paths, ASCII identifiers).Format-rendering refs (HOW).
markdown-rendering.mdandhtml-rendering.mddescribe hard invariants, the precedence stack for style preferences (conversation > stylesheet reference in loaded context > DESIGN.md > skill fallback), format principles, affordance idioms, agent-consumability rules, and a post-compose audit. Both files are byte-duplicated across ce-plan and ce-brainstorm (cross-skill convention; drift enforced by tests).HTML failure-mode defenses as principles, not pinned values.
<script type="application/json">copy that drifts.<span class="status">active</span>→completed), parallel to the markdown frontmatter convention.<strong>is not colored by default. Accent palette reserved for genuine accents.<script>for active-section tracking is acceptable.paint-order: stroke fillhalos — halo width is a judgment call (narrow enough not to bleed into glyph strokes, wide enough to mask underlying arrows), not a pinned number.ce-work HTML compatibility. ce-work globs both
.mdand.html, flips status visibly in HTML alongside the markdown frontmatter convention, and tolerates HTML wrapper noise when locating section regions by their contract name.Notes
The earlier sibling design (HTML + markdown emitted together,
OUTPUT_FORMAT_SOURCEtracking, mutual-exclusion menu gate, byte-duplicatedhtml-output.mdreference) is gone.The post-generation menu's option 4 is format-keyed: "Open in Proof" for markdown (Proof operates on markdown), "Open in browser" for HTML.
/ce-workstays the recommended option in both modes.Test plan
bun test: 1403 pass, 0 fail, 3784 expect() calls across 52 files.tests/skills/ce-plan-output-mode.test.tsandtests/skills/ce-brainstorm-output-mode.test.ts: argument-hint advertisesoutput:html; Phase 0.0 resolution lives inline; token-parsing convention names bothmode:andoutput:; active-key principle for config matching (ignores commented YAML); fallback note reflects final resolved mode; Phase 0.0 routes to the right format-rendering ref; post-generation menu offers format-keyed option 4; brainstorm→plan handoff does not auto-propagateoutput:; exclusivity is documented (noOUTPUT_FORMAT_SOURCE).tests/skills/html-output-invariants.test.ts: every failure-mode defense inhtml-rendering.mdholds — single-file invariant, no hidden JSON frontmatter, stable IDs anchored AND visible, editable status, precedence stack, active-recall, DESIGN.md discovery, markdown-is-content-not-design, prose-authoritative, local contrast, body<strong>uncolored, no JS framework, halo with judgment-call framing, geometry-first shape differentiation, plan diagrams not directional sketches, wireframe scope, agent-consumability rules, section heading vocabulary, post-compose audit.tests/skills/ce-brainstorm-section-order.test.ts: Key Decisions placement in the include-when-material catalog (after Problem Frame, before Actors / Key Flows / Scope Boundaries) and the catalog item's inline placement rationale.tests/compound-support-files.test.ts: byte-parity formarkdown-rendering.mdandhtml-rendering.mdacross ce-plan and ce-brainstorm.tests/skills/ce-plan-handoff-routing.test.ts: "Open in browser" added to the per-option inline-routing assertions.bun run release:validate: in sync, no drift.