DEV Community: Russell Jones

A beginner's guide to Git worktrees: What they are, why they matter, and how to use them without breaking anything

Russell Jones — Thu, 16 Jul 2026 20:47:15 +0000

Ahnii!

If you have ever needed to work on two branches at the same time, Git worktrees can save you a lot of friction. This post covers what worktrees are, why they exist, and how you can use them safely as a beginner.

Prerequisites

You have Git installed
You can run commands in your terminal
You already have a local repository

What Is a Git Worktree?

A Git worktree is an extra working folder connected to the same repository history.

You can think of it as another checkout of your project, without making another full clone.

Your main folder still exists. A worktree gives you a second folder where a different branch can be checked out at the same time.

Why Worktrees Exist

Git worktrees solve a practical problem. You may be in the middle of feature work, then need to fix a bug on another branch right away.

Without worktrees, you usually do one of these:

Stash or commit unfinished work, then switch branches
Open a second full clone of the same repository

Both options work, but both add overhead. Worktrees give you a cleaner path.

Normal Clone vs Branch Checkout vs Worktree

Here is the simple difference:

Normal clone

A clone is a separate copy of a repository with its own .git directory.

git clone https://github.com/example/project.git

You use this when you need the repository on your machine for the first time. It is fully independent from other clones.

Branch checkout

A branch checkout changes which branch is active in your current folder.

git checkout feature/foo

This is fast, but only one branch can be active in that folder at a time.

Worktree

A worktree creates another folder tied to the same repository, usually on a different branch.

git worktree add ../feature-foo feature/foo

Now you have two folders open at once: your main folder and ../feature-foo. Each can point at a different branch.

Core Benefits of Worktrees

1) Multiple branches checked out at once

You can keep your main branch open in one folder and your feature branch in another.

No constant branch switching.

2) Isolated environments for experiments

You can test risky changes in one worktree without touching the working state in another folder.

3) No need for multiple full clones

Worktrees share repository data, so you avoid duplicate clones for everyday branch work.

A Safe Beginner Workflow

This is a clean workflow you can use right away.

1) Create a worktree

git worktree add ../feature-foo feature/foo

This command creates a new folder named ../feature-foo and checks out feature/foo there.

If feature/foo does not exist yet, create it first with git branch feature/foo.

2) Switch into it

cd ../feature-foo

Now every Git command runs inside that worktree folder.

Before you edit files, confirm where you are with pwd and git branch --show-current.

3) Commit from it

git add .
git commit -m "Add first pass of feature foo"

These commits belong to the branch checked out in that worktree.

You do not need to return to your original folder to commit.

4) Remove it safely

First leave the worktree folder, then remove it with Git.

cd ../your-main-repo
git worktree remove ../feature-foo

This tells Git to unregister the worktree and remove the directory safely.

Always prefer this over deleting the folder manually.

How to See Your Current Worktrees

git worktree list

This shows every registered worktree path and branch.

Use this often, especially when you are learning.

Common Beginner Mistakes

Deleting the directory without removing the worktree

If you run rm -rf on a worktree folder first, Git can keep stale metadata.

Remove worktrees with git worktree remove <path> whenever possible.

Forgetting which worktree you are in

It is easy to commit to the wrong branch when two folders look similar.

Check pwd and git branch --show-current before making changes.

Trying to check out the same branch twice

Git does not allow the same branch to be active in two worktrees at once.

Create a new branch if you need a second experimental space.

A Simple Mental Model for `.git/worktrees`

Your main repository still has the real Git database.

Inside it, .git/worktrees stores small records that point to each extra working folder.

Think of it like a clipboard that says:

Which extra folders exist
Which branch each one uses
Whether Git still expects them to be present

That is why manual deletion can confuse Git. The clipboard still has an entry, even if the folder is gone.

How to Clean Up Orphaned Worktrees

Sometimes a worktree folder gets deleted outside Git.

You can clean this up safely in a few steps.

Step 1: List what Git thinks exists

git worktree list

Look for paths that no longer exist on disk.

Those are likely orphans.

Step 2: Prune stale metadata

git worktree prune

This removes stale worktree entries that no longer point to valid folders.

It is a safe maintenance command for this situation.

Step 3: Verify cleanup

git worktree list

Run the list command again to confirm orphan entries are gone.

If everything looks clean, you are done.

Verify It Works

Run this quick check whenever you start using worktrees:

git worktree list
git branch --show-current
pwd

These three commands tell you what worktrees exist, which branch is active, and which folder you are in.

That simple habit prevents most beginner mistakes.

Baamaapii

The hackathon Anthropic didn't expect

Russell Jones — Thu, 16 Jul 2026 20:47:11 +0000

Ahnii!

Casey Newton interviewed Boris Cherny, the creator of Claude Code, for Platformer last week. Most of the coverage pulled the headline-friendly quote that coding is "solved" and moved on. I want to point at a smaller moment in the same interview that I think matters more. This post is about that moment, and three things I've watched up close that line up with it.

The hackathon Anthropic didn't expect

Newton asks Cherny about the AI divide. The worry, in shorthand, is that the people who already have power will use these tools to get more of it. The early data on who benefits from new technology usually goes that way. So who's actually getting the most out of Claude Code?

Cherny's answer surprised Newton, and it surprised me when I read it. He talks about a recent Anthropic hackathon for the Opus 4.7 release, and says the people who won were largely not professional engineers. "There was an electrician, a doctor, a carpenter who used it to build an app." Same pattern at the 4.6 hackathon. He calls it a continuous surprise. The people who get the most value out of Claude Code, he says, are not the people he'd expect.

That's a small line in a long interview. It's the line I haven't stopped thinking about.

Two questions, not one

The AI-jobs discourse is mostly fighting over one question: will engineers be replaced. Cherny's answer to that question, if you read the whole interview, is actually mild. He thinks the title "software engineer" probably changes ("builder" is the word he uses), the role expands, and the number of people writing code with the help of agents goes up roughly a hundred-fold. That's not an extinction story. It's a transformation story, with a hiring pull, not a layoff cliff.

But that's not the only question we should be asking. The other question is the one Newton was getting at: when the syntax gate falls, who walks through?

The hackathon detail is an early answer. Not "the engineers got faster." An electrician, a doctor, and a carpenter built apps that won. The default story we tell about new technology — the people in the room get more powerful first — doesn't fit. The people in the room didn't even win.

Three things I've watched up close

Here's what I'm seeing in three different places.

I just finished my Grade 12 coursework as an adult learner through Sagamok Anishnawbek's Lifelong Learning Centre. AI was in the loop for a lot of it. I'm not the demographic anyone meant when they said "AI for developers." I'm a forty-something who came back to finish his OSSD, and the tools worked for me anyway. I finished the work that for years had been hard to finish. That's one shape.

I started a petition asking the Rainbow District School Board to publish a real public AI policy before next semester. Students across the board are using these tools every day. The adults setting the rules haven't caught up. Partway through my own coursework, I was pulled aside and questioned about my AI use because there was no policy to point at. The petition is about that, but it's also about the kids: they're walking through a door before anyone has written a rule about it. That's another shape.

I'm building Anokii, the embedded chat on the OIATC site, on top of my own framework. Anokii isn't being built for engineers. It's being built so a member of a community can find a community-specific resource and get an answer that cites where it came from. Per-community variants. A relevance gate so it stays quiet when it shouldn't speak. A topic-confidence gate on the citations. When the tool is reachable, and built with the people who'll use it in mind, the people who reach for it are not the obvious ones. That's a third shape.

