review coverage
0 / 9 checked
01

## The 90-second read

flow-next 2.0.0 gains an opt-in HTML artifact mode: when artifacts.html.enabled is on, capture/plan emit a spec render lens and make-pr emits a PR review instrument — self-contained single-file HTML, generated by the host agent from one shared disclosure reference. OFF by default; markdown stays the only record. This page is the feature reviewing its own PR.

Three load-bearing claims to verify: (1) with the mode off/unset every touched skill is gated by a real bash config check — no reference load, no artifacts, no output change · (2) the disclosure reference alone reproduces the house style — proven by a fresh-session generation (the committed spec.html) · (3) the 2.0.0 breaking change (crossEpic alias removal) is complete across code, tests, prose, and this repo's own config.
02

## Churn map — where the 2,858 changed lines live

grouped by review intent · click to expand
▸Disclosure reference — the core contractthe single file that makes any session generate house-style artifacts+325 −0 1 file

- plugins/flow-next/references/html-artifacts.md+325 · hard rules → design contract → per-lens guidance → DAG discipline → Lavish → checklist

▸Skill integrations — canonicalcapture §5.10 · plan Step 8.5 · make-pr Phase 1.5 · setup ceremony+282 −10 10 files

- skills/flow-next-capture/{SKILL,phases,workflow}.md spec lens post-write + LAVISH_OK interactive-only guard
- skills/flow-next-plan/{SKILL,steps}.md regeneration after the Step-8 refinement loop exits
- skills/flow-next-make-pr/{SKILL,phases,workflow}.md Phase 1.5 PR lens: LENS_OK guards, exact-file check-ignore, narrow commit
- skills/flow-next-setup/workflow.md + templates/usage.md HTML question (only-if-unset), gitignore choice, lavish offer

▸flowctl + regression testsone config default block; crossEpic alias removal + its removal tests+337 −198 4 files

- plugins/flow-next/scripts/flowctl.py+26 −31 · artifacts default block; _CONFIG_KEY_ALIASES emptied
- tests/test_artifacts_config.py (new) · test_config_alias.py (converted) · test_init_crossspec_mirror.py+311 −167

▸Codex mirrorgenerated verify sync-codex ran clean — don't line-review+608 −11 12 files

- plugins/flow-next/codex/references/html-artifacts.md (byte-identical) + codex/skills/{capture,plan,make-pr,setup} mirrors regen audited in fn-62.6 (no spurious ask-blocks, no canonical tool names)

▸Docs & release surfacesnew html-artifacts.md reference doc · README · teams · ralph · GLOSSARY · CHANGELOG+216 −36 13 files

- plugins/flow-next/docs/html-artifacts.md (new feature reference)activation, lenses, link strategies, Lavish reality, autonomous discipline
- CHANGELOG.md (2.0.0: Added + BREAKING crossEpic line) · GLOSSARY.md (5 terms) · README/CLAUDE/teams/ralph/releasing/local-dev

▸Sync/install scriptsreferences/ dir propagation+29 −1 2 files

- scripts/sync-codex.sh · scripts/install-codex.sh sibling cp -R for references/; ~/.codex/references install

▸Mechanicallockstep 2.0.0 version surfaces + synced dogfood copy+32 −37 6 files

- 3× plugin.json + 2× marketplace.json (2.0.0) · .flow/bin/flowctl.py (byte-identical sync)

▸Process stateflow task evidence, receipts, captured memories + the committed proof artifact+686 −50 16 files

- .flow/artifacts/fn-62-…/spec.html+553 · the fresh-session proof artifact (R4 evidence)
- .flow/specs + tasks + config + 3 captured build-error memories+133 −50

03

## R-ID → evidence

14 / 14 covered · external-repo evidence flagged honestly

