petal-power/wiki-vault
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4be2c247be
wiki-vault/Sources/Dev/repo-hygiene-remediation.md

12 KiB
Raw Blame History

created path project tags type
2026-05-20 Sources/Dev repo-hygiene-remediation
repo-hygiene
documentation
dev
cleanup
security
audit
git
ansible
project-plan

Goal

Remediate every finding and due-out surfaced by the documentation audit of 2026-05-19/20 (the "guided review of all the project folders" pass), and stand up a lightweight recurring process so the project folders don't drift back into inconsistency.

The audit touched 23 repos across four domain folders, created/fixed ~45 doc files (~4,400 lines), and surfaced a deduped list of ~20 findings spanning security, blocked repos, cross-repo cleanups, and policy decisions. Those findings are the backlog this plan works through. This plan is hygiene-scoped only — it does NOT absorb the unrelated feature/initiative work from the same working session (reflector follow-ups, scene-management deploy, pbs-hub-mcp landing, enricher migration) — those live in their own threads and are cross-referenced below.

Starting Condition (Phase 0 gate)

herbys-dev-setup must be completed before this plan's work begins. The dev-environment hardening that project covers (Proxmox / Tailscale / dev-environment baseline) is the foundation this hygiene work sits on top of — no point hardening repo hygiene on a dev environment that's still being hardened underneath it. Treat Phase 0 as a hard gate: confirm herbys-dev-setup is at completed status before opening Phase 1.

Context — what the audit found

The 23 doc commits are sitting local and unpushed on docs-audit branches (clean repos) or as doc-only commits on existing default branches (dirty repos). Travis reviews via git and pushes/merges himself. The audit also confirmed a structural truth that motivated this plan: documentation drifts silently, and a one-time sweep isn't enough — a recurring review is needed.

Audit commit log (all local, none pushed):

  • homelab: trellis-mcp 7188a4f, vault-mcp 82bccc6, homelab-ansible 61e0f6c, OB1 eab4416, ob1-deploy e6b5e6e, hunyuan3d-sunnie 8c88adc, instamesh-docker 5cff79d
  • pbs: a-review-skill a3accf2, Claude-Code-Scaffolding-Skill 4e062eb, cli-standardization 69681a0, docker-container 8b825e6, dotfiles c03d203, python-uv a3ad752, session-notes-skill 3fe5478, work-index-dashboard 25a0a07, ssh-login-alerter 0de0e9a
  • docker: authelia 31b66d2, authentik fc640be, cloudflared 2f4fc25, n8n 04c995d, traefik 15b42bc
  • root: wiki-vault 570e96f, wiki-context 1435726

Locked Decisions / Conventions

  • md files only. The audit and this remediation touch CLAUDE.md / README.md only unless a phase explicitly says otherwise. Source/config/vendored files are out of scope per-phase unless called out.
  • Travis pushes GitHub-destined repos manually. Gitea-destined repos can auto-push. Audit doc commits all wait for Travis's git review.
  • Doc-role split: README = human onboarding; CLAUDE.md = agent operating guide (concise, gotcha-focused, not a README clone).
  • docker compose stacks get README only, no per-stack CLAUDE.md. Non-git docker dirs need git init before they can be doc'd/reviewed.
  • Audit methodology (reusable for the recurring review): score each doc on accuracy (heaviest) → freshness → internal contradiction → completeness rubric → role fit. Verify documented commands/paths against the real tree; a confidently-wrong doc is worse than a missing one.