The pattern

Three different angles. An adult learner finishing high school. A petition asking for a fair rule. A chat that surfaces community resources without pretending to be smarter than it is.

None of these are "engineers replaced." All of them are "someone got access to a tool that wasn't available before, and the question is whether the systems around them caught up."

Cherny's hackathon detail isn't an outlier. It's the leading edge of what happens everywhere when the syntax-and-credentials gate falls. People who were never in the room start showing up. The electrician builds the app. The adult learner finishes the coursework. The community member finds the resource they needed and gets a real citation instead of an authoritative-sounding guess.

The energy we spend arguing about whether engineers will exist in five years is energy we are not spending on what the hackathon detail is actually telling us.

Where the energy belongs

Three places I'd want it to go.

Schools need policy now, not after the next semester. The Rainbow District petition is one example. Every board with students using these tools is facing the same problem. The students are already there. The policy can't be retroactive forever.

Communities deserve tools built for them, not demos pointed at them. Anokii is the version of that I'm running, and the way to tell whether a community tool is real is whether it cites its sources, whether it knows when to stay quiet, and whether it gets better when the community pushes back on it. Demos do not pass any of those tests.

For engineers and builders and whatever else we get called next: stop pretending the threat is your job disappearing. The threat, if there is one, is that the tools become most useful to the people who already had power. Cherny's data so far says that is not what's happening. Don't make it happen. (If you want the engineer-facing half of this argument, I wrote the playbook for taking a vibe-coded prototype to something a stranger can run earlier this week. This post is the other half.)

Closing

The people getting the most out of these tools right now are not the people the discourse expects. The electrician winning the hackathon, the adult learner finishing the diploma, the community member finding the resource. None of them are the story we're telling. All of them are the story we should be telling.

That should change how we talk about this.

Baamaapii

From vibe-coded to shippable: a playbook

Russell Jones — Thu, 16 Jul 2026 20:46:37 +0000

Ahnii!

There's a lot of energy right now spent bashing vibe coding. I think most of it is aimed at the wrong target. The MVP you stand up with AI doesn't have to generalize. That's not what it was for. The interesting craft is what you do next to take that prototype from "it works on my laptop" to something a stranger can run, debug, and trust. That's a craft worth respecting. This post is the playbook I'm currently running on a real public repo, with six specific moves and an artifact for each.

The wrong fight

The bashing usually goes like this: "Look at this AI-generated MVP, look at how brittle it is, look at how much it cost in tokens to get it half-right." Sure. Now compare it to the alternative: an empty directory and a developer who hasn't started. The point of the prototype isn't to be production code. The point of the prototype is to find out whether the idea works at all. To answer a question. To make something move on a screen that wasn't moving yesterday.

Once it moves, you have new information. You know which parts are load-bearing. You know which gotchas bit you. You know which assumptions held up. You're now in a much better position to do the second pass, and the second pass is where the craft lives. The craft is the set of moves you make to take a working prototype to a state where someone else can run it, debug it, and trust it.

Those moves are not mysterious. They have names. They are the rest of this post.

The repo on the bench

The worked example is the OIATC application, a public PHP repo I build alongside my own modern PHP framework, Waaseyaa:

https://github.com/waaseyaa/oiatc-waaseyaa

It powers oiatc.ca. The marquee feature inside it is Anokii, an embedded AI chat that grounds its answers in the site's own community-resource pages and cites them. Anokii started as a vibe-coded chat experiment. It's now a RAG pipeline with a relevance gate, per-community variants, anonymous query-gap logging, and a topic-confidence gate on citations. Every step below points at a specific artifact in that repo.

Step 1. Milestone the roadmap

The first thing that turned the Anokii work from "a directory of chat hacks" into "a project" was naming the phases. Phase 1 got a chat working at all. Phase 2 introduced RAG grounding, split into stages: Stage 1 was the doc_chunk entity and the app:ingest-docs CLI that fills it; Stage 2 was the keyword-RAG retrieval over those chunks.

Branches in the repo carry the phase names. feat/doc-chunk-ingestion landed Stage 1. feat/keyword-rag-chat landed the MVP retrieval. feat/sagamok-resources and feat/data-sovereignty-and-masthead carried sibling work. Each branch closes with a merge commit that documents what shipped, and only after that does the next phase begin.

Three phases, a handful of branches, every one of them with a concrete definition of done. That's enough structure to know what to work on next, and just as importantly, what not to work on right now.

You don't need a wiki or a project board. You need branch names that announce intent and merge commits that close the loop.

Step 2. Write the runbook, including the gotchas

The repo's CLAUDE.md is the runbook. It opens with a Strategy folder pointer: a separate workspace outside the repo tracks every live page on oiatc.ca against its canonical Twig source, last-updated date, and analytics. The CLAUDE.md says, plainly, that if the two disagree, the repo wins.

Below that pointer it documents the architecture (Access/, Controller/, Domain/, Entity/, Provider/, Support/), the ServiceProvider DI methods with full signatures (singleton, bind, resolve, tag, entityType), the queue Job pattern with tries, timeout, retryAfter, and the frontend template families (site shell vs. longform documents vs. news). An Operations section, added in commit 896ec8f, covers deploy, Raspberry Pi access, and secrets.

The runbook is the operating manual you wish someone had handed you. The OIATC one is dense because it earned every line. The mistakes that produced those lines aren't generic; they're specific to this app, this framework version, this deployment target. That's exactly what makes them worth writing down.

Step 3. Pin the world

Vibe-coded prototypes love composer install and git clone main. That works on Tuesday. It breaks on Friday when upstream cuts a release. The OIATC repo pins the world three different ways.

First, composer.lock is committed and treated as the source of truth. Lock-file drift gets its own entry in the upstream-notes (entry 003 walks through a drift caused by a post-hash php: >=8.5 constraint and the fix). Second, the deploy contract is a docker compose run that calls bin/waaseyaa db:init before bringing the app up:

docker compose run --rm oiatc-app bin/waaseyaa db:init
docker compose up -d

db:init is idempotent. Fresh volume gets migrations. Current schema is a no-op. Safe to invoke on every deploy. That's what makes a deploy step a contract instead of a tradition.

Third, the app lives on a specific waaseyaa/framework alpha version (currently alpha.188). Upgrades happen as deliberate events with their own branch and their own entry in the upstream-notes, not as quiet drift. When upstream cuts a release that breaks something, you have a working baseline to compare against.

Step 4. Name the graveyard

The repo has a literal graveyard directory: docs/archive/2026-04-20-cut-pages/. It holds Twig templates and design notes for pages that were on oiatc.ca and got cut. Not deleted from git history. Not pretended to never have existed. Filed under a date and a reason so the next person can read what we tried and why we stopped.

This pattern shows up in the codebase too. The keyword-RAG retrieval merge commit literally calls itself "Path B." There was a Path A. Path A's notes are still around. Anyone looking at the current Path B implementation can see the alternative that was considered and the trade-offs that drove the decision.

Naming the graveyard is one of the cheapest, most under-used moves in software. Most repos don't do it because it feels embarrassing. The OIATC repo does it because each cut page and each abandoned path represents a hypothesis tested. The next person who has a similar hypothesis deserves to see the result.

Step 5. Recon before you build

The single most useful artifact in the repo is docs/waaseyaa-upstream-notes.md. It's a running log of framework quirks, bugs, breakages, and missing pieces hit while building on an alpha release of waaseyaa/framework. Each entry uses a fixed format:

