Design: shard artifacts/requirements.yaml into per-id files so parallel adds never share a region (structural fix for #422)

[avrabe]

Spun out of #422 item 2 (the triage there explicitly deferred this to its own design issue). This is the structural fix for the recurring parallel-PR conflict, as opposed to the discipline (PR #489) and the merge=union debate.

Problem

Every PR that files a REQ appends to the single artifacts/requirements.yaml, so any two in-flight PRs collide on its EOF. Documented + mitigated (PR #489), but the conflict is structural: one append-only file shared by all authors. It has recurred on REQ-184/185, 195/196, 206 (#487), … — a standing tax on the dogfooding loop.

Proposed direction

Let an artifact source be a directory of per-id files in addition to a single file — e.g. artifacts/requirements/REQ-NNN.yaml (one artifact per file), loaded by globbing the dir. Two PRs adding REQ-207 and REQ-208 then touch different files → zero conflict, ever.

Sketch / open questions for design:

• Loader: load_artifacts already walks sources; allow a source path: to be a directory of *.yaml (each a single-artifact or small-list doc). Likely small — the YAML collector already handles multiple files.
• rivet add: when the target source is a directory, write …/REQ-NNN.yaml instead of appending to a file. mutate::append_artifact_to_file becomes "write new file" for dir-sources.
• Migration: a rivet command (or one-shot) to explode an existing requirements.yaml into per-id files, and/or keep both layouts supported so adoption is opt-in per project.
• Ordering/diff: per-file means stable, reviewable diffs (one file = one artifact) and kills the "next id reserved by an unmerged PR" half too (rivet next-id allocates from the local working tree only — hands out IDs already claimed by open PRs/branches (logical collision, distinct from #422) #479) — though id allocation still needs the cross-ref awareness from rivet next-id allocates from the local working tree only — hands out IDs already claimed by open PRs/branches (logical collision, distinct from #422) #479.
• Trade-off: many small files vs one big file (tooling, grep, review). Worth weighing; could be scoped to high-churn types (requirements) only.

This is behaviour-changing for the artifact layout, so it wants a design pass before code. Filing as the tracked design issue #422 asked for; not implementing unilaterally. Found via the hourly dogfooding loop (the heaviest generator of these conflicts).

[avrabe]

Triage pass (issue-triage agent run 2026-06-05).

Premise confirmed against main: the friction is real and recurring (REQ-184/185, 195/196, 206/#487, and the new REQ-208/#489-vs-#490 collision in the same hour the design issue was filed). And the body itself frames this as "wants a design pass before code; not implementing unilaterally" — which is exactly the call this is.

But because it's a design issue, the done-state isn't "code merged"; it's "decisions recorded and the next implementation issue can be branched cleanly from them." The body lists four open design questions (loader semantics for a directory source; rivet add write semantics; migration path; ordering/diff/scope trade-off) and the autonomous pickup rule needs each to land as a yes/no answer with a testable artifact attached.

Could you add an explicit ## Acceptance Criteria block? Sketch — feel free to revise / re-scope:

## Acceptance Criteria — design (this issue)
- [ ] **Decision: loader.** A source `path:` pointing at a directory MAY/MUST load every `*.yaml` under it as artifacts (one artifact per file, or small-list docs). Choose: recursive or one level; ordering = lexicographic by filename for stable diffs. Recorded in `docs/design/sharded-artifact-sources.md` (or a new ADR), with a fixture project under `tests/fixtures/sharded-source/` that loads green and a unit test asserting equivalence with a single-file source of the same artifacts.
- [ ] **Decision: `rivet add` write semantics.** When the target source is a directory, `rivet add` writes `<dir>/<ID>.yaml` (one artifact per file). When it's a single file, behavior is unchanged. Documented + one regression test per branch.
- [ ] **Decision: migration.** One of (a) `rivet migrate split-source <file>` explodes an existing list-file into per-id files; (b) both layouts supported indefinitely, opt-in per project; (c) hybrid (default tooling on dir-source, file-source kept working). Decision recorded in the design doc with rationale; if (a), the command's own AC lives in a follow-up implementation issue.
- [ ] **Decision: scope.** Whether this lands for *all* artifact types or only high-churn ones (requirements). Recorded.
- [ ] **Out-of-scope (deferred to follow-up issues):** the actual loader/`rivet add` implementation; the migrate command (if chosen); cross-ref id allocation (covered by #479); the `requirements.yaml merge=union` debate (covered by #422).
- [ ] **Linkage:** the design doc references #422 (parent), #479 (id-allocation half), #489 (the discipline mitigation), and the recurring conflict examples (REQ-184/185, 195/196, 206/#487).
- [ ] Commit trailer: `Refs: #422, #479, #489` on the design-doc PR; `Trace: skip` is acceptable since the design doc itself is `docs` (per AGENTS.md exempt types).
- [ ] **Definition of done for *this* issue:** the design doc is merged, and a child implementation issue is filed referencing this one with its own implementation-shaped AC (loader + `rivet add` + tests). Closing this issue means "design pinned, work tractable elsewhere," not "code shipped."

If you'd rather skip the design-doc step and go straight to an implementation slice (e.g. "loader accepts a directory source, rivet add writes per-id files, leave migration for later"), say so and the AC shape collapses to the standard implementation form — fixture project, regression tests, golden-file diff equivalence, commit trailers, cargo test + rivet validate green.

Process side-rail (same as the other open triage threads this week): https://pulseengine.eu/blog/ is still HTTP 503 (the site's TLS cert is expired — same symptom flagged on #420 and noted in earlier triage comments on #468 / #436 / #431 / #422 / #408 / #479 / #482 / #488). The binding workflow guidance can't be consulted, so no PR will land from this triage run regardless. Comment is the AC ask only.

Not implemented this run.

---

Generated by Claude Code — issue-triage agent run 2026-06-05.

---

Generated by Claude Code