I asked my agent (opencode) to review this repo's config. The whole ask was to check ManningWorks/lukemanning-site against best practices for a private solo-dev repo and tell me if anything needs changing.

My honest expectation was a list of green ticks and maybe a nitpick about something I'd decided on purpose. The site builds, Vercel deploys it, nothing's on fire. What could be wrong?

Most of it was fine. Some of it really wasn't.

The parts that were fine

Secrets hygiene, the part I actually cared about, came back clean. .env* is gitignored and .env.local holds a real GITHUB_TOKEN and a DEV_TO_API_KEY, untracked. Better still, the audit ran this check

git log --all --oneline -- '.env*'

Empty output. No env file was ever committed, on any branch, ever. That's the check I'd never have thought to run.

Ignores for node_modules, .next, .velite, tsbuildinfo were all correct. No LICENSE file, also correct for a private repo. No license means all rights reserved by default.

My own .gitignore was the problem

Then it got to line 7 of my .gitignore.

/package-lock.json

My own lockfile. At some point I told git to ignore it, deliberately, and then apparently never thought about it again.

I pushed back on this one, because ignoring a lockfile is a real opinion. Plenty of library maintainers do exactly that, and I've shipped a library myself, so the instinct has history.

But this isn't a library, it's a deployed app. Vercel builds this site from the repo, and with no tracked lockfile every build resolves dependencies fresh. What package-lock.json actually does is pin those resolutions to exact versions, which is what makes deploys reproducible. Without it, a transitive dependency can publish a breaking version and break a deploy with zero code changes on my side. Dependabot also needs the lockfile to open version update PRs at all.

Extra mess in the same area was pnpm archaeology. A .pnpmfile.cjs in the repo root and a pnpm block in package.json, leftovers from a pnpm phase. Meanwhile .npmrc and package-lock.json say npm is the actual current tool, the lockfile sitting on disk, untracked. Two package managers' worth of config, one of them dead.

Dependabot was off. One API call fixed it

Dependabot alerts are GitHub watching my dependencies for known vulnerabilities and telling me when it finds one. They were off, so nothing would have told me when a dependency picked up a CVE. The audit caught it via the API.

gh api repos/ManningWorks/lukemanning-site/vulnerability-alerts

404. On this endpoint that's just how GitHub says off, which threw me because 404 usually means the repo name is wrong. The docs say 204 means enabled, and this endpoint never returns 200.

The fix was a PUT.

gh api -X PUT repos/ManningWorks/lukemanning-site/vulnerability-alerts

Enabling alerts is free even on private repos. One API call.

Branch protection needs GitHub Pro on private repos

Branch protection on private repos needs GitHub Pro. The API says so directly.

Upgrade to GitHub Pro or make this repository public

Secret scanning and push protection aren't available on free private repos either. My first thought was that both are moot for a solo dev, but that's only half true. Secret scanning would have real value here, because I'm the most likely person to leak my own secrets. That one's a genuine gap, and closing it costs GitHub Pro money. Push protection, fair enough, there's nobody else's push to protect against. At least now I know it's a plan limit and not a config miss.

Forty stale branches and one silent failure

The pile was ~40 stale branches, local and remote. Every PR merged on GitHub left its head branch behind, and I'd clearly never gone back to clean up. Mostly merged, long forgotten.

I set the bar before deleting anything. Only branches proven merged get deleted. Two checks. git branch --merged master and its -r twin for ancestry, plus a cross-check against gh pr list --state merged.

One branch failed the ancestry check and was still safe to delete, and that's the interesting case.

