Reframe dev-loops as a state-graph control surface

[mfittko]

Summary

Adds The State Graph Is the Surface, an article positioning dev-loops against Ralph loops, Karpathy-style evaluated loops, and graph engineering, plus a matching Slidev deck in the repository's existing dark-glass visual language. Both are linked from docs/index.md.

The reframe: dev-loops is a graph/loop control surface. The lifecycle graph models the lifecycle of a change, not the age of the codebase, so greenfield and brownfield differ in context package, invariants, and verification burden rather than in control architecture. The deferred Phase 7 second-repository pilot stays conceptually separate — it is a reproducible portability proof, not the only evidence of cross-context use.

GitHub is presented as the current tracker/review/evidence backend, preserving the exact v1 seam boundary: issues and boards have a provider seam with GitHub as the built-in default, while PRs, review threads, CI, and Copilot remain GitHub-coupled.

This is a lightweight PR: it closes no issue, and this description is the spec-of-record.

Scope and context

Boundary: documentation content only. No runtime code, no configuration, no contract text.

• docs/articles/the-state-graph-is-the-surface.md — the new article.
• docs/presentations/state-graph-surface-presentation.md — the matching Slidev deck.
• docs/index.md — two index entries pointing at the above.

Out of boundary: the strict Markdown-to-HTML article renderer, the GitHub Pages publication list, and every runtime path. Nothing outside docs/ is touched.

Acceptance criteria

• The article and deck describe dev-loops as it actually is: claims about the lifecycle graph, conductor routing, the Copilot/reviewer state graphs, the PR lifecycle, and the tracker seam match the contracts that own them.
• The v1 backend boundary is stated accurately — provider seam for issues and boards, GitHub-coupled for PRs, review threads, CI, and Copilot.
• The greenfield/brownfield claim is presented as lifecycle-of-a-change, and the deferred second-repository pilot is not presented as the sole evidence of cross-context use.
• Both artifacts are reachable from docs/index.md, and every relative link in the added files resolves.
• The deck renders without slide overflow.

Definition of done

• npm run verify green, CI green.
• Draft gate clean at the reviewed head.
• No file outside docs/ modified.

Non-goals

• Extending the Markdown-to-HTML article renderer.
• Adding either artifact to the GitHub Pages publication list.
• Any runtime, contract, or configuration change.

Open questions and risks

• The article and deck assert facts about contracts that continue to change. The draft gate's contract-surface angle already caught two: a lifecycle diagram missing the legal Refinement -> IssueIntake edge, and an authorization enum written as permitted/needs confirmation/forbidden rather than the contract's authorized | needs_confirmation | not_authorized. Both are corrected here. Nothing mechanically re-checks these claims when the contracts move, so the same drift can recur.
• The deck states the v1 seam boundary. If the provider seam widens before v1, the boundary slide goes stale with no test to catch it.
• Neither artifact is on the Pages publication list, so the rendered output is not exercised by the site build.

Validation command

npm run verify

Content was additionally checked against the bundled articles and existing presentations, and against the public routing contract, lifecycle model, conductor routing, Copilot/reviewer state graphs, PR lifecycle contract, and tracker seam contract. A separate 14-slide PowerPoint rendering was generated, all slides rendered, the montage visually inspected, and the slide-overflow test passed.

[mfittko]

Gate fan-out findings: draft_gate

Reviewed head: 0411b4c

Worth fixing now (2)

• contract-surface: Diagram 2 renders 13 of the 14 legal lifecycle edges but omits Refinement -> IssueIntake, which LIFECYCLE_TRANSITIONS[REFINEMENT] in packages/core/src/loop/lifecycle-state.mjs declares legal, so the diagram under-states the transition graph its caption claims to show. — deferred
  • files: docs/articles/the-state-graph-is-the-surface.md
• contract-surface: The slide labelled "Canonical state dimensions" lists the authorization values as "permitted, needs confirmation, or forbidden", but skills/docs/public-dev-loop-contract.md owns that enum as authorized | needs_confirmation | not_authorized; "forbidden" also implies a permanent denial, whereas the contract routes a not-authorized state to stop_blocked_or_not_authorized, which stops for a human decision that can clear it. — deferred
  • files: docs/presentations/state-graph-surface-presentation.md

[mfittko]

Gate review: review

Reviewed head SHA: 2fe1f451f29eac7419f1ece9e0e794fcb394d9b4
Verdict: clean
Execution mode: inline_single_agent — smoke B3 pi review round (dev-loop smoke scenario B3)

Findings summary: smoke B3 pi review round: 1 medium + 7 low informational findings, no high-severity; verdict clean

Body-filed findings (no in-diff location):

low (pr-comments): PR description mixes review-verdict/evidence content into the body: the 'Open questions and risks' section narrates what the draft gate's contract-surface angle already caught (a process/verdict record), and the closing paragraph asserts unverifiable evidence claims ('14-slide PowerPoint rendering was generated, all slides rendered, the montage visually inspected, and the slide-overflow test passed', 'Content was additionally checked against...'). Per the review contract, verdict status and evidence belong in the review verdict, not the PR description. The rendering/montage/overflow claims are also not reproducible from anything in the PR or repo (no artifact or script referenced), so a reviewer cannot verify the 'deck renders without slide overflow' acceptance criterion from the description alone.
Recommendation: Move the gate-catching narration and evidence assertions into the review verdict; link (or commit alongside) the overflow-check artifact or name the exact command used so the claim is reproducible. Not blocking: the claim itself is plausible and the slide count (14) checks out against the deck source.