## NNN — short title

- **Date / version:** YYYY-MM-DD · waaseyaa/framework alpha.NNN
- **Doing:** what we were doing when we hit it
- **Symptom:** the observable problem
- **Workaround:** what we did to get unblocked
- **Likely upstream fix:** the proper change in waaseyaa/framework

There are 16+ entries. Stale VERSION files. Ambiguous class resolution between the metapackage and split mirrors. Lock-file drift after a platform requirement bump. Hard ext-sodium dependency via the OIDC stack. Each one is recon for the framework itself.

The point of the upstream-notes is not to complain. The point is to keep app-level hacks out of the consumer code. Every entry is a decision: do we patch around it here, do we file the upstream fix now, do we wait until the next alpha. Without the log, those decisions get re-litigated every time someone hits the same wall.

This is also the move I think AI tooling makes most useful. When you hit a quirk, write the entry first. The structured shape forces you to articulate what you actually saw, what you're guessing, and what would fix it upstream. That writing is exactly the input the model needs to either help you work around it cleanly or propose an upstream change.

Step 6. Layer specs on what's next

The hardest current work on Anokii doesn't get vibe-coded. The topic-confidence gate that decides whether a citation is worth showing (65de562), the relevance gate that ensures only genuinely relevant passages are cited (8359e37), the climate-companion variant for the Massey Solar resource cluster (c8956f6), the shared relational-graph instance per community (928191d) — all of those run through docs/superpowers/specs and docs/superpowers/plans. Each change has a spec articulating the intent, a plan decomposing the work, and reviewable PRs landing the implementation.

Why specs and not just commits: a relevance gate that filters citations is the kind of thing where a hallucinated implementation looks fine until a user gets a confidently-wrong answer. The spec gives you a contract for what the gate is supposed to do. The plan gives reviewers something to evaluate against. The implementation has a referenceable target.

This is the handoff move. Vibe coding got the chat answering. The runbook captured the patterns. The pinned world made the deploys reproducible. The graveyard remembered the dead ends. The upstream-notes captured what the framework still owes us. And now spec-driven work takes over for the parts that are too big or too risky to vibe through. Each layer earned the right to the next layer.

What this looks like together

The OIATC repo is not a clean codebase. It's a layered one. Some Anokii code still reads like the experiment it started as, because it still works and the cost of replacing it is higher than the cost of keeping it. The newer pieces — the keyword-RAG retrieval, the relevance gate, the topic-confidence gate — were built with specs and reviewed PRs because each of them is a place where a quiet bug becomes a confidently-wrong answer to a real person looking for real community resources.

Vibe coding was the first move. The six moves above are the second, third, fourth, fifth, sixth, and seventh. None of them are mysterious. None of them are expensive. They are the boring craft that turns a working prototype into something a stranger can run, debug, and trust.

If you've been bashing vibe coding, you're aiming at the start of a process and ignoring the rest of it. If you've been vibe-coding without any of the rest, you're going to keep losing days to the same gotchas, and the next person who touches your prototype is going to lose them too.

There's no shame in vibe coding. There's a lot of value in what comes next.

Baamaapii

AI keeps speccing my projects on pre-AI timelines

Russell Jones — Thu, 16 Jul 2026 20:46:33 +0000

Ahnii!

You sit down to spec a new feature with Claude Code or whichever assistant. You describe the surface, the constraints, the slices you want it broken into. The plan comes back: "5 work packages, 6 to 8 weeks." You shipped a 5-WP mission in a day yesterday. This post is about that gap and why it eats more time than it should.

The pattern

Spec mode is where it shows up worst. You ask for a plan. The plan arrives with timelines attached. Those timelines are calibrated to a world that ended around 2023. A "2-week task" inside a modern plan is often something you can ship the same afternoon if the scope is honest.

When you push back, the assistant does not back down quickly. It cites "industry norms," talks about "code review cycles," reminds you about testing time and edge cases. All of which are real concerns. None of which describe what actually happens when you and an AI co-author the work at full session-pace.

You end up in a loop. You spec. It estimates long. You explain that the work is being done with AI. It hedges. You re-spec. You ship in a fraction of the estimate. Next time you do this same dance again, because the assistant has no persistent sense that you ship faster than the baseline it was trained on.

Why this happens

Almost every public dataset that taught these models how long things take pre-dates widespread AI-assisted development. Stack Overflow threads from 2019 about how long a Laravel package takes to build. Engineering manager blog posts from 2021 about ticket-pointing conventions. Git histories from teams that did not have Claude on the keyboard. The model sees those signals and projects.

The reasoning models are smart enough to know AI assistance changes velocity. They will say so if you ask them directly. The problem is they do not apply that knowledge to estimation by default. You have to invoke it explicitly, every time, and even then they hedge in case you turn out to be slower than you said.

It is the same failure mode as asking an assistant in early 2024 whether you should use React 18 features. It knows React 19 exists. It does not always update its working assumptions to match.

What this costs

Two things.

First, time. Every spec session has a recalibration tax. You say two weeks; it says six. You push; it says four. You re-explain; it says three. You ship in two days. Multiply across a year of speccing and you are spending real hours arguing with an estimator that is wrong in one direction.

Second, drift. When you accept a long estimate to move on, the WP breakdown that gets generated is shaped by that estimate. Work packages get padded with imagined complexity to justify the duration. Tasks get split that did not need splitting. You end up implementing a plan designed for a slower world and discovering halfway through that half the WPs collapse into one.

The downstream version of this is worse: an assistant reviewing your PR will sometimes flag "is the scope of this change too large for a single WP?" when the change is fine and the WP boundary was the artifact of a stale estimate.

What to do about it

The fixes are all small and all annoying because you have to repeat them.

State the velocity assumption in your spec prompt explicitly. "This is being done with AI assistance. Estimate WPs in hours, not days, and assume each WP fits inside a single focused session." This is not subtle and it works. You can put it in your project's spec template so you do not have to remember.

Reject the estimate during planning, not after. If the plan comes back with multi-week WPs, push back before generating the WP breakdown. The breakdown is downstream of the duration assumption; if you let it materialize, you inherit its shape.

Cite recent evidence. "I shipped a 5-WP mission yesterday in a day. Use that as the baseline, not pre-2024 industry norms." The model responds to concrete recent counter-evidence more than to abstract argument.

Strip duration estimates from the plan entirely when you can. Half the time you do not need them and they only exist because the spec template asked for them. A plan that says "5 WPs, dependency-ordered" is more honest than a plan that says "5 WPs, 6-8 weeks." You are not running a Gantt chart. You are sequencing work.

The deeper problem

This will probably get worse before it gets better. Training data for "how long does this take" lags real-world velocity by a couple of years. Right now the gap is roughly 2023 vs 2026, which is about a 3-5x estimation error in many domains. As AI-assisted development accelerates, that gap widens, and the public-corpus signal stays stuck in the past.

The assistants that handle this well will be ones that calibrate against the user's recent shipping pace, not against the corpus average. That requires per-user telemetry the current tools do not have, or explicit user-state that they do not yet persist between sessions. Until then, the workaround is the four-step dance above.

The honest version of the complaint is not "AI is bad at estimates." It is "AI is estimating on a baseline that the existence of AI itself made obsolete." Worth naming so you can stop arguing with it and just override the defaults.

Baamaapii

Bimaaji: agent-safe mutations for Waaseyaa

Russell Jones — Thu, 02 Jul 2026 06:43:30 +0000

