flow-next pr render lens·diff-derived, verified against the spec's r-id export·spec FLOW-12

fn-62 — Optional HTML artifact mode: spec & PR render lenses

fn-62-optional-html-artifact-mode-spec-pr → origin/main · 19 commits · release 2.0.0
+2,515 −343
diff
64
files
14 / 14
r-id coverage
8 / 8
tasks done
~1,189
human-review lines*
ship
completion review

* 2,515 added lines minus generated/mechanical churn: Codex mirror (+608), committed proof artifact (+553), dogfood flowctl copy (+26), .flow state (+133), version manifests (+6).

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 −01 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 −1010 files
  • skills/flow-next-capture/{SKILL,phases,workflow}.mdspec lens post-write + LAVISH_OK interactive-only guard
  • skills/flow-next-plan/{SKILL,steps}.mdregeneration after the Step-8 refinement loop exits
  • skills/flow-next-make-pr/{SKILL,phases,workflow}.mdPhase 1.5 PR lens: LENS_OK guards, exact-file check-ignore, narrow commit
  • skills/flow-next-setup/workflow.md + templates/usage.mdHTML question (only-if-unset), gitignore choice, lavish offer
▸flowctl + regression testsone config default block; crossEpic alias removal + its removal tests+337 −1984 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 mirrorgeneratedverify sync-codex ran clean — don't line-review+608 −1112 files
  • plugins/flow-next/codex/references/html-artifacts.md (byte-identical) + codex/skills/{capture,plan,make-pr,setup} mirrorsregen 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 −3613 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 −12 files
  • scripts/sync-codex.sh · scripts/install-codex.shsibling cp -R for references/; ~/.codex/references install
▸Mechanicallockstep2.0.0 version surfaces + synced dogfood copy+32 −376 files
  • 3× plugin.json + 2× marketplace.json (2.0.0) · .flow/bin/flowctl.py (byte-identical sync)
▸Process stateflowtask evidence, receipts, captured memories + the committed proof artifact+686 −5016 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-IDCriterion (abridged)TaskEvidence commits
R1Opt-in via setup/config, OFF default; mode off ⇒ no reference load, no artifacts, no sessions, no visible output.15597dd1
R2Progressively disclosed shared reference file + explicit anti-slop design system.2e4a4263 · 5ba324d
R3Markdown/tracker-sync sole source of truth; artifacts regenerable, never parsed back.2 ·.3e4a4263 · c892ae1
R4ONE spec-artifact pathway, state-dependent rendering (spec-only ↔ +DAG/matrix).3c892ae1 · 1235c6d · fce92a1
R5PR artifact diff-derived (never commit messages), R-ID-verified, read-only instrument.43975a0f · 74a4ecd
R6Self-contained single-file HTML, zero external requests, print-friendly.2e4a4263
R7Lavish optional dep: detect-on-PATH; annotate → markdown edit → regenerate.2 ·.3e4a4263 · c892ae1
R8PR artifact never in the annotate loop; autonomous never polls.3 ·.4fce92a1 · 3975a0f
R9Setup ceremony documents + offers lavish-axi on HTML opt-in.15597dd1
R10Spec + PR markdown link their artifacts; GitHub limitation documented.3 ·.4 ·.5c892ae1 · 74a4ecd · a2478b0
R11Fixed regenerable .flow/artifacts/ layout, commit-or-gitignore per project.15597dd1
R12externalflow-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.7flow-next.dev@1dd356d
R13externalflow-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.8flow-next.dev@2a226be
R142.0.0: version lockstep, crossEpic removal (BREAKING), mirror regen + audit, CHANGELOG.5 ·.6a2478b0 · ee13019
04

Where to look — the review checklist

check off as you go · persists locally
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.