Skip to content

refactor(generate): make the step graph directly testable and harden it#2105

Merged
dyoshikawa merged 2 commits into
mainfrom
resolve-issue-2082-harden-generate-step-graph
Jul 1, 2026
Merged

refactor(generate): make the step graph directly testable and harden it#2105
dyoshikawa merged 2 commits into
mainfrom
resolve-issue-2082-harden-generate-step-graph

Conversation

@dyoshikawa

Copy link
Copy Markdown
Owner

Summary

  • Follow-up to refactor(generate): enforce shared-file write order via a declarative step graph #2081 / PR refactor(generate): enforce shared-file write order via a declarative step graph #2081, which refactored generate()'s shared-file write ordering into a declarative step graph (dependsOn + writesSharedFile), topologically sorted and validated by resolveExecutionOrder/assertSharedFilesOrdered.
  • Extracts the graph's static shape (id, writesSharedFile, dependsOn) into an exported GENERATION_STEP_GRAPH, separate from the run closures that need a live config/logger. This lets tests exercise resolveExecutionOrder against the real graph instead of a hand-copied stand-in.
  • Restores short rationale comments on each non-obvious dependsOn edge, explaining which shared file forces the ordering (the original PR's prose comments were dropped when the graph became declarative).
  • Adds a test that walks every dependsOn edge and asserts it corresponds to either an actual overlapping writesSharedFile token or the one documented value-dependency (rules reading the skills step's output) — this catches a stale or unjustified edge, and combined with the existing assertSharedFilesOrdered runtime check (which catches a missing edge for a real overlap), the two together keep the declared edges honest in both directions.
  • Adds a test pinning the full execution order of the real graph, so the mcp step's position (2nd → 5th after the refactor) — or any future reordering that changes runtime behavior — is caught rather than silently regressing.

Not addressed (left for a follow-up if needed)

  • Fully automated verification that writesSharedFile enumerates every shared file across all tool targets (proving there's no un-declared overlap) would require cross-referencing each feature's getSettablePaths() per tool target, which is a materially larger undertaking than this hardening pass. The new edge-justification test narrows the risk (no stale/incorrect edges) but doesn't fully close this gap.
  • The two "effectively unreachable" defensive checks flagged in the original issue (if (!skillsResult) throw, get()'s missing-result throw) were left as-is — they're a cheap safety net against future graph regressions and only rated low/nit.

Test plan

  • pnpm cicheck passes
  • New tests: graph well-formedness, edge-justification, and full execution-order pinning, all run against the real GENERATION_STEP_GRAPH
  • Existing generate.test.ts and resolveExecutionOrder tests still pass unmodified

Closes #2082

Extract the generate() step graph's static shape (id, writesSharedFile,
dependsOn) into an exported GENERATION_STEP_GRAPH, separate from the
run closures that need a live config/logger. This lets the ordering
guarantee be tested directly against the real graph instead of a
hand-copied one, restores rationale comments explaining why each
dependsOn edge exists, and adds a test asserting every dependsOn edge
corresponds to an actual writesSharedFile overlap (or the documented
rules->skills value dependency) plus a test pinning the real execution
order, so a future edit that silently drops a shared-file overlap or
reorders steps in a way that changes runtime behavior fails loudly.
… dedupe test stub

Address low-severity review feedback: mark GENERATION_STEP_GRAPH and
its writesSharedFile/dependsOn arrays readonly so the module-level
singleton can't be mutated by a consumer, correct the hooks/permissions
rationale comments to name the actual overlapping shared-file tokens,
and share one stub run() between the two test helpers instead of
duplicating the literal result.
@dyoshikawa
dyoshikawa merged commit 66129b9 into main Jul 1, 2026
8 checks passed
@dyoshikawa
dyoshikawa deleted the resolve-issue-2082-harden-generate-step-graph branch July 1, 2026 06:55
@dyoshikawa

Copy link
Copy Markdown
Owner Author

@dyoshikawa Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Harden the declarative generate() step graph: verify edge direction & writesSharedFile completeness (follow-up to #2081)

2 participants