Open Items (decisions needing Travis input)

  1. python-uv tracking policy — pure upstream mirror of a5chin/python-uv, zero Travis commits (all 137 recent commits are upstream/dependabot). Decide: live tracker (keep rebasing) vs frozen snapshot (this audit is the cutoff).
  2. OB1 fork policy — upstream community project (Nate B. Jones). README left as upstream-canonical; CLAUDE.md lightly fixed. Same tracker-vs-snapshot question as python-uv; contributor/dependabot PRs may collide with local doc edits.
  3. cli-standardization name vs scope — has outgrown its name (now a full Arch workstation orchestrator, 5 roles). Rename the repo (workstation-ansible? pbs-workstation?) + update gitea remote, OR redefine the name to mean "the standard way we provision a workstation."
  4. docker/authelia secrets — JWT/session/storage-encryption hex committed inline in compose.yml (different from the .env boundary the rest of docker/ uses). Extract to .env, rotate-and-recommit if ever public, or accept as-is for a private repo.
  5. docker/n8n_server (non-git dir) — the live n8n/ stack consumes its external volume (n8n_server_n8n_data). Confirm whether n8n_server/ is retired (remove) or still load-bearing (version-control it).
  6. Recurring-review cadence + owner — who/what drives the periodic guided review (Phase 7). Travis's quip "not sure who is doing the guiding" is the live question: cadence (monthly? per-merge?), and whether it's a skill, a scheduled task, or a manual checklist.

Phases

Phase 0 — Starting condition (gate)

  • Confirm herbys-dev-setup is at completed status. Do not start Phase 1 until it is.

Phase 1 — Land the audit's doc commits

Review and ship the 23 local doc commits.

  • git diff review each docs-audit branch (clean repos) — 12 branches.
  • Review the 11 doc-only commits on existing default branches (dirty repos) — confirm they only touched md files (already verified by the audit, but spot-check).
  • Merge/push per repo following the manual-push rule for GitHub-destined repos; auto-push acceptable for gitea-destined.
  • For dirty repos where the doc commit sits alongside unrelated uncommitted work (ob1-deploy, hunyuan3d-sunnie, instamesh-docker, Claude-Code-Scaffolding-Skill, work-index-dashboard, the 4 dirty docker stacks, wiki-vault), decide how to sequence the doc commit vs the in-flight work.

