A message visibility hotfix opened on April 4. By midday it had sprawled into a documentation rebuild and a PreToolUse hook that refuses to let Claude edit master or develop. The hotfix shipped. Everything around it was collateral.

That same window also held a build failure I had to root-cause and a mobile login button regression. The ticket you open is rarely the hardest thing you touch that day. That is the actual texture of the work when you’re the one holding the keyboard.

the docs viewer was a file dump wearing a costume

The production app’s staff portal has a documentation viewer. Before April 4, it was a file dump. You could navigate to a path, get raw content rendered in some approximate way, and that was it. No breadcrumbs, no consistent styling, no AJAX loading, no client-side markdown. The kind of page you build when you need something, then come back to never.

I rebuilt it. The new version uses external JavaScript and CSS, loads docs via AJAX, renders markdown client-side through marked.js, and has breadcrumb navigation that tracks where you are in the folder structure. The portal’s goals section got reorganized into a real folder hierarchy. Dead sections got cut. AI and Dev Notes surfaces got added to the layout.

The practical bugs took longer than the architecture. UTF-8 handling required ADODB.Stream because the simpler path was silently mangling characters. Windows backslash paths were breaking the URL routing, which I found the usual way, by loading a doc with a nested path and getting a 404 with no obvious cause. The host template’s CSS was bleeding into rendered doc content, so headings inside documents inherited styles from the surrounding admin chrome. Each of these is the kind of bug that only surfaces in a real system, on real infrastructure, once someone actually opens the page.

the branch guard was the consequential change

While I was in the viewer, I added a PreToolUse hook to the Claude Code settings. This matters more than the docs work.

In this configuration, the hook ran before Edit or Write calls. It read the current branch, compared it with permitted branch conventions such as feature/ and hotfix/, and returned a one-line refusal on protected branches. master and develop were protected. The goal was a visible stop before a write, rather than relying only on a later commit check.

This is the same family of safety as the commit lock wrapper that coordinates repo access across sessions. But the lock wrapper operates at commit time. The branch guard operates before the first file is touched. Earlier in the loop means cheaper to catch.

Why does this exist? Because AI-assisted work changes the error mode. When I was the only one editing files, a wrong-branch mistake cost me a git checkout and a few minutes. When an AI-assisted session edits files, I might not notice the active branch until several changes have accumulated. A session can follow the stated task while the wrong branch is checked out unless branch context is surfaced and constrained. The guard is not distrust of the model; it makes a repository constraint explicit at the point of action.

I also spent part of that afternoon on agent governance design. I talked myself into building a dedicated task manager to track agent work state outside JIRA, then talked myself back out of it. JIRA already has the fields I would build. Adding a parallel structure means two places to check and two places to drift. I pushed the impulse back into JIRA and kept moving. Not every internal-tooling itch should become a build.

what I had not said out loud yet

The message visibility fix was what I opened the session for. The docs viewer and the branch guard were what the day revealed I needed.

The docs viewer became important because I used the staff portal as a durable reference surface across AI-assisted sessions. A file dump makes orientation harder; a navigable, consistently rendered surface gives people and tools a clearer starting point. The quality of that internal surface affects how much re-orientation the work requires.

The branch guard became load-bearing because I had been one careless session away from a bad edit on develop. I knew that in the back of my head. I had not written it down as a constraint the system enforces.

Two things stay honestly unresolved. A PreToolUse hook works cleanly in a single-agent session. Once multiple agents are editing across task branches at the same time, the enforcement model gets more complicated. Which session’s hook applies when two agents are open on the same repo? And does the rebuilt docs portal stay useful as goals, AI notes, and dev notes keep expanding? A better viewer is only a partial answer to the information-architecture problem.

Once AI starts helping you ship, internal docs and branch guardrails become part of the operating system around the product. They need the same ongoing ownership, review, and maintenance as other high-leverage internal surfaces.