docs: backfill architecture decision records for earlier decisions - #76
Merged
Conversation
The document-classification ADR introduced in the skip-non-workloads
change was numbered 0001, but it is a late, narrow decision. Backfill the
higher-level decisions that predate it so the ADR log reflects the real
architecture, numbered chronologically.
Records six decisions (terse; each dated to when it was actually made and
marked recorded-retrospectively):
0001 typed Kubernetes decoding + fixed workload kinds (accepted, under
reconsideration — #26)
0002 positional-argument CLI input model, with `-` for stdin
0003 cmd → processor → yamlparser → k8s package layout
0004 golden/approval testing
0005 in-process Run(args, stdin, stdout, stderr) int seam
0006 Conventional Commits + automated releases
CONTRIBUTING.md points contributors (human and AI) at docs/adr/ so the
decisions are read and kept current. The document-classification ADR is
renumbered to 0007 in its own change.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pc6NAURAqjU4LYJx93tgSC
MPV
force-pushed
the
claude/adr-backfill
branch
from
August 9, 2026 06:39
cc9263c to
8eaa3a4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Establishes
docs/adr/and backfills the higher-level architectural decisions that predate the document-classification ADR, numbered chronologically so the log reads as the project's actual architecture story.Each ADR is dated to when the decision was actually made and marked recorded retrospectively (2026-08-08) — the numbers are chronological, the honesty about backfilling is explicit.
-for stdincmd → processor → yamlparser → k8spackage layoutRun(args, stdin, stdout, stderr) intseamPlus a
docs/adr/README.mdindex.Why
The document-classification ADR (added in #54) landed in the
0001slot, but it's a late, narrow decision. The foundational decisions — how images are extracted, the input model, the package layout, the test strategy, the CLI seam, the release process — deserve the low numbers. ADR 0001 is deliberately the most consequential and most contested decision (typed decoding), which is exactly why it's worth recording: #26 and #27–#30 are actively exploring replacing it, and #75 catalogs what it misses.Notes
docs:→ no version bump).0001to0007(separate change on that PR).🤖 Generated with Claude Code
https://claude.ai/code/session_01Pc6NAURAqjU4LYJx93tgSC
Generated by Claude Code