Next action: none — informational review, no re-gate required

[mfittko]

low (acceptance-criteria): AC 'deck renders without slide overflow' is satisfied only by PR-body attestation (a manually generated 14-slide render, visually inspected). No reproducible check exists in the repo (no slide-overflow test in scripts/ or package.json), and the deck is deliberately not on the Pages publication list, so nothing mechanically re-verifies overflow if content changes later.
Recommendation: Acceptable for a docs-only lightweight PR since the limitation is disclosed in the PR body; if deck drift becomes a recurring concern, add a bounded slide-overflow check to the presentation pipeline.

[mfittko]

low (config-drift): The new deck's frontmatter (theme, colorSchema, class, transition, mdc, css) exactly matches the two existing Slidev decks, so no config drift there. However, the deck relies on the CSS class card-label (first used at line 32, 10+ occurrences) which is not defined anywhere in docs/presentations/style.css — the card labels render as unstyled paragraphs instead of the styled label look the markup implies.
Recommendation: Defer: both sibling decks (applied-dev-loops, process-observability) already use card-label unstyled, so this is a pre-existing shared style.css gap, not drift introduced by this diff. If a follow-up is wanted, add a .card-label rule to docs/presentations/style.css — but that is out of this PR's stated boundary (no style change).

[mfittko]

low (correctness): The article presents the status dimension's values as 'active, waiting, blocked, approval-ready, merge-ready, or done' under 'The public state contract already exposes five dimensions', but the owning contract enum DEV_LOOP_STATUS in packages/core/src/loop/public-dev-loop-routing-contract.mjs:45 also defines 'retrospective_gate_pending'. The PR's own acceptance criterion requires claims to 'match the contracts that own them', and the PR body notes the draft gate already caught two similar enum drifts; this is a third, smaller instance.
Recommendation: Either add retrospective_gate_pending to the enumerated status values (article line 95 and the matching deck slide at docs/presentations/state-graph-surface-presentation.md:124), or soften the prose so it no longer reads as a complete enumeration of the contract's status values.

[mfittko]

low (kiss): The 'Five Planes, One Repeating Traversal' slide invents a new five-plane decomposition (fact/model/control/execution/learning) that appears nowhere else in the PR, the paired article (whose 'resulting stack' is a different six-line summary), or any owning contract. Two competing taxonomies for the same architecture in a matched article/deck pair add reader complexity and create a second unowned drift surface.
Recommendation: Align the deck slide with the article's six-line stack framing, or ground the plane names in an existing contract so future contract changes have a single canonical decomposition to be checked against.

[mfittko]

medium (packaging-runtime): The new article is structurally incompatible with the repo's own strict article renderer (scripts/pages/render-article.mjs): it uses 4 markdown tables (first table row at line 34; also lines 90, 224, 241) which the parser rejects outright (/^[#>|]/ -> 'unsupported markdown construct'), and all 4 mermaid captions (lines 80, 146, 216, 309) lack the mandatory '<!-- figure' region that parseDiagramRegion throws on ('diagram caption must be followed by a "<!-- figure" region'). Every pre-existing article in docs/articles (introducing-dev-loops, dev-loops-deep-dive, how-dev-loops-decided-itself) is rendered via RENDERED_ARTICLES/ARTICLES; this one cannot ever be added to those lists without a rewrite or a renderer extension, and the renderer extension is an explicit non-goal of this PR. It is linked from docs/index.md as a peer of articles that all render, so the incompatibility is latent packaging debt: any future 'publish this article' attempt fails hard at build time.
Recommendation: Either reformat the article to renderer-compatible markup (replace tables with lists, add '<!-- figure' regions after each mermaid caption per the dev-loops-deep-dive pattern) and add it to RENDERED_ARTICLES/ARTICLES, or add a visible note in the file (or PR body follow-up issue) recording that the markdown is not renderer-compatible and is intentionally unpublished, so the latent build failure is documented rather than discovered later.

[mfittko]

low (semantic-drift): Unevidenced adoption claim: both the article and the deck state the toolset "has already been used successfully in both greenfield and brownfield contexts", but no in-repo doc, decision record, or evidence pointer backs that operational history (no other doc under docs/ or skills/ even uses the greenfield/brownfield vocabulary). The PR body's own AC requires the artifacts to "describe dev-loops as it actually is"; an uncited success claim is the one assertion in these docs that a reader cannot trace to a contract or record.
Recommendation: Either cite the concrete cross-context usage evidence (e.g. a pointer into the decision log, migrating-to-dev-loops.md, or a retrospective) or soften to capability language ("the same control model carries both contexts") so the claim describes design rather than an unverifiable usage history. Mirrored claim at docs/presentations/state-graph-surface-presentation.md:314.

[mfittko]

low (ui-validation): The 'deck renders without slide overflow' acceptance criterion is validated only by prose in the PR body (an external 14-slide PowerPoint render described as inspected); no committed artifact or repo-reproducible command backs it. Existing decks ship review-notes companions (docs/presentations/applied-dev-loops-review-notes.md, process-observability-review-notes.md) but this deck ships none, so the render evidence is not independently checkable from the tree.
Recommendation: Add a brief review-notes companion (matching the existing deck pattern) or record the exact render/overflow-check command in the deck or PR so the overflow claim is reproducible; otherwise accept the prose-only evidence as a known docs-PR limitation.