8ca8fd1 feat: auto-inject referral boxes... (#26)

That's the output of git log master..feat/referral-link-injection --oneline. One commit, and it wasn't an ancestor of master. But the (#26) suffix is a squash-merge fingerprint. My PRs land as squash merges, and squash doesn't carry a branch's commits into master. It forges one fresh commit and stamps "title (#PR)" on it.

Which leaves a question. That stamp belongs on the commit squash forges on master, not on anything sitting at a branch tip. How this one got there, I never fully reconstructed. My best guess is the branch picked up a squash-style commit somewhere along the way, a cherry-pick of one or a reset onto one.

The cross-check showed the branch actually went out through PR #53, same name, merged, feature live on master. It got reused across PRs at some point and the stale #26 fingerprint never washed off. An orphaned copy, in other words. Tip not in master's history anywhere, changes already live.

The branch was a husk.

git branch -d would refuse it forever, so it needed -D (force-delete, the shortcut for --delete --force), with the receipt above as justification.

Then the batch deletion failed halfway through.

The chain was a long run of git branch -d calls for the proven-merged branches, then git branch -D feat/referral-link-injection at the very end. One of the -d deletions refused for merge/review-publisher-published-posts-into-master because it apparently wasn't merged into master, but it was. The reason is a rule I didn't know existed. From the git man page on -d.

The branch must be fully merged in its upstream branch, or in HEAD if no upstream was set.

This branch tracked a differently named remote upstream, origin/review/publisher-published-posts. The refusal explained it clearly enough. Not yet merged to 'refs/remotes/origin/review/publisher-published-posts', even though it is merged to HEAD.

AI figured it out and helped me clean it up.

Sweep before pull doesn't work

First instinct for the cleanup was git sweep && git pull. Wrong order, and for a different reason than the -d refusal earlier. The sweep's filter, git branch --merged <base>, reads whatever base branch it points at. That's a separate check from the -d safety rule above. The filter decides what makes the delete list, and the -d check gives each branch its final veto. If I swept before pulling, my local master didn't yet contain the merge I'd just done on GitHub, so the freshly merged branch never even made the delete list. No error, just a sweep that did nothing useful, so I needed a second sweep anyway. Pull first, then sweep.

The aliases that landed in ~/.gitconfig

[alias]
	sync = "!f() { git pull && git sweep; }; f"
	sweep = "!f() { git fetch --prune; b=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null) || b=$(git rev-parse --verify -q main >/dev/null 2>&1 && echo main || echo master); git branch --merged \"$b\" | grep -vE \"^\\*\" | grep -Fvx \"  $b\" | xargs -r git branch -d; }; f"

(-r is a GNU xargs thing, it makes xargs do nothing on empty input. macOS's BSD xargs doesn't have it.)

The real protection for the drafts is the filter, not the -d. git branch --merged <base> only lists branches that are ancestors of the base branch, so the unmerged feat/draft-* branches never make the delete list at all. The -d is the backstop. And as that merge/review-publisher... refusal showed, the backstop has its own opinions about upstreams and can refuse mid-sweep. It just refuses safely, which is why it's still -d and not -D. Every sweep run so far: drafts untouched.

The first cut of the sweep alias had a bug I noticed after: the grep skipped any branch name containing "master", so merge/review-publisher-published-posts-into-master would never make the sweep list. It would just sit there forever. That bugged me enough to rewrite it, and the alias above is the rewrite. It resolves the base branch now, origin/HEAD if set, then a main/master fallback, and the greps only skip the current branch and the base itself. The into-master branch gets swept like everything else.

Then one more API call to set delete_branch_on_merge=true, so merged PR head branches auto-delete on the remote from now on, and the pile can't quietly rebuild itself.

I went for a walk.

When I came back, the work had landed across three branches. Each subagent had worked in its own worktree on its own branch. The build was green on each one. The tests were green. The lint was green. The typecheck was green. The release manager subagent had drafted the changelog. Nine of the ten issues were closed. The tenth stayed open — it needed a real union restructure, not a mechanical fix.

I had not read a single line of the diff yet.

What I actually asked for

I had a backlog of small things in the Projex repo. Tagged-union cleanups. Type tightening. Documentation gaps. A bug where one of the smart-grid props was a documented prop but a no-op at runtime. A redundancy where two functions with slightly different spellings did the same thing.

I described this to my main agent. The main agent looked at the issue tracker, saw the labels (bug, enhancement, documentation), grouped them by file area, and dispatched three subagents in parallel.

One subagent got the package.json + bundling issues. One got the type-system + tagged-union issues. One got the documentation + test-coverage issues. Each one worked in a separate worktree on a separate branch. Each one committed locally and reported back. A fourth subagent, the release manager, handled release prep alongside them: the version bump and the changelog.

I watched the transcript. Mostly I stayed out of the way. I made tea.

What the subagents actually did

I saw the dispatch messages. I saw the report-back messages. I did not read the intermediate diffs. The subagents were set up to commit per-issue. Each commit was meant to be independently reviewable.

A few things I noticed in the report-backs:

• One subagent caught a redundancy I hadn't seen. Two exported functions, normalizeStats and normaliseStats, with the American and British spellings. Both did the same thing. The codebase had drifted to the British spelling in the actual logic. The American spelling was the alias. Both were exported. The subagent deprecated the American one with a JSDoc tag and updated the docs to point at the British spelling.
• One subagent found a related issue while fixing another one. While narrowing the ProjectStats union, it noticed FetchProjectDataResult.commits was using undefined while sibling fields used null. The subagent opened a new issue and included the fix in the same branch.
• One subagent flagged a peer-dependency problem I had been ignoring for two months. The CLI packages (ts-morph, chalk, @inquirer/prompts, commander) were installed by every consumer, even ones who only imported the components. The subagent moved them to optional peerDependencies so consumers importing only components stopped dragging in the CLI bundle.

None of these were in my original brief. The subagents went past the edges of what I asked for, in the direction of "things that were obviously wrong in the same file area."

Where I read the code

The first time I read any of the code was after all three subagents finished and opened their PRs. I skimmed the diffs before merging. Not a line-by-line review. A sanity check.

I was looking for decisions the AI made without asking me. Function names I wouldn't have picked. Behaviour that wasn't in the brief. Edits that touched code outside the file area I asked about. The kind of things a real code review catches, except I was reviewing the decisions, not the code.

Some of the diffs were four lines. Some were thirty. None of them were complex enough to need a real review. They were tagged-union narrowings, JSDoc additions, dependency relocations. The kind of work where you skim it once, you understand it, you move on.

If I'd skimmed each PR as it landed, I'd have read the rename with no idea the docs were about to change under it. Reading the batch, I could see the normaliseStats deprecation and the docs update pointing at it in the same sitting. The batch skim was faster than piecemeal would have been.

Where I did intervene

I didn't push back on any of the code. The three branches each shipped clean. I steered the architecture around the loop, not the code inside it.

The dispatch went out as three parallel opencode run invocations, not three subagents. I asked for that change when the opencode TUI failed on the first attempt and the right path was to skip the interactive layer. I also argued for splitting the release prep out from the fix work, because trying to do both in the same dispatch kept blocking on the release-manager hitting its timeout before the fix branches landed.

What this loop replaced

My previous loop was one PR at a time. I'd describe an issue to the agent. The agent would open a PR. I'd skim it, sanity-check the decisions, merge or push back. One issue, one PR, one round of skimming. Repeat.

For this kind of small mechanical work, that's fine. It works. But the context switching adds up. Each PR is its own session — its own dispatch, its own transcript, its own review pass. The overhead is small per PR and large per backlog.

The new loop:

1. Describe the backlog.
2. Wait.
3. Skim the batch of PRs.
4. Push the release prep.

The release prep runs alongside the fix work instead of after it. One description covers all of them.

I want to be careful about what I'm claiming here. I'm not claiming the subagents did better work than the agent would have done one PR at a time. Most of these issues were mechanical. The interesting decisions — which redundancy to deprecate, which naming to standardize — the agent would have surfaced them either way, given the brief. What I'm claiming is that the per-PR overhead moved out of my hands and the interesting decisions stayed in my hands.

Reading at the end, not in the middle

I did not read the code while it was being written.

In the old loop, I skimmed each PR after the agent opened it. One PR at a time.

In the new loop, the skim happened after the writing finished across all three PRs. The subagents were the feedback loop during the work. I was the feedback loop at the end.

There's a different cost structure. A wrong fix in the old loop was caught in the per-PR skim, or it shipped. A wrong fix in the new loop is caught in the batch skim, or it ships.

I shipped none of the wrong fixes in this batch. The issues were mechanical and the code area was small. If I'd asked the subagents to redesign the normalise function, I would have read every line, pushed back, rewritten pieces.

The loop works for the kind of work that has a clear right answer. The loop does not work for the kind of work that needs taste. I haven't found the line yet.

For this batch, the line was "moves stuff around, adds JSDoc, narrows types." Below the line, I delegated. Above the line, I didn't. The line is in a different place than I would have guessed.

Running it again

I'm going to run this loop again. On a different repo. On a different kind of work.

I want to see what happens when the issues aren't mechanical. I want to see where the line moves. I want to see what kinds of work I delegate that I later wish I hadn't, and what kinds I keep that the loop could have handled.

I'm not going to delegate design decisions. I'm not going to delegate "what should this library do". I'm going to delegate "make this library do what it already says it does, correctly."

The batch skim at the end is non-negotiable. That's the part I own.

I was trying to read an issue on this site's repo:

gh issue view 28 --repo ManningWorks/lukemanning-site --comments

What came back was this:

GraphQL: Projects (classic) is being deprecated in favor of the new Projects
experience, see: https://github.blog/changelog/2024-05-23-sunset-notice-projects-classic/.
(repository.issue.projectCards)

I asked my AI assistant (opencode) what it meant. It told me it was just a deprecation warning, not an error, and the command works fine.

Except it kept telling me the command had failed. So I pushed back: "You keep telling me that command fails though." It ran the command, and a different error surfaced. This one was mine. In my message I'd written gh issue view 28 --repo --comments with no repo value, assuming it would fill in the blanks. It ran exactly what I'd written. --repo with no value swallowed --comments:

expected the "[HOST/]OWNER/REPO" format, got "--comments"

Fine. My shorthand, my missing value. With the repo filled in, the original failure came straight back:

Exit code 1. Zero bytes on stdout. The deprecation message, alone, on stderr.

That's when it clicked. The "warning" was the failure. The command produced nothing except a note formatted like a heads-up about the future.

The assistant then decided the deprecation message was a red herring that would only appear once the repo resolved. Also wrong. Twice in one conversation.

Problem One: The Warning Was the Error

Ubuntu ships gh 2.45.0. That version requests repository.issue.projectCards as part of its GraphQL query for issue views. GitHub sunset Projects (classic) in May 2024 and now returns that field as a hard GraphQL error. A hard error kills the whole query, so every gh issue view and gh pr view on 2.45.x fails with output that reads like a deprecation notice.

This is a known thing: cli/cli#11992. The maintainers' answer is to stop using distro packages and install from GitHub's official repo. GitHub's Linux install docs now say it outright: as of November 2025 they strongly recommend the official Debian packages, since the community-distributed 2.45.x and 2.46.x are broken against current GitHub APIs.

So Ubuntu's gh is broken in a way GitHub officially acknowledges. Weirdly comforting.

The Workaround

gh api goes through REST, not GraphQL, so it still worked:

gh api repos/ManningWorks/lukemanning-site/issues/28 --jq '.title, .body'
gh api repos/ManningWorks/lukemanning-site/issues/28/comments --jq '.[] | .author.login, .body'

Clunky, but it let me read the issue while I sorted out the upgrade.

Problem Two: The Wrong Repo URL

The assistant set up GitHub's apt repo from memory: https://cli.github.com/apt.

The repository 'https://cli.github.com/apt stable Release' does not have a Release file.

That's a 404. The repo isn't there. I enjoyed this one. The assistant guessed a URL instead of checking the docs, which is the exact thing it tells me not to do constantly.

GitHub's own install docs say it's https://cli.github.com/packages. The assistant followed them this time, keyring staged through /tmp since wget can't write to /etc/apt/keyrings as me:

wget -nv -O /tmp/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg
cat /tmp/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list

Repo added, apt update clean, apt install gh... nothing. Still 2.45.0. Three failure layers, for anyone counting.

Problem Three: ESM Refuses to Lose

apt-cache policy gh explained it:

gh:
  Installed: 2.45.0-1ubuntu0.3+esm3
  Candidate: 2.45.0-1ubuntu0.3+esm3
  Version table:
     2.97.0 500
        500 https://cli.github.com/packages stable/main amd64 Packages
 *** 2.45.0-1ubuntu0.3+esm3 510
        510 https://esm.ubuntu.com/apps/ubuntu noble-apps-security/main amd64 Packages

GitHub's repo offers 2.97.0 at priority 500, the apt default. Ubuntu ESM pins its version at 510. ESM is Expanded Security Maintenance, the security-update stream that comes with Ubuntu Pro, and this machine is Ubuntu 24.04 (noble), amd64, with Pro enabled. Higher priority wins the candidate slot, even though ESM's 2.45.0 is ancient.

An explicit version bypasses the priority contest:

sudo apt install gh=2.97.0

That worked. gh --version reported 2.97.0, and gh issue view 28 --comments (from the repo root, so no --repo needed) finally exited 0 with full output.

The Pin, Validated

The explicit install worked, but the candidate was still ESM's 2.45.0. The assistant said I needed a pin file so GitHub's repo wins going forward. Before touching anything in /etc/apt/preferences.d/, I asked it to validate that. Do Ubuntu or GitHub actually document this, or is it forum folklore?

Three primary sources:

1. My own machine. /etc/apt/preferences.d/ubuntu-pro-esm-apps, shipped by ubuntu-pro-client, pins release o=UbuntuESMApps at 510. The file's own comment says it's deliberate: when ESM is enabled, ESM packages are preferred over non-ESM ones.

2. man apt_preferences. Priorities from 500 to 990 install a version unless a newer one is already installed. 1000 or higher is required to downgrade. So ESM can't drag me back to 2.45.0, but a plain apt upgrade would never pick up a future GitHub release either. I'd be frozen on 2.97.0.

3. Canonical's tracker and docs. ubuntu-pro-client issue #3330 is someone hitting exactly this: a newer fish from a PPA, ignored in favour of ESM's. A Canonical maintainer closed it as intended, because cloud customers didn't want ESM security fixes silently reverted. The stated remedy:

   manually configure apt... by creating a preferences file pinning the PPA to a higher version than ESM.

   Canonical's Pro Client docs say close to the same: give the third-party repo at least 510.

So the pin is real, and documented. Good.

Why 600 and Not 510

Those two sources don't quite agree, it turns out. The docs allow equal: at least 510. The issue thread says higher than ESM. And what apt actually does when two repos sit at the same priority, I couldn't find in man apt_preferences. Maybe there's a tie-break rule somewhere. I didn't find it.

I let the assistant pick the number in the end, within the bounds the man page had already given me. It went with 600: unconditionally "GitHub's repo is authoritative for gh", above both suggested floors, and below 1000 so nothing can ever downgrade me.

Works for me. 510 would satisfy the docs, but a pin that only ties the thing it's fighting isn't a config I want to reason about again in six months.

/etc/apt/preferences.d/gh:

# gh: prefer GitHub official apt repo over Ubuntu ESM pin (510).
# ESM gh 2.45.x is broken vs current GitHub APIs - see cli/cli#11992.
# Canonical documents this remedy: https://documentation.ubuntu.com/pro-client/en/latest/explanations/about_esm/
Package: gh
Pin: origin cli.github.com
Pin-Priority: 600

Then I verified with apt-cache policy gh, which now shows *** 2.97.0 600. I checked because the assistant had flagged the failure mode to watch for: if the origin in the pin doesn't match the host in the sources list, there's no error. The pin just doesn't apply.

What Stuck

Any one of these three alone would have been a proper rabbit hole.

The assistant was confidently wrong twice, and that's the part I keep relearning. First that the message was harmless, then that it was a red herring. Both times, actually running the command with stdout and stderr separated settled it in seconds. Asking an AI what a command does is asking it to hallucinate from training data. The apt URL guess showed exactly how that goes.

gh works now. Which is nice, because I originally just wanted to read one issue.

I was on WSL (Windows Subsystem for Linux) working on my blog project like any other day. Ran git log to check my recent commits and got this:

error: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty
error: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty
fatal: loose object b92de209f45b133daeeb97a46ea9ed354a2b9664 (stored in .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664) is corrupt

Three corrupt objects. Empty files. Admittedly I have somewhat limited Git experience, but I had never seen this before.

Was I about to lose commits?

The Diagnosis

First, I needed to figure out how bad this was. I navigated to my repository root (where the .git folder is) and ran:

$ git fsck --full

This command scans every object in your repository for corruption. The --full flag makes it check everything, not just what's reachable from current branches.

The output was worse than I thought:

error: object file .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 is empty
error: object file .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 is empty
fatal: loose object 287186e66df4cf7057d2897bc1da0027affbfbe5 (stored in .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5) is corrupt
error: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty
error: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty
fatal: loose object b92de209f45b133daeeb97a46ea9ed354a2b9664 (stored in .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664) is corrupt
error: object file .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 is empty
error: object file .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 is empty
fatal: loose object e2ec99bf1bb260a461c1b7670ad2e891ab0d7f88 (stored in .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88) is corrupt

Three corrupt object files. All empty (0 bytes).

I didn't know what these objects were exactly - could have been commits, could have been file contents, could have been something else. That was the scary part. Were these unreferenced objects I wouldn't miss, or was I about to lose actual work?

Git splits object hashes into two-character directories (b9/) to avoid having millions of files in a single folder. That's normal Git internals.

If you're managing a home server and run into data recovery issues, I also wrote about fixing Unraid Docker containers after an upgrade — less Git-related, but same problem-solving mindset.

The Safety-First Question

The initial solution I got was:

rm .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 \
   .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 \
   .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88

But I stopped. Because here's the thing: what if this doesn't work?

I asked: "Do we have to rm? Can we mv in case this doesn't work? Or am I screwed either way?"

This turned out to be the right question. Even though these files were corrupt and empty, having a backup before doing anything destructive felt smarter. Even if it was arguably pointless. Sometimes you need a safety net, you know?

The Actual Fix

Here's what I did instead:

Step 1: Create a backup location

mkdir -p .git/corrupt-backup

Will this work? I wasn't sure, but at least I'd have a backup if things went sideways.

Step 2: Move the corrupt files (don't delete)

mv .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 \
   .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 \
   .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 \
   .git/corrupt-backup/

Now the corrupt objects are gone from Git's perspective, but I still have them if I need to investigate later.

I did try running git fetch origin before moving the files, but Git still threw the same corruption error. The empty files were blocking everything - they had to go.

Step 3: Recover from the remote

This was the scary part. From the same repository root, I ran:

git fetch origin

Git compared my local repo to GitHub, saw the missing objects, and re-downloaded them to .git/objects/. Because these commits existed on GitHub, I got back the exact object files I'd lost.

origin is the default name Git gives to your main remote. You can check your remotes with git remote -v if you're curious.

Step 4: Verify everything is fixed

That output looked good. But I needed to be sure. So I ran fsck again:

$ git fsck --full
Checking object directories: 100% (256/256), done.
Checking objects: 100% (257/257), done.

Step 5: Confirm Git commands work

$ git log --oneline -10
b92de20 Adding +2 reviews for setup blog post
626e596 refactor(content): apply multi-agent review fixes to setting-up-velite-nextjs-revised
42f41d7 Token optimization plan improvements
db5c595 refactor(content): apply multi-agent review fixes to setting-up-velite-nextjs-revised
4bf342a refactor(orchestrators): use VOICE_GUIDE.md instead of reading recent posts
...

Everything works. Repository fully recovered.

What If You Don't Have a Remote?

Honestly, I got lucky. I had pushed everything to GitHub, so git fetch origin worked immediately.

If I hadn't had a remote, I would have been in trouble. I could have tried git reflog to see if Git still had references locally, but if the commits weren't pushed and weren't in reflog, they'd be gone.

This is why regular pushes matter - they're not just for sharing, they're for disaster recovery.

What I Learned

Object corruption happens. System crashes, disk issues, power loss, process killed at the wrong moment - any of these can leave you with empty 0-byte files in .git/objects/. I don't know which one hit me.

Remote repositories are your safety net. Because I'd pushed these commits to GitHub, git fetch could restore them. The objects weren't actually lost, they just needed to be re-downloaded. If I hadn't pushed recently, this would've been scarier.

Always have a rollback plan. Moving files instead of deleting them was the right call. Even though they were corrupt and useless, having them in .git/corrupt-backup/ meant I could investigate or restore if something went wrong. I asked myself: "before any destructive operation, do I have an escape hatch?" That question saved me stress, even though I didn't end up needing the backup.

git fsck saved me time. When I first ran git fsck --full, I was overwhelmed by how verbose the output was. But once I realized it was showing me EXACTLY which three files were corrupt (with full paths and hashes), I knew what I needed to fix. Before this, I was guessing. After running fsck, I had precision.

Git object corruption sounded terrifying when it first happened. But because I had GitHub and had pushed my commits, recovery was straightforward. The remote wasn't just for sharing code, it was my disaster recovery system.

And that mv instead of rm? Saved me from unnecessary stress. Even though the files were genuinely corrupt and I never needed them again, having that backup gave me confidence to proceed.