Phase 2 — Security remediation

  • docker/authelia/compose.yml inline secrets — resolve per Open Item #4.
  • docker/traefik/.env is world-readable (0664) → tighten to 0600/0660.
  • Sweep .env permissions across all docker/* stacks — normalize to 0660 (or 0600).
  • Confirm no other secrets are committed in compose files across the docker domain.

Phase 3 — Unblock un-auditable repos

  • pbs/pbsii + pbs/zero-check-pipeline — dubious .git ownership. Fix via chown -R or git config --global --add safe.directory <path>, then audit their docs.
  • homelab/sshkm — has no .git despite the global CLAUDE.md asserting it exists. Either re-init + push to gitea, or correct the global CLAUDE.md to match reality.
  • docker/ non-git dirs (cloudbeaver, it-tools, n8n_server, obsidian, ollama, postgres) — git init + initial commit with .env gitignored from the start, then README each. Resolve the n8n_server retired-vs-live question (Open Item #5) first.
  • homelab/second-brain + homelab/shared — no .git; decide whether to version-control (they have real content) or leave as local-only scaffolding.
  • pbs/youtube-analytics — zero commits, everything untracked. Initial commit pass, then doc audit.
  • pbs/wordpress-install — finish or stash the dirty staging-branch work (10 modified ansible files), then audit its docs.

Phase 4 — Cross-repo cleanups

  • uv init leftovers (main.py / pyproject.toml / uv.lock / .python-version / .venv/) in ~10 non-Python repos (docker-container, work-index-dashboard, ssh-login-alerter, hunyuan3d-sunnie, instamesh-docker, and the docker stacks authelia/cloudflared/n8n/traefik). Sweep-remove where they're not part of the build path.
  • herbygitea SSH-alias residue — the alias was removed from ~/.ssh/config; the audit caught + fixed lingering references in cli-standardization/CLAUDE.md and dotfiles/README.md. Grep the whole tree (config files, scripts, gitea remotes) for remaining references.
  • Claude-Code-Scaffolding-Skill/project-scaffolding/SKILL.md still says "14 types" in frontmatter (missing the 3 Ansible types). It's the description Claude Code surfaces, so it's load-bearing — update + repack the .skill.
  • docker/cloudflared — finish the in-flight docker-compose.yml → compose.yml rename (git rm docker-compose.yml && git add compose.yml).
  • docker/traefik — decide if the debug-state compose (--api.insecure=true, port 8080, 443 commented out) is becoming the new normal; if so, update the README gotchas.
  • pbs/work-index-dashboard — stale GEMINI.md / gemini-review-2026-04-27.md (untracked). Remove or move into a reviews/ subdir per the convention the new CLAUDE.md documents.
  • pbs/ssh-login-alerter — references an Ansible role that doesn't exist in the repo yet. Verify the role landed somewhere reachable (likely the broader pbs platform repo) before next deployment.

Phase 5 — Deferred audits (post-conditions)

  • pbs/pbs-video-manager — re-audit CLAUDE.md/README after the 5-branch stack (scene-management → web-bp-csrf → scene-management-ux-fixes → phase1-paste-import → phase1-api-reads) merges to main. Docs are mid-flight on the stack; auditing now would conflict.
  • homelab/OB1 ~100 component READMEs (recipes/skills/extensions/primitives/integrations/schemas/dashboards) — templated batch pass with a shared format. Define the canonical component-README template first; do NOT review one-at-a-time. (Coordinate with OB1's upstream-fork policy, Open Item #2.)
  • docker/ non-git dirs — audit their READMEs once Phase 3 puts them under git.

Phase 6 — Policy decisions (close the Open Items)

  • Resolve python-uv tracking policy (#1).
  • Resolve OB1 fork policy (#2).
  • Resolve cli-standardization rename-vs-redefine (#3).
  • Document whatever's decided in the relevant CLAUDE.md so future agents inherit the call.

Phase 7 — Establish the recurring guided review

The audit proved a one-time sweep isn't durable. Stand up a lightweight recurring process.

  • Decide cadence + owner (Open Item #6) — monthly? per-major-merge? triggered by a scheduled task?
  • Capture the audit methodology (the 5-dimension rubric + the enumeration approach) as a reusable artifact — candidate: a repo-hygiene skill or a checklist doc, so the next review doesn't have to re-derive the method.
  • Consider a canonical CLAUDE.md skeleton for the homelab so new repos start consistent (purpose / architecture / build+test+run / gotchas / don't-touch zones).

Notes

Cross-references (NOT absorbed into this plan — tracked separately)

  • herbys-dev-setup — the Phase 0 starting-condition gate.
  • pbs-hub-scene-management (trellis: paused) — its branch stack must merge before pbs-video-manager docs can be re-audited (Phase 5).
  • pbs-hub-data-import-and-mcp (trellis: active) — pbs-hub-mcp is a new repo; its docs were rubber-stamped clean in the audit.
  • postgres-consolidation-reflection-layer + ob1-reflector-post-launch-followups (trellis: paused) — unrelated feature work; the audit only touched their repos' docs.
  • env-file-hardening — overlaps with Phase 2 (the .env permission + secrets-boundary work). Coordinate so the two don't duplicate.

Process learnings from the audit (worth keeping)

  • Cowork workspace trust is per-exact-folder, not recursive. Pre-trust the domain subfolders, or route multi-folder work through one already-trusted session.
  • start_code_task timeouts can still spawn the task — never blind-retry (caused 3 redundant agents on the homelab batch; converged harmlessly only because those repos weren't worktree-isolated).
  • Routing a multi-folder batch through a single trusted session worked cleanly and avoided both the trust prompts and the duplicate-spawn risk.

Scope discipline

This plan is repo-hygiene only. Feature/initiative due-outs from the same working session are explicitly out of scope and live in their own trellis threads + vault plans. If a hygiene item turns out to need feature work (e.g., sshkm needs to actually be built, not just doc'd), spin that out rather than absorbing it here.