docs(solutions): committed-bundle attribution + SBOM hygiene

[marcusrbrown]

Captures the reusable lessons from PR #978 (deterministic, committed third-party notices + CI SBOM) as a workflow-issue solution doc, and cross-links it into the build/release doc family.

New doc

docs/solutions/workflow-issues/committed-dist-attribution-and-sbom-hygiene-2026-06-21.md — seven rules:

• If the bundle is committed, the attribution is committed too — verify it under the same dist-sync gate, don't exempt it with a CI carve-out.
• Generate deterministically so the dist-diff gate is the reproducibility proof.
• Fail closed on a total collection failure, not on benign per-dependency gaps.
• Fix the file model, don't exempt the file — the remove-the-exception-don't-add-a-drift-check meta-rule.
• ignorePaths is a scan exclusion, not a commit filter — Renovate's postUpgradeTasks already rebuilds dist, which is what makes removing the carve-out safe.
• Ship the SBOM as a non-blocking CI artifact (CycloneDX via pnpm sbom), separate from the human-readable notice.
• Probe empirically before assuming a root cause — the file was already deterministic; the defect was process. A high-confidence reviewer "scoped-package collision" finding was a verified false positive.

Cross-links

Bidirectional with the closest siblings: harness-base-version (the remove-the-exception meta-rule) and gateway-docker (the build-time-invariant + CI-self-check pattern), plus one-way links to the fail-closed canon, Renovate/versioned-tool, and dist-rebuild-verification docs.

Docs-only; no source or dist impact.

[fro-bot]

Verdict: PASS

Docs-only change: adds one workflow-issue solution doc (committed-dist-attribution-and-sbom-hygiene-2026-06-21.md) and two one-line bidirectional cross-links into sibling docs. No source, dist/, test, or public-API surface is touched, so there is no runtime regression or security exposure.

I verified the load-bearing technical claims against the live repo rather than taking the doc at face value:

• All five cross-linked targets resolve (harness-base-version, cross-libc-build-and-release-safety, versioned-tool-config-plugin-pattern, gateway-docker-runtime-resolution-crash-loop, tool-binary-caching-ephemeral-runners), and the two sibling edits make the linkage bidirectional.
• .github/renovate.json5 matches the doc: ignorePaths: ['dist/**'], postUpgradeTasks.commands: ['pnpm install', 'pnpm run build', 'pnpm run fix'], executionMode: 'branch'.
• .github/workflows/ci.yaml dist-diff gate matches the quoted snippet (git diff --ignore-space-at-eol dist/), confirming the "unconditional gate, no renovate carve-out" framing.
• Frontmatter schema (title, date, problem_type, component, severity, applies_when, tags) is consistent with the sibling workflow-issue doc.

Blocking issues

None

Non-blocking concerns

• Rule 6's actions/upload-artifact@... and the pnpm sbom redirect example are illustrative pseudo-snippets (pinned-SHA elided). Since the SBOM lane is described as aspirational guidance rather than landed CI, this is fine as documentation, but a reader should not copy the @... literally.
• The doc references dist/THIRD_PARTY_NOTICES.txt as the target name; if PR #978 actually landed a different filename, a future reader cross-checking the tree should confirm. Not blocking — this doc captures the lesson, not the canonical config.

Missing tests

None — documentation-only; no behavior to cover. The doc itself argues (correctly) that the dist-diff gate is the reproducibility proof, so no new test is warranted.

Risk assessment (LOW): Docs-only, additive, no executable paths. Regression likelihood negligible; no security exposure; blast radius limited to the docs tree. All referenced links and config claims verified against the repository.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	27915839762
Cache	hit
Session	ses_114384feeffedfdmqSKXhwBqKK