feat(schemas): draw post-apply schema steps after implementation

[nthansen]

What this does

Draws a schema step that runs after implementation (like verify) after the apply node — as a dashed, inferred edge — instead of beside apply as a peer.

Why

OpenSpec's requires: can only name other artifacts. There is no way to say "runs after apply." So authors work around it: point the post-implementation step at the last planning artifact, and state the real order in prose.

spek drew the declared graph literally, so the step landed on apply's level and read as its peer — inviting the exact mistake the schema's runtime precheck exists to block.

Simple example — superpowers-bridge

verify in superpowers-bridge:

• declares requires: [plan]
• its instruction says it "MUST run on a completed implementation"
• apply also requires plan

Before — verify sits beside apply, looking interchangeable with implementation:

      plan
      /  \
   apply  verify      <- peers. wrong.

After — spek infers verify runs after apply and draws it there, dashed:

      plan
       |
     apply
       :               <- dashed = spek's guess, not enforced
     verify

One edge into verify, from apply. The declared plan -> verify is dropped: the path plan -> apply -> verify already carries it, so drawing both says the same thing twice.

(anvil's verify is the same shape — its instruction opens "Produced AFTER apply completes.")

How spek decides

A step runs after implementation when both:

1. it needs everything apply needs, and
2. apply needs nothing from it.

~82% precise across 88 community schemas. It can misread a planning artifact that happens to depend on everything apply does — so the edge is dashed and marked a guess, never asserted as a rule openspec blocks on.

The note a reader sees

Click a derived step:

Assumed to run after apply. spek's guess, since it relies on the same artifacts apply does — not something openspec enforces.

Notes for review

• Breaking (view only): a schema declaring an artifact literally named apply no longer collapses against the synthesized apply step (superspec does this).
• No new CLI call, no filesystem read — the rule reads the requires graph spek already has.
• Forward path: when OpenSpec adds a way to declare this ordering (#1456), it is one branch in resolveImplementationOrdering — a declared ordering renders as an ordinary solid edge, pinned by a test.
• Gates: type-check, lint, and the core / ui / web suites pass (340 / 24 / 182).

🤖 Generated with Claude Code

[kewang]

Thanks for this — the derived-ordering rule is carefully thought through, and I appreciate that the guards in 1.7 each name the input that motivated them. The key-vs-id split in schemaView.ts is the right call, and the drawableEdges origin-aware reduction reads well.

Fourteen things below. Note first that the branch is behind master, and master requires branches to be up to date before merging — so a merge from master is needed either way, and it will surface the first item.

1. border-accent/30 will fail the contrast guard once master is merged in

packages/web/src/components/SchemaFlow.tsx:105 (and three sibling spots) adds border-accent/30. master's packages/web/src/styles/contrast.test.ts scans every packages/web/src/**/*.tsx for border-<token>/<alpha> and fails on any pair that is neither measured nor listed in DECORATIVE_BORDERS — which today holds only accent/40 and status-warning/40. So Node gates goes red the moment the branch is up to date, and it can't reproduce on the branch as it stands.

Simplest fix is to reuse the existing accent/40; otherwise add "accent/30" to DECORATIVE_BORDERS with the reason (the callout's own text names the state, which is the exemption the table is for).

2. postApplyArtifacts and the new types are missing from the package index

packages/core/src/index.ts:95-102 exports levelArtifacts and resolveImplementationOrdering (plus type OrderingSource), but:

• postApplyArtifacts isn't there at all, so task 1.5's "and the package index" is only half done.
• ArtifactLevelling, RequiresNode, OriginEdge and OriginNode aren't exported either. A consumer who does import { levelArtifacts } from "@spekjs/core" can't name the return type or resolveImplementationOrdering's second parameter without reaching into the subpath.

This ships as a minor on the core line, so it's worth getting the surface right in one go.

3. The post-hoc apply-level override can contradict the graph

packages/web/src/utils/schemaView.ts:202-208 recomputes apply's level from new Map(steps.filter(s => !s.isApply).map(s => [s.id, s.level])) — keyed by declared id, after keyOf/incoming have already resolved edges by key.

On the duplicate-id input the key indirection exists for, the two disagree. With artifacts = [{id:"p"}, {id:"x", requires:["p"]}, {id:"x", requires:[]}] and apply.requires = ["x"], the graph levels apply at 3 (its edge came from the first x), then the override recomputes from {p:1, x:1} — the second x won the map — and drops apply to 2. Apply then sits in the same row as its own parent, and layoutGraph draws an arrow with dy <= 0.

In every other case the override just recomputes the level the graph already produced. I think this block can go away entirely now that apply is levelled as a graph node; if it needs to stay, it should key by key.

4. Duplicate parallel edges survive the reduction and collide downstream

packages/core/src/schema-flow.ts:287 — a schema listing the same id twice in one step's requires produces two FlowEdges with the same from, and impliedBy strips both direct hops from its start stack so neither is judged implied. layoutGraph's anchor() keys its slot map by "${parent.key}->${child.key}", so both get the same p0/p3 and the same path string, and SchemaGraph renders two <path> siblings with the same React key (console warning, stacked arrowheads). Inherited from drawableRequires, but it comes along into the new path.

5. The archive step's displayed requires can list the same name twice

packages/web/src/utils/schemaView.ts:246 uses leaves.map((s) => s.id) while incoming correctly uses s.key. A schema with a declared artifact named apply that nothing requires, alongside an apply phase that nothing requires, has both as leaves — the detail panel then reads requires apply, apply, and so does the <title>. The comment just above already acknowledges that a leaf's id doesn't always name the step the edge points at; the list could dedupe or disambiguate.

6. closureOf's doc promises something the code doesn't do

packages/core/src/schema-flow.ts:97 says "including the seeds themselves", but the loop's !requiresOf.has(current) guard continues before seen.add(current). Both current call sites pre-filter, so nothing is wrong today — but the obvious next caller is one seeding with a raw apply.requires, which is exactly the field the doc talks about, and it would silently change what the resolved.every(id => needs.has(id)) superset test means.

7. schemaLayout.ts:257's comment now says the opposite of the code

"why a derived edge may not imply a declared one away" is left over from 9490bb6, which d900865 reversed. drawableEdges' own doc now says declared and derived hops are counted alike, and there's a test pinning it (layoutGraph: a redundant declared edge is reduced away by the derived path). As written, the comment invites someone to "fix" the behaviour back.

8. CLAUDE.md:217 still points at the dead function

It says the diagram draws drawableRequires, which after this PR has no production caller; the schema-flow export list a few lines up (:204) lists drawableRequires but not drawableEdges. Since CLAUDE.md is meant to describe master's implementation, both send a reader to the wrong place.

9. DERIVED_EDGE_MEANING has three surfaces but only two readers

packages/web/src/utils/schemaView.ts:80's comment says three surfaces read it, but only two do (SchemaGraph.tsx:123 and the legend at SchemaFlow.tsx:217). The selected-step detail at SchemaFlow.tsx:106-111 spells the sentence out inline. That's the most-read of the three, and the drift the constant exists to prevent — especially given the comment anticipates editing it when OpenSpec #1456 lands.

10. drawableEdges and drawableRequires are one traversal written twice

packages/core/src/schema-flow.ts:257 and :314 build the same childrenOf map, run the same "reachable without the direct hop" DFS with the same seen guard, and apply the same declared.has(...) && !implied(...) filter. Only drawableEdges is reachable from the app, yet the eight tests (cycle termination, undeclared-entry drop, declared-order preservation, levelling invariance) all sit on drawableRequires and no longer exercise the live rule. drawableRequires can delegate — wrap each id as {from, origin: "declared"}, map the result back — leaving one traversal and one test suite over the code that runs.

11. OriginEdge.from changes meaning halfway through drawableEdges

packages/core/src/schema-flow.ts:263 stores outgoing adjacency in an OriginEdge, whose from is documented as the prerequisite — so inside childrenOf it holds the successor, and impliedBy's e.from !== to reads backwards. A { to, origin } shape, or a plain Map<string, string[]> for adjacency, removes the trap at no cost.

12. The same small graph is walked four times per render

resolveImplementationOrdering builds applyContext at :183; postApplyArtifacts rebuilds the identical requiresOf/beforeApply and additionally runs a full levelArtifacts(artifacts) at :141 purely for the cyclic flag; buildFlowSteps runs levelArtifacts again on the step graph, and drawableEdges runs once there and once in layoutGraph. applyContext exists precisely so "the two rules cannot disagree" — hoisting it and the cyclicity answer up and passing them down keeps that guarantee and collapses the traversals.

13. The derived edge's <title> is hard to reach

packages/web/src/components/SchemaGraph.tsx:123 — hit-testing on a fill="none" path covers only the painted stroke, and stroke-dasharray="5 4" removes 44% of a 1.5px line. Under max-w-full on a phone the target is sub-pixel. A transparent wide companion path with pointer-events: stroke would make it reachable; otherwise the meaning really only lives in the legend and the detail panel.

14. Three dash patterns for one meaning

SchemaGraph.tsx:120 uses DERIVED_DASH = "5 4" under a comment about sharing the archive node's vocabulary for "not declared by this schema", the archive node at :165 hardcodes "4 3", and the legend swatch (SchemaFlow.tsx:202) uses Tailwind's border-dashed (3px 3px). The dash is the only non-colour cue carrying that distinction, so either export the archive pattern alongside DERIVED_DASH and share it, or drop the "same vocabulary" claim.

Thanks again — happy to talk through any of these.