docs(patches): give every patch a schema-checked upstream status record

.gitignore

@@ -60,3 +60,10 @@ CLAUDE.md
 .spur_job_*.sh
 .spur_ns_*.sh
 spur-*.out
+
+# Per-task agent workspaces. These hold the working log, validation scripts and
+# scratch copies for one piece of work — useful while it is in flight and to
+# re-run later, but they are not repo deliverables. The conclusions that ARE
+# deliverables get written into the patch records and into the reports at the
+# repo root instead.
+work/

.pre-commit-config.yaml

@@ -28,6 +28,19 @@ repos:
       - id: ruff-check
         args: [--fix]
 
+  # Style gate for the hand-written YAML under deploy/docker/ only. check-yaml
+  # above answers "does this parse"; yamllint answers "does it say what its
+  # author meant" — an unquoted ` #` opens a comment, so a PR number mid-sentence
+  # silently truncates the value. Scoped by `files:` rather than turned loose on
+  # the repo: deploy/operator/ holds a much larger body of existing k8s YAML and
+  # is left alone deliberately. Config in .yamllint.yaml.
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.38.0
+    hooks:
+      - id: yamllint
+        args: [--strict]  # warnings fail too; a hook that exits 0 gets ignored
+        files: ^deploy/docker/.*\.ya?ml$
+
   # Rust formatting gate (needs a local toolchain: rustup + rustfmt). clippy and
   # tests are heavier, so they run in CI (.github/workflows/ci.yml, job `rust`).
   - repo: local
@@ -39,6 +52,21 @@ repos:
         files: ^rust/.*\.rs$
         pass_filenames: false
 
+      # Every patch under deploy/docker/patches/ must have a status record that validates
+      # against its schema and agrees with the index, so a patch cannot be added — or
+      # silently outlive its upstream fix — without saying where it stands.
+      # language: python (not system) so pre-commit builds an env holding the two
+      # deps — the CI lint job installs pre-commit alone, never the project, so a
+      # system hook has no jsonschema. Kept in sync with pyproject's [dev] extra,
+      # which is what the pytest job uses.
+      - id: validate-patch-status
+        name: patch upstream status (schema + index cross-check)
+        entry: python scripts/validate-patch-status.py
+        language: python
+        additional_dependencies: ["jsonschema>=4.18", "PyYAML>=6"]
+        files: ^deploy/docker/(patch\.upstream\.status\.yaml|patches/)
+        pass_filenames: false
+
       # Refuse a commit whose git email is a machine-generated local hostname
       # (git's fallback when user.email is unset), so an internal build-host
       # name can't leak into permanent public history. Skipped in CI.

.yamllint.yaml

@@ -0,0 +1,42 @@
+# Style gate for the hand-written YAML under deploy/docker/ (the patch status
+# records and their index). check-yaml already answers "does this parse"; this
+# answers "does it say what its author meant".
+#
+# Scoped by the pre-commit hook's `files:`, not from here — the k8s manifests and
+# Helm charts under deploy/operator/ are a much larger body of existing YAML and
+# are deliberately left alone for now.
+#
+# Run by hand over the same set:
+#   yamllint $(git ls-files 'deploy/docker/**/*.yaml')
+
+extends: default
+
+rules:
+  # The records quote upstream verbatim — issue titles, engine error strings,
+  # call chains — and those have to stay byte-exact to stay greppable, so the
+  # limit is set where it catches a runaway line without asking anyone to reflow
+  # a fact. 80 (the default) is unusable here; the longest line today is 156.
+  line-length:
+    max: 160
+    allow-non-breakable-words: true  # a bare URL should not have to wrap
+
+  # These are single-document files by construction; the schemas have no notion
+  # of a multi-doc record, so a leading `---` would be noise on all 27 of them.
+  document-start: disable
+
+  # This one is load-bearing, not cosmetic. In YAML an unquoted ` #` opens a
+  # comment, so `action: Get #2725 reviewed; ...` silently parses as `Get` and
+  # the rest of the sentence is discarded. Eleven values were losing text that
+  # way before this hook went in — every one of them a PR number mid-sentence.
+  comments:
+    require-starting-space: true
+    min-spaces-from-content: 2
+
+  # Warnings are failures: a hook that prints and exits 0 teaches people to
+  # ignore it.
+  truthy:
+    level: error
+  braces:
+    level: error
+  brackets:
+    level: error

deploy/docker/Dockerfile.vllm

@@ -33,7 +33,9 @@ RUN if [ "${BUILD_AITER}" = "1" ]; then \
 # Apply patches/vllm/ (general PD-transport / scheduler fixes) then patches/
 # vllm-dsv4/ (DSv4-specific: moriio_dsv4 {hybrid_blocksize, sparse_backend,
 # noncontig_register} + aiter flydsl). Each patch no-ops if its anchor is absent,
-# so a base bump degrades gracefully. legacy/ is upstream on this base, not applied.
+# so a base bump degrades gracefully. The retired legacy/ patches have moved to
+# patches/archived/vllm-dsv4/ (recorded in patches/archived/patch.archived.yaml) and are
+# no longer copied into the image at all.
 #
 # Removed on v0.25.1 (were no-op here): the three GLM-5.1 moriio patches
 # patch_moriio_dsa_write.py, patch_moriio_hetero.py and patch_vllm_moriio_blocksize.py.