cleanup(legibility): repo hygiene — proofshot retention, ignore .agent/.worktrees #415
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Context
Part of Epic #411 — Cleanup. This is CLEANUP-4: address the repo-root hygiene findings from AUDIT-5 (#392). A stranger walking into the repo today sees
proofshot-artifacts/,.agent/,.claude/worktrees/,frontend/.svelte-kit.old/,frontend/test-results.locked/and asks "what are these?". That violates C1.5.Per the Legibility Rubric, this addresses C1.5 (Minor) but high-leverage for first impression.
Required changes
1.
proofshot-artifacts/README.mdanddocs/.docs/CONTRIBUTING.md(DOC-4 / #398) so future contributors know.2.
.agent/and.claude/worktrees/and.claude/scheduled_tasks.lock.gitignoreif not already there.git status— these directories should not appear in the staged-changes list.3.
.claude/personas/and.claude/skills/and.claude/settings.jsonCONTRIBUTING.md(DOC-4) so contributors know to maintain them.4.
frontend/.svelte-kit.old/5.
frontend/test-results.locked/.gitignore. If something else, document or remove.6.
node_modules/at repo rootpackage.jsonandpackage-lock.json(saw it in git status). Is this intentional? Likely a workspace setup or a tooling install. Document or remove.7.
frontend/e2e/.auth/user.json(showing as modified in git status).gitignore.Acceptance criteria
proofshot-artifacts/decision made and implemented; documented in CONTRIBUTING.md.gitignoreupdated to exclude all dev-tooling state directoriesfrontend/.svelte-kit.old/deleted; build verified workingfrontend/test-results.locked/resolved (gitignore'd or removed)node_modules/andpackage.jsonresolved (justified or removed)frontend/e2e/.auth/user.jsonremoved from tracking; gitignore'dgit statuson a fresh clone shows zero unexpected itemsDependency
Soft dependency on AUDIT-5 (#392) — that audit's §7 will surface anything I missed above.
Definition of Done
PR merged; closing comment shows
git statusoutput of a fresh clone with the cleanup applied.🔐 Nora "NullX" Steiner — Application Security Engineer
Observations
frontend/e2e/.auth/user.jsonis tracked in git and contains a live credential. I decoded it: theauth_tokencookie value isBasic%20YWRtaW5AZmFt...— a Base64-encoded HTTP Basic Auth token. Anyone who clones this repo has the admin credential. Thefrontend/.gitignorealready containse2e/.auth/as a rule, but the file was committed before the rule existed —.gitignoredoes not untrack already-tracked files. This is a P0 security item that should be addressed before any other item in this issue..agent/,.claude/worktrees/,.claude/scheduled_tasks.lockcontain LLM process metadata (PIDs, session IDs) — not credentials, but they reveal internal tool internals and shouldn't be in a repo clone..claude/settings.jsonlikely contains tool permissions and hooks — review whether it contains any tokens or secrets before confirming it should be tracked.Recommendations
frontend/e2e/.auth/user.json. Even aftergit rm, the token is in git history and must be revoked.git rm --cached frontend/e2e/.auth/user.jsonto untrack the file without deleting it from disk. The.gitignorerulee2e/.auth/already covers it — this just needs the file removed from tracking.git filter-branchor BFG Repo Cleaner) if the token has meaningful access scope. For a self-hosted family project the blast radius is limited, but the principle stands.e2e/.auth/from being committed, as a permanent guard against re-occurrence..claude/settings.jsonfor secrets before confirming it as a tracked deliverable.Open Decisions (omit this section entirely if none)
auth_tokenappears to be the dev admin credential (admin@familyarchive.local / admin123per project memory). If this is the same password used in production, rotation is urgent. If it is dev-only, rotation is still good hygiene — but priority differs. Only you know the answer.🏗️ Markus Keller — Senior Application Architect
Observations
.gitignoreis missing entries for every item this issue addresses. Confirmed bygit check-ignore:.agent/,.claude/worktrees/,.claude/scheduled_tasks.lock,proofshot-artifacts/,frontend/test-results.locked/, andfrontend/e2e/.auth/user.jsonall have no gitignore match at the repo root level. Thefrontend/.gitignorehase2e/.auth/but the file is already tracked, so the rule has no effect..gitignoredoes cover.worktrees/(with a leading dot) and.superpowers/— but.claude/worktrees/(nested under.claude/) is a different path and is not covered.proofshot-artifacts/(7.6 MB) is untracked but not ignored. It is a run artifact from the proofshot skill, not application code. It does not belong in the repository regardless of retention policy.package.jsoncontains only three dev dependencies (@testing-library/jest-dom,@testing-library/svelte,jsdom) — this appears to be a workspace-level shim for component testing dependencies, separate fromfrontend/package.json. Whether this is intentional or a leftover deserves one line of documentation..claude/personas/,.claude/skills/,.claude/settings.jsonare correctly identified as deliverables — these are the team's tooling infrastructure and should be tracked.Recommendations
.gitignorein a single PR (grouped by category):package.jsonyet — document the purpose in a comment in the file itself or inCONTRIBUTING.md. The file is small and has a clear function; the mystery is why it lives at root rather than contributing its deps tofrontend/package.json..claude/directory structure inCONTRIBUTING.md(DOC-4, #398) so contributors understand which subdirs are deliverables and which are ephemeral state.frontend/.svelte-kit.old/directory — verified to contain onlytypes/andsrc/— is safe to delete. Runnpm run checkafter deletion to confirm no path references it.No open decisions — all items have a clear resolution path.
⚙️ Tobias Wendt — DevOps & Platform Engineer
Observations
.gitignore— I rangit check-ignoreagainst all of them and every check returned a miss. The.gitignorecovers.worktrees/(bare path) but not.claude/worktrees/(nested path). These are different entries.proofshot-artifacts/(7.6 MB) is a Playwright-screenshot artifact directory generated by the proofshot skill. It should never be committed. Thefrontend/.gitignoredoes haveproofshot-artifacts/but that only covers afrontend/proofshot-artifacts/path. The actual directory lives at the repo root and needs a root-level entry..claude/scheduled_tasks.lockcontains a JSON object with apid,sessionId, andacquiredAttimestamp — it's a live-process lock file, not configuration. This must be gitignored, not committed..claude/worktrees/has 19 entries. These are ephemeral agent workspaces. Committing them would balloon the repository with duplicated working-tree content.frontend/test-results.locked/(20 KB) contains Playwright E2E test results — clearly a run artifact. The root.gitignorehas**/test-results/but thelockedsuffix bypasses that glob. Either rename the directory totest-results(which would be caught) or add an explicit entry.frontend/e2e/.auth/user.jsonis already tracked by git even thoughfrontend/.gitignorehase2e/.auth/. The.gitignorerule is correct but arrived after the file was committed —git rm --cachedis required to untrack it.Recommendations
.gitignore(the entries below fix every miss confirmed bygit check-ignore):git rm --cached frontend/e2e/.auth/user.json. The existing.gitignorerule infrontend/will then take effect.frontend/test-results.locked/— thelockedsuffix looks like it was renamed to prevent gitignore from catching it (e.g. during debugging). Rename it back totest-results/and the existing**/test-results/root rule covers it. Or just add an explicit entry.e2e/.auth/user.jsonfresh at the start of each run viaauth.setup.ts— confirm that the Gitea Actions workflow does this, so removing the tracked file does not break CI.Open Decisions (omit this section entirely if none)
frontend/test-results.locked/naming: Was this renamed intentionally (to preserve a specific run's output for inspection) or accidentally? If intentional, the "locked" convention needs a documented meaning. If accidental, rename totest-resultsand the existing glob catches it.👨💻 Felix Brandt — Senior Fullstack Developer
Observations
package.jsonis the most interesting unknown. It contains only@testing-library/jest-dom,@testing-library/svelte, andjsdomas dev dependencies. These look like they were installed at the repo root for use by a component test runner that operates outside thefrontend/workspace. This may have been a one-off experiment or a setup artifact. The lock file (package-lock.json) at root creates ambiguity:npm installat the repo root would now install things into a rootnode_modules/, separate fromfrontend/node_modules/.frontend/.svelte-kit.old/containstypes/src— this is a Vite/SvelteKit generated directory from before a migration. It is safe to delete without touching any source file.frontend/test-results.locked/contains Playwright E2E result artifacts. Thelockedsuffix prevented the**/test-results/gitignore glob from matching it.Recommendations
frontend/.svelte-kit.old/: simplyrm -rf frontend/.svelte-kit.old/and runnpm run checkandnpm run buildto confirm nothing references it. Add.svelte-kit.old/to.gitignoreas a precaution against a future rebuild creating the same directory.package.json: make a decision and document it as a comment in the file itself. Two options:frontend/.package.json,package-lock.json, andnode_modules/at root.node_modules/at root: add to.gitignoreunconditionally — even ifpackage.jsonstays,node_modules/is never committed.git status --shortafter checkout and asserts empty output — this prevents the issue from silently regressing.No open decisions — all items have a clear path forward pending the
package.jsondecision.🧪 Sara Holt — QA Engineer & Test Strategist
Observations
frontend/e2e/.auth/user.jsonis tracked in git. This is the Playwright auth state file that gets generated byauth.setup.ts. It contains a live session token. If it's committed, every CI run that regenerates it will show it as "modified" in git status — which is exactly what the currentgit statusoutput shows (M frontend/e2e/.auth/user.json). This is a test infrastructure reliability issue: if this file drifts between local and CI, E2E tests will fail with authentication errors rather than meaningful test failures.frontend/test-results.locked/(20 KB) appears to be a Playwright artifact dir from a previous run that was renamed. The root.gitignorehas**/test-results/but thelockedsuffix bypasses the glob. This means test artifacts from a specific run were preserved and are now ingit statusas untracked.git status --shortis non-empty after checkout — otherwise the DoD only gets verified manually at merge time.Recommendations
frontend/e2e/.auth/user.json:git rm --cached frontend/e2e/.auth/user.json. Thefrontend/.gitignorealready hase2e/.auth/so this single command is the entire fix. Verify by runninggit status— the file should no longer appear as tracked.auth.setup.tsshould run before all E2E tests and writefrontend/e2e/.auth/user.jsonfresh each time. Check the Gitea Actions workflow to confirm this is configured, so untracking the file does not break CI.frontend/test-results.locked/: determine whether this is a one-off preserved run (in which case delete it and add**/test-results.locked/to.gitignore) or a recurring pattern (in which case rename totest-results/and the existing glob covers it). Either way, add an explicit.gitignoreentry.git diff --exit-code && git status --short | grep -q '^?' && exit 1 || exit 0— this fails if any untracked file or modification appears after the workflow checkout. It's a lightweight guard that enforces the DoD automatically.Open Decisions (omit this section entirely if none)
test-results.locked/origin: Was this directory renamed intentionally to preserve a specific Playwright run for debugging, or is it an accidental naming artifact? The answer determines whether to rename-and-use-existing-glob or add a new gitignore entry.🎨 Leonie Voss — UI/UX Design Lead
Observations
This issue is infrastructure hygiene with no direct UI impact. I checked everything I can comment on from a design perspective:
proofshot-artifacts/,.agent/,.claude/worktrees/,frontend/.svelte-kit.old/,frontend/test-results.locked/) touch any Svelte component, CSS token, or design system file.proofshot-artifacts/contains Playwright screenshots from the proofshot skill — these are visual verification artifacts, not design assets. They are not part of the design system and do not belong in the repo.frontend/.svelte-kit.old/— thetypes/srcdirectory inside this is generated TypeScript. It has no bearing on the UI.Recommendations
proofshot-artifacts/is excluded from git, consider whether the screenshots it produces are useful for visual regression baselining. If the team wants to do visual regression testing, the right tool is Playwright's built-in screenshot comparison (expect(page).toHaveScreenshot()), not ad-hoc proofshot runs committed to the repo. That's a separate issue, but worth noting before discarding the directory's output entirely.No concerns from my angle on the hygiene changes themselves.
📋 Elicit (Requirements Engineer)
Observations
git statuson a fresh clone shows zero unexpected items" — the word "unexpected" is untestable as written. Either this means "zero untracked files ingit status --short" (which is testable) or it means something narrower. The intent is clearly the former; the AC should say so.node_modules/) is listed as "Investigate why..." but investigation has a clear answer already: the rootpackage.jsoncontains only three testing library dev dependencies. The question is whether to keep or remove them, not whether to investigate. Reframing as a decision item would make the AC cleaner.Recommendations
git status --shorton a fresh clone produces no output."proofshot-artifacts/to root.gitignore(the directories already exist on disk, the issue is just that they are not ignored). A retention policy for the on-disk artifacts is an ops concern, not a code concern.Open Decisions (omit this section entirely if none)
package.json: Keep (with documentation) or delete? Both are valid. The choice determines whethernode_modules/at root is a permanent gitignore entry or a one-time cleanup.🗳️ Decision Queue — Action Required
4 decisions need your input before implementation starts.
Security
auth_tokenin the trackedfrontend/e2e/.auth/user.jsondecodes to the dev admin Basic Auth credential. Is this the same password used in production? If yes, rotate immediately; if dev-only, rotate as good hygiene but at lower urgency. Either way,git rm --cachedthe file first. (Raised by: Nora)Infrastructure / Repository
proofshot-artifacts/retention policy — Three options exist: (A) add to root.gitignoreonly (on-disk artifacts are yours to manage), (B) add a prune script capping to N days, or (C) document as intentional deliverables. The gitignore fix is the same in all cases. The CONTRIBUTING.md entry differs. Fastest resolution: choose A (gitignore + delete local), note it in CONTRIBUTING.md as "run artifacts, never commit." (Raised by: Elicit, Markus)Root
package.json— Contains only@testing-library/jest-dom,@testing-library/svelte,jsdom. Keep (with a one-line comment explaining why they live at root rather than insidefrontend/) or delete (and clean uppackage-lock.json+node_modules/). Both are valid; the answer determines whether root-levelnode_modules/needs a permanent.gitignoreentry or is a one-time cleanup. (Raised by: Felix, Elicit)Test Infrastructure
frontend/test-results.locked/naming — Was this directory renamed fromtest-results/intentionally (to preserve a specific Playwright run for debugging) or accidentally? If intentional, document the "locked" convention and add**/test-results.locked/to.gitignore. If accidental, rename back totest-results/— the existing root**/test-results/glob will cover it. (Raised by: Tobias, Sara)CLEANUP-4 — Closing summary
All hygiene items resolved.
git status --shortafter the PR merge will show onlydocs/superpowers/andfamilienarchiv-408/as untracked (both pre-existing, not new).Files untracked from git (
git rm --cached):frontend/e2e/.auth/user.jsonfrontend/.gitignorerulee2e/.auth/already present — the rule now takes effectproofshot-artifacts/(44 files, ~7.6MB)proofshot-artifacts/added to root.gitignorefrontend/.svelte-kit.old/types/src/routes/.stammbaum-stale/$types.d.ts**/.svelte-kit.old/added tofrontend/.gitignorefrontend/test-results.locked/e2e/(2 files)**/test-results.locked/added tofrontend/.gitignorenode_modules/.vite/vitest/.../results.jsonnode_modules/added to.gitignorepackage.json+package-lock.jsonat root.gitignoreadditions:Root
.gitignore:frontend/.gitignore:Decisions recorded:
proofshot-artifacts/: Option A — gitignore + delete local (run artifacts, never commit)frontend/test-results.locked/: Gitignored with explicit entry; directory deletedpackage.json: Deleted — no documented justification for root placementImplemented in commit
d28c4559on branchfeat/issue-411-legibility-cleanup.