DEV Community: HideyukiMORI

My Upload Check Trusted the Attacker's Word: 8 Bytes Fixed It

HideyukiMORI — Fri, 31 Jul 2026 15:12:50 +0000

A QA pass sent my document uploader a Windows executable that declared itself application/pdf. It was accepted, stored, and listed like any other document.

The MIME allowlist that was supposed to stop it had run, matched, and passed. It wasn't buggy. It was reading a value the uploader had written.

This is the companion to my Bug Smash post about environment variables poisoning a test run — that one was about my machine lying to me. This one is about my input lying to me.

What the check actually covered

The uploader had what looked like several layers of protection. Laid out by who controls each value, the picture changes:

Layer	What it checked	Who controls it	Stops a spoof?
`accept=".pdf,.jpg,.jpeg,.png"`	file picker filter	the browser UI	❌ cosmetic only
Declared MIME allowlist	a string in the multipart body	the uploader	❌
File extension	the filename	the uploader	❌
First bytes of the payload	the actual content	the file itself	✅
`nosniff` + `attachment` on download	how the browser treats the response	the server	⚠️ mitigation, not a fix

Three of those layers were reading values the uploading client had chosen. The allowlist contents were correct — PDF, JPEG, PNG, exactly what the compliance rule says. It just never saw the file.

I wasn't validating the file. I was validating a string the uploader chose.

That bottom row deserves a note, because it's the one I could have hidden behind. The download path already sent X-Content-Type-Options: nosniff and Content-Disposition: attachment before any of this happened. That mitigation is real, and it predates the bug — which is exactly why it isn't a fix. It changes what a browser does with a file that I already agreed to store. Rejecting at intake is a different question, and I hadn't answered it.

How it was found

Not by a scanner. By a person following a QA script, escalating one step at a time: send a .exe (rejected, good), send an .svg (rejected, good), then send the .exe bytes with a spoofed application/pdf content type.

That third step is the one automated checks tend not to reach, because it requires deciding to lie about your own request.

The fix: read eight bytes

Keep the declared-MIME allowlist as a cheap first gate, then put content sniffing behind it. No new dependencies — no finfo, no library, composer.json untouched:

private function sniffMimeType(string $tmpPath): ?string
{
    $handle = @fopen($tmpPath, 'rb');
    if ($handle === false) {
        return null;
    }

    $header = fread($handle, 8);
    fclose($handle);

    if ($header === false || $header === '') {
        return null;
    }

    if (str_starts_with($header, '%PDF-')) {
        return 'application/pdf';
    }
    if (str_starts_with($header, "\xFF\xD8\xFF")) {
        return 'image/jpeg';
    }
    if (str_starts_with($header, "\x89PNG\r\n\x1A\n")) {
        return 'image/png';
    }

    return null;
}

Eight bytes because the PNG signature is eight bytes long; the other two are shorter prefixes of the same read. The call site is four lines:

$sniffed = $this->sniffMimeType($input->tmpPath);
if ($sniffed === null || !in_array($sniffed, self::ALLOWED_MIME_TYPES, true)) {
    throw new MimeTypeNotAllowedException($input->mimeType, $sniffed ?? 'unknown');
}

Two decisions in there matter more than the signatures.

Undecidable means rejected. An unreadable file, an empty file, or anything whose first bytes don't match a known signature all return null, and null fails. A sniffer that returns "unknown" and then shrugs is not a gate.

The two rejections say different things. A disallowed declaration gets File type 'x' is not allowed. Only PDF, JPEG, and PNG are accepted. A spoof gets Declared file type 'application/pdf' does not match the file content ('unknown'). Only genuine PDF, JPEG, and PNG files are accepted. Collapsing those into one message would have been less code and would have thrown away the only signal that distinguishes a confused user from someone probing you.

One thing I did not do: SVG is rejected, not sanitized. An SVG renamed and re-declared as PNG fails the signature check and never reaches storage. If you need to accept SVG, this post doesn't help you — that's a different problem with a much larger surface.

The test that couldn't be written

Here's the part that changed how I read my own test suites.

Before the fix, the test helper passed tmpPath: '/tmp/fake-upload'. That's a string. There was no file at that path. There had never been a file at that path.

So a content-based test wasn't merely missing from the suite. It was impossible to write. The validation logic stopped at the declared value because the fixtures had no content for it to go on to.

The check was as deep as my fixtures were.

The line that unlocked everything was tempnam() — create a real temporary file, write real bytes into it, delete it in tearDown(). Once fixtures were files instead of strings, the new cases wrote themselves: a spoofed .exe asserting the mismatch message, an SVG declared as PNG, and genuine JPEG and PNG regressions to prove the gate still lets real documents through.

What's still open

The vulnerability is closed at intake, and I'd rather end on the part I haven't finished than on the part I have.

The end-to-end test that originally caught this still carries its discovery-time assertion:

expect(listed > 0 || modalText.length > 0, 'upload resolved (accepted or errored)').toBeTruthy();

Read that carefully. It passes when the spoofed file is accepted and listed, and it passes when the upload errors out. It was written to observe what happened, back when nobody knew. It would go green whether or not my fix works.

I closed the vulnerability and left the test that found it unable to prove it. A test written to demonstrate a bug does not become a regression test until you flip its expectation.

What I'd tell past me

If the value you're validating arrived in the request body, you're validating the attacker's input, not the file.
Undecidable must mean rejected. "Unknown, so I'll allow it" is not a gate.
Fixtures set the ceiling on what your tests can check. A fixture that isn't a file can never catch a content bug.

What's still in your upload path that the uploader gets to declare?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

Fact-Checking My Own Blog Posts Turned Into Product QA: 3 Real Bugs

HideyukiMORI — Fri, 31 Jul 2026 15:08:02 +0000

I was fact-checking a sentence in one of my own blog posts — "the API returns no-store" — and found out the API did no such thing.

So I didn't edit the sentence. I fixed the product.

I have a rule for myself: before I publish anything technical, I go through it and check every factual claim against the actual code. Not to impress the reader — to keep myself honest, because it's embarrassingly easy to write something that sounds true. This week that habit stopped being about the writing. Reviewing four posts turned up three real bugs, in the product, not the posts.

Bug 1: the sentence was right, the product was late

The post was about an auth-header quirk on shared hosting, and it claimed the API returned Cache-Control: no-store on authenticated responses. Reasonable thing to claim. Also, when I actually checked, not true — the header wasn't being set.

Because of how the app worked around a proxy that strips the standard Authorization header, the usual "responses tied to Authorization aren't shared-cacheable" protection didn't apply. Which meant an authenticated response could, in theory, land in a shared cache.

I had two options: soften the blog sentence, or make it true. I added a small middleware that sets no-store at the outermost layer of the pipeline, left a couple of tests behind, and shipped it. The sentence is now correct because the product changed to match it — not the other way around.

That's the case I like most. My writing was ahead of my code, and checking the writing is what surfaced it.

Bug 2: "nothing accumulates" — except the thing that did

Another post described a disposable-demo setup: click a link, get a throwaway tenant, and an hourly sweep deletes everything, so nothing piles up. I went to verify the "nothing piles up" claim literally.

Nearly nothing piled up. But each demo tenant left behind a small per-tenant stamp file — a throttle bookkeeping artifact — that the sweep wasn't cleaning. Every demo click added one and never removed it. Not a leak that would take the server down soon, but a direct contradiction of a sentence I was about to publish.

The sweep now removes those stamps when it deletes a tenant, and self-heals any orphans from tenants that are already gone. Claim restored to true.

Bug 3: the demo was showing the future