Ahnii!

If you let an AI agent modify your application, the agent needs more than a text editor. Raw str_replace on a PHP file passes a lot of tests and still breaks things an hour later in production, because the tool has no idea what the file actually represents. Bimaaji is the Waaseyaa package that gives agents a structured path from "I want to add a field to this entity" to a reviewable patch that a community's sovereignty rules have already vetted. This post walks through what shipped in waaseyaa/bimaaji and why each piece exists.

Prerequisites: familiarity with Waaseyaa's package layout, PHP 8.4+, and the idea that an application has more state than the filesystem (routes, entities, introspection metadata).

Why not just let the agent edit files

The failure mode you want to avoid: an agent reads a prompt like "add a published_at field to the Post entity," does a reasonable-looking edit to Post.php, and leaves the rest of the app inconsistent. The migration is missing. The JSON:API resource doesn't expose the field. The admin panel still doesn't know it exists. The sovereignty profile that was supposed to block the change on a local-only deployment never got consulted.

Each of those is a different subsystem. A good agent can write a correct edit to any one of them. What a filesystem-level tool cannot do is ensure the edit is coordinated across all of them and is allowed under the community's posture.

Bimaaji separates that problem into three stages: introspect, propose, patch.

The pipeline

The package description (from packages/bimaaji/composer.json) spells it out: application graph introspection and agent-safe mutation for Waaseyaa. The flow is:

Introspection → ApplicationGraph → MutationRequest → Validator → PatchGenerator → PatchSet

An agent reads the graph, submits a structured mutation request, a validator checks it against sovereignty rules, and the patch generator returns reviewable diffs. Nothing touches the filesystem until a human (or a higher-level workflow) accepts the PatchSet.

Introspection: what the agent reads first

src/Introspection/ holds a provider for every surface the agent might need context on:

AdminIntrospectionProvider — what's exposed to the admin panel
EntityIntrospectionProvider — entity definitions
JsonApiIntrospectionProvider — public API shape
PublicSurfaceProvider — what's reachable from outside
RoutingIntrospectionProvider — route table
SovereigntyIntrospectionProvider — the community's deployment posture and rules

Each one implements GraphSectionProviderInterface and contributes a GraphSection to the ApplicationGraph. The point is that the agent never reads source files to understand the app. It reads the graph. That is the canonical view.

This matters because it means an agent's understanding of your app is a data structure you control, not whatever the agent's context window happened to pick up from grep.

The task DSL

src/Dsl/ is the entry point for agents. TaskParser parses a structured task definition into TaskDefinition objects. TaskPipeline runs them, producing a TaskPipelineResult. The DSL describes what to change (add a field, add an entity type, add a route stub, add a test skeleton), not how.

That separation is the whole point. An agent says "add field published_at: datetime to entity Post." Bimaaji decides how that compiles into a PHP edit, a migration stub, an admin surface update, and a JSON:API resource change. The agent is not writing PHP. It's writing a task.

Mutation: the reviewable proposal

src/Mutation/ turns a parsed task into a MutationRequest, runs it through MutationValidator, and returns a MutationResult. The validator is where the sovereignty guardrails plug in.

src/Policy/SovereigntyGuardrails.php and GuardrailRule hold the rules. The model: a community declares a SovereigntyProfile (local, hybrid, cloud) on their Waaseyaa deployment. Certain mutations are allowed under certain profiles and not others. A local-only community might forbid any mutation that adds outbound network dependencies. A cloud-hosted community might allow them but require a specific audit annotation. The guardrails are declarative, matrixed per profile, and they stop the mutation at the proposal stage, not after the patch has already rewritten files.

This is where Waaseyaa's sovereignty story gets teeth. Community control over AI-driven changes is not a policy document. It's a validator in the mutation path.

Patching: AST, not strings

src/Patch/PatchGenerator.php takes a validated MutationRequest and produces a PatchSet of PatchEntry objects. For PHP files, it uses nikic/php-parser via PhpFileBuilder to round-trip through an AST. That means the patch is syntactically valid by construction. You cannot generate a patch that breaks parsing because the patch itself is a parsed tree that gets printed back out.

For non-PHP files, the generator falls back to constrained operations with risk flags. Anything that can't be AST-verified is surfaced as unsafe and requires an explicit opt-in. That's the right default. Agents should fail loudly on anything they can't guarantee.

The integration test

tests/Integration/FullPipelineTest.php runs the whole flow: introspect an app, submit a task through the DSL, validate against guardrails, generate a patch, assert the patch is well-formed. It's the check that all five subsystems (Graph, Dsl, Mutation, Policy, Patch) still agree on the contracts between them. When any one of them changes, that test catches the drift.

Where this fits in the bigger picture

Bimaaji is the seam where Waaseyaa's AI tooling meets Waaseyaa's community governance. The whole Waaseyaa thesis is that the software communities run should answer to the community, not the other way around. Sovereignty profiles are the policy expression of that. Bimaaji is the enforcement point for anything an AI agent wants to do to the app.

The package is at waaseyaa/framework packages/bimaaji. The README is still a scaffold note; the code has moved past that. If you want to read one thing, start with tests/Integration/FullPipelineTest.php — it's the shortest honest tour of what the pipeline does end to end.

Baamaapii

The ingest side of a sovereign language platform

Russell Jones — Thu, 25 Jun 2026 18:39:42 +0000

Ahnii!

I just shipped the ingest side of Minoo, the Anishinaabemowin language platform I am building. The short version: an Elder posts a video of himself holding a whiteboard with a word on it, and that teaching becomes a published, searchable lesson, with a human reviewing every step and the community owning the whole stack. This post walks through how it actually works and the decisions underneath it.

The problem

Anishinaabemowin teaching happens constantly, but it is scattered. Elders share words on Facebook, in notebooks, in classrooms, and almost none of it flows into anything a learner can search tonight. The few deep digital resources that do exist are owned by institutions, not by the communities whose language they hold.

So I set two goals that have to be true at the same time. Turn everyday teaching into structured, reusable data. And keep that data under community control end to end. Not control as a policy promise bolted on afterward, but control built into where the data lives, who can read it, and who can change it.

The pipeline

The source material is real. Steven Bennett, an Elder from Sagamok, posts short videos holding up a whiteboard with one word, the Anishinaabemowin on top and the English gloss below. The pipeline turns one of those into a lesson in four stages.

Ingest. A reel comes in, by upload or through a URL importer backed by a swappable media-fetcher interface. The system pulls a keyframe and the audio, stages the media, and creates a draft tagged with its community provenance.

Vision. The keyframe goes to a vision model through the framework's provider abstraction, which returns a small JSON object: the Ojibwe and the English read straight off the whiteboard. Today that provider is Claude vision. The binding is swappable by config, and the sovereign-stack goal is a local model before any public beta.

Transcribe, Curate, Publish. Each of these is a human gate, not an automated hop. The model drafts, a person confirms. Curate promotes the entry into the dictionary. Publish puts it on the live site inside a lesson. Nothing reaches the public without a human pass.

The design principle is that the model is an assistant that fills a draft, never an authority that publishes.

Language tags: BCP 47, three layers

One of the core decisions was how to tag the language so it can federate across the 21 Robinson Huron Treaty nations without flattening their dialects into one another. I use BCP 47 with three layers and a fallback chain.

There is the macrolanguage, oj, always displayed with the autonym Anishinaabemowin rather than the ISO exonyms. There is an optional dialect layer in the middle. And there is community provenance as a private-use subtag, for example oj-x-sagamok.

