From 7ebf58ee3bd46d1593c6221e033c4cf0dce35ad9 Mon Sep 17 00:00:00 2001 From: gsxdsm Date: Sat, 27 Jun 2026 18:33:02 -0700 Subject: [PATCH] FN-7147: add report-only HTML CE doc review Enable CE document review to inspect HTML artifacts without mutating generated plans. - Expand ce-doc-review guidance to accept markdown and HTML plan artifacts, keeping autofix/write-back only for markdown. - Update ce-plan and brainstorm handoffs so HTML plans route through report-only findings instead of skipped-review envelopes. - Add regression coverage that rejects legacy HTML-skip wording across the edited CE review surfaces. - Document the compound-engineering workflow behavior and add the release changeset. Files changed: .changeset/fn-7147-html-aware-ce-doc-review.md | 7 ++ docs/workflow-editor.md | 2 +- docs/workflow-steps.md | 4 +- .../src/__tests__/ce-doc-review-html-mode.test.ts | 81 ++++++++++++++++++++++ .../src/skills/ce-brainstorm/references/handoff.md | 26 ++++--- .../ce-brainstorm/references/html-rendering.md | 20 +++--- .../src/skills/ce-doc-review/SKILL.md | 37 ++++++---- .../skills/ce-ideate/references/html-rendering.md | 20 +++--- .../src/skills/ce-plan/SKILL.md | 25 ++++--- .../skills/ce-plan/references/html-rendering.md | 18 ++--- .../src/skills/ce-plan/references/plan-handoff.md | 37 +++++----- 11 files changed, 196 insertions(+), 81 deletions(-) Fusion-Task-Id: FN-7147 Fusion-Task-Lineage: 1f710dd9-ced7-4026-bc74-55a4160cb1bd Co-authored-by: Fusion (runfusion.ai) --- .../fn-7147-html-aware-ce-doc-review.md | 7 ++ docs/workflow-editor.md | 2 +- docs/workflow-steps.md | 4 +- .../__tests__/ce-doc-review-html-mode.test.ts | 81 +++++++++++++++++++ .../ce-brainstorm/references/handoff.md | 26 +++--- .../references/html-rendering.md | 20 ++--- .../src/skills/ce-doc-review/SKILL.md | 37 ++++++--- .../ce-ideate/references/html-rendering.md | 20 ++--- .../src/skills/ce-plan/SKILL.md | 25 +++--- .../ce-plan/references/html-rendering.md | 18 ++--- .../skills/ce-plan/references/plan-handoff.md | 37 +++++---- 11 files changed, 196 insertions(+), 81 deletions(-) create mode 100644 .changeset/fn-7147-html-aware-ce-doc-review.md create mode 100644 plugins/fusion-plugin-compound-engineering/src/__tests__/ce-doc-review-html-mode.test.ts diff --git a/.changeset/fn-7147-html-aware-ce-doc-review.md b/.changeset/fn-7147-html-aware-ce-doc-review.md new file mode 100644 index 0000000000..a8f9680bb0 --- /dev/null +++ b/.changeset/fn-7147-html-aware-ce-doc-review.md @@ -0,0 +1,7 @@ +--- +"@runfusion/fusion": minor +--- + +summary: CE HTML plans and brainstorm docs now get report-only ce-doc-review instead of being skipped. +category: feature +dev: Updates bundled Compound Engineering ce-doc-review handoffs so HTML runs review without autofix/write-back. diff --git a/docs/workflow-editor.md b/docs/workflow-editor.md index 93a6320232..71f83ac1e4 100644 --- a/docs/workflow-editor.md +++ b/docs/workflow-editor.md @@ -134,7 +134,7 @@ Fusion ships built-in workflows as read-only references: - `builtin:coding` — the default coding lifecycle and fallback for tasks without a workflow selection. - `builtin:quick-fix` — a short path for trivial or no-commit/decision work. - `builtin:review-heavy` — a standard execute/review/merge path with an additional gated security review. -- `builtin:compound-engineering` — a plugin-gated Compound Engineering pipeline: `/ce-plan` writes the CE plan doc, optional `ce-doc-review` can pressure-test markdown plans, `/ce-work` implements, `/ce-code-review` gates merge, and autoMerge-off projects route through the CE PR/feedback skills before Fusion's manual merge seam. +- `builtin:compound-engineering` — a plugin-gated Compound Engineering pipeline: `/ce-plan` writes the CE plan doc, optional `ce-doc-review` can pressure-test plans (markdown gets autofix/Open Questions write-back; HTML is report-only with no mutation), `/ce-work` implements, `/ce-code-review` gates merge, and autoMerge-off projects route through the CE PR/feedback skills before Fusion's manual merge seam. - `builtin:stepwise-coding` — a graph variant that models per-step parse, execute, review, and rework structure. - `builtin:design` — a UI-heavy work path with a gated design/UX review before standard review and merge. diff --git a/docs/workflow-steps.md b/docs/workflow-steps.md index aaf602c0c0..785bc16c1c 100644 --- a/docs/workflow-steps.md +++ b/docs/workflow-steps.md @@ -45,7 +45,7 @@ Decision-only or investigation tasks can also declare `noCommitsExpected` / `**N | Quick fix | `builtin:quick-fix` | Short path for trivial or no-commit/decision work; omits the standard review stage. | | Review-heavy | `builtin:review-heavy` | Standard execute/review/merge path with an additional gated security review. | | Marketing | `builtin:marketing` | Content pipeline with custom Ideation, Backlog, Drafting, Editorial review, Published, and Archived columns plus structured marketing brief/draft/editorial prompts; drafts are persisted as task documents for review while the workflow reuses standard lifecycle traits and merge primitives. | -| Compound engineering | `builtin:compound-engineering` | Plugin-gated CE workflow that invokes `/ce-plan`, optional advisory `ce-doc-review`, `/ce-work`, merge-blocking `/ce-code-review`, CE PR/feedback skills, Fusion merge, and learnings capture. | +| Compound engineering | `builtin:compound-engineering` | Plugin-gated CE workflow that invokes `/ce-plan`, optional advisory `ce-doc-review` (markdown autofix; HTML report-only), `/ce-work`, merge-blocking `/ce-code-review`, CE PR/feedback skills, Fusion merge, and learnings capture. | | Stepwise coding | `builtin:stepwise-coding` | Graph-executor workflow that models per-step parse/execute/review/rework explicitly. | | Design | `builtin:design` | UI-heavy work path that implements, persists a user-facing design preview task document, runs a gated design/UX review, then performs the standard review and merge. | | PR lifecycle | `builtin:pr-workflow` | Reusable PR lifecycle graph fragment (create PR → await review → respond → gate → merge); it is a fragment, not directly selectable as a task workflow. | @@ -140,7 +140,7 @@ The default built-in catalog entry `builtin:coding` is backed by the canonical ` `builtin:marketing` is a non-coding content workflow with marketing-specific columns (`ideation`, `backlog`, `drafting`, `editorial-review`, `published`, `archived`) and prompt seams for content brief, draft, and editorial review. Its draft stage saves the primary content deliverable as a task document for human review, while the workflow uses the same lifecycle traits (`intake`, `hold`, `wip`, `merge-blocker`, `human-review`, `complete`, `archived`) and the same merge-gate/branch-group/merge-attempt primitive region as coding workflows, so scheduler, capacity, review blocking, and merge orchestration behavior remain standard. -`builtin:compound-engineering` is plugin-gated by `fusion-plugin-compound-engineering`. Its graph runs `/ce-plan` first and expects the CE plan document artifact under `docs/plans/`; an optional default-off `ce-doc-review` advisory step can then review markdown plans without blocking merge. Implementation runs `/ce-work`, merge-blocking code review runs `/ce-code-review`, and the PR lane runs `/ce-commit-push-pr` then `/ce-resolve-pr-feedback` before Fusion's native merge seam. When project `autoMerge` is off, that merge seam no-ops into manual review instead of forcing an unattended board merge, so the CE-created pull request remains the human merge path. +`builtin:compound-engineering` is plugin-gated by `fusion-plugin-compound-engineering`. Its graph runs `/ce-plan` first and expects the CE plan document artifact under `docs/plans/`; an optional default-off `ce-doc-review` advisory step can then review plans without blocking merge. Markdown plans retain safe autofix and Append-to-Open-Questions behavior, while HTML plans run in report-only mode with no in-file mutation. Implementation runs `/ce-work`, merge-blocking code review runs `/ce-code-review`, and the PR lane runs `/ce-commit-push-pr` then `/ce-resolve-pr-feedback` before Fusion's native merge seam. When project `autoMerge` is off, that merge seam no-ops into manual review instead of forcing an unattended board merge, so the CE-created pull request remains the human merge path. During triage/planning sessions, agents can call `fn_workflow_list` to discover available built-in and custom workflows and read their descriptions before routing work. They can call `fn_workflow_select` only when the user explicitly requested a workflow or when selecting a workflow for a task they created, and they can pass `workflow_id` when creating child tasks with `fn_task_create`; decision-only or investigation tasks can also set `noCommitsExpected` / `**No commits expected:** true` when no code changes are expected. The built-in triage thresholds, decision-only verb list, and default routing IDs are workflow-native typed settings resolved from the selected workflow. diff --git a/plugins/fusion-plugin-compound-engineering/src/__tests__/ce-doc-review-html-mode.test.ts b/plugins/fusion-plugin-compound-engineering/src/__tests__/ce-doc-review-html-mode.test.ts new file mode 100644 index 0000000000..2830674892 --- /dev/null +++ b/plugins/fusion-plugin-compound-engineering/src/__tests__/ce-doc-review-html-mode.test.ts @@ -0,0 +1,81 @@ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const skillsRoot = fileURLToPath(new URL("../skills/", import.meta.url)); + +function readSkill(relativePath: string): string { + return readFileSync(join(skillsRoot, relativePath), "utf8"); +} + +function expectNoLegacyHtmlSkipLanguage(surfaces: Record): void { + const forbidden = [ + /ce-doc-review is markdown-only today/i, + /Requirements review unavailable in output:html mode/i, + /review unavailable for HTML/i, + /ce-doc-review is skipped/i, + /skipped_reason:\s*output_format_html/i, + /not currently an HTML consumer/i, + /not a current HTML consumer/i, + /skips? (?:the )?(?:5\.3\.8 )?(?:doc-review|document-review|ce-doc-review)[^\n.]*HTML/i, + /HTML[^\n.]*skips? (?:the )?(?:doc-review|document-review|ce-doc-review)/i, + ]; + + for (const [name, content] of Object.entries(surfaces)) { + for (const pattern of forbidden) { + expect(content, `${name} must not contain legacy HTML-skip language matching ${pattern}`).not.toMatch(pattern); + } + } +} + +/* +FNXC:CompoundEngineering 2026-06-27-18:31: +FN-7147 replaces the CE document-review HTML skip with a non-mutating report-only path. This guard reads the prompt-executed bundled skill text directly so future upstream refreshes cannot leave one handoff saying “skip HTML” while another routes HTML to review. +*/ +describe("ce-doc-review HTML report-only mode", () => { + const docReviewSkill = readSkill("ce-doc-review/SKILL.md"); + const planSkill = readSkill("ce-plan/SKILL.md"); + const planHandoff = readSkill("ce-plan/references/plan-handoff.md"); + const brainstormHandoff = readSkill("ce-brainstorm/references/handoff.md"); + + it("documents that HTML doc review is report-only and non-mutating", () => { + expect(docReviewSkill).toMatch(/HTML artifacts? (?:are reviewed|receive)[^\n.]*report-only/i); + expect(docReviewSkill).toMatch(/same document-quality and persona-lens checks/i); + expect(docReviewSkill).toMatch(/apply no fixes of any class/i); + expect(docReviewSkill).toMatch(/Append-to-Open-Questions write-back that inserts markdown/i); + expect(docReviewSkill).toMatch(/HTML artifacts are reviewed in report-only mode and are never mutated/i); + }); + + it("routes ce-plan HTML artifacts through report-only review instead of a skipped envelope", () => { + expect(planHandoff).toMatch(/HTML plans use `ce-doc-review` in report-only mode/i); + expect(planHandoff).toMatch(/applied_fixes_count = 0/i); + expect(planHandoff).toMatch(/no `skipped_reason` field/i); + expect(planHandoff).toMatch(/Free-form requests for review[^\n]*HTML plan in report-only mode/i); + }); + + it("keeps ce-plan SKILL.md aligned with report-only HTML review", () => { + expect(planSkill).toMatch(/For HTML plans \(`OUTPUT_FORMAT=html`\)[^\n]*still runs ce-doc-review/i); + expect(planSkill).toMatch(/HTML reviews are report-only and do not offer apply or Open Questions write-back/i); + expect(planSkill).toMatch(/Document review is mandatory for markdown plans and report-only for HTML plans/i); + }); + + it("shows ce-brainstorm requirements review for HTML in report-only mode", () => { + expect(brainstormHandoff).toMatch(/Shown when a unified plan artifact exists/i); + expect(brainstormHandoff).toMatch(/Under `OUTPUT_FORMAT=html`, run `ce-doc-review` in report-only mode/i); + expect(brainstormHandoff).toMatch(/This nudge applies to markdown and HTML artifacts/i); + expect(brainstormHandoff).toMatch(/For `\.html` artifacts, state that the review is report-only/i); + }); + + it("removes old HTML markdown-only skip language from all edited review surfaces", () => { + expectNoLegacyHtmlSkipLanguage({ + "ce-doc-review/SKILL.md": docReviewSkill, + "ce-plan/SKILL.md": planSkill, + "ce-plan/references/plan-handoff.md": planHandoff, + "ce-brainstorm/references/handoff.md": brainstormHandoff, + "ce-brainstorm/references/html-rendering.md": readSkill("ce-brainstorm/references/html-rendering.md"), + "ce-ideate/references/html-rendering.md": readSkill("ce-ideate/references/html-rendering.md"), + "ce-plan/references/html-rendering.md": readSkill("ce-plan/references/html-rendering.md"), + }); + }); +}); diff --git a/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/handoff.md b/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/handoff.md index ed9545bb8d..1d12e51b09 100644 --- a/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/handoff.md +++ b/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/handoff.md @@ -8,9 +8,8 @@ unified plan is written. #### 4.1 Present Next-Step Options The Phase 4 menu's visible option count varies by state: no unified plan -artifact hides the review and Proof options, `OUTPUT_FORMAT=html` also hides -the review option (ce-doc-review is markdown-only today), unresolved `Resolve -Before Planning` hides both `Create the implementation plan` and `Ship it +artifact hides the review and Proof options, unresolved `Resolve Before +Planning` hides both `Create the implementation plan` and `Ship it autonomously with lfg`, and the lfg option is also hidden for non-software brainstorms (`execution` other than `code`). Count the visible options for the current state and choose the rendering mode accordingly: @@ -54,14 +53,18 @@ Present only the options that apply. Renumber so visible options stay contiguous 1. **Create the implementation plan** *(recommended)* - Hand off to `ce-plan` and sharpen the requirements into a complete, testable plan. Shown only when `Resolve Before Planning` is empty. 2. **Ship it autonomously with `lfg`** - Hand the requirements to the full autonomous pipeline: `lfg` plans (`ce-plan`), implements, simplifies, runs independent code review and applies the fixes, opens a PR, and watches CI to green — hands-off, no check-ins. It plans first (unlike a raw `/goal` straight from requirements), so it's the safer autonomous path. Best when you trust the requirements and want it built and shipped without steering. **Opens a PR and pushes a branch.** Shown only for software brainstorms (`execution: code`) with `Resolve Before Planning` empty **and a unified plan artifact was created** — `lfg` hands `ce-plan` that artifact path in pipeline mode and cannot prompt, so with no artifact (e.g. a brief-alignment brainstorm that skipped doc creation per the "Decide whether a doc is warranted" rule) there is nothing to enrich; offer option 1 instead, which can plan interactively from the conversation. For a quicker plan-then-decide flow, or to run a `/goal` yourself, pick option 1 and choose at the `ce-plan` handoff. -3. **Pressure-test the requirements** - Dispatch reviewer agents with `ce-doc-review` to find gaps, conflicts, weak premises, and scope issues in the requirements; auto-apply safe fixes; route the rest interactively. Shown only when a markdown unified plan exists **and `OUTPUT_FORMAT=md`** — ce-doc-review's walkthrough applies markdown-only mutations (`##`/`###` heading inserts, single-file markdown edits via apply-set) and would corrupt an HTML artifact, so HTML brainstorms skip this option until ce-doc-review gains HTML-aware mutation support. Under HTML mode, surface a one-line note above the menu: `Requirements review unavailable in output:html mode — ce-doc-review is markdown-only today. Switch to output:md if you want a review pass.` + +3. **Pressure-test the requirements** - Dispatch reviewer agents with `ce-doc-review` to find gaps, conflicts, weak premises, and scope issues in the requirements; auto-apply safe fixes for markdown; route the rest interactively. Shown when a unified plan artifact exists. Under `OUTPUT_FORMAT=html`, run `ce-doc-review` in report-only mode: persona lenses run and findings are presented, but no in-file mutations, markdown apply-set edits, or Append-to-Open-Questions write-back are offered. 4. **Publish to Proof — shareable link** - Publish the markdown unified plan to Every's Proof editor and get a shareable link to read, comment on, or share with others. One-way: the local doc stays canonical. Shown only when a markdown unified plan exists. **Render only when `OUTPUT_FORMAT=md`** (Proof operates on markdown and cannot ingest HTML). 4. **Open in browser** — open the HTML unified plan locally for review and sharing. Shown only when an HTML unified plan exists. **Render only when `OUTPUT_FORMAT=html`.** Replaces "Publish to Proof" at the same slot under exclusive output mode — the artifact is either markdown OR HTML, never both, so exactly one of the two labels applies per run. 5. **More clarifying questions to sharpen the doc** - Keep refining scope, edge cases, constraints, and preferences through further dialogue. Always shown. There is no "done" / "pause" option — the blocking question already waits, and the user ends by dismissing it (Esc) or saying they're finished. The unified plan artifact is already saved. -**Post-review nudge (subsequent rounds only):** If the user has already run `ce-doc-review` this session and residual P0/P1 findings remain unaddressed, add a one-line prose nudge adjacent to the menu (e.g., "Document review flagged 2 P1 findings you may want to address — pick \"Pressure-test the requirements\" to run another pass."). Reference the option by label, not number: the menu renumbers when `Resolve Before Planning` hides `Create the implementation plan` and the lfg option, so a hardcoded option number can point users at the wrong action. Do not add a separate menu option; reuse the existing `Pressure-test the requirements` option. Suppress this nudge when `OUTPUT_FORMAT=html` — that option is hidden in that mode, so the nudge would point users at a missing action. +**Post-review nudge (subsequent rounds only):** If the user has already run `ce-doc-review` this session and residual P0/P1 findings remain unaddressed, add a one-line prose nudge adjacent to the menu (e.g., "Document review flagged 2 P1 findings you may want to address — pick \"Pressure-test the requirements\" to run another pass."). Reference the option by label, not number: the menu renumbers when `Resolve Before Planning` hides `Create the implementation plan` and the lfg option, so a hardcoded option number can point users at the wrong action. Do not add a separate menu option; reuse the existing `Pressure-test the requirements` option. This nudge applies to markdown and HTML artifacts; HTML reruns remain report-only. #### 4.2 Handle the Selected Option @@ -80,11 +83,14 @@ re-scanning the repo. Do not print the closing summary first. **If user selects "Pressure-test the requirements":** Load the `ce-doc-review` skill, passing the unified plan path as the argument. -When ce-doc-review returns "Review complete", return to the Phase 4 options -and re-render the menu (the requirements may have changed, so re-evaluate -`Resolve Before Planning`, the lfg software gate, and residual findings). If -residual P0/P1 findings remain unaddressed, include the post-review nudge -above the menu. Do not show the closing summary yet. +For `.html` artifacts, state that the review is report-only and that no +autofix or Append-to-Open-Questions write-back will run. When ce-doc-review +returns "Review complete", return to the Phase 4 options and re-render the +menu (the requirements may have changed for markdown; HTML findings are +advisory unless the user chooses to edit the artifact manually, so still +re-evaluate `Resolve Before Planning`, the lfg software gate, and residual +findings). If residual P0/P1 findings remain unaddressed, include the +post-review nudge above the menu. Do not show the closing summary yet. **If user selects "Ship it autonomously with `lfg`":** diff --git a/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/html-rendering.md b/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/html-rendering.md index 156e2665a9..15f049302f 100644 --- a/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/html-rendering.md +++ b/plugins/fusion-plugin-compound-engineering/src/skills/ce-brainstorm/references/html-rendering.md @@ -10,11 +10,10 @@ 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`, human readers) do so directly; -the agent-consumability rules below make that work. `ce-doc-review` is -*not* currently an HTML consumer — its mutation mechanics are markdown-only, -so the ce-plan handoff gates the 5.3.8 doc-review pass to `OUTPUT_FORMAT=md` -runs and skips it for HTML. +consumers that read HTML today (`ce-work`, `ce-doc-review` report-only mode, +human readers) do so directly; the agent-consumability rules below make that +work. `ce-doc-review` reviews HTML without mutation: markdown autofix and +Append-to-Open-Questions write-back remain disabled for `.html` artifacts. ## Hard invariants @@ -543,11 +542,12 @@ fine when the content suggests them. ## Agent-consumability rules -Downstream agents that read HTML today (`ce-work`, 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` is not a current HTML consumer (see -opening note). +Downstream agents that read HTML today (`ce-work`, `ce-doc-review` in +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 that text-readable structure for persona findings but does not mutate +HTML (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 diff --git a/plugins/fusion-plugin-compound-engineering/src/skills/ce-doc-review/SKILL.md b/plugins/fusion-plugin-compound-engineering/src/skills/ce-doc-review/SKILL.md index cade8fb2c2..fe86bc665e 100644 --- a/plugins/fusion-plugin-compound-engineering/src/skills/ce-doc-review/SKILL.md +++ b/plugins/fusion-plugin-compound-engineering/src/skills/ce-doc-review/SKILL.md @@ -1,17 +1,22 @@ --- name: ce-doc-review -description: "Review Compound Engineering markdown plan documents for coherence, feasibility, scope alignment, and safe markdown-only fixes. Use headless mode for automated plan handoff review." -argument-hint: "[mode:headless] " +description: "Review Compound Engineering markdown or HTML plan documents for coherence, feasibility, and scope alignment. Use headless mode for automated plan handoff review; HTML is report-only." +argument-hint: "[mode:headless] " --- # CE Document Review -Review a Compound Engineering markdown plan or requirements document. This skill is intentionally markdown-only: do not mutate HTML artifacts. If the target is HTML, missing, or not a CE plan/requirements document, report a non-blocking skip with notes. +Review a Compound Engineering markdown or HTML plan/requirements document. Markdown artifacts may receive safe markdown-only fixes; HTML artifacts are reviewed in report-only mode and are never mutated. + + ## Modes -- `mode:headless `: run an automated advisory pass, apply only safe markdown fixes, and return a concise review envelope. -- `` without `mode:headless`: run the same review, but include actionable findings clearly enough for an interactive caller to decide what to apply. +- `mode:headless `: run an automated advisory pass and return a concise review envelope. For markdown, apply only `safe_auto` markdown fixes; for HTML, report findings only and apply nothing. +- `` without `mode:headless`: run the same review for an interactive caller. For markdown, include actionable findings clearly enough for the caller to decide what to apply; for HTML, present a report-only summary and do not offer apply or Append-to-Open-Questions write-back options. ## Review boundary @@ -23,21 +28,27 @@ Review a Compound Engineering markdown plan or requirements document. This skill ## Procedure -1. Resolve the target path from the arguments. Prefer an explicit path. If no path is provided, inspect `docs/plans/` for the most recent markdown plan-like artifact and use that; if none exists, skip non-blockingly. -2. Confirm the target is markdown (`.md`). If it is not markdown, skip and explain that HTML document review is not supported yet. -3. Read the document enough to evaluate structure and consistency. For long documents, scan headings first, then read the Goal Capsule/Product Contract/Plan/Implementation Units/Verification/Definition of Done sections as present. +1. Resolve the target path from the arguments. Prefer an explicit path. If no path is provided, inspect `docs/plans/` for the most recent markdown (`.md`) or HTML (`.html`) plan-like artifact and use that; if none exists, skip non-blockingly. +2. Classify the target type: + - Markdown (`.md`): review with markdown-safe mutation enabled for `safe_auto` fixes only. + - HTML (`.html`): review in report-only mode. Run the same document-quality and persona-lens checks, preserve classifications, return structured findings text, and set `fixes_applied`/`applied_fixes_count` to `0`. Do not run `safe_auto` writes, `gated_auto`/`manual` apply-set edits, or Append-to-Open-Questions write-back that inserts markdown `##`/`###` headings. + - Any other type: skip non-blockingly and explain that only markdown and HTML CE plan/requirements artifacts are supported. +3. Read the document enough to evaluate structure and consistency. For long documents, scan headings first, then read the Goal Capsule/Product Contract/Plan/Implementation Units/Verification/Definition of Done sections as present. For HTML, use the rendered document text/semantic headings as review input; do not rewrite tags or inject markdown. 4. Check for: - Product scope drift: requirements or Product Contract rewritten without a clear preservation note. - HOW gaps: implementation units lacking files, dependencies, risks, or verification scenarios. - Coherence gaps: contradictory decisions, stale handoff instructions, duplicated or inconsistent artifact readiness metadata. - Feasibility gaps: sequencing that cannot work, missing prerequisite decisions, or verification that cannot prove the stated Definition of Done. - - Markdown-only hygiene that is safe to fix automatically: broken heading levels, obvious duplicate blank lines, malformed checklists, or typo-level wording that does not change meaning. -5. In headless mode, apply only `safe_auto` fixes directly to the markdown file. Do not apply changes that alter product scope, technical decisions, acceptance criteria, or verification obligations; report those as findings. + - Markdown-only hygiene that is safe to fix automatically: broken heading levels, obvious duplicate blank lines, malformed checklists, or typo-level wording that does not change meaning. This check may produce report-only findings for HTML but must not edit HTML. +5. In headless mode, apply only `safe_auto` fixes directly to markdown files. Do not apply changes that alter product scope, technical decisions, acceptance criteria, or verification obligations; report those as findings. In HTML mode, apply no fixes of any class and return the review envelope with counts/classifications intact. 6. If findings remain, classify each as: - `proposed_fix`: a safe but non-trivial improvement the user may accept. - `decision`: a scope/technical judgment that needs human or planner choice. - `fyi`: useful observation that does not need routing. -7. End with a concise summary and exactly one trailing JSON object on the final line. +7. Interactive routing: + - Markdown: the caller may choose whether to apply proposed fixes, route decisions, or append unresolved items to Open Questions. + - HTML: skip apply and Append-to-Open-Questions choices entirely. Present the findings as a report-only summary, recommend regenerating markdown only if the user wants in-file autofix/write-back, and leave the HTML artifact unchanged. +8. End with a concise summary and exactly one trailing JSON object on the final line. ## Output contract @@ -48,7 +59,9 @@ Use this shape for the final line: ``` - `APPROVE`: no actionable issues remain. -- `APPROVE_WITH_NOTES`: non-blocking observations or skipped review; this is the normal result for optional workflow use. +- `APPROVE_WITH_NOTES`: non-blocking observations or report-only HTML findings; this is the normal result for optional workflow use. - `REVISE`: only for severe document issues that make downstream work unsafe or impossible. In the Fusion built-in workflow this skill is advisory/non-blocking, but the verdict still helps humans see severity. +For HTML report-only reviews, the JSON must still be emitted, `fixes_applied` must be `0`, and notes should mention that HTML was reviewed without autofix. + Do not wrap the final JSON in markdown fences. diff --git a/plugins/fusion-plugin-compound-engineering/src/skills/ce-ideate/references/html-rendering.md b/plugins/fusion-plugin-compound-engineering/src/skills/ce-ideate/references/html-rendering.md index 156e2665a9..15f049302f 100644 --- a/plugins/fusion-plugin-compound-engineering/src/skills/ce-ideate/references/html-rendering.md +++ b/plugins/fusion-plugin-compound-engineering/src/skills/ce-ideate/references/html-rendering.md @@ -10,11 +10,10 @@ 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`, human readers) do so directly; -the agent-consumability rules below make that work. `ce-doc-review` is -*not* currently an HTML consumer — its mutation mechanics are markdown-only, -so the ce-plan handoff gates the 5.3.8 doc-review pass to `OUTPUT_FORMAT=md` -runs and skips it for HTML. +consumers that read HTML today (`ce-work`, `ce-doc-review` report-only mode, +human readers) do so directly; the agent-consumability rules below make that +work. `ce-doc-review` reviews HTML without mutation: markdown autofix and +Append-to-Open-Questions write-back remain disabled for `.html` artifacts. ## Hard invariants @@ -543,11 +542,12 @@ fine when the content suggests them. ## Agent-consumability rules -Downstream agents that read HTML today (`ce-work`, 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` is not a current HTML consumer (see -opening note). +Downstream agents that read HTML today (`ce-work`, `ce-doc-review` in +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 that text-readable structure for persona findings but does not mutate +HTML (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 diff --git a/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/SKILL.md b/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/SKILL.md index d29d81bc68..2d80f23eb3 100644 --- a/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/SKILL.md +++ b/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/SKILL.md @@ -736,9 +736,12 @@ Then continue to Phase 5.2 without a blocking question. **REQUIRED: Write the plan file to disk before presenting any options.** -HTML note: `ce-doc-review` is markdown-only today. HTML plans still render the -unified artifact, but the Phase 5.3.8 document-review autofix pass is skipped -for HTML by the format gate in `references/plan-handoff.md`. +HTML note: `ce-doc-review` runs for HTML plans in report-only mode. HTML plans still render the unified artifact; the Phase 5.3.8 document-review pass reviews the `.html` plan without autofix or Append-to-Open-Questions write-back. + + Use the Write tool to save the complete plan to the resolved format's extension: @@ -761,7 +764,7 @@ Write the unified plan artifact according to `references/plan-sections.md`. - Do not set `artifact_contract: ce-unified-plan/v1` on universal-planning outputs, answer-seeking outputs, or approach-plans unless they include the full software implementation contract. - Do not write a launch prompt into the doc. The launch prompt is generated at handoff (Phase 5.4 menu — `/goal` copy-paste on Claude Code, `create_goal` on Codex) from the plan's current content, so it never goes stale; it points to Goal Capsule, Verification Contract, Definition of Done, and U-IDs rather than duplicating them. -**HTML composition timing.** When `OUTPUT_FORMAT=html`, Phase 5.3 deepening runs before this write completes its final form, but `ce-doc-review` is skipped in HTML mode (its mutation mechanics are markdown-only today — see Phase 5.3.8 format gate in `references/plan-handoff.md`). The HTML artifact reflects deepening synthesis but not doc-review autofixes; this is a known gap until ce-doc-review gains HTML-aware mutation. +**HTML composition timing.** When `OUTPUT_FORMAT=html`, Phase 5.3 deepening runs before this write completes its final form, and `ce-doc-review` then reviews the HTML artifact in report-only mode (see Phase 5.3.8 format gate in `references/plan-handoff.md`). The HTML artifact reflects deepening synthesis and receives doc-review findings, but no in-file autofix or Append-to-Open-Questions mutation is attempted. Confirm (use absolute path so the reference is clickable in modern terminals): @@ -814,7 +817,7 @@ Build a risk profile. Treat these as high-risk signals: - **Thin local grounding override:** If Phase 1.2 triggered external research because local patterns were thin (fewer than 3 direct examples or adjacent-domain match), always proceed to scoring regardless of how grounded the plan appears. When the plan was built on unfamiliar territory, claims about system behavior are more likely to be assumptions than verified facts. The scoring pass is cheap — if the plan is genuinely solid, scoring finds nothing and exits quickly - **Load-bearing external research override:** If Phase 1.4 marked external research as load-bearing (it materially shaped a KTD, Alternative, Scope boundary, or Risk), always proceed to scoring — **even when local implementation patterns are strong**. A landscape or prior-art finding can shape recommendations the local codebase cannot verify, and the thin-grounding override above would miss it. This enters the scoring pass only; it does not force deepening -If the plan already appears sufficiently grounded and neither the thin-grounding nor the load-bearing-external-research override applies, report "Confidence check passed — no sections need strengthening", then **load `references/plan-handoff.md` now and execute 5.3.8 → 5.3.9 → 5.4 in sequence**. Document review is mandatory for markdown plans — do not skip it because the confidence check passed. The two tools catch different classes of issues. For HTML plans (`OUTPUT_FORMAT=html`), the plan-handoff 5.3.8 format gate skips ce-doc-review since its mutation mechanics are markdown-only today; the menu summary surfaces that limitation explicitly. +If the plan already appears sufficiently grounded and neither the thin-grounding nor the load-bearing-external-research override applies, report "Confidence check passed — no sections need strengthening", then **load `references/plan-handoff.md` now and execute 5.3.8 → 5.3.9 → 5.4 in sequence**. Document review is mandatory for markdown plans and report-only for HTML plans — do not skip it because the confidence check passed. The two tools catch different classes of issues. For HTML plans (`OUTPUT_FORMAT=html`), the plan-handoff 5.3.8 format gate suppresses mutation but still runs ce-doc-review and surfaces findings explicitly. ##### 5.3.3–5.3.7 Deepening Execution @@ -822,9 +825,9 @@ When deepening is warranted, read `references/deepening-workflow.md` for confide ##### 5.3.8–5.4 Document Review, Final Checks, and Post-Generation Options -**STOP. Load `references/plan-handoff.md` now before continuing.** It carries the full instructions for 5.3.8 (document review), 5.3.9 (final checks and cleanup), and 5.4 (post-generation handoff, including the Publish to Proof flow and Issue Creation branching). **This load is non-optional** — without it, the agent renders the post-generation menu, captures the user's selection, and stops without firing the routed action. Document review at 5.3.8 runs unconditionally for `OUTPUT_FORMAT=md` regardless of whether the confidence check already ran; for `OUTPUT_FORMAT=html`, plan-handoff's 5.3.8 format gate skips ce-doc-review because its mutation mechanics are markdown-only today. The default mode for markdown is headless (`mode:headless`) — `safe_auto` fixes apply silently, remaining findings surface contextually above the menu, and a deeper interactive review is opt-in via free-form prompt. +**STOP. Load `references/plan-handoff.md` now before continuing.** It carries the full instructions for 5.3.8 (document review), 5.3.9 (final checks and cleanup), and 5.4 (post-generation handoff, including the Publish to Proof flow and Issue Creation branching). **This load is non-optional** — without it, the agent renders the post-generation menu, captures the user's selection, and stops without firing the routed action. Document review at 5.3.8 runs unconditionally for `OUTPUT_FORMAT=md` and runs report-only for `OUTPUT_FORMAT=html` regardless of whether the confidence check already ran. The default mode is headless (`mode:headless`) — markdown `safe_auto` fixes apply silently, HTML applies no fixes, remaining findings surface contextually above the menu, and a deeper interactive review is opt-in via free-form prompt. -After document review and final checks, print a one-line summary of the headless review state above the menu (e.g., `Doc review applied 3 fixes. 2 decisions, 1 proposed fix, 4 FYI observations remain (1 at P1).`; for HTML plans where 5.3.8 was skipped, print `Doc review skipped — ce-doc-review is markdown-only today; the HTML plan was not reviewed.`), then present the menu. Options 1 (`Start /ce-work`) and 2 (`Run it as a /goal`) render only for implementation-ready code plans, and option 2 only on hosts with a top-level `/goal` command (Claude Code and Codex); the `Decide on the review's open items` option renders only when actionable findings remain (`proposed_fixes_count + decisions_count > 0`) — the FYI-only and HTML-skip (`skipped_reason: output_format_html`) cases hide it because the walkthrough is gated to actionable markdown findings. See `references/plan-handoff.md` for the full rule. When 5 or more options render (exceeding the `AskUserQuestion` 4-option cap), render the menu as a numbered list in chat with the hint "Pick a number or describe what you want." rather than trimming options. On platforms whose blocking question tool has no option cap (Codex `request_user_input`, Pi `ask_user`), use the blocking tool with all rendered options; when it is unavailable or errors (e.g., Codex edit modes), fall back to the same numbered-list-in-chat rendering. When 4 or fewer options render, use the platform's blocking tool (`AskUserQuestion` in Claude Code — call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), with the same numbered-list fallback. Renumber the visible options 1-N. Never silently skip the question. +After document review and final checks, print a one-line summary of the headless review state above the menu (e.g., `Doc review applied 3 fixes. 2 decisions, 1 proposed fix, 4 FYI observations remain (1 at P1).`; for HTML plans, print `Doc review (report-only) found N findings; HTML plans are reviewed without autofix.`), then present the menu. Options 1 (`Start /ce-work`) and 2 (`Run it as a /goal`) render only for implementation-ready code plans, and option 2 only on hosts with a top-level `/goal` command (Claude Code and Codex); the `Decide on the review's open items` option renders only when actionable findings remain (`proposed_fixes_count + decisions_count > 0`). FYI-only cases hide it because the walkthrough is gated to actionable findings. HTML cases may show it when actionable findings exist, but the interactive pass remains report-only: present findings and decisions, do not apply fixes or append markdown headings. See `references/plan-handoff.md` for the full rule. When 5 or more options render (exceeding the `AskUserQuestion` 4-option cap), render the menu as a numbered list in chat with the hint "Pick a number or describe what you want." rather than trimming options. On platforms whose blocking question tool has no option cap (Codex `request_user_input`, Pi `ask_user`), use the blocking tool with all rendered options; when it is unavailable or errors (e.g., Codex edit modes), fall back to the same numbered-list-in-chat rendering. When 4 or fewer options render, use the platform's blocking tool (`AskUserQuestion` in Claude Code — call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), with the same numbered-list fallback. Renumber the visible options 1-N. Never silently skip the question. **Question:** "Plan ready at ``. What would you like to do next?" (use absolute path so the reference is clickable in modern terminals) @@ -834,7 +837,7 @@ After document review and final checks, print a one-line summary of the headless 2. **Run it as a `/goal`** - Run this plan as an autonomous `/goal` to its Definition of Done — fewer check-ins; good for longer or unattended runs. The alternative to option 1, not an add-on — pick one. Implementation-ready code plans only, and only where the host has goal mode (a callable tool like Codex `create_goal`, or a user-typed `/goal` like Claude Code). Where it can start directly, it does; otherwise it hands over a copy-paste prompt. **Recommended marker (dynamic):** `/goal` is the recommended default when the host supports it — mark option 2 *(recommended)* and leave option 1 unmarked; on hosts without `/goal` (option 2 omitted), mark option 1 *(recommended)* instead. Exactly one option carries it. -3. **Decide on the review's open items** - Confirm or skip the suggested edits, and settle the judgment calls the auto-pass left for you. (Safe, mechanical fixes were already applied; you can also defer items into Open Questions.) +3. **Decide on the review's open items** - Confirm or skip the suggested edits, and settle the judgment calls the auto-pass left for you. (Markdown safe fixes were already applied; HTML reviews are report-only and do not offer apply or Open Questions write-back.) 4. **Create Issue** - Create a tracked issue from this plan in your configured issue tracker (e.g., GitHub Issues, Linear, Jira) 5. **Publish to Proof — shareable link** - Publish the plan to Every's Proof editor and get a shareable link to read, comment on, or share with others. One-way: the local plan file stays canonical. **Render only when `OUTPUT_FORMAT=md`.** 5. **Open in browser** - Open the HTML plan file locally for review and sharing. **Render only when `OUTPUT_FORMAT=html`.** @@ -843,13 +846,13 @@ After document review and final checks, print a one-line summary of the headless - **Start `/ce-work`** — Offered only when the artifact is `artifact_readiness: implementation-ready` and `execution: code` (not for requirements-only, universal-planning, answer-seeking, or approach-plan outputs). Invoke the `ce-work` skill via the platform's skill-invocation primitive (`Skill` in Claude Code and Codex, the equivalent on Gemini/Pi), passing the plan path as the skill argument; `ce-work` owns engine selection and the tail. If no skill-invocation primitive exists, print the `ce-work` fallback prompt for the user to run. Do not merely tell the user to type `/ce-work` when a skill invocation primitive is available. - **Run it as a `/goal`** — Offered on the implementation-ready-code gate, and only where the host has goal mode (callable tool or user-typed `/goal`). **`ce-work` does not also run.** Build a **thin** objective from the plan here (not from a doc section), pointing to the plan's sections — do **not** copy its resolved decisions, exact commands, or requirements into the prompt (deletion test: if the draft names a specific command, file path, U-ID dependency, stop condition, or DoD item, cut it — it should read the same for any plan except the path), and carry the PR-precedence line instead of a hardcoded open/don't-open directive: implement `` to its Definition of Done; scan headings, don't read the whole doc; read the Goal Capsule then work units in dependency order with their cited R/F/AE/KTD; run the plan's Verification Contract gates and satisfy each unit's test scenarios; track progress outside the plan file; follow the plan's PR/landing strategy if it defines one, with repo conventions and user preferences overriding it; surface a genuine blocker (changes scope or contradicts the plan) instead of guessing, using judgment on details the plan leaves open. If a callable goal tool is available (Codex `create_goal`), call it with that objective — the session works toward the DoD; do not call `update_goal` (the goal session completes itself). Otherwise (user-typed `/goal` only, e.g. Claude Code), print that objective as a copyable `/goal` prompt for the user to paste, then return to the menu. -- **Decide on the review's open items** — Re-invoke the `ce-doc-review` skill on the plan path **without** `mode:headless` so the interactive routing question and walkthrough fire. After it returns, re-render this menu with refreshed counts so the user can pick a next-stage action. +- **Decide on the review's open items** — Re-invoke the `ce-doc-review` skill on the plan path **without** `mode:headless` so the interactive routing question and walkthrough fire for markdown, or the report-only findings review fires for HTML. HTML review presents findings and decisions without apply or Append-to-Open-Questions write-back. After it returns, re-render this menu with refreshed counts so the user can pick a next-stage action. - **Create Issue** — Detect the project tracker from the project instructions already in your context and create the issue from the plan file as described under "Issue Creation" in `references/plan-handoff.md`. Create the issue through whatever interface the tracker actually exposes — `gh` for GitHub when it's installed and authenticated, otherwise GitHub's connector/MCP tool or API; for Linear, a connector/MCP tool, documented API/GraphQL, or a documented CLI (no guaranteed `linear` CLI). Do not treat a missing binary, env var, or unloaded MCP tool as proof the tracker is unavailable. After creation, display the issue URL and ask whether to proceed to `/ce-work` via the platform's blocking question tool. - **Publish to Proof — shareable link** — Load the `ce-proof` skill to publish the plan: create a shared Proof doc from the plan file (title = plan title; identity `ai:compound-engineering` / `Compound Engineering`), surface the share URL to the user, then return to this menu. One-way publish — the local plan file stays canonical, nothing syncs back. If the upload fails, see the graceful-fallback note in `references/plan-handoff.md`. - **Open in browser** — Display the absolute path to the `.html` plan file so the user can open it locally. Where the platform exposes a browser-opening primitive (e.g., `open` on macOS, `xdg-open` on Linux, `start` on Windows), the agent may use it; otherwise print the absolute path and let the user open it. Do not invoke `ce-work` from this option — the user picked HTML for review/sharing, not handoff. -If the user types free-form prompts targeting the findings (e.g., "review", "walk through", "deep review"), route as if they picked `Decide on the review's open items` — fire the skill rather than looping back to the menu. For other free-text revisions, accept the input and loop back to this menu after applying the revision. +If the user types free-form prompts targeting the findings (e.g., "review", "walk through", "deep review"), route as if they picked `Decide on the review's open items` — fire the skill rather than looping back to the menu. For HTML plans, that free-form route is still report-only and must not offer apply or Append-to-Open-Questions write-back. For other free-text revisions, accept the input and loop back to this menu after applying the revision. **Completion check:** This skill is not complete until the post-generation menu above has been presented, the user has selected an action, and the inline routing for that selection has been executed. Presenting the menu and stopping at the user's selection is not completion — fire the routed action. -**Pipeline mode exception:** In LFG or any `disable-model-invocation` context, skip the interactive menu and return control to the caller after the plan file is written, confidence check has run, and `ce-doc-review` has run in headless mode (per `references/plan-handoff.md`). Pipeline mode forces `OUTPUT_FORMAT=md` at Phase 0.0, so the 5.3.8 format gate never selects the HTML skip path in pipeline runs. +**Pipeline mode exception:** In LFG or any `disable-model-invocation` context, skip the interactive menu and return control to the caller after the plan file is written, confidence check has run, and `ce-doc-review` has run in headless mode (per `references/plan-handoff.md`). Pipeline mode forces `OUTPUT_FORMAT=md` at Phase 0.0, so pipeline reviews keep the markdown autofix path. diff --git a/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/html-rendering.md b/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/html-rendering.md index 156e2665a9..a1701925d4 100644 --- a/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/html-rendering.md +++ b/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/html-rendering.md @@ -10,11 +10,10 @@ 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`, human readers) do so directly; -the agent-consumability rules below make that work. `ce-doc-review` is -*not* currently an HTML consumer — its mutation mechanics are markdown-only, -so the ce-plan handoff gates the 5.3.8 doc-review pass to `OUTPUT_FORMAT=md` -runs and skips it for HTML. +consumers that read HTML today (`ce-work`, `ce-doc-review` report-only mode, +human readers) do so directly; the agent-consumability rules below make that +work. `ce-doc-review` reviews HTML without mutation: markdown autofix and +Append-to-Open-Questions write-back remain disabled for `.html` artifacts. ## Hard invariants @@ -543,10 +542,11 @@ fine when the content suggests them. ## Agent-consumability rules -Downstream agents that read HTML today (`ce-work`, 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` is not a current HTML consumer (see +Downstream agents that read HTML today (`ce-work`, `ce-doc-review` in +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 without mutating HTML (see opening note). These rules are why such a consumer can locate one item (a single diff --git a/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/plan-handoff.md b/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/plan-handoff.md index 35b112fb47..2484b6fa65 100644 --- a/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/plan-handoff.md +++ b/plugins/fusion-plugin-compound-engineering/src/skills/ce-plan/references/plan-handoff.md @@ -4,31 +4,36 @@ This file contains post-plan-writing instructions: document review, post-generat ## 5.3.8 Document Review -**Format gate.** This phase runs only when `OUTPUT_FORMAT=md` (resolved in SKILL.md Phase 0.0). `ce-doc-review`'s mutation mechanics are markdown-specific — its walkthrough applies `gated_auto`/`manual` fixes as "single-file markdown changes" via the platform's edit tool, and its Append-to-Open-Questions flow inserts `##`/`###` markdown headings (see the walkthrough and open-questions-defer references inside the ce-doc-review skill). Running those mutators against an HTML artifact would produce malformed output. Until ce-doc-review gains HTML-aware mutation, HTML plans skip this phase entirely. +**Format gate.** This phase runs for both markdown and HTML plans. Markdown plans use the full headless `ce-doc-review` path, including safe markdown-only autofixes. HTML plans use `ce-doc-review` in report-only mode: persona lenses run and findings are returned as structured text, but all mutation mechanics are suppressed because `gated_auto`/`manual` apply-set edits and Append-to-Open-Questions write-back are markdown-specific. -**When `OUTPUT_FORMAT=html`:** Skip the ce-doc-review invocation. Capture a synthetic "skipped" envelope so the menu summary line in 5.4 can name the limitation explicitly: -- `fixes_applied = 0` -- `proposed_fixes_count = 0`, `decisions_count = 0`, `fyi_count = 0` -- `skipped_reason = "output_format_html"` + -Then proceed directly to Final Checks (5.3.9). Do not block on this — the confidence check at 5.3 already strengthened the plan. Free-form requests for review in the post-generation menu will be declined for HTML runs with a prompt to switch to `output:md` (see 5.4); review is not available for HTML plans until ce-doc-review gains HTML-aware mutation. +**When `OUTPUT_FORMAT=html`:** Run the `ce-doc-review` skill with `mode:headless` on the `.html` plan file and explicitly treat the invocation as report-only. Pass `mode:headless ` as the skill arguments. Capture the returned envelope so the menu summary in 5.4 can name the report-only result: +- `fixes_applied = 0` / `applied_fixes_count = 0` +- `proposed_fixes_count`, `decisions_count`, and `fyi_count` from the reviewer output +- no `skipped_reason` field + +Do not block on this — the optional workflow remains advisory — but do surface P0/P1 findings before returning control to the caller. Free-form requests for review in the post-generation menu re-run `ce-doc-review` on the HTML plan in report-only mode (present findings; no autofix; no Append-to-Open-Questions write-back). **When `OUTPUT_FORMAT=md`:** Run the `ce-doc-review` skill with `mode:headless` on the plan file. Pass `mode:headless ` as the skill arguments. When this step is reached for a markdown plan, it is mandatory — do not skip it because the confidence check already ran. The two tools catch different classes of issues. -Headless is the default at this phase because most users want to start work after planning, not adjudicate every reviewer concern up front. Headless applies `safe_auto` fixes silently and returns structured findings text — no walkthrough, no per-finding routing, no blocking prompts. The post-generation menu (see 5.4) offers `Decide on the review's open items` as a first-class option so users can opt into the full interactive walkthrough when they want it. +Headless is the default at this phase because most users want to start work after planning, not adjudicate every reviewer concern up front. For markdown, headless applies `safe_auto` fixes silently and returns structured findings text — no walkthrough, no per-finding routing, no blocking prompts. For HTML, headless returns the same structured findings text but applies nothing. The post-generation menu (see 5.4) offers `Decide on the review's open items` as a first-class option so users can opt into the full interactive walkthrough when they want it; for HTML that walkthrough stays report-only and omits apply/Append choices. The confidence check and ce-doc-review are complementary: - The confidence check strengthens rationale, sequencing, risk treatment, and grounding - Document-review checks coherence, feasibility, scope alignment, and surfaces role-specific issues Capture the headless envelope so it can drive the contextual summary above the post-generation menu: -- The number of fixes auto-applied +- The number of fixes auto-applied (always `0` for HTML) - The count of remaining findings, broken out by user-facing bucket (proposed fixes, decisions, FYI observations) - The severity breakdown of decisions and proposed fixes (specifically the P0/P1 count, since those benefit from explicit user attention) When ce-doc-review returns "Review complete", proceed to Final Checks. -**Pipeline mode:** Pipeline runs (LFG or any `disable-model-invocation` context) force `OUTPUT_FORMAT=md` at Phase 0.0, so the format gate above never selects the HTML skip path in pipeline mode. Pipeline runs always invoke `ce-doc-review` with `mode:headless` and the plan path — the headless mode is identical to the interactive default at this phase. No further routing is offered in pipeline mode; the caller decides what to do with the returned findings. Address any P0/P1 findings before returning control to the caller. +**Pipeline mode:** Pipeline runs (LFG or any `disable-model-invocation` context) force `OUTPUT_FORMAT=md` at Phase 0.0, so they always invoke the markdown headless path with `mode:headless` and the plan path. No further routing is offered in pipeline mode; the caller decides what to do with the returned findings. Address any P0/P1 findings before returning control to the caller. ## 5.3.9 Final Checks and Cleanup @@ -41,11 +46,11 @@ If artifact-backed mode was used: - Clean up the temporary scratch directory after the plan is safely updated - If cleanup is not practical on the current platform, note where the artifacts were left -**Format-specific composition.** When `OUTPUT_FORMAT=html` (resolved in SKILL.md Phase 0.0), the plan is written as a single self-contained `.html` file — there is no markdown sibling. Read `references/html-rendering.md` for composition rules: invariants, precedence stack, format principles, agent-consumability rules, and the post-compose audit. The `.html` file is the artifact downstream consumers (ce-work, human readers) read. `ce-doc-review` is not a current HTML consumer — its mutation mechanics are markdown-only today, and HTML plans skip the 5.3.8 doc-review pass until that gap closes. +**Format-specific composition.** When `OUTPUT_FORMAT=html` (resolved in SKILL.md Phase 0.0), the plan is written as a single self-contained `.html` file — there is no markdown sibling. Read `references/html-rendering.md` for composition rules: invariants, precedence stack, format principles, agent-consumability rules, and the post-compose audit. The `.html` file is the artifact downstream consumers (ce-work, human readers, and ce-doc-review's report-only path) read. `ce-doc-review` reviews HTML without mutation; its markdown autofix and Open Questions write-back mechanics remain markdown-only. When `OUTPUT_FORMAT=md`, write the markdown directly per `references/markdown-rendering.md`. No HTML is composed. -After all mutations in this run have settled (initial write, deepening synthesis, ce-doc-review `safe_auto` fixes when `OUTPUT_FORMAT=md`), the artifact at its single path reflects the final state. Publishing to Proof is one-way and does not mutate the local file. HTML runs skip the ce-doc-review autofix step (see 5.3.8 format gate). +After all mutations in this run have settled (initial write, deepening synthesis, ce-doc-review `safe_auto` fixes when `OUTPUT_FORMAT=md`), the artifact at its single path reflects the final state. Publishing to Proof is one-way and does not mutate the local file. HTML runs receive ce-doc-review findings but no autofix mutations (see 5.3.8 format gate). ## 5.4 Post-Generation Options @@ -53,7 +58,7 @@ After all mutations in this run have settled (initial write, deepening synthesis **Path format:** Use absolute paths for chat-output file references — relative paths are not auto-linked as clickable in most terminals. -**Summary line above the menu (always):** Print a single concise line summarizing the headless review state — e.g., `Doc review applied 3 fixes. 2 decisions, 1 proposed fix, 4 FYI observations remain (1 at P1).` When no fixes were applied and no findings remain, print `Doc review clean — no fixes needed.` When the envelope carries `skipped_reason: output_format_html` (HTML run, per Phase 5.3.8 format gate), print `Doc review skipped — ce-doc-review is markdown-only today; the HTML plan was not reviewed.` so the user knows the autofix pass did not run on this artifact. This line establishes what the autofix pass did (or didn't) so the user has the context to choose between the menu options below. +**Summary line above the menu (always):** Print a single concise line summarizing the headless review state — e.g., `Doc review applied 3 fixes. 2 decisions, 1 proposed fix, 4 FYI observations remain (1 at P1).` When no fixes were applied and no findings remain, print `Doc review clean — no fixes needed.` For HTML envelopes, print `Doc review (report-only) found N findings; HTML plans are reviewed without autofix.` (or `Doc review (report-only) clean — HTML plan reviewed without autofix.` when no findings remain). This line establishes what the autofix/report-only pass did so the user has the context to choose between the menu options below. **Question:** "Plan ready at ``. What would you like to do next?" @@ -62,7 +67,7 @@ After all mutations in this run have settled (initial write, deepening synthesis 2. **Run it as a `/goal`** - Run this plan as an autonomous `/goal` to its Definition of Done — fewer check-ins; good for longer or unattended runs. The alternative to option 1, not an add-on — pick one. Show only when (a) the artifact is `artifact_readiness: implementation-ready` plus `execution: code` AND (b) the host has goal mode at all — a callable goal tool (Codex `create_goal`) or a user-typed `/goal` (Claude Code); omit it where neither exists. Where the host can start a goal directly the session begins it immediately; where it cannot, it hands over a copyable `/goal` prompt. See the routing below. **Recommended marker (dynamic):** `/goal` is the recommended default when its host supports it — render option 2 as **Run it as a `/goal`** *(recommended)* and leave option 1 unmarked. On hosts without `/goal` (option 2 omitted), mark option 1 **Start `/ce-work`** *(recommended)* instead. Exactly one option ever carries *(recommended)*. -3. **Decide on the review's open items** - Confirm or skip the suggested edits, and settle the judgment calls the auto-pass left for you. (Safe, mechanical fixes were already applied; you can also defer items into Open Questions.) +3. **Decide on the review's open items** - Confirm or skip the suggested edits, and settle the judgment calls the auto-pass left for you. (Markdown safe fixes were already applied; HTML reviews are report-only and do not offer apply or Open Questions write-back.) 4. **Create Issue** - Create a tracked issue from this plan in your configured issue tracker (e.g., GitHub Issues, Linear, Jira) 5. **Publish to Proof — shareable link** - Publish the plan to Every's Proof editor and get a shareable link to read, comment on, or share with others. One-way: the local plan file stays canonical. **Render only when `OUTPUT_FORMAT=md`.** 5. **Open in browser** - Open the HTML plan file locally for review and sharing. **Render only when `OUTPUT_FORMAT=html`.** @@ -73,7 +78,7 @@ There is no "done" / "pause" option — the blocking question already waits, and **Menu rendering:** The menu has up to 5 options (execution options 1 and 2 render only for implementation-ready code, and option 2 only on hosts with a `/goal` command; option 3 is conditional — see below). When 5 render, exceeding the `AskUserQuestion` 4-option cap, render the menu as a numbered list in chat with the hint "Pick a number or describe what you want." rather than trimming options — each is a distinct destination and none are removable without losing real user choice. On platforms whose blocking question tools have no option cap (e.g., Codex `request_user_input`, Pi `ask_user`), use the blocking tool with all rendered options. When the visible-option count is 4 or fewer (e.g., a requirements-only/non-code plan hides options 1 and 2, or doc review is dropped), use `AskUserQuestion` on Claude Code and renumber the visible options 1-N. When the platform's blocking tool is unavailable or errors (e.g., Codex edit modes where `request_user_input` is not exposed, or `ask_user` returns no match), fall back to the same numbered-list-in-chat rendering. Never silently skip the question. -**Hide `Decide on the review's open items` (option 3) when no actionable findings remain or doc review was skipped.** Show this option only when the headless envelope reports `proposed_fixes_count + decisions_count > 0` — i.e., at least one `gated_auto` or `manual` finding at confidence anchor `75` or `100`. Drop the option in any other case, including FYI-only state. FYI observations (anchor `50`) do not enter `ce-doc-review`'s interactive routing question or walkthrough — that flow is gated to actionable findings — so a `Decide on the review's open items` option that only has FYIs to show is a dead-end: ce-doc-review would re-dispatch the persona team, find the same FYIs, skip the routing question, and fall through to the terminal question with nothing to walk through. The user paid the dispatch cost for no engagement surface. **Also drop this option when the envelope carries `skipped_reason: output_format_html`** — ce-doc-review's mutation mechanics are markdown-only today (see Phase 5.3.8 format gate), so a `Decide on the review's open items` option on an HTML plan would route into the same markdown-oriented walkthrough the gate exists to prevent. Always renumber the *visible* options 1-N for display so users see a clean sequence (e.g., an implementation-ready plan with no actionable findings shows ce-work, give-me-`/goal`, Create Issue, Proof/browser, Done; a requirements-only plan hides both execution options and shows only the doc/issue/share/pause options). The summary line above the menu still names the FYI count when present (`Doc review applied 3 fixes. 2 FYI observations remain.`) so the user sees what was found, even though there is no menu action attached to it — the FYIs are visible in the headless envelope text the menu rendered alongside. +**Hide `Decide on the review's open items` (option 3) when no actionable findings remain.** Show this option only when the headless envelope reports `proposed_fixes_count + decisions_count > 0` — i.e., at least one `gated_auto` or `manual` finding at confidence anchor `75` or `100`. Drop the option in any other case, including FYI-only state. FYI observations (anchor `50`) do not enter `ce-doc-review`'s interactive routing question or walkthrough — that flow is gated to actionable findings — so a `Decide on the review's open items` option that only has FYIs to show is a dead-end: ce-doc-review would re-dispatch the persona team, find the same FYIs, skip the routing question, and fall through to the terminal question with nothing to walk through. The user paid the dispatch cost for no engagement surface. For HTML plans, keep this option visible when actionable findings exist, but route it into ce-doc-review's report-only interactive summary: no apply-set edits and no Append-to-Open-Questions write-back. Always renumber the *visible* options 1-N for display so users see a clean sequence (e.g., an implementation-ready plan with no actionable findings shows ce-work, give-me-`/goal`, Create Issue, Proof/browser, Done; a requirements-only plan hides both execution options and shows only the doc/issue/share/pause options). The summary line above the menu still names the FYI count when present (`Doc review applied 3 fixes. 2 FYI observations remain.` or `Doc review (report-only) found 2 FYI observations.`) so the user sees what was found, even though there is no menu action attached to it — the FYIs are visible in the headless envelope text the menu rendered alongside. Based on selection (the bare per-option routing is also stated inline in the SKILL.md so it cannot be missed when this reference is not loaded; the elaborate sub-flows below are the reason this reference still exists): - **Start `/ce-work`** -> Classify the artifact first. If it is not `artifact_readiness: implementation-ready` plus `execution: code`, do not execute it; route requirements-only artifacts back to `ce-plan` enrichment and non-code artifacts to their own workflow. If it is executable, invoke the `ce-work` skill via the platform's skill-invocation primitive, passing the plan path as the skill argument; `ce-work` then owns engine selection (inline/subagent vs goal-mode vs dynamic-workflow) and the implementation tail. If no skill-invocation primitive exists on this host, print the `ce-work` fallback prompt for the user to run; in that prompt, tell the executor to read Goal Capsule, Verification Contract, Definition of Done, and active U-IDs (scanning headings to find them) rather than the whole document first. Do not merely tell the user to type `/ce-work` when a skill invocation primitive is available. @@ -82,7 +87,7 @@ Based on selection (the bare per-option routing is also stated inline in the SKI - **If only a user-typed `/goal` exists (Claude Code):** print that objective as a single copyable `/goal …` block and tell the user to paste it at the start of a message (a skill cannot issue `/goal` itself there). After printing, return to the options. Render only for implementation-ready code plans, and only where the host has goal mode at all (a callable tool or a user-typed `/goal`) — omit the option where neither exists. -- **Decide on the review's open items** -> Re-invoke the `ce-doc-review` skill on the plan path **without** `mode:headless` so the interactive routing question and walkthrough fire. The headless pass already applied `safe_auto` fixes and recorded its findings in the session, so the interactive pass picks up where headless stopped — its R29 suppression rule prevents prior-round Skipped/Deferred entries from re-raising. After it returns, re-render this menu with the refreshed counts so the user can pick what to do next. +- **Decide on the review's open items** -> Re-invoke the `ce-doc-review` skill on the plan path **without** `mode:headless` so the interactive routing question and walkthrough fire for markdown, or the report-only findings review fires for HTML. The headless pass already applied any markdown `safe_auto` fixes and recorded its findings in the session, so the interactive pass picks up where headless stopped — its R29 suppression rule prevents prior-round Skipped/Deferred entries from re-raising. For HTML, present the findings and decisions but do not offer apply/Append-to-Open-Questions write-back. After it returns, re-render this menu with the refreshed counts so the user can pick what to do next. - **Create Issue** -> Follow the Issue Creation section below - **Publish to Proof — shareable link** -> Load the `ce-proof` skill to publish the plan. Pass: - source file: `docs/plans/.md` @@ -95,7 +100,7 @@ Based on selection (the bare per-option routing is also stated inline in the SKI If the upload fails (network error, Proof API down), retry once after a short wait. If it still fails, tell the user the upload didn't succeed and briefly explain why, then return to the options — don't leave them wondering why the option did nothing. - **Open in browser** -> Display the absolute path to the `.html` plan file so the user can open it locally. Where the platform exposes a browser-opening primitive (e.g., `open` on macOS, `xdg-open` on Linux, `start` on Windows), the agent may invoke it directly; otherwise print the absolute path and let the user open it. After the path is displayed (or the browser is opened), return to the post-generation options so the user can pick a follow-up action. -- **Free-form prompts that target the findings** (e.g., the user types "review", "walk through", "deep review" instead of picking a numbered option) -> route as if they had picked `Decide on the review's open items`. Do not loop back to the menu without firing the review. **Exception:** when the envelope carries `skipped_reason: output_format_html`, do not fire ce-doc-review — instead, reply once with `ce-doc-review is markdown-only today; the HTML plan can't be reviewed without HTML-aware mutation support. Switch to /ce-plan output:md to regenerate as markdown if you want a review pass.` and loop back to the menu. +- **Free-form prompts that target the findings** (e.g., the user types "review", "walk through", "deep review" instead of picking a numbered option) -> route as if they had picked `Decide on the review's open items`. Do not loop back to the menu without firing the review. For HTML plans, fire ce-doc-review in report-only mode: present findings and decisions, apply nothing, and do not append markdown headings into the HTML artifact. - **Other free-form input** -> Accept revisions to the plan and loop back to options. ## Issue Creation