While writing the English version of that demo post, I clicked through the seeded data the way a reader would. The demo plants realistic history — a few invoices, some payments — so it looks like a live business.

Open it in the first half of a month and some of that "history" was dated in the future: a payment recorded for a date that hadn't happened yet, a paid invoice due next week. The seed used fixed day-of-month values, so early in the month they landed ahead of today.

The person most likely to notice that is an accountant — exactly the audience the demo is for. The fix clamps every seeded event date to "today or earlier," while leaving genuinely future dates (like due dates) alone. I added a test that seeds on the first of the month — the worst case — and confirmed it failed before the fix.

Being honest about the yield

Four posts, three product fixes — but I don't want to oversell the hit rate. Two of the four posts had zero product bugs; their claims were already true, and checking them just cost me an hour and bought me confidence. The three bugs clustered in two of the posts, not one per article. If I dressed this up as "every blog post hides a bug," that would be its own small fabrication.

The point isn't a reliable yield. It's the lens.

Why prose catches what tests miss

Tests check the assertions you thought to write. Prose makes a different kind of claim, and a more dangerous one: "the system does X," stated plainly enough for a stranger to falsify.

Your code doesn't say no-store. Your blog post does. Your test suite never asserted "nothing accumulates" or "no dates are in the future" — but your paragraph did, out loud, to the whole internet. Writing forces you to compress behavior into flat declarative sentences, and flat declarative sentences are exactly the thing you can walk over to the code and check.

So publishing under a rule of "every claim gets verified against the code" isn't just hygiene for the post. It's a QA pass driven by a question your tests never asked: is what I'm telling people actually true right now?

And when the answer is "no, but it should be" — like the no-store case — the honest fix isn't to edit the sentence down. It's to make the sentence true.

Do you check your posts against the code before you hit publish — and has it ever turned up a bug in the thing you were writing about?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

My Generator Hid a Lint Error: CI Never Checks What Nobody Commits

HideyukiMORI — Thu, 30 Jul 2026 15:49:46 +0000

The lint error lived in a file my CI had never seen. It couldn't have seen it — the file only exists after you run a generator with a particular flag, and nobody had ever committed that flag's output.

The setup

NENE2, my framework for typed business apps, ships frontend scaffolding generators: gen:entity builds the typed API layer for a resource, gen:feature builds a state-machine-shaped feature on top. They're template-based and deterministic on purpose — deterministic output is what makes generated code reviewable and lets AI agents use the generators safely.

And like most generators, they have flags. gen:entity <noun> --write adds mutation hooks and write handlers on top of the read-only default. Flags mean branches. Branches mean output shapes that may exist nowhere in your repo.

That's where the bug was.

The bug

The entity mutations template emitted this:

UseMutationResult<Noun, AppError, unknown>

The third type argument, unknown, is exactly the parameter's default — so @typescript-eslint/no-unnecessary-type-arguments flags it. Which means every single output of gen:entity <noun> --write failed lint, in a codebase where CI runs ESLint with --max-warnings 0.

And CI was green the whole time. The generator's determinism tests passed — they verify the templates produce stable, expected output. The committed exemplar for the default archetype passed lint, because it's real committed code and CI lints it like everything else. But the --write branch's output had never been committed anywhere, so no type-checker and no linter had ever run over a single line of it.

A determinism test proves your generator is consistent. It will happily prove it's consistently wrong.

This is a cousin of a broader failure mode I keep running into: gates that glow green while checking nothing in the branch that matters.

How it surfaced

Not by auditing. By building the next feature.

In PR #1580 I was adding a --mutation archetype to gen:feature — a four-state union (idle | submitting | error | success) for form-style features. That archetype consumes what gen:entity --write produces, so for once, verifying the new thing forced me to actually generate the old thing.

The verification was a full rehearsal on real output: run gen:entity payment and gen:feature submit-payment payment --mutation, then put the generated files through the same gauntlet as committed code — type-check, ESLint with --max-warnings 0, Prettier, and the generated transition tests against a real mock server.

Lint went red on code no human had written and no CI had judged. There it was.

The fix

One line in the template. Drop the third type argument — TVariables defaults to unknown anyway, so the emitted types are identical and behavior doesn't change. The PR body records the before/after; the generated output now comes out type-check clean, lint clean at --max-warnings 0, with its four transition tests passing (4/4, exercised against mocked 200 and 500 responses).

The fix took a minute. The bug had unlimited shelf life. That asymmetry is the whole story.

The general lesson: enumerate your generator's branches

If your codebase has a generator with flags or optional archetypes, each branch of its output is code you're shipping to your future self — and CI's default posture toward it is total blindness. Two ways to close the gap:

Keep a committed exemplar per branch. Generate one real instance of every archetype/flag combination and commit it as living code. CI then type-checks, lints, and tests it forever, for free. Drift between templates and exemplar shows up as a normal red build.
Add a generate-and-check smoke to CI. Generate every branch into a temp dir, run type-check + lint + tests over the output, throw it away. No repo noise; costs CI minutes instead.

Either works. What doesn't work is what I had: determinism tests that hold the generator's output stable while nothing ever asks whether that output is valid.

Full honesty about where I actually am: PR #1580 did option 2 manually, once — a rehearsal, not a gate. The PR body itself flags a committed exemplar for the mutation branch as a follow-up. So the branch that bit me is verified today and unguarded tomorrow, and I'm writing this partly so I can't quietly forget that.

Takeaways

Every generator flag is a code branch CI has never met. Green CI says nothing about output nobody commits.
Determinism/golden tests check stability, not validity — pair them with a committed exemplar per branch, or a generate → type-check → lint → test smoke.
The cheapest audit is a rehearsal: generate each archetype for real and run your normal check over the output. My first rehearsal of an old flag found a lint error of unknown age.

Primary sources

NENE2 PR #1580 (merge c2b5311) — the --mutation archetype, the rehearsal, and the one-line template fix

If you have a generator in your codebase: when did the output of every one of its flags last pass your linter? I'd honestly love to know if anyone gates this properly.

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

My Committed Bundle Went Stale: CI Rebuilt It and Never Compared

HideyukiMORI — Thu, 30 Jul 2026 15:38:47 +0000

I found out that a bundle committed to one of my repos had gone stale because an unrelated PR left my git tree dirty.

Not a test. Not a review. A dirty tree, noticed by accident.

The setup

nene-concierge is one of my self-hosted business tools. Its repo commits a built frontend artifact: public_html/admin/app.js, the admin bundle, produced by esbuild via npm run build. The public_html/ tree is the deployable root, generated files included.

Committing build output is a choice with a known tradeoff. I knew the tradeoff. I just wasn't paying for it.

What broke

