| 1 | --- |
| 2 | name: vendored-assets |
| 3 | description: Vendored assets. Use when importing or updating checked-in third-party or externally generated JavaScript, CSS, registries, schemas, snapshots, or Scalar, Swagger, and MIME artifacts. |
| 4 | --- |
| 5 | |
| 6 | Treat upstream artifacts as supply-chain inputs. Change their generator or |
| 7 | documented import source, then regenerate; generated output is review evidence, |
| 8 | not an editing surface. |
| 9 | |
| 10 | ## Workflow |
| 11 | |
| 12 | 1. **Trace ownership.** Identify the artifact, generator or exact import |
| 13 | procedure, upstream source/version, license, consumers, tests, and shipped |
| 14 | package or bundle. Search by asset and upstream project name to find current |
| 15 | packaging scripts, generated artifacts, consumers, and history. |
| 16 | Continue when every input and consumer is accounted for. |
| 17 | 2. **Pin provenance.** Resolve moving URLs, tags, branches, and omitted versions |
| 18 | to an immutable release or artifact. Record project, version, path or URL, |
| 19 | and digest in the generator or maintenance header. Omit a digest only when |
| 20 | another enforced immutable source is recorded. |
| 21 | Continue when a future run cannot silently select different bytes. |
| 22 | 3. **Clear the license gate.** Verify release metadata, license files, bundled |
| 23 | notices, and the license trail retained in the distributed form. |
| 24 | Continue when every distributed artifact has a verified retained license trail. |
| 25 | 4. **Regenerate.** Improve the generator or import reference first. Recover an |
| 26 | exact procedure for generatorless assets; add a deterministic script only |
| 27 | for recurring updates. Record a one-off procedure beside the artifact. A |
| 28 | clean rerun must produce no diff. |
| 29 | 5. **Audit the complete diff.** Account for behavior, URLs and runtime fetches, |
| 30 | source maps, notices, encoding, format changes, and additions or removals. |
| 31 | For browser assets, also read [browser-assets.md](browser-assets.md). |
| 32 | Continue when every change is attributable and suspicious content is resolved |
| 33 | or reported. |
| 34 | 6. **Clear test and size gates.** Record byte sizes before and after, use |
| 35 | focused consumer tests, and compare bundle size or composition when shipped |
| 36 | JavaScript, CSS, or registry output changes materially. Compare that output |
| 37 | against the pre-update revision rather than measuring only current size. |
| 38 | Continue when focused checks pass and every non-trivial size delta is explained. |
| 39 | 7. **Close release impact.** Apply root changeset routing for consumer-visible |
| 40 | behavior, browser support, wire data, or meaningful shipped-size changes. |
| 41 | Generated sections owned by barrels, AI docs, or migration tooling remain |
| 42 | with the owners named in root instructions. |
| 43 | |
| 44 | The task is complete when every input and consumer is accounted for, provenance |
| 45 | and licenses are immutable and retained, regeneration is deterministic, every |
| 46 | output change and non-trivial size delta is explained, focused checks pass or |
| 47 | are reported as not runnable, and release impact is recorded. |