R-ID | Criterion (abridged) | Task | Evidence commits
--- | --- | --- | ---
R1 | Opt-in via setup/config, OFF default; mode off ⇒ no reference load, no artifacts, no sessions, no visible output | .1 | 5597dd1
R2 | Progressively disclosed shared reference file + explicit anti-slop design system | .2 | e4a4263 · 5ba324d
R3 | Markdown/tracker-sync sole source of truth; artifacts regenerable, never parsed back | .2 ·.3 | e4a4263 · c892ae1
R4 | ONE spec-artifact pathway, state-dependent rendering (spec-only ↔ +DAG/matrix) | .3 | c892ae1 · 1235c6d · fce92a1
R5 | PR artifact diff-derived (never commit messages), R-ID-verified, read-only instrument | .4 | 3975a0f · 74a4ecd
R6 | Self-contained single-file HTML, zero external requests, print-friendly | .2 | e4a4263
R7 | Lavish optional dep: detect-on-PATH; annotate → markdown edit → regenerate | .2 ·.3 | e4a4263 · c892ae1
R8 | PR artifact never in the annotate loop; autonomous never polls | .3 ·.4 | fce92a1 · 3975a0f
R9 | Setup ceremony documents + offers lavish-axi on HTML opt-in | .1 | 5597dd1
R10 | Spec + PR markdown link their artifacts; GitHub limitation documented | .3 ·.4 ·.5 | c892ae1 · 74a4ecd · a2478b0
R11 | Fixed regenerable .flow/artifacts/ layout, commit-or-gitignore per project | .1 | 5597dd1
R12external | flow-next.dev mainline surfacing (visual-aids pages, landing card, both navbars, site changelog)evidence lives in the flow-next.dev repo (commit 1dd356d) — outside this diff range by design; verify in the site repo before release push | .7 | flow-next.dev@1dd356d
R13external | flow-next.dev strategy/pipeline pass (pipeline page, autonomy content, Introduction)evidence lives in the flow-next.dev repo (commit 2a226be) — outside this diff range by design; verify in the site repo before release push | .8 | flow-next.dev@2a226be
R14 | 2.0.0: version lockstep, crossEpic removal (BREAKING), mirror regen + audit, CHANGELOG | .5 ·.6 | a2478b0 · ee13019

04

## Where to look — the review checklist

check off as you go · persists locally

### `references/html-artifacts.md` — the contract

Is the design system concrete enough to regenerate the house style from scratch? Tool-name-agnostic (grep AskUserQuestion/Task/spawn_agent: must be empty)? Is §1.4's repo-relative-vs-blob link split right?

### `capture workflow §5.10` — the gate

Config check is a real bash block, not prose. LAVISH_OK guard covers MODE != interactive AND the env-marker family (AUTONOMOUS/FLOW_AUTONOMOUS/FLOW_RALPH/REVIEW_RECEIPT_PATH).

### `plan steps Step 8.5` — timing

Generation fires AFTER the Step-8 refinement loop exits; a later mutation regenerates before the final footer. Link line replaced via marker, never duplicated.

### `make-pr Phase 1.5` — side effects

--dry-run writes nothing; LENS_OK guards every git step (no unguarded add/commit under set -e); exact-file check-ignore; narrow pathspec commit lands BEFORE HEAD_SHA capture; Ralph stdout stays PR_URL= only.

### `flowctl.py` — defaults + alias removal

artifacts block follows the land/work precedent; _CONFIG_KEY_ALIASES emptied with machinery retained; removal regression tests (19 + 5) pin no-fallback/no-redirect/no-deprecation semantics.

### crossEpic prose surfaces

setup workflow, flowctl.md, plan-sync.md, releasing.md, local-dev.md all updated; this repo's own .flow/config.json dropped the stale key (crossSpec kept canonical).

### Codex mirror integrity

references/ copy byte-identical; mirror diff is exactly the canonical prose edits; no spurious R2 ask-block injections (fn-62.6 audit notes in the task summary).

### Committed proof artifact

.flow/artifacts/fn-62-…/spec.html was generated by a FRESH session from the reference alone — spot-check it embodies the contract (self-contained, layered DAG, staleness stamp).

### Site repo (post-merge gate)

flow-next.dev commits 1dd356d + 2a226be are local-only: visual-aids + pipeline pages, both navbars, 2.0.0 site changelog/version. Push them with the release, then tag flow-next-v2.0.0.

05

## Risk register

what could bite later

### high · breaking change exposure

crossEpic removal ships in 2.0.0. Any user config still carrying `planSync.crossEpic` gets default behavior silently (raw-null semantics). The CHANGELOG carries an explicit BREAKING + migration line — make sure release notes surface it prominently.

### med · reference-quality drift

The disclosure reference is the single quality gate for all future artifacts. Edits to it are unguarded by tests — the fresh-session proof was a one-time check. Treat reference changes as design reviews.

### med · mirror staleness

Canonical skill edits require a sync-codex regen; the references/ copy must stay byte-identical. The fn-62.6 audit caught a pre-existing braced-var escape in the setup mirror (noted, out of scope).

### low · lavish coupling

Zero hard coupling by design (detect-on-PATH, pull-only). Worktree = separate session and global ~/.lavish-axi/state.json are documented caveats, not defects.