Translation memory keys on the full tag, never on a dialect-only code, so each community keeps its own granularity. Dialect groupings (Nishnaabemwin spans two ISO codes) are derived from the community tag, not stored as the source of truth. A tag like oj-x-sagamok resolves oj-x-sagamok to oj to en, which needed a small fix to the framework's i18n fallback chain so it would resolve private-use subtags at all. That fix shipped upstream.

The translation side

Alongside transcription there is a translation memory exposed at /api/lang: exact match first, then fuzzy, then log the gap when there is no entry yet, so the backlog fills itself as it gets used.

To seed it with real demand instead of guesses, I crawled the public English interface strings off the 21 RHT nation websites and ranked them by how many sites each one appears on. The result is a demand-ordered list of the words communities actually put on their own sites, things like Governance, Education, Membership, Chief and Council, a few hundred of them, waiting on speaker-verified translations. That ranked list is the backlog, highest demand first.

Sovereign by construction

The part I care about most: this runs on infrastructure the community controls. The app is a PHP service built on the Waaseyaa framework, in Docker behind Caddy, on a Raspberry Pi the community runs, not on someone else's cloud. The corpus stays local. The AI provider is swappable by config. The model assists, it does not own the language, the data, or the hosting.

That boundary shows up in the API too. The public /api/lang surface is read-only and validated, returning a 422 on a malformed tag rather than guessing. The admin pipeline and the corpus behind it are staff-gated. Reading is open. The language itself is governed.

What is honest about it

Build-in-public should include the rough parts. Pulling video off Facebook is login-walled, so reliable ingest is upload-first for now. The vision provider is a hosted model, which is the interim and not the destination. And "published in the admin" has to actually mean "visible on the public site," which is exactly the kind of seam you only find by walking the whole pipeline on camera. Finding those is the point of demoing it for real.

The language has been taught this way for a long time, one word at a time, by people willing to stand in front of a camera and share it. The software's only job is to catch those teachings and hand them back to the community in a form a learner can use, without taking ownership of them along the way.

Watch the walkthrough: youtu.be/zfx7CHs_Ec0. The framework is open source at github.com/waaseyaa/framework and on Packagist.

Baamaapii

One URL, two readers: serving HTML to people and Markdown to agents

Russell Jones — Mon, 22 Jun 2026 22:04:37 +0000

Ahnii!

The web has two kinds of readers now: people and agents. Most stacks make you build a second system to serve the second one, a separate API with its own routes, auth, and serializers. This post shows the approach Waaseyaa takes instead: one URL serves a human a web page and an AI agent clean Markdown, decided by HTTP content negotiation. It covers the content type you define, the negotiation that picks the format, and the agent-facing routes that come along for free.

Prerequisites: Familiarity with HTTP Accept headers and basic PHP. Waaseyaa is an early-alpha PHP framework, so treat the specifics as a moving target.

Define the content once

You describe the shape of your content one time. In Waaseyaa that is a single command:

waaseyaa make:content-type story --fields="title:string,body:text,source_url:string"

That scaffolds a story content type with three fields. Then you add an entry:

waaseyaa entity:create story --field title="The Five Totems" --field status=1

You never write a controller, a route, or a serializer for any of this. The type is the only thing you author. Everything that follows is the framework reading that one definition.

One URL, negotiated by Accept

The same canonical path, /{type}/{id}, serves both audiences. What comes back depends on the request's Accept header. A browser sends text/html and gets a rendered page. An agent that asks for text/markdown gets Markdown. The decision lives in MediaTypeAcceptNegotiator:

namespace Waaseyaa\Foundation\Http\ContentNegotiation;

final class MediaTypeAcceptNegotiator
{
    public const string HTML = 'text/html';
    public const string MARKDOWN = 'text/markdown';

    public function negotiate(string $acceptHeader, array $supported, string $default): string
    {
        // Ranks the Accept entries (RFC 7231) and returns the best supported match.
    }
}

The negotiator parses the Accept header by quality value and returns the most specific supported media type. The human path and the agent path converge on one URL, so there is no /api/story/123 shadow of /story/123 to keep in sync.

A human toggle for the same switch

Accept headers are invisible in a browser, so there is also an explicit query override. The negotiator recognizes it directly:

public function resolveQueryOverride(array $query, array $supported): ?string
{
    if (\array_key_exists('raw', $query)) {
        return self::MARKDOWN;
    }

    if (isset($query['format']) && \is_string($query['format'])) {
        return match (strtolower(trim($query['format']))) {
            'md', 'markdown' => self::MARKDOWN,
            'html' => self::HTML,
            default => null,
        };
    }

    return null;
}

Append ?raw or ?format=md to any content URL and you see exactly what an agent sees. That makes the agent-facing output something you can eyeball in a browser, not a black box you have to script against to inspect.

Caching two formats at one address

Serving two representations from one URL has a well-known hazard: a shared cache can hand the HTML variant to an agent or the Markdown to a browser. SsrPageHandler guards against that by varying the cache on the negotiated type:

$mediaType = $this->negotiateMediaType($httpRequest);

// ...render either Markdown or HTML based on $mediaType...

$headers['Vary'] = 'Accept';

The Vary: Accept header tells every cache in the chain that the response depends on the request's Accept header, so the Markdown and HTML variants never cross-contaminate. One URL, two cache entries, no leakage.

The agent-facing routes you get for free

Because the framework already knows which content types are public, it can publish the discovery surface agents and crawlers expect without you wiring anything. SeoPublicController exposes three zero-config routes:

public function robotsTxt(): Response   // /robots.txt
public function sitemapXml(): Response   // /sitemap.xml
public function llmsTxt(): Response      // /llms.txt

/llms.txt is the emerging convention for telling language models what a site contains and where to look. Here it is generated from the same content-type metadata that drives everything else, alongside schema.org JSON-LD injected into the page head. Your content becomes legible to an AI assistant the moment it is published, without a second pipeline.

Why this matters

As more of the web gets read through AI assistants, the content you publish is increasingly consumed by something that does not render HTML. The common answer is to stand up a parallel API: more routes, more auth surface, more drift between what people see and what machines see. Negotiating on one URL collapses that back into a single source of truth. You define the content once, and the same address answers both readers correctly.

It is still alpha, and the write side has rougher edges than the read side. But the read path holds the thesis: one URL, two readers, no second system.

Baamaapii

AI slop and the content treadmill every developer is on

Russell Jones — Mon, 22 Jun 2026 22:04:32 +0000

Ahnii!

I built a machine that turns my git commits into social media posts. This post is about why I did that, what it costs, and whether any of us can share our work anymore without contributing to the flood of AI slop.

Let me be honest about my own setup first.

I automated my own content pipeline

Every day a script scans my repositories for recent commits. It groups them by theme, scores each group on how postable it looks, and files a queue item. I review the queue, pick the good ones, and a second tool drafts a blog post or a short update. A third tool rewrites that draft three times, once for Bluesky, once for LinkedIn, once for Facebook, and pushes all three into a scheduler.

Four stages: mine, curate, produce, distribute. A human, me, sits in the middle of two of them. The rest runs on its own.

I am not proud of all of it. I am also not going to pretend I would keep up without it.

The treadmill has a lot of belts

Here is the part nobody mentions when you start sharing your work. It is not one post. It is one idea, reshaped for every platform's algorithm, because each one punishes you for treating it like the others.

Bluesky wants one or two sentences and a link, under 300 characters, or it reads as spam.