An earlier refactor (#178/#179) added "type": "module" to frontend/package.json.

That one line changed esbuild's CJS interop output. Every helper call in the bundle went from __toESM(x) to __toESM(x, 1). From that day on, the app.js sitting in main no longer matched what a clean build produces — a 573-insertion diff of pure drift.

Nothing failed. Type-check green. Lint green. Tests green. Nothing in the pipeline had any opinion about that file.

Here's the detail that stings most. My CI runs npm run check, and check includes build. So CI was rebuilding that bundle on every single run — producing the correct, fresh output in its own workspace — and then throwing it away without ever comparing it to the file committed two directories over.

A committed artifact is a claim about your source code, and nothing was checking the claim.

How it surfaced

By luck. While verifying an unrelated PR (#183, a lint-suppressions ratchet gate), I ran the full check locally and git status came back dirty: npm run build had rewritten public_html/admin/app.js under me.

That PR's body records it as an explicitly out-of-scope finding, the artifact was restored so the ratchet PR stayed clean, and the drift got its own issue: #185.

If that ratchet PR hadn't happened to run a build on my machine, I have no idea when I'd have noticed.

The fix — and what the fix doesn't fix

PR #186 (merged as b7eb1ea) is deliberately boring: run npm run build, commit the output as-is. Machine diff only, zero source changes, two generated files touched (app.js and its sourcemap).

Two things made me trust it:

Idempotency: two independent builds, byte-identical output. If your bundler embeds timestamps or random chunk names, a freshness check is off the table until that's fixed — so prove determinism first.
Clean tree after: rebuild, then git status shows nothing. That was the acceptance criterion on the issue.

But notice what this fix is: a resync. It repairs this drift and does nothing about the next one. Any future change that shifts compiler output — a bundler upgrade, a tsconfig flag, another package.json line — re-creates the exact same silent lie.

The actual lesson: freshness must be a test

If a build artifact lives in git, CI has to prove it's fresh. The check is about four lines:

- run: npm ci && npm run build
  working-directory: frontend
- name: Committed artifacts must match a clean build
  run: |
    test -z "$(git status --porcelain)" || {
      git status; git diff | head -50
      echo "::error::Committed build output is stale. Run npm run build and commit."
      exit 1
    }

Build from a clean checkout, then assert the tree is still clean. That's it. It would have turned this whole story into a red X on the PR that added "type": "module", instead of a discovery-by-accident later.

Full honesty: as I write this, that gate is not yet in nene-concierge's workflow — the resync is merged, the guard is the follow-up. I checked the workflow file before writing this paragraph, because claiming a fix you haven't shipped is exactly the kind of lie this article is about.

And the cleaner alternative deserves saying out loud: if you can avoid committing artifacts at all — build in CI, build at deploy — do that. An artifact that's never committed can't go stale in the repo. Committing output is sometimes the pragmatic choice when the deploy target is a plain host that just serves files; that convenience is fine, but it isn't free. The freshness check is the price.

Takeaways

A committed artifact is an unverified claim. CI must rebuild and git status --porcelain-assert it, or the artifact will eventually lie.
Toolchain config changes ("type": "module", bundler bumps) can change output while every semantic check stays green — drift needs no bug to happen.
Prove build determinism (two builds, byte-identical) before you rely on any freshness comparison.

Primary sources

nene-concierge issue #185 and PR #186 (merge b7eb1ea) — the drift and the resync
nene-concierge PR #183 — the out-of-scope note where the drift was first recorded

Do you commit build output anywhere — and if so, what would actually fail today if it went stale? If the answer is "nothing," I'd check.

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

Half My Tests Failed and None Were Broken: My Shell Poisoned PHPUnit

HideyukiMORI — Wed, 29 Jul 2026 15:00:34 +0000

For about a day I believed I had roughly 150 broken tests. I was wrong — not one of them was broken. Then I was wrong about the cause. Twice.

Here's the walk from "our test suite is rotting" to "one stray line in my shell was winning a fight I didn't know it was in."

The symptom

I ran the suite and about half of it was red. Every failure was the same shape: 403 org-access-denied. Tenant-scoped tests, denied across the board.

It looked exactly like accumulated test debt — the kind of thing you file, sigh at, and schedule for "later." So that's what I did. I opened an issue: ~150 failing tests, org access denied.

Correction #1: the tests were fine, my machine wasn't

Before scheduling the cleanup, I ran the suite in a clean environment — a fresh shell with none of my profile loaded.

All green.

Not "fewer failures." Zero. The tests were fine. The failures were a property of my environment, not the code. Which is a worse feeling than a broken test, honestly, because it means the call is coming from inside the house.

The mechanism turned out to be a PHPUnit detail I'd never had to think about: env vars you set in the config do not override an env var that's already set in your shell — not unless you mark them force="true". My shell profile exported a variable that the test config also set, and by default, the shell won. So my tests were quietly running against the wrong context, and everything tenant-scoped got denied.

Correction #2: I blamed the scary variable, not the guilty one

Here's the part I'm least proud of and find most useful.

My first theory for which variable was a JWT signing secret. It's the dangerous-sounding one; of course a bad secret breaks auth. I wrote it up that way.

It was wrong, and the code says why. A signing secret is symmetric: if signing and verifying both read the same (wrong) value, the tokens are still internally valid. A polluted secret doesn't produce 403 org-access-denied — it produces valid tokens for a wrong-but-consistent world. It couldn't be the cause.

The actual culprit was boring: a tenant-slug variable. My shell had it set to one thing; the tests minted tokens for another. So the request would resolve one tenant from the env, carry a token for a different tenant, and the access check — correctly — denied it. Every tenant-scoped test, 403.

I'd spent my first guess on the variable that sounded like a security problem, when a plain identifier was doing all the damage.

The fix was one attribute

force="true" on the env entries, so the test configuration wins over whatever the shell happens to export. That's it. The suite is now hermetic: it runs the same on my machine, on a colleague's, and in CI, regardless of anyone's shell profile.

I proved it the honest way — by injecting the bad variable on purpose. With the injection and no force, the suite collapses (about 150 failures and a pile of errors). With force, the same injection does nothing; everything stays green. The fix is verified against the attack, not against my memory.

What I can't tell you

I can't tell you the exact line that was in my shell profile that day. I don't have it pinned down, and I'm not going to invent it to make the story cleaner. What I have is a reproduction — inject the variable, watch it break — and that's what the fix is proven against.

The count is fuzzy too. It was around 150 failures out of somewhere near 290 tests, and both numbers drifted day to day as the suite changed. "156 out of 291" would look precise and be a small lie. Half the suite red, zero tests actually broken is the true and useful shape of it.

Two takeaways

Make your tests hermetic. Test configuration should beat the machine it runs on, unconditionally — force, or the equivalent in your stack. A suite whose result depends on the developer's shell isn't testing your code; it's testing your dotfiles.

When you're debugging, suspect the boring variable. I lost real time pointing at a secret because it sounded dangerous, while a plain tenant id sat there quietly denying everything. The scary-looking cause is a great way to feel productive and stay wrong.

What's the worst "it's the tests" you've had that turned out to be your own environment?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

Pilot Then Fan Out: Killing Unknown Blockers in 2 Repos First

HideyukiMORI — Wed, 29 Jul 2026 14:59:58 +0000

I maintain about a dozen small products that share one homemade framework. Last week I built a conformance linter — a little tool that scans each repo for architectural drift — and I was one command away from wiring it into all of them at once.

I didn't. I ran it in two repos first.

That two-repo dry run is the cheapest safety I've added all year, and it caught two things that would otherwise have gone off in every repo at the same time. One of them was the linter being wrong about my own code.

Why fan-out is tempting, and why it bites

When you have a change that clearly belongs everywhere — a lint rule, a CI step, a dependency bump — the obvious move is to apply it everywhere. One sweep, done.

The problem is that a shared tool doesn't fail in the tool. It fails in the consumers, and consumers differ in ways the tool's own tests never exercise. So "all green in the framework repo" tells you almost nothing about what happens when a dozen repos actually pull it in.

If you fan out first and discover the blocker second, you don't get one failure. You get the same failure a dozen times, concurrently, and now you're triaging a wall of red instead of a single problem.

The pilot: two repos, chosen to disagree

The trick isn't "test it somewhere first." It's picking the right somewhere.

I have two ways a repo consumes the shared framework:

one pulls it from a package registry at a pinned version,
the other uses a local path repo — a symlink to a checkout that moves with development.

So the pilot was one of each. Not two similar repos — two that maximize the difference along the axis most likely to break. If a change survives both consumption modes, it'll probably survive the rest. If it breaks, it breaks here, cheaply, where I'm paying attention.

Blocker 1: the local green was a lie

The linter ran fine on my machine in every repo. Then I pushed it to the two pilots' CI and both went red immediately — a hard fatal, exit 255, before the linter did any work.

The cause: the linter loaded the framework's own dependencies to run. On my machine that resolved, because my local setup symlinks to a full checkout of the framework, dependencies and all. But a consumer doesn't have the framework's private vendor/ tree, and CI does a shallow clone without installing it. So the exact same command that was green locally was a guaranteed fatal in every consumer.

"Works on my machine" had a specific, mechanical reason to lie: the symlink was hiding the fact that consumers don't get the tool's dependencies. The fix was to resolve against the consumer's dependency tree instead of the tool's. Small change. But if I'd fanned out first, it would have been a dozen red pipelines at once, all with the same confusing exit 255.

Blocker 2: the linter was wrong about my own fleet

The second one was more humbling.

One of the linter's rules flags hardcoded default secrets — a real thing you want to catch. But my correct, intended pattern for dev secrets routes them through a guarded resolver that refuses to use them in production. The rule saw the literal and screamed, not understanding that this literal was the safe, guarded case.

So the linter's very first real run produced a false positive in roughly eleven of my products at once — every repo that used the guarded pattern, which is to say every repo doing it right.

That's the nightmare version of a fleet-wide rollout: a tool that's confidently, uniformly wrong. If those false alarms had landed in a dozen repos on the same afternoon, the rational response would have been to distrust the linter and turn it off — killing the whole effort. Instead, the pilot showed me the rule needed an exception for the guarded pattern before anyone else saw a single false alarm.

What I'd have lost by skipping the pilot

I want to be honest about this part: the "dozen simultaneous red pipelines" is a thing that didn't happen, so there's no log of it. It's a projection, not an incident.

But it's a well-supported projection. Both blockers came from structure shared by every consumer — the dependency layout and the guarded pattern — so both would have fired everywhere. The pilot didn't get lucky with two repos; it exercised the two conditions that made the failures universal. That's the difference between "I tested it" and "I tested the thing that varies."

The method, generalized

Unknown blockers live in the consumer, not the tool. A shared tool's own green suite doesn't cover the environments it will run in. Assume the interesting failures are downstream.
Blast radius = consumers × shared structure. If a failure comes from something all consumers share, fanning out multiplies it. Sequence it instead.
Pick the pilot to span the variation axis. Two repos that differ where breakage is likely beat ten repos that are all the same. Diversity, not count.
Leave a stop valve. Every rollout step — human or agent — should be allowed to halt and escalate when a premise looks wrong, instead of pushing through.

There was a bonus, too. Once the linter was correct and did fan out, it immediately surfaced a genuine latent auth gap in one repo that everyone had walked past. The tool I built to prevent drift turned out to be a decent detector of the drift already there. But it only earned that trust because it didn't cry wolf a dozen times on day one.

When you roll a change across many repos, what's your pilot — and how do you choose which repos go first?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

Why My Install Zip Won't Upload: 89MB, and Half Is a PDF Library's Fonts

HideyukiMORI — Tue, 28 Jul 2026 14:28:00 +0000

My install package is 89MB. A lot of Japanese shared hosts cap uploads somewhere between 2 and 50MB. So the simplest distribution path I offer — download a zip, upload it through a control panel — just doesn't work for a chunk of the people I built it for.

Docker never told me this. A container doesn't care about a 90MB layer. A shared host's upload form does, and that's a constraint my whole dev setup was structurally blind to.

I blamed the wrong fonts

My first instinct was the heading fonts. The app bundles IPAex for headings — a few megabytes of TTF — and that was the obvious suspect. I even had a build report that agreed with me and pointed the finger there.

Then I actually unzipped the release and measured.

IPAex wasn't the problem. The heading fonts were about 9MB compressed — real, but not the story. The story was the PDF library's bundled CJK fonts. Two files alone:

Sun-ExtA.ttf — about 22MB on disk
Sun-ExtB.ttf — about 17MB on disk

Those two, plus the rest of that library's font directory, were the single largest region of the package by a wide margin — roughly half the compressed zip. I'd been ready to optimize the 9MB I could see instead of the 40MB I couldn't, because I trusted a summary instead of the artifact.

Lesson one, before anything else: when something is too big, measure where the bytes actually are. Not where a report says. Where unzip -v says.

Why the fonts can't just go

The tempting move is "delete the giant fonts." I can't.

The app generates PDF invoices, and it has to render Japanese — including the rare Extension-B kanji that show up in real personal and place names (the kind where someone's surname uses a character most fonts don't have). Drop those fonts and the invoice renders tofu — little empty boxes — for exactly the customers whose names are unusual. For a compliance document, that's not a cosmetic bug. It's wrong output.

So the fonts are load-bearing. The size isn't waste; it's the cost of rendering a whole writing system correctly.

The design (which I have not shipped)

Here's where I have to be careful, because it would be easy to write this as a finished story. It isn't one.

What I've designed — and written up as an architecture decision, not yet built — is a deferred font pack:

Ship only the minimal fonts the PDF engine needs to boot, plus the small heading set. That gets the base package under typical upload limits.
Publish the big CJK fonts as a separate, versioned, signed artifact. Verify it on arrival with a SHA-256 and a bundled public key; refuse to use it if the signature doesn't match.
Fetch it two ways: server-side over HTTPS by default, with a manual upload fallback for hosts that block outbound connections.
Fail closed. Before generating a PDF, check that the required fonts are present. If they're missing and can't be fetched, don't emit a tofu invoice — stop with a clear error.

That's the plan. The architecture decision is written down and currently marked proposed; the implementation issue is open; there is no slimmed build yet.

Which means I'm not going to tell you it dropped to 20MB or 40MB or any number, because I haven't built it and measured it. I've seen enough of my own writing lately claim outcomes that hadn't happened. The honest version is: here's an 89MB problem, here's where the bytes are, and here's the design I'm going to try. If the slimmed number turns out interesting, that's a follow-up post with a real measurement in it.

The takeaway that generalizes

Two things I'll actually carry forward:

Distribution size is a first-class constraint, and Docker hides it. If you ship anything people install by hand — a plugin, a zip, an appliance — the size limit lives in someone's upload form, and your container-based workflow will never surface it. Put it in CI or a checklist, because you won't feel it otherwise.

Optimize the measured bytes, not the visible ones. The fonts I could name were not the fonts that mattered. I nearly spent effort on the 9MB in front of me because I hadn't opened the box.

What's unexpectedly blown up an artifact or image size for you — and when you finally measured, was it the thing you first blamed?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

The Codemod Left My Build Red: I Committed Its Output Untouched Anyway

HideyukiMORI — Tue, 28 Jul 2026 14:26:55 +0000

This week I ran the same codemod, at the same version, across four of my repos. It left a different gap in each one — and in two repos, its raw output didn't even type-check.

I committed that output as-is anyway. On purpose. Here's why.

The setup

The codemod is nene2-a1-hooks-to-model, from my published standards package (@hideyukimori/nene2-standards@1.1.0). It does one boring thing: move React hooks from features/*/hooks/ into model/, per the layering convention my frontends share, and rewrite the imports that point at them.

I ran it, one-shot via npx, in four repos: nene-field, nene-suite, nene-profile, and nene-contact.

Four repos, four different gaps

Same tool. Same version. Four outcomes:

nene-field (PR #102): the clean case. 15 hooks moved across 10 slices, 15 files' imports rewritten, +18/−18 lines, every move detected as a 100%-similarity rename. Nothing to add by hand.
nene-suite (PR #389): the moves were fine (18 files, all renames at 100% similarity), but the codemod reprinted two files it touched with formatting that disagreed with the repo's Prettier config. A +2/−2 formatting fight.
nene-profile (PR #120): hooks/ contained a non-hook file — a shared zod schema. The codemod moved the two hooks that imported it, left the schema behind, and didn't rewrite their relative ./preset-schema imports. Raw output: tsc -b red, TS2307 × 2.
nene-contact (PR #401): 13 hooks and a co-located test moved — and zero imports rewritten. 24 importer references now pointed at files that weren't there. Raw output alone: type errors, by design of the PR.

So a mechanical migration needed a human (well, a human-supervised agent) to finish it in three of four repos. That's normal. The question is what you do about it.

The temptation is to patch silently

The easy move: fix the imports, run Prettier, squash, open a green PR titled "applied the codemod."

Now the diff is a lie. It claims a machine did all of it. Your reviewer — future you, a colleague, or an AI agent reading history to learn "how migrations are done here" — can no longer tell which lines a deterministic tool produced and which lines a tired human typed at 1 a.m.

Commit 1 is what the machine did. Commit 2 is what it couldn't. Never mix them.

The pattern: commit-separated gaps, with rename proof

Every one of these PRs follows the same discipline:

Commit 1: the codemod's raw output, byte-for-byte, zero edits. Even if it's red. In nene-contact, commit 3b71717 is intentionally broken on its own — the PR body says so out loud, so nobody bisecting later is surprised.

Commit 2 (and 3): mechanical completion only, one kind of mechanical thing per commit. In nene-profile that meant two commits: b58aaa9 is a pure git mv of the leftover schema file, and e0e0e40 is a single import-path line. In nene-suite, commit 8044f11 is only prettier --write restoring the repo's formatting on the two reprinted files. In nene-contact, commit 661f2b0 fixes the 24 importer references and re-runs the formatter.

And you paste the proof in the PR body. For the git mv commit, that's rename detection:

$ git show b58aaa9 --find-renames --name-status --format=
R100    frontend/src/features/mapping-presets/hooks/preset-schema.ts    frontend/src/features/mapping-presets/model/preset-schema.ts
 1 file changed, 0 insertions(+), 0 deletions(-)

R100 — 100% similarity, zero insertions, zero deletions. The reviewer doesn't have to trust my adjective "mechanical." Git certifies it.

For an import fix, the proof is exhaustiveness: in nene-profile I noted that grep -rn "hooks/" frontend/src returned exactly the one line commit 3 changes. The completion commit isn't "some cleanup" — it's provably the whole gap and nothing else.

What this buys you

Review time collapses to where it belongs. Commit 1 is audited as "do I trust this tool at this version" — once, cheaply, across every repo it runs in. Commits 2–3 are audited line-by-line, but they're tiny (1 line; +2/−2; 24 one-pattern references) and each does one nameable operation.

And the gap itself becomes a first-class artifact. Because the profile run isolated exactly what the codemod failed to do, filing it upstream was trivial: nene2-fleet-tooling#83 documents the leftover-file and unrewritten-import behavior, with the TS2307 reproduction pasted in. That issue is still open — the tool isn't fixed. But the workaround is a documented, repeatable pattern instead of four divergent hand-patches, and when the fix lands, commit 2's exact shape tells us what should disappear from future runs.

Silent hand-patching produces none of this. It just makes the tool look better than it is.

Where I'd skip all this

Honestly: a solo throwaway repo, a one-file move, no reviewers, no agents reading history? Just fix it and squash. The ceremony has a cost.

The discipline earns its keep the moment anyone — human or model — needs to answer "what did the machine actually do?" from the record. In my case that's every migration, because the record is what my AI agents learn the house style from.

Takeaways

A codemod PR should let a reviewer audit "machine work" and "human completion" separately — that's a commit boundary, not a PR description.
Prove the mechanical-ness: git show --find-renames for moves (R100), a grep count for import fixes, "formatter only" for reprints.
When the tool leaves a gap, file it upstream with the isolated diff — the separation gives you the reproduction for free.

Primary sources

nene-profile PR #120 (commits 9c28709 / b58aaa9 / e0e0e40, rename proof in body) and issue #119
nene-suite PR #389 (commits e28f0b0 / 8044f11)
nene-contact PR #401 (merge 59f283e, commits 3b71717 / 661f2b0)
nene-field PR #102 (move-only, +18/−18)
Upstream gap: nene2-fleet-tooling#83 (open)

How do you make codemod PRs reviewable — squash and trust the tool, or separate and prove it? I'd genuinely like to hear where you draw the line.

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

An Honesty Guard for AI Subagents: The Fabrication It Caught Was Mine

HideyukiMORI — Tue, 28 Jul 2026 14:26:48 +0000

I run a small fleet of open source business tools, mostly solo, with AI subagents doing a lot of the grunt work: reading across repos, drafting docs, cross-checking claims against the actual code.

For a while, my problem with that setup wasn't wrong code. It was confident prose.

An agent would write "this was standardized in the framework" — and it sounded right, and the framework did have something like it, and if I hadn't gone and looked, I would have shipped a sentence that was simply not true. Not malicious. Just the model smoothing a gap with something plausible.

So I added one paragraph to the instructions every subagent gets.

The paragraph

It's not clever. It's a standing rule, in every task:

Cite it or drop it. Every claim comes from a named source — a file, a PR, a line. If you can't source it, don't assert it; skip it and say you skipped it.
Don't link to anchors you haven't confirmed exist.
Report what you couldn't do. A skipped step is information, not a failure to hide.
Don't touch unrelated changes. Check git status before you start.

That's it. No framework, no eval harness. A short list that turns "sound confident" into "show the receipt."

What the agents did with it

The interesting part is that the agents started policing themselves.

In one run, an agent was documenting a feature and was about to reuse a phrasing from a sibling repo — "synchronization was made standard here." It checked, found the sibling had no such thing, and left the claim out on its own, with a note that it couldn't source it.

In another, it wanted to deep-link to a named section that didn't exist. Instead of inventing the anchor, it fell back to a file-level link and flagged it.

And the one I keep thinking about: an agent was handed an instruction that said a piece of work was "Phase 2, in progress." It went to check the current state, found that phase had already shipped days earlier, and corrected the instruction I gave it.

That last one matters. The guard wasn't just stopping the agent from making things up. It was catching my stale assumptions, because "verify against the record" cuts both ways.

Then it caught me for real

Here's the part that earned the whole thing.

I had an agent draft a technical article — a failure story about a bug on shared hosting. Every code snippet was correct. Every default value, every config detail, checked out against the repo. It was, technically, flawless.

The framing was fiction.

The article told it as a lived production incident: "I shipped the in-memory version, tests were green, and in production it never fired." Compelling. Also something that never happened. The git history was unambiguous — that component had been file-backed from its very first commit. The in-memory version was never deployed. The "production incident" I was about to narrate in the first person had no trace in the code or the records.

A guarded review caught it before it went out. I run new drafts through an adversarial pass — a few reviewer personas plus a hard cross-check against the actual repo and my own work logs — and the verdict was unanimous: the technical content is true, the story is invented. The fix was to demote the fake incident to what actually happened — a design decision ("shared hosting can't do in-memory counters, so it was file-backed from day one") — and keep every correct code block.

Then I checked the sibling articles in the same series. Two more had the same shape: real bugs, but dressed up as production incidents that were actually caught in a staging rehearsal. One was clean — a genuine outage, logged and dated. So I fixed the two, left the real one alone, and moved on.

The lesson isn't "trust the AI more"

It's the opposite. The guard works because it doesn't rely on trust. It makes "cite it or drop it" the path of least resistance, so the cheap move is also the honest one.

And it reframed what I was even guarding against. I started out worried about agents inventing APIs. The failure mode that actually threatened me was subtler: prose that is factually correct at the code level and fictional at the story level. A test suite can't catch that. A linter can't catch that. Only checking the narrative against the record does — the same move the guard already required for facts, applied one level up.

So the honesty guard grew a second clause, for anything written in the first person: the story has to be verifiable too, not just the code. "This broke in production" is a factual claim. It needs a log, the same way a benchmark needs a number.

What I can and can't claim

I'm not going to tell you fabrications went to zero forever — I have no counter for that, and the honest evidence cuts against the clean version anyway. What I can say is narrower and, I think, more useful:

In the runs where the guard was in the prompt, the agents stopped filling gaps with plausible-but-unsourced claims, and started reporting the gaps instead.
When a fabrication did reach a draft, a guarded review — personas plus a record cross-check — caught it before publish.

Two different mechanisms, same principle: make the receipt mandatory, at the fact level and the story level.

None of this is a framework I'm selling. It's four sentences in a prompt and a habit of checking the narrative, not just the numbers.

What's in your AI agents' instructions to stop them from making things up — and does it cover the story, or only the facts?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

CI Paid for Itself on the First Run: 4 Repos, Real Bugs

HideyukiMORI — Mon, 27 Jul 2026 12:13:44 +0000

I added CI to four small apps that had been living without it. The first run went red before it executed a single test — and not because my code was broken. Because a file I had never actually tested was.

Here's what a first CI run catches that your machine has been quietly hiding.

The pipeline was nothing special

Same shape for all four: fresh checkout, cp .env.example .env, install dependencies, run the checks, run a dependency audit. The kind of thing you'd copy off a template in ten minutes.

The value wasn't the sophistication. It was the word fresh. My laptop has a real .env, an installed node_modules, a warm cache, and years of accumulated state. CI has none of that. It starts from what's actually committed — which turns out to be a very different thing.

Bug type 1: `.env.example` broke a clean boot

Two of the four repos couldn't boot from their own example environment file.

The values had unquoted spaces — think APP_NAME=My App — and the dotenv parser rejects that outright. On my machine it never mattered, because I have a real .env from months ago and never re-copy the example. CI copies the example on every run, so the first thing it did was fail to parse it, which failed to boot the app, which took a chunk of the test suite down with it before any real test ran.

That's the whole "works on my machine" trap in one line: the example env is a file you ship to every new contributor and every deploy, and it's the one file your own environment guarantees you'll never exercise.

Bug type 2: a required variable was in the example, but blank

Related, in one of those same repos: a required encryption key was listed in .env.example but deliberately left blank — it's a secret you don't commit — so a fresh checkout had no usable value for it. The app booted fine for me — my environment had a real key — and fell over in the clean room, where there was nothing to fill it in with.

CI made the missing value explicit the only way that ever really happens: by being a machine that starts from nothing.

Bug type 3: the audit gate caught real, known vulnerabilities

The pipelines ran a dependency audit and failed on high-severity findings. This wasn't uniform, and I want to be precise — including about the limits of what I can still reproduce:

One repo's audit flagged a high in its build-tool chain — a vite advisory of the kind npm audit fix clears. This is the one I can point you straight at: it's documented in that repo's CI-setup PR.
My notes from the same week flagged advisories in a second repo's test-runner / vite chain, but the pinned lockfile I can re-audit today comes back clean. So I'll only claim what the PR trail still shows, and leave that one as "flagged then, not reproducible now."
The other repos turned up moderate/low at most.

So the honest version is smaller than "every repo was hiding a critical": at least one repo had a real high-severity advisory that the first gated npm audit surfaced — sitting there silently because nobody had ever run npm audit in a gate that could fail.

The pattern, not the scoreboard

None of these were logic bugs. Every one lived in the gap between "runs on my machine" and "runs from a clean checkout": a broken example env, an undocumented required variable, a stale dependency nobody re-audited.

My machine had exactly the state needed to hide all three.

I'll be honest about the counting, too. I'm not going to hand you a tidy "13 products now have CI" number — the exact figure depends on what you call a product, and it was a self-tally at the end of that week, not a measurement. What I can stand behind is smaller and more useful: four repos that had no CI, one afternoon of adding the most boring possible pipeline, and real defects on the first run of each.

That's the argument for CI I actually believe. Not "it catches regressions someday" — that's the slow, abstract payoff. The immediate one is that CI is the only environment that starts from nothing, and starting from nothing is where your .env.example, your undocumented variables, and your un-audited dependencies all come due at once.

The four CI-setup PRs, if you want the workflow files and the audit output: nene-field, nene-contact, nene-deal, nene-vault.

It's the same bet I made on my documentation, for the same reason: 261 docs in 6 languages with one maintainer, where the index is generated and CI goes red when it drifts. Different problem, identical logic — a machine that checks every single time doesn't have a bad week, and I do.

If you've got a repo running without CI right now, the cheapest pipeline you can write will probably pay for itself on run #1.

What did your first CI run catch that your machine had been hiding?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

HideyukiMORIFollow

Building API-first PHP tools for self-hosted business workflows. Creator of NENE2 and the NeNe OSS series.

261 docs, 6 languages, one maintainer: frontmatter is the source of truth

HideyukiMORI — Fri, 24 Jul 2026 16:17:54 +0000

If you maintain a docs folder that keeps drifting — missing index entries, stale translations, categories that no longer match — this is for you.

NENE2 is my small PHP framework for building AI-readable business APIs.

Repository:

https://github.com/hideyukiMORI/NENE2

Over time it grew a large set of how-to guides. Today the English directory holds 261 guides, and every one of them is mirrored into five more languages: Japanese, French, Chinese, German, and Brazilian Portuguese.

That is 261 guides across 6 locales — 1,566 files in all.

Maintained by one person.

The only way this stays sane is to stop treating docs as prose and start treating them as data.

This article is about the machinery that makes that possible.

What you'll learn:

How to make YAML frontmatter the single source of truth and regenerate every index from disk
How to keep six-locale translations in sync without duplicating the taxonomy
How to turn index drift into a red CI check instead of a manual chore

The problem with hand-maintained indexes

If you have ever kept a docs folder, you know how index pages rot.

You add a guide. You forget to add it to the index. Someone else renames a file. The category list drifts. A translation goes missing and nobody notices for months.

None of this is dramatic. It is just slow decay.

At six guides it does not matter. At 261 × 6 it is fatal.

So the rule I settled on is simple:

No index is ever edited by hand. Every index is regenerated from the files on disk.

Frontmatter is the source of truth

Each English guide opens with a YAML frontmatter block:

---
title: "How-to: A/B Testing Framework"
category: product
tags: [ab-testing, experimentation, state-machine, analytics]
difficulty: advanced
related: [feature-flags, feature-flag-api]
---

That block is the source of truth for everything the index knows about the guide:

title — display name
category — one of seven fixed buckets
tags — lowercase kebab-case labels
difficulty — beginner, intermediate, or advanced
related — slugs of sibling guides
ft — an optional field-trial reference

The seven categories are fixed in code:

getting-started
auth
security
database
api-design
infrastructure
product

The guide body follows the frontmatter. The frontmatter is not decoration — it is structured data that a generator reads.

The generator

A single script, tools/build-howto-index.php, rebuilds every index. It is wired to composer howto:index.

For English, it walks every guide, parses the frontmatter, and groups guides into the seven categories. It writes two things:

a "Browse by category" table injected into docs/howto/README.md
a separate by-tag.md page grouping every guide under each tag

The category loop is the whole idea in a few lines:

foreach (guideFiles($dir) as $file) {
    $slug = basename($file, '.md');
    $fm   = readFrontmatter($file);
    if ($fm === null || !isset($fm['category'])) {
        $missing[] = basename($file);
        continue;
    }
    $byCategory[(string) $fm['category']][] = [
        'slug'       => $slug,
        'title'      => $fm['title'] ?? $slug,
        'difficulty' => $fm['difficulty'] ?? '',
        'tags'       => $fm['tags'] ?? [],
    ];
}

Guides that have no frontmatter, or no category, are not silently dropped. They are collected into $missing and printed as a warning. Skipping something is a visible event, not a quiet gap.

Translations carry no frontmatter

Here is a decision that surprises people: the translated guides have no frontmatter at all.

A Japanese guide starts straight with its H1:

# ハウツー: A/B テストフレームワーク

There is no category: line in the translation. Duplicating the taxonomy into six languages would mean six chances to drift out of sync.

So the generator treats locales differently. For every non-English locale it builds a flat, alphabetical index using the first H1 it finds in each file:

function howtoTitle(string $path): string
{
    foreach (preg_split('/\r?\n/', file_get_contents($path)) as $line) {
        if (preg_match('/^#\s+(.+?)\s*$/', $line, $m) === 1) {
            return $m[1];
        }
    }
    return basename($path, '.md');
}

The taxonomy lives in exactly one place — the English frontmatter. Translations only need to exist and have a heading. That keeps the source of truth singular.

Injecting without clobbering

Each README has a hand-written part I want to keep: a curated "I want to…" finder table.

So the generator does not overwrite the whole file. It only replaces the content between two markers:

<!-- AUTO-INDEX:START (generated by `composer howto:index` — do not edit by hand) -->
...regenerated content...
<!-- AUTO-INDEX:END -->

Everything before the start marker and after the end marker is preserved verbatim. The injection is idempotent: run it twice and you get byte-identical output. That property is the reason the whole thing can be enforced in CI.

Drift is a CI failure

The generator is only useful if a stale index cannot be merged. That guarantee lives in the CI pipeline:

- name: Verify howto index is up to date
  run: |
    composer howto:index
    git diff --exit-code docs/howto/README.md 'docs/*/howto/README.md' docs/howto/by-tag.md

- name: Validate howto frontmatter
  run: composer howto:frontmatter -- --require-all

The first step regenerates every index and then runs git diff --exit-code. If regenerating produced any change, the working tree is dirty, the diff is non-empty, and the build fails.

In other words: if you added a guide but did not regenerate the index, CI notices — because it regenerates the index for you and sees that your committed version does not match.

The second step is a separate validator, tools/validate-howto-frontmatter.php. It checks every English guide against the schema: required fields present, category and difficulty from the allowed sets, tags lowercase kebab-case, related pointing at guides that actually exist. The --require-all flag means an English guide with no frontmatter also fails the build.

Between the two steps, drift cannot accumulate silently. A missing index entry, a typo in a category, a broken related link, or a guide with no metadata all turn into a red check.

How it got here, in phases

This was not built in one shot. The git history shows a deliberate rollout:

Phase A — add auto-generated indexes at all, from the H1 heading.
Phase B1 — settle the frontmatter schema and prove it on five guides.
Phase B2 — annotate every English guide with frontmatter (256 at the time).
Phase B3 — regenerate the indexes from the frontmatter and make it permanently required in CI.

That last step is the one that flipped frontmatter from "nice to have" to "the build fails without it." The guide count has grown from 256 to 261 since then, and the machinery absorbed the growth without any manual index edits.

The translation workload

Adding a guide is not one file. It is one English guide plus five translations, and the index must stay complete in all six locales.

In practice the translations land in batches — the commit history has entries like "translate N untranslated guides into all five locales." This is an AI-assisted solo project, so drafting six language variants of a guide is exactly the kind of work that gets delegated to a model and then reviewed.

But the honest part is this: the quality gate is not "an AI wrote it." The gate is the same mechanical check for everyone. A translation either exists and produces an index row, or the locale index differs from what CI regenerates and the build goes red. The generator does not care who or what produced the file.

What I would tell my past self

Three things held up at scale:

One source of truth. The taxonomy lives in English frontmatter and nowhere else. Translations only mirror content, never metadata.
Generate, never hand-edit. Every index is a build artifact. The only hand-written parts sit outside the auto-index markers.
Make drift a failure, not a chore. Regenerate in CI and diff against the commit. A stale index is a red build, not a thing you hope someone remembers.

None of this is clever. It is boring on purpose.

Boring is what lets one person keep 261 guides alive in six languages without the docs quietly rotting underneath them.

A production fix trapped in a month-old feature PR: extract it and ship it alone

HideyukiMORI — Mon, 20 Jul 2026 15:14:37 +0000

If you've ever fixed a real bug inside a feature branch and then watched the fix wait weeks for the feature to merge, this is for you.

There is a failure mode that looks responsible but isn't: you find a real bug while building a feature, you fix it inside the feature branch, and then the whole thing waits for the feature to be reviewed and merged.

The bug is done. The fix works. But it can't ship, because it's now a passenger on a much bigger PR.

This happened in one of my open source projects, NeNe Vault, a self-hosted archive for received business documents. Here is what happened, the call I made, and the small mechanics of undoing it.

What you'll learn:

How to spot when a bug fix has become a hostage to a feature's review timeline
How to extract just the bug-fix subset and land it on main independently
How to keep the git history honest about where an extracted fix came from

The setup

A feature PR was open to add an integrity-verified inline preview to the document detail page: render stored images and PDFs in the browser, re-compute their SHA-256, and show a "verified" badge only when the hash matches.

It was a substantial change: a new preview component with tests, a data-fetching hook, object-URL lifecycle handling, new locale keys for two languages, and a scope-contract entry. Exactly the kind of surface that takes real review time.

While building it, the author noticed the page's Download button was already broken — unrelated to the preview, a pre-existing defect. So they fixed it in the same branch and noted it in the PR description under "also fixes a pre-existing download bug."

That is a reasonable instinct. You're already in the file, you see the bug, you fix it. The problem is what happens next.

The bug that was trapped

The download bug was not cosmetic. The Download button failed for every user role. Confirmed in a real-browser walkthrough of the deployed demo, admin and viewer alike.

Two defects lived in the same handler:

No credentials. It built a plain <a href> and clicked it. A plain link carries no Authorization header, and this backend is JWT-only with no session cookie — so the request could never authenticate, on any hosting environment.
Wrong key. The URL used the ordinal version_number (1, 2, 3…), but the download route is keyed by the version's ULID. So even an authenticated request would have hit a 404.

The demo walkthrough had a highlighted step: "download the document and verify its SHA-256." With this bug, that step could not be performed at all. This was a production-facing defect on a page that's supposed to demonstrate trustworthiness.

And the fix for it was sitting, done, inside a feature PR that had been open for close to a month.

The call

The rule I try to hold to is simple:

A bug fix and a feature have different urgencies. Do not couple their release.

The feature can take its time in review — that's healthy. But the production bug should not wait on the feature's review just because they happen to share a branch. The moment they're coupled, the fix inherits the feature's schedule, its review scope, and its risk of stalling.

So the call was: extract the bug-fix subset, land it on main on its own, and let the feature keep cooking.

Concretely, that meant three artifacts instead of one:

A bug issue describing only the download defect — root cause, reproduction, impact — and noting explicitly that the fix already exists inside the feature PR and is being extracted so it can land independently.
A small, focused PR containing only the download fix.
The original feature PR left open, to be rebased down to just the preview surface once the fix is on main.

The mechanics

The important part of splitting a fix out is honesty about provenance. You are not pretending the fix was written fresh. You're relocating a known-good change to a smaller, faster vehicle and saying so.

The extracted PR carried exactly the download plumbing and nothing else:

the authenticated blob-fetch method on the shared API client
the entity-layer helper that targets the ULID-keyed download path
the page change that resolves the version ULID from the history response and downloads through the authenticated client

Everything that belonged to the feature stayed in the feature PR: the preview component and its tests, the SHA-256 re-verification hook, the object-URL lifecycle for previews, the locale keys, and the scope-contract entry.

The core of the page-level fix was small. Before, condensed (the DOM-append boilerplate around the anchor click is elided in both snippets):

function handleDownload() {
  if (doc === undefined) return;
  const base = env.apiBaseUrl.replace(/\/$/, '');
  // ordinal version_number + plain <a href> => 404 and no auth header
  const url = `${base}/admin/vault/documents/${doc.id}/versions/${String(doc.version_number)}/download`;
  const a = document.createElement('a');
  a.href = url;
  a.download = doc.original_filename ?? `document-${doc.id}`;
  a.click();
}

After — resolve the real version ULID, fetch through the authenticated client, save from an object URL:

// The download endpoint is keyed by the version's ULID, which only the
// history response carries — the detail payload exposes just the ordinal.
const currentVersion =
  doc !== undefined
    ? history?.versions.find((v) => v.version_number === doc.version_number)
    : undefined;

async function handleDownload() {
  if (doc === undefined || currentVersion === undefined) return;
  const blob = await fetchDocumentBlob(doc.id, currentVersion.id);
  const objectUrl = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = objectUrl;
  a.download = doc.original_filename ?? `document-${doc.id}`;
  a.click();
  URL.revokeObjectURL(objectUrl);
}

Plus regression tests: at the entity level, that the request targets the ULID-keyed path and sends the auth headers; at the page level, that clicking Download issues a request keyed by the version ULID from the history response, not the ordinal 1.

The commit message recorded where the change came from, in words to this effect:

Extracted from the pending inline-preview feature PR, which first implemented this fix bundled with the preview feature; this lands the bug-fix subset on main independently.

That one sentence keeps the history honest. Anyone reading git log later can see that the fix and the feature are two halves of the same original idea, deliberately separated.

How it actually went

The whole extraction, once decided, was fast. The bug issue was filed, the focused PR opened a few minutes later, and it merged a couple of minutes after that — closing the issue. The production download failure was fixed on main the same afternoon, while the feature PR stayed open.

The feature PR didn't get thrown away. A comment on it recorded exactly what had been lifted out and what remained, so the suggested next step was a straightforward rebase: most of the download plumbing was already on main, so slimming the feature down to the preview-only surface would be mostly deletions. The rebase-or-close decision was left to the PR's owner. The feature was never the thing in a hurry.

When coupling is actually fine

To be fair to the original instinct: bundling a fix into a feature branch is not always wrong.

If the bug and the feature touch the same code, the feature is small and about to merge, and nothing production-facing is broken in the meantime — then splitting them is just ceremony. Ship the branch.

The signal that you have a problem is specific:

something production-facing is broken now, and
the branch holding the fix is not close to merging.

When both are true, the fix has become a hostage. The longer the feature takes, the longer a known, solved defect stays live in production for no reason other than branch geography. That's the case worth acting on. The rest of the time, use judgment and don't over-process it.

There's also a cheap diagnostic. When you write the PR description and find yourself adding a line like "this also fixes an unrelated bug," treat that sentence as a small alarm. It's telling you the branch is carrying two changes with two different reasons to exist. Sometimes that's fine. Sometimes it's the thing you'll wish you'd split a month from now.

The takeaway

Finding a bug while you build a feature is normal and good. Fixing it in the same branch is the trap — not because the fix is wrong, but because you've quietly bound a production concern to a feature's timeline.

When it happens, don't argue about whether the feature should merge faster. Just split the fix out:

File the bug on its own terms. Root cause, repro, impact — as if the feature didn't exist.
Extract only the fix. Leave every line that belongs to the feature behind.
Say where it came from. Provenance in the issue, the PR, and the commit message keeps the history readable.
Let the feature keep its own pace. It was never the urgent part.

Two changes with different urgencies should have two release paths. If a production fix is stuck behind a feature review, the feature isn't the problem. The coupling is.

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com

DEV Community: HideyukiMORI

My Upload Check Trusted the Attacker's Word: 8 Bytes Fixed It

What the check actually covered

How it was found

The fix: read eight bytes

The test that couldn't be written

What's still open

What I'd tell past me

HideyukiMORIFollow

Fact-Checking My Own Blog Posts Turned Into Product QA: 3 Real Bugs

Bug 1: the sentence was right, the product was late

Bug 2: "nothing accumulates" — except the thing that did

Bug 3: the demo was showing the future

Being honest about the yield

Why prose catches what tests miss

HideyukiMORIFollow

My Generator Hid a Lint Error: CI Never Checks What Nobody Commits

The setup

The bug

How it surfaced

The fix

The general lesson: enumerate your generator's branches

Takeaways

Primary sources

HideyukiMORIFollow

My Committed Bundle Went Stale: CI Rebuilt It and Never Compared

The setup

What broke

How it surfaced

The fix — and what the fix doesn't fix

The actual lesson: freshness must be a test

Takeaways

Primary sources

HideyukiMORIFollow

Half My Tests Failed and None Were Broken: My Shell Poisoned PHPUnit

The symptom

Correction #1: the tests were fine, my machine wasn't

Correction #2: I blamed the scary variable, not the guilty one

The fix was one attribute

What I can't tell you

Two takeaways

HideyukiMORIFollow

Pilot Then Fan Out: Killing Unknown Blockers in 2 Repos First

Why fan-out is tempting, and why it bites

The pilot: two repos, chosen to disagree

Blocker 1: the local green was a lie

Blocker 2: the linter was wrong about my own fleet

What I'd have lost by skipping the pilot

The method, generalized

HideyukiMORIFollow

Why My Install Zip Won't Upload: 89MB, and Half Is a PDF Library's Fonts

I blamed the wrong fonts

Why the fonts can't just go

The design (which I have not shipped)

The takeaway that generalizes

HideyukiMORIFollow

The Codemod Left My Build Red: I Committed Its Output Untouched Anyway

The setup

Four repos, four different gaps

The temptation is to patch silently

The pattern: commit-separated gaps, with rename proof

What this buys you

Where I'd skip all this

Takeaways

Primary sources

HideyukiMORIFollow

An Honesty Guard for AI Subagents: The Fabrication It Caught Was Mine

The paragraph

What the agents did with it

Then it caught me for real

The lesson isn't "trust the AI more"

What I can and can't claim

HideyukiMORIFollow

CI Paid for Itself on the First Run: 4 Repos, Real Bugs

The pipeline was nothing special

Bug type 1: .env.example broke a clean boot

Bug type 2: a required variable was in the example, but blank

Bug type 3: the audit gate caught real, known vulnerabilities

The pattern, not the scoreboard

HideyukiMORIFollow

Bug type 1: `.env.example` broke a clean boot