tepichord/milner
1
1
Fork 0
Code Issues 8 Pull requests 5 Projects 1 Releases Packages Wiki Activity Actions

Clean up OPERATIONS.md #69

Merged
tepichord merged 9 commits from feat/66-clean-up-operations-md into main 2026-09-17 17:56:58 -07:00
Conversation 1 Commits 9 Files changed 40 +3282 -3202
tepichord commented 2026-09-17 15:19:13 -07:00
Owner
Copy link

Closes #66

Automated PR created by forgejo-done adapter.

Closes #66 Automated PR created by forgejo-done adapter.
Split the 3,100-line OPERATIONS.md into domain-specific files under docs/,
keeping OPERATIONS.md as an index + §1 (What lives where) + §8 (Bring-up
order). Delete the duplicate §13 bring-up order (§8 is authoritative).

Files created:
  docs/tailscale.md       — §2 admin console, §3 operator bootstrap, §6 client devices
  docs/vault.md           — §4 Vault apply/init/unseal/run
  docs/pocket-id.md       — §5 Pocket ID OIDC provider
  docs/headlamp.md        — §7 Dashboard Headlamp
  docs/woodpecker-ci.md   — §9 Woodpecker CI
  docs/storage.md         — §10 Storage
  docs/durable-volumes.md — §11a–§11e protection, teardown, drills
  docs/preview-environment.md — §11h preview router/console/TTL/teardown
  docs/logging.md         — §12 VictoriaLogs
  docs/history.md         — §11f migration record, §11g open questions

Fix stale §N cross-references across the repo (7 rows from the plan's
stale-pointer table plus additional discovered references). Every reference
now uses file-qualified docs/<domain>.md §N form.

Add a pytest cross-reference guard (test_cross_references_resolve) that
scans all markdown files and verifies every file §N reference resolves to a
heading in the named file. Retarget existing documentation guards
(test_runbook_carries_no_volatile_identity_literals, test_runbook_keeps_its_tokens_out_of_argv)
to scan all RUNBOOKS. The vk call-site window is reworked to check the
preceding two lines across all runbooks (since vk may live in docs/vault.md
while call sites live in docs/pocket-id.md/docs/woodpecker-ci.md).

Refs: #66
The split moved OPERATIONS.md sections into docs/, but the relative
link paths in zot/README.md and worker/README.md were left pointing
at paths relative to the repo root instead of relative to the file's
own directory.

Refs: #66
The split left several references pointing at the wrong file because the
old section numbers were already stale:

- README.md, ARCHITECTURE.md and local-path/values.yaml cited the teardown
  procedure as §9 (Woodpecker CI); it lives in docs/durable-volumes.md §11c,
  and the PV-patching detail in §11e. The plan's stale-pointer table listed
  these; they were mapped to docs/woodpecker-ci.md §9 instead of corrected.
- .gitignore, the secret-extension Dockerfile and tests/test_static.py still
  named OPERATIONS.md (or bare OPERATIONS) for §9d/§9e/§9k and §12d, which
  moved to docs/durable-volumes.md and docs/logging.md.
- docs/pocket-id.md cited the storage classes as §8c; they are §10c in
  docs/storage.md.
- The OAuth reference in .env.example is the registration step, §9a.

Refs: #66
test(docs): scan every tracked file for unresolvable §N references
All checks were successful
ci/woodpecker/pr/gates Pipeline was successful
Details
7c32ddb2aa 
The cross-reference guard only read `git ls-files '*.md'`, so stale
pointers in .gitignore, Dockerfiles, shell scripts and manifest comments
were invisible to it — exactly the uncovered form the plan's pre-mortem
warned about. Scan every git-tracked text file instead, flag the bare
`OPERATIONS §N` form, and assert at least one reference was checked so
an empty scan cannot pass vacuously.

Refs: #66
tepichord commented 2026-09-17 16:14:17 -07:00
Author
Owner
Copy link

Merge changes from main

Merge changes from main
tepichord added this to the MVP project 2026-09-17 16:20:17 -07:00 
Commit c0d5097 moved the set-credential.sh, values.yaml and
zot-htpasswd.yaml references to the split docs, but missed README.md —
and it evaded tests/test_static.py's cross-reference guard because the
filename is written in backticks there, so `OPERATIONS.md` §N never
matched the `file.md §N` pattern. §9k now lives in
docs/woodpecker-ci.md and §4c-ter in docs/vault.md; OPERATIONS.md keeps
only §1 and §8.
refactor(zot): drop the duplicate local declaration in verify (#69)
All checks were successful
ci/woodpecker/pr/gates Pipeline was successful
Details
ci/woodpecker/pull_request_closed/cleanup Pipeline was successful
Details
25c37d99d5 
`code` is already declared in verify's opening `local rc=0 cleartext
stored cond code`, so the second `local code` before the registry probe
declares nothing.
tepichord deleted branch feat/66-clean-up-operations-md 2026-09-17 17:56:58 -07:00
tepichord referenced this pull request from a commit 2026-09-17 17:57:00 -07:00
Clean up OPERATIONS.md (#69)
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
blocked

   
bug

Something is not working

  
duplicate

This issue or pull request already exists

  
effort
high

  
effort
low

  
effort
medium

  
effort
minimal

  
enhancement

New feature

  
help wanted

Need some help

  
invalid

Something is wrong

  
pr
feedback
Used for PRs, indicates that feedback has been given and agent needs to make changes

  
pr
reviewing
Used for PRs, indicates that a human is waiting to review the pull request, no action needed by the agent

  
question

More information is needed

  
status
backlog
Ignore, no work needed yet, human will assign this work by changing to status/planning

  
status
document
Record findings, create flashcards, and document knowledge in knowledgebase for the future

  
status
done
Completed when PR is merged, no more work needed.

  
status
implement
Make the code changes. Should be done by a faster and cheaper model

  
status
pending
Give human a chance to review planning details

  
status
planning
Ready to begin. Fill out implementation details and things like acceptance criteria, etc. A smarter thoughtful llm should be delegated for this

  
status
reviewing
PR is created and feedback loop begins between human and agent

  
waiting

   
wontfix

This won't be fixed

No labels
blocked
bug
duplicate
effort
high
effort
low
effort
medium
effort
minimal
enhancement
help wanted
invalid
pr
feedback
pr
reviewing
question
status
backlog
status
document
status
done
status
implement
status
pending
status
planning
status
reviewing
waiting
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
MVP
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
tepichord/milner!69
No description provided.