LinkedIn wants 1,200 to 1,800 characters with the hook in the first two lines, because everything after "see more" is invisible to people who never click.

Facebook barely shows text posts to anyone who does not already follow you, so you end up writing for an audience that is already yours.

X wanted something else again, before I disconnected it.

Same idea. Four rewrites. Four character budgets. Four hashtag policies. Four mental models of an algorithm I do not control and cannot see. And that is before you reach Mastodon, Threads, Reddit, a newsletter, dev.to, and whatever launched this quarter.

I am a developer. I want to share what I built and have a few of the right people see it. Instead I am a one-person content team optimizing for five recommendation engines.

Where the slop actually comes from

We talk about AI slop like it is a content problem. Low-effort articles, generated images, summaries of summaries. But the slop is a symptom. The disease is the incentive.

When the only way to be seen is to feed five algorithms every day, nobody can do that by hand and still ship code. So we automate. And automated, optimized, competent, voiceless content is exactly what slop is.

My pipeline is good. The posts are accurate, they link to real commits, they read fine. That is the problem. "Reads fine" at infinite scale is the slop. I am not flooding the feed with garbage. I am flooding it with volume. Past a certain point those are the same thing.

What I think the way out looks like

I do not have this solved. I have a few moves that feel less bad than the alternative, and I would genuinely like your read on them.

Write once, syndicate from a canonical source. The blog post is the real thing. Everything else points back to it. The social copy is a doorway, not the room. One piece of writing holds my actual voice, instead of five disposable ones competing to be the loudest.

Automate distribution, not authorship. I let machines handle scheduling and reformatting. I do not let them decide what is worth saying. The human stays on the idea and the voice. The robot does the cross-posting. The moment the robot picks the topic, it is slop.

Cover fewer platforms, on purpose. You do not have to be everywhere. Owning one channel you control, an RSS feed, a newsletter, your own domain, beats renting attention on five you do not. I would rather have 200 readers who chose me than 5,000 impressions an algorithm rented me for an afternoon.

Treat the reader as the tiebreaker. When the algorithm and the human want different things, pick the human. It performs worse this quarter. It is the only thing that compounds.

Disclose the assistance. If a tool helped me write something, saying so costs me nothing and keeps me honest about what I am putting into the feed.

A question, not a conclusion

Here is what I keep getting stuck on. If I stop, I lose to the people who do not. If we all keep going, the feeds become unreadable and none of us win either. That is a coordination problem, and I cannot solve it from inside my own pipeline.

So I am asking you. How do you share your work without turning into a content factory? Have you cut platforms and survived it? Did owning your own channel actually work, or is it a slow fade into obscurity? Is disclosing AI assistance signal, or just more noise?

I will read every reply. Not the algorithm. Me.

Baamaapii

Agent-friendly JSON output for PHP CI tools

Russell Jones — Sun, 24 May 2026 19:33:07 +0000

Ahnii!

When an AI agent runs your test suite or a CI gate during an implement-or-review loop, the verbose stdout gets piped straight back into its context window. A full PHPUnit run on the Waaseyaa framework monorepo is around 12,000 lines. bin/check-package-layers is about 600. Per iteration, per gate. The token cost is real, and it compounds across review cycles. This post walks through waaseyaa/agent-output, a Layer 0 package that shrinks that output to a single NDJSON line for agents while leaving human terminal output completely unchanged.

Why agent context windows hate CI output

The pattern shows up the moment you let an agent drive your test loop. The agent runs composer test. PHPUnit emits its banner, then a dot per test, then a footer summary, then optionally a slow-test report. None of that helps the agent. It needs three things: did the run pass, what failed, where. Everything else is noise that displaces real signal.

The same is true for bin/check-package-layers, bin/check-phpstan, tools/drift-detector.sh, and friends. Each one is a CI gate that the agent already understands at the contract level. The full human-readable output exists to help a person scan and react. An agent does not need any of it.

What the package does

waaseyaa/agent-output is a single-purpose Layer 0 package (no waaseyaa/* runtime deps, installable standalone). It does three things:

Detects an agent runtime from a list of well-known env vars (CLAUDE_CODE, CURSOR_AGENT, and the rest), extensible.
Provides a FormatterInterface and first-party formatters for PHPUnit, Pest, PHPStan, the bin/check-* CI gates, and the drift detector.
Honors three activation triggers per command: an --output=json flag, a WAASEYAA_OUTPUT=json env var, or auto-activation when an agent env var is set.

When none of those triggers apply, the affected command emits exactly the human output it always did. No JSON fields leak, no exit codes change.

Three ways to flip a tool into agent mode

bin/check-package-layers --output=json
WAASEYAA_OUTPUT=json bin/check-package-layers
CLAUDE_CODE=1 bin/check-package-layers

The first is explicit per-invocation. The second sets it for the shell. The third is what happens automatically when Claude Code (or another supported agent) drives your terminal — you do not have to wire anything up; the auto-detection kicks in.

Coverage

Here is the full set of tools the package now covers, taken verbatim from the package README:

Tool	Trigger	Formatter
`bin/check-package-layers`	`--output=json` / env	`PackageLayersFormatter`
`bin/check-dead-code`	`--output=json` / env	`DeadCodeFormatter`
`bin/check-getquery-bindings`	`--output=json` / env	`GetQueryBindingsFormatter`
`bin/check-composer-policy`	`--output=json` / env	`ComposerPolicyFormatter`
`bin/check-phpstan`	`--output=json` / env	`PhpStanFormatter`
`tools/drift-detector.sh`	`--output=json` / env	`DriftDetectorFormatter`
`vendor/bin/phpunit`	`WAASEYAA_OUTPUT=json` (PHPUnit does not surface custom CLI flags)	`PhpUnitFormatter` via `AgentOutputPhpUnitExtension`

Five bin/check-* scripts, a drift detector, and PHPUnit. Each one emits an NDJSON envelope through a formatter dedicated to that tool's domain.

PHPUnit is the awkward one

PHPUnit's extension API does not surface custom CLI flags. There is no clean way to add --output=json and have PHPUnit pass it to your extension. So the env var is the canonical trigger, and the package ships a PHPUnit 10 extension that registers six event subscribers (passed, failed, errored, marked-incomplete, skipped, execution-finished) over a shared run-state object:

final class PhpUnitRunState
{
    public int $passed = 0;
    public int $failed = 0;
    public int $skipped = 0;

    /** @var list<array{test: string, file: string, line: int, message: string}> */
    public array $failures = [];
}

That class lives in its own file rather than as an anonymous shape inside the extension, so PHPStan can type-check the field accesses without inferring mixed through anonymous classes. A small thing, but it is the kind of detail that decides whether a package's own lint suite stays green.

