test(infra): serialize integration tests — fileParallelism=false

[thewrz]

Closes #73

Summary

• pnpm test:integration runs *.integration.test.ts files in parallel by default. They share a single PostgreSQL instance and race on FK constraints + unique keys, producing non-deterministic local failures (paragraphs_parent_id_fkey, specs_section_source_unique).
• Sets fileParallelism: false on the integration project in vitest.config.ts to serialize test file execution. Unit project untouched.
• Note on divergence from design doc: the approved design at docs/superpowers/specs/2026-05-18-issue-073-design.md specified pool: 'forks' + poolOptions: { forks: { singleFork: true } }. Vitest 4.1.5 (current dep) removed test.poolOptions; applying the doc's diff verbatim triggers a runtime deprecation warning and is silently ignored — verified by running the failing test under that config first. fileParallelism: false is the Vitest 4 replacement (sets maxWorkers=1 internally per vitest/dist/chunks/coverage.DM_a_rWm.js:223). Same intent, current API.

Test plan

• pnpm test:integration — 3 consecutive runs, all 14 files / 95 tests green, no FK / unique-key flakes
• pnpm test (unit) — still parallel, 43 files / 435 tests in 1.09s
• pnpm lint — green
• pnpm build — green
• CI green on PR

Summary by CodeRabbit

• Documentation

  • Added design specs for DOCX cross-reference extraction and for surfacing structural parsing warnings.

• Chores

  • Improved integration-test stability by disabling file-level parallelism for integration runs.
  • Updated development environment settings and added a .worktrees ignore pattern to project ignores.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds three design specification documents (DOCX refs, parse-time warnings, integration-test serialization), disables Vitest integration file parallelism, and updates .gitignore to ignore .worktrees.

Changes

Design planning and test infrastructure

Layer / File(s)	Summary
Integration test serialization docs/superpowers/specs/2026-05-18-issue-073-design.md, vitest.config.ts	Documents race conditions from parallel integration tests and sets fileParallelism: false for the integration Vitest project to serialize file execution.
DOCX cross-reference extraction design docs/superpowers/specs/2026-05-18-issue-027-design.md	Specifies src/parser/refs/ with regex-driven ExtractionRule types, buildStandardRefRules, and extractRefsFromTree; documents wiring DOCX parsing to persist refs into spec_references and test expectations.
Parse-time warnings design docs/superpowers/specs/2026-05-18-issue-068-design.md	Defines typed ParseWarnings (root-continuation, empty-part, no-structure-found), a post-build detection pass populating CsiTree.warnings, and conditional 'parse-warnings' capability exposure without persistence.
Git maintenance .gitignore	Adds .worktrees ignore pattern for Git worktree directories.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• #73 — Integration test serialization and vitest.config.ts change directly address local race conditions on a shared PostgreSQL instance.
• #27 — DOCX cross-reference extraction design matches the proposed refs module and extraction wiring.
• #68 — Parse-time warnings design corresponds to adding typed warnings on CsiTree and capability gating.

Poem

"I nibble specs by moonlit beams,
Docs stitched neat like carrot seams,
Tests now march in single rows,
Worktrees hushed where soft wind blows,
Refs and warnings dream in prose."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: serializing integration tests by setting fileParallelism=false in Vitest config.
Linked Issues check	✅ Passed	The PR fully addresses issue #73 by implementing fileParallelism=false to serialize integration test execution and eliminate DB race conditions while preserving parallel unit tests.
Out of Scope Changes check	✅ Passed	All changes are directly in-scope: vitest.config.ts configuration change for issue #73, and three documentation files (.gitignore addition, design specs for issues #27, #68, #73) that align with roadmap objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-73

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/specs/2026-05-18-issue-027-design.md`:
- Around line 25-39: The fenced code block that begins with the tree listing
starting "src/parser/refs/" is missing a language identifier (triggers MD040);
update the opening fence to include a language tag (e.g., ```text) so the block
becomes ```text and keep the rest unchanged; ensure the closing fence remains
``` and run markdownlint to verify the MD040 warning is resolved.

In `@docs/superpowers/specs/2026-05-18-issue-073-design.md`:
- Around line 86-90: Update the "## Files" section of the design doc to reflect
that this is a newly added file: replace the lines under that heading (the
bullet block containing “- **Modified:** `vitest.config.ts`” and the sentence
“No new files. No deletions. No migrations.”) with accurate metadata indicating
this doc is a new file (e.g., mark as **Added** or **New:** and remove the
contradictory “No new files” statement); ensure the heading text and bullets
consistently state that the design doc itself is a newly added file.
- Around line 26-27: The spec still documents using `pool: 'forks'` and
`poolOptions: { forks: { singleFork: true } }` for the `integration` project
block in vitest.config.ts but the implemented config uses `fileParallelism:
false`; update the spec's Approach, Change snippet, and Acceptance Criteria to
reference `fileParallelism: false` in the `integration` project block (and
remove or replace mentions of `pool`/`poolOptions.singleFork`) so the document
matches the shipped config; search for occurrences in the doc (including the
blocks around the current references and the other affected ranges) and replace
the config example and acceptance text to show `fileParallelism: false` under
the `integration` project.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 202c100d-74a0-4bf4-b8e1-f373fafa8a93

📥 Commits

Reviewing files that changed from the base of the PR and between fee597a and 22601fa.

📒 Files selected for processing (5)

• .gitignore
• docs/superpowers/specs/2026-05-18-issue-027-design.md
• docs/superpowers/specs/2026-05-18-issue-068-design.md
• docs/superpowers/specs/2026-05-18-issue-073-design.md
• vitest.config.ts

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/specs/2026-05-18-issue-073-design.md`:
- Line 1: The document title still references the deprecated "singleFork"
approach but the actual configuration uses fileParallelism: false; update the
heading "Integration Test Race — Serialize via `singleFork`" to accurately
describe the implemented solution (e.g., "Integration Test Race — serialize
tests using fileParallelism: false") and remove or replace any other mentions of
`singleFork` so the doc and the configured behavior (fileParallelism: false) are
consistent.
- Line 66: Update the stale count in the verification line that reads "1.
**Local serial run** — `pnpm test:integration` completes with all 16 integration
files passing." (search for that exact sentence) to reflect the PR's recorded
result (change "16" to "14" and/or include the reported "14 files / 95 tests"
phrasing) so the spec matches the evidence.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b0023f96-ae5d-4d70-96bc-733daa141b6a

📥 Commits

Reviewing files that changed from the base of the PR and between 22601fa and 3c44fce.

📒 Files selected for processing (2)

• docs/superpowers/specs/2026-05-18-issue-027-design.md
• docs/superpowers/specs/2026-05-18-issue-073-design.md

✅ Files skipped from review due to trivial changes (1)

• docs/superpowers/specs/2026-05-18-issue-027-design.md