The extension itself is a no-op when WAASEYAA_OUTPUT is not json — zero overhead in human mode. When it is, the envelope is printed at TestRunner\ExecutionFinished with a leading newline so it lands on its own trailing line. Agent consumers read the file line-by-line and parse the line that starts with {"tool":"phpunit".

What the numbers say

WP06 of the mission was an empirical token-reduction smoke test against the original NFR. The headline result, measured on packages/foundation/tests/Unit --no-coverage:

Standard PHPUnit output: 2,209 bytes
Agent envelope (NDJSON line only): 117 bytes
Reduction: 94.70%

The threshold was ≥90%. The pattern delivers. And that number understates the savings on a full monorepo run, where the human output runs in the thousands of lines and the envelope stays a single line.

Why not just use Laravel PAO?

The pattern was lifted from Laravel PAO (released around May 2026), but the package is framework-native for two reasons. First, PAO does not cover the custom CI gates the Waaseyaa monorepo runs as hard gates (bin/check-package-layers and the rest). Second, the formatters need to live alongside the gate scripts so the contract between script and envelope shape can evolve in the same PR — third-party packaging would have made that coupling awkward.

The package is also a Layer 0 dependency, which means anyone outside the Waaseyaa monorepo can install just waaseyaa/agent-output and reuse the formatter interface for their own tools. The detection logic and envelope contract travel; the bin/check-* wrappers stay in the framework where they belong.

Try it in your own monorepo

composer require waaseyaa/agent-output

Then either pass --output=json to any supported script, set WAASEYAA_OUTPUT=json in your shell, or run under an agent that sets CLAUDE_CODE=1. For PHPUnit specifically, register the extension in phpunit.xml.dist:

<extensions>
    <bootstrap class="Waaseyaa\AgentOutput\Listener\AgentOutputPhpUnitExtension"/>
</extensions>

The extension self-disables when WAASEYAA_OUTPUT is not set to json, so registering it does not change human-mode output.

For the full envelope schema, formatter contract, and a guide for writing third-party formatters, see docs/specs/agent-output.md in the framework repo.

Baamaapii

Spot the AI: can you tell which passage Claude wrote?

Russell Jones — Sat, 23 May 2026 21:11:45 +0000

Ahnii!

Spot the AI is a small web game. You're shown two short passages, one written by a human author and one written by Claude, and you pick which one is the AI. This post is a heads up that the game is live and an invitation to play a few rounds.

How to play

Open spot-the-ai.oiatc.ca.
Read both passages.
Pick the one you think Claude wrote.

That is the whole loop. No account, no setup.

Why it exists

People talk a lot about AI writing without testing whether they can actually tell the difference. The game is a tiny way to test yourself before you make claims about what AI writing sounds like.

It is also a small thing under the OIATC umbrella, which is the broader push toward Indigenous-controlled AI tooling and infrastructure. Most of that work happens out of view. This one happens to be playable in a browser.

Play a few rounds and see how you do.

Baamaapii

Bumping a PHP monorepo to 8.5: the mechanics

Russell Jones — Mon, 11 May 2026 18:22:30 +0000

Ahnii!

This is the first of three posts about taking Waaseyaa to PHP 8.5. This one is about the mechanics: how a coordinated version bump across a 67-package monorepo actually happens. The next two cover the deprecation sweep that came with it and the features we deliberately did not adopt.

Context: Waaseyaa is the open-source PHP framework I have been writing about. Mission: php-8-5-upgrade-01KR8DN2. Shipped as PR #1406, merge commit e0f8cb57. Released in alpha.176.

The starting state

Before the bump, Waaseyaa required PHP 8.4. Sixty-six first-party composer.json files, all aligned on >=8.4. Plus a skeleton package, which is a template artifact and is kept at the lowest reasonable floor on purpose.

CI ran a single PHP version. PHPStan was pinned to a matching phpVersion. The floor was tight and consistent. That alignment is what makes a bump cheap. The expensive version of this story is the one where every package picks its own minimum and you have to negotiate sixty-six exceptions.

Mission shape

The mission split into five work packages plus a closing one:

WP01. Constraint bump, CI, Docker, lockfile, PHPStan pin, docs, governance charter touch.
WP02. 8.5 deprecation sweep.
WP03. Adopt #[\NoDiscard] on critical surfaces.
WP04. Targeted array_find() adoption.
WP05. PHP-CS-Fixer migration rules.
WP06. CHANGELOG and verification.

WP01 is the only one that touches the floor. Everything after is feature work that becomes available because the floor moved. Splitting it this way matters: if WP01 lands clean, the rest can land in any order without coupling.

What WP01 actually changed

The mechanical surface of a floor bump is smaller than people expect. From the merge:

66 first-party composer.json files updated from >=8.4 to >=8.5.
3 GitHub Actions workflows repinned to php-version: '8.5': ci.yml, skeleton-smoke.yml, release-cut.yml. Ten total occurrences of the string '8.5'.
phpstan.neon updated: phpVersion: 80500.
Lockfile regenerated against 8.5.

That is the bump. Everything else in the mission is downstream of those four artifacts moving in lockstep.

The reason the surface is small is that Waaseyaa has hard gates that already enforce alignment. There is a bin/check-composer-policy script that fails CI if any package drifts from the root constraint. There is a bin/check-package-layers script that fails if the dependency direction inverts. There is a tools/drift-detector.sh that fails if docs lag the code. The floor is one number defended in many places.

The verification surface

For a bump to be safe, every hard gate has to be green on the new floor. Waaseyaa's full gate list for this mission:

composer phpstan (root level + package level)
vendor/bin/phpunit
composer cs-check
bin/check-composer-policy
bin/check-package-layers
bin/audit-dead-code
tools/drift-detector.sh

At merge time the test suite was 7,497 unit tests, 18,118 assertions, 0 deprecations, 2 expected skips. That is the number to trust. Not because tests prove a version is fine, but because the test corpus is dense enough that deprecation warnings would surface.

Why split it into work packages at all

This is the part worth paying attention to if you maintain a PHP monorepo. The actual diff for a version bump is small. You could do it in one PR with one commit. People do.

The cost of doing it that way is that the diff conflates four different kinds of change:

The floor moves (a policy change).
Deprecations get removed (a behavior change).
New features get adopted (a style change).
New tooling gets wired (a configuration change).

When all four land in one squash commit, the next person to touch any of them cannot read the rationale. Six months later, someone reverts a #[\NoDiscard] attribute thinking it is part of the floor bump, and now the floor bump cannot be reverted cleanly either.

The work package structure makes each kind of change auditable on its own terms. WP02 is removable without affecting WP01. WP04 can be reverted without touching WP03. The mission directory is the persistent record of why each was done.

That is the same point I made about the Spec Kitty mission lifecycle post: the output of any mission is replaceable. The trail is not.

What the next posts cover

Post 2 in this series digs into the deprecation sweep: what 8.5 surfaced, where it was hiding in the codebase, and how the sweep got from 34 warnings to 0.

Post 3 covers the features we deliberately did not adopt. Property hooks. The pipe operator. Broader array_find(). The argument is that restraint is part of the upgrade, not absent from it.

Baamaapii

PHP 8.5 restraint: features we did not adopt

Russell Jones — Mon, 11 May 2026 18:21:56 +0000

Ahnii!

Third in the PHP 8.5 upgrade series. Post one was the floor-bump mechanics. Post two was the deprecation sweep. This one is about what we deliberately did not adopt.

Most upgrade write-ups read like a feature tour. Here is what is new, here is how to use it. They are useful and they are not the whole story. The other half of an upgrade is what you choose not to add. That choice is invisible in the diff and load-bearing in the codebase.

Mission: php-8-5-upgrade-01KR8DN2, merge commit e0f8cb57. Five work packages shipped. Property hooks were not in any of them.

Property hooks: not in scope

PHP 8.4 introduced property hooks. Define get and set on a property directly, eliminate the boilerplate getter and setter pair. Asymmetric visibility came in the same window. Lots of writeups called this the biggest PHP language change in years.

Waaseyaa did not adopt either. The mission spec did not mention them. The plan did not list them as a non-goal. They simply were not part of the upgrade.

If you grep the codebase for the patterns property hooks would replace, you will find traditional methods everywhere:

public function getClientId(): string
{
    return $this->clientId;
}

public function setClientId(string $clientId): void
{
    $this->clientId = $clientId;
}

Boring. Repetitive. Could be a property hook. Was not converted.

The reason this is intentional rather than accidental: the mission was scoped to "raise the PHP requirement and fix what 8.5 surfaces, plus a focused 8.5 feature-adoption pass." Property hooks are an 8.4 feature, not an 8.5 feature. The line was drawn at the version being adopted.

That line is the discipline. An upgrade pass is a window where adopting new patterns is cheap because everyone is reading the diff anyway. The temptation is to use the window for everything. The cost of using it for everything is that the diff conflates "we now require 8.5" with "we changed our property style." Two reverts deep, those become impossible to separate.

Property hooks are not rejected. They are deferred. They get their own mission when the conversion is the work, not a side effect of something else.

The pipe operator: not used

PHP 8.5 introduced |>, a pipe operator that lets you write $x |> $fn1 |> $fn2 instead of nested calls.

Waaseyaa shipped 8.5 without using |> anywhere. The plan considered it in WP04 alongside array_first() and array_find(). After the survey pass, no use sites were strong enough to take.

The reason is that pipe shines when you have a multi-step transform that reads naturally as a chain. Waaseyaa's transforms are usually one-step (use a function), two-step (assign an intermediate), or many-step but heterogeneous (a builder pattern with named methods). The middle band where pipe wins is narrow.

Adopting |> at every two-step site for style would create a second idiom alongside the existing intermediate-variable style. Mixed idioms have a tax: every reader has to decide which style is in play before reading. That tax is paid every time the file is opened.

So pipe stays unused until a real call site asks for it. Then it gets adopted in that one place. Not across the codebase.

`array_find()`: two adoptions, five rejections

The most interesting case. PHP 8.5 added array_find() for "first matching element or null." The surface use case is exactly the foreach-and-return-first pattern that shows up in every codebase.

WP04 surveyed seven candidate sites. Two were adopted. Five were rejected.

The two adoptions

packages/search/src/SearchResult.php::getFacet():

// Before
foreach ($this->facets as $facet) {
    if ($facet->name === $name) {
        return $facet;
    }
}
return null;

// After
return array_find(
    $this->facets,
    static fn(SearchFacet $facet): bool => $facet->name === $name,
);

packages/cli/src/Testing/CliTester.php::findOption() follows the same pattern. Three lines of foreach become one array_find() with a typed predicate.

Both sites win because the return type is ?SearchFacet or ?OptionDefinition. The null case is a real outcome the caller handles. array_find returns null when nothing matches, and that lines up cleanly with the existing contract.

The five rejections

SqlEntityStorage, AuthController, EntityResolver, JsonApiController, DbalTransport. The mission notes give one rationale that covers all five:

all rejected because the surrounding type contracts (load() accepts int|string, not null) require an explicit empty guard either way

The point is subtle. array_find() returning null is only a win if the caller wants null. If the caller's contract guarantees non-null (because the input was validated upstream, or because nullness is an error condition), then the foreach version is doing two things: searching and asserting. Replacing it with array_find() keeps the search but loses the assertion. You end up writing an explicit guard right after the array_find() call. The line count is the same. The intent is worse.

The fastest way to spot this in your own codebase: read the immediate caller of the candidate site. If it does throw or assert on the result, do not adopt array_find() there. The foreach is encoding more than iteration.

What was adopted, intentionally

To be specific about what restraint does not mean: WP03 added #[\NoDiscard] to sixteen API surfaces. Four allowed/forbidden/neutral factory methods on AccessResult. Five repository interface methods that return loaded entities. Ten fluent-builder methods on DBALSelect that return the modified builder.

#[\NoDiscard] is a semantic safety net. If a caller ignores a find() return value they probably have a bug. The attribute makes the compiler say so. Adopting it on sixteen surfaces was a security-shaped decision, not a style one.

WP05 also wired three mechanical PHP-CS-Fixer rules: octal_notation (52 sites converted to 0o755), new_expression_parentheses (58 chained-new conversions), and heredoc_indentation (8 SQL and HTML heredocs reindented). Mechanical, fixer-driven, no judgement required per site. Easy to adopt at scale because the fixer makes the decision.

The pattern across both: adoption is at its best when it is either a safety improvement on a critical surface, or a mechanical fixer rule that can be applied uniformly. Adoption is at its worst when it is a style change applied site by site by humans.

The point

An upgrade is a decision about what to add and what not to add. Both decisions live in the diff. The "did not adopt" decisions are invisible if you only read the merged code, which is why they are worth writing down somewhere.

Mission directories are the place we write them down. The five-site rejection rationale for array_find() is one line in WP04's notes. Six months from now, someone will look at SqlEntityStorage::load() and think "why isn't this array_find()?" The mission directory has the answer.

If your team is doing a PHP 8.5 upgrade, the most useful thing you can write down is not the list of features you adopted. It is the list of features you considered and rejected, with one sentence each. That list is what makes the upgrade a position, not a checklist.

Baamaapii

DEV Community: Russell Jones

A beginner's guide to Git worktrees: What they are, why they matter, and how to use them without breaking anything

Prerequisites

What Is a Git Worktree?

Why Worktrees Exist

Normal Clone vs Branch Checkout vs Worktree

Normal clone

Branch checkout

Worktree

Core Benefits of Worktrees

1) Multiple branches checked out at once

2) Isolated environments for experiments

3) No need for multiple full clones

A Safe Beginner Workflow

1) Create a worktree

2) Switch into it

3) Commit from it

4) Remove it safely

How to See Your Current Worktrees

Common Beginner Mistakes

Deleting the directory without removing the worktree

Forgetting which worktree you are in

Trying to check out the same branch twice

A Simple Mental Model for .git/worktrees

How to Clean Up Orphaned Worktrees

Step 1: List what Git thinks exists

Step 2: Prune stale metadata

Step 3: Verify cleanup

Verify It Works

The hackathon Anthropic didn't expect

The hackathon Anthropic didn't expect

Two questions, not one

Three things I've watched up close

The pattern

Where the energy belongs

Closing

From vibe-coded to shippable: a playbook

The wrong fight

The repo on the bench

Step 1. Milestone the roadmap

Step 2. Write the runbook, including the gotchas

Step 3. Pin the world

Step 4. Name the graveyard

Step 5. Recon before you build

Step 6. Layer specs on what's next

What this looks like together

AI keeps speccing my projects on pre-AI timelines

The pattern

Why this happens

What this costs

What to do about it

The deeper problem

Bimaaji: agent-safe mutations for Waaseyaa

Why not just let the agent edit files

The pipeline

Introspection: what the agent reads first

The task DSL

Mutation: the reviewable proposal

Patching: AST, not strings

The integration test

Where this fits in the bigger picture

The ingest side of a sovereign language platform

The problem

The pipeline

Language tags: BCP 47, three layers

The translation side

Sovereign by construction

What is honest about it

One URL, two readers: serving HTML to people and Markdown to agents

Define the content once

One URL, negotiated by Accept

A human toggle for the same switch

Caching two formats at one address

The agent-facing routes you get for free

Why this matters

AI slop and the content treadmill every developer is on

I automated my own content pipeline

The treadmill has a lot of belts

Where the slop actually comes from

What I think the way out looks like

A Simple Mental Model for `.git/worktrees`

`array_find()`: two adoptions, five rejections