DEV Community: Russell Jones

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

The PHP 8.5 deprecation sweep: from 34 warnings to zero

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

Ahnii!

Second in the PHP 8.5 upgrade series. The first post covered the floor-bump mechanics. This one is about what 8.5 surfaced when the floor moved and how the sweep cleared it.

Mission: php-8-5-upgrade-01KR8DN2, work package WP02. Merge commit e0f8cb57. The CHANGELOG entry for alpha.176 records the verification: 34 PHPUnit deprecations to 0, across 7,497 tests.

The starting number

Before WP02 ran, the test suite was emitting 34 deprecation warnings against 8.5. That number does not measure how broken the codebase was. It measures how dense the test corpus is. A weaker test suite would have surfaced fewer warnings because fewer code paths run during CI.

PHPUnit's deprecation handling matters here. Waaseyaa runs PHPUnit in strict mode where deprecation messages are captured and counted per test, not just printed. The mission's exit criterion was zero deprecations on the matrix that already ran 18,118 assertions.

Three categories, twenty-nine sites

The 34 warnings collapsed into three deprecation patterns once you grouped them. Twenty-nine distinct call sites across the monorepo.

1. `Reflection*::setAccessible()` — 22 sites

The biggest category. ReflectionMethod::setAccessible() and ReflectionProperty::setAccessible() were marked as no-ops in PHP 8.1 (private members became reflectively accessible by default) and deprecated outright in 8.5.

Twenty-two call sites across seven test files. Packages: entity, user, ssr, foundation, entity-storage, and one integration test under tests/Integration/Phase13/.

Every site looked roughly like this:

$reflection = new ReflectionMethod($object, 'privateMethod');
$reflection->setAccessible(true);
$reflection->invoke($object, $arg);

The fix was deletion. The line that called setAccessible(true) was removed. The line that called invoke() worked unchanged. No behavior change at runtime. The reflection access was already implicit.

This is the cleanest kind of deprecation removal you can do: the warning was telling you the line was already useless.

2. `$http_response_header` — 1 site

A single site in packages/http-client/src/StreamHttpClient.php. The magic global variable $http_response_header was deprecated in favor of the explicit function http_get_last_response_headers().

Before:

$headers = $http_response_header ?? [];

After:

$headers = http_get_last_response_headers() ?? [];

Same null-coalesce default. Explicit function call instead of a side-effect global. Easier to read, easier to mock, easier to grep for.

This is the kind of language cleanup that arrives one site at a time when the language standardizes a long-running pattern. PHP's magic globals are slowly being retired across the major versions.

3. `curl_close()` — 6 sites

Six call sites of curl_close(), deprecated in 8.5 because libcurl has treated it as a no-op since version 7.20.0. PHP held onto the function for years for compatibility. 8.5 finally removes it.

Files:

packages/ai-agent/src/Provider/AnthropicProvider.php — 3 sites
packages/ai-agent/src/Provider/OpenAiCompatibleProvider.php — 2 sites
packages/mercure/src/MercurePublisher.php — 1 site

All six were paired with curl_exec() calls in HTTP request flows. Removed without replacement. The cURL handle is collected by GC when it goes out of scope.

A second tautological PHPStan warning was cleaned up in the same area while we were there. Worth noting because deprecation sweeps are a good moment to fix the things you keep walking past.

What did not get removed

WP02 was a deprecation sweep, not a code cleanup. The bar for removal was "PHP 8.5 marks it deprecated" or "PHPStan reports it tautological in the file we are already editing." Nothing else.

That bar matters. It is tempting during an upgrade to fold in unrelated cleanup. The reason not to is that the diff stops being readable. A reviewer looking at WP02 should be able to read it as "deprecation removals" with no surprises. Adding "and we also renamed this variable while we were there" makes every line of the diff a question.

The verification

The exit criterion was numeric and binary. Run the full suite. Count deprecations. The number must be zero.

Locked by full PHPUnit (7497 tests / 18118 assertions / 0 deprecations / 2 expected skips)

That line in the CHANGELOG is the work package's signature. Two expected skips are environment-dependent tests that always skip in CI (Redis, Mercure broker variants). Zero deprecations across 7,497 tests is dense enough coverage that a future deprecation drift would surface immediately.

If you are running a similar sweep on your own codebase, the methodology is straightforward:

Move the PHP floor.
Run the full test suite. Capture deprecation output.
Group warnings by the deprecation key (E_USER_DEPRECATED message, function name, or class).
For each group, write a one-line removal pattern and apply it across all sites in one commit per group.
Rerun. The number is zero or it is not done.

The reason to group by deprecation pattern (not by file) is that each group has the same fix. Mixing them in one commit makes the diff hard to read and impossible to revert selectively.

Post 3 in the series covers the features 8.5 introduced that we deliberately did not adopt. Property hooks. The pipe operator. Broader array_find() adoption beyond the two confirmed sites. The reasoning is that restraint is part of the upgrade, not the absence of one.

Baamaapii

Spec Kitty mission lifecycle: a domain modeling pass through Giiken

Russell Jones — Mon, 11 May 2026 16:24:24 +0000

Ahnii!

A lot of agent frameworks promise "end to end" workflows. Most of them stop at "generate a plan and hope." Spec Kitty is different. It runs a real mission through a state machine, with artifacts on disk and gates between phases. This post walks one of those missions, giiken-domain-modeling-01KR2HKT, from spec to merge.

Context: Giiken is the community knowledge service built on Waaseyaa. The mission did discovery and docs for its domain model. Real commit: waaseyaa/giiken@5b2328b.

What "a mission" actually is

A Spec Kitty mission is a directory under kitty-specs/, named with a slug and an ULID. After this mission landed, that directory looked like this:

kitty-specs/giiken-domain-modeling-01KR2HKT/
  spec.md
  plan.md
  research.md
  data-model.md
  meta.json
  status.json
  status.events.jsonl
  mission-events.jsonl
  checklists/
    requirements.md
  research/
    evidence-log.csv
    source-register.csv

That is not a generated artifact dump. Each file has a role in the state machine. spec.md is the contract. plan.md is the chosen approach. research.md plus the CSVs are the evidence trail. status.json and the two .jsonl files are the lane state and the audit log. The checklist is a hard gate, not a suggestion.

The phases

The mission moved through these phases. Each one writes an artifact and emits a status event.

Specify. Compile a spec.md from the mission brief. Requirements get checklisted. Ambiguity gets surfaced before code touches the repo.
Plan. Choose an approach in plan.md. Inputs from spec. Output is the shape of the work.
Tasks. Break the plan into work packages (WPs). Each WP is independent enough to assign and review on its own.
Implement. Each WP runs through implement and review until approved. State transitions go through the orchestrator, not by hand.
Review. Per WP, against the spec. Reviewers can reject with structured feedback.
Merge. Once every WP is approved, the mission squash-merges and the events log records the terminal state.

The thing that makes this different from a long prompt is that every transition is gated. You can't move a WP to approved without a passing review. You can't merge with WPs still in flight. The agent is constrained to the shape of the state machine.

What this mission actually produced

Beyond the kitty-specs directory, the merge commit added two architecture documents to the Giiken repo:

docs/architecture/domain-model.md
docs/architecture/lifecycle.md

And the implementation work in WP01 and WP02 left the data model migration-aligned, with PHPUnit and Vitest both green at merge time. Thirteen files in one squash commit, all traceable back to the spec.

The point is the trail. A reader six months from now can open kitty-specs/giiken-domain-modeling-01KR2HKT/ and see: what was asked for, what was chosen, what evidence informed it, what got built, and which checks passed. That is a working memory you can hand to the next agent or the next human.

Why this matters more than the output

The output of this mission is fine. Useful, even. But the output is replaceable. The trail is not.

If you have been around agent workflows for any length of time, you know the failure mode: an AI session ends, the context evaporates, and the next session has to reconstruct everything from the code. Spec Kitty inverts that. The mission directory is the persistent context. The next agent picks up the spec and the checklist, not a chat log.

That is the lifecycle proof: not "an agent shipped code," but "an agent moved through a structured workflow that another agent or human can audit, resume, or extend."

Try it

If you want to see one of these missions in your own repo, the easiest path is to install Spec Kitty and run spec-kitty next --agent <name> on a small scope. Pick something with a clear question, not a vague refactor. Discovery missions like this one are a good first try.

The commit for the mission described here is waaseyaa/giiken@5b2328b. The full mission directory is in that repo at kitty-specs/giiken-domain-modeling-01KR2HKT/.

Baamaapii

Hugo blog shortcodes: adding a visual component system to PaperMod

Russell Jones — Wed, 08 Apr 2026 20:41:09 +0000

Ahnii!

PaperMod is a clean, fast Hugo theme. What it doesn't give you out of the box is a component library: no callouts, no numbered steps, no before/after comparisons. If you write tutorials or technical posts, you end up compensating with blockquotes and bold text where purpose-built components would serve the reader better.

This post covers all six shortcodes, the CSS behind them, and how to add the same components to your own PaperMod blog. All of it came together in a single Claude Code session.

What we're building

Six shortcodes, one CSS file:

callout: highlighted aside with five severity types
steps / step: auto-numbered procedure blocks
pullquote: large-format quote for emphasis
stats / stat: side-by-side metric tiles
compare / before / after: side-by-side comparison panels
cta: call-to-action box with a button

All styles hook into PaperMod's CSS variables (--primary, --entry, --border, etc.), so they adapt to dark and light mode automatically.

File locations

Hugo resolves shortcodes from layouts/shortcodes/. Create one .html file per shortcode:

layouts/shortcodes/
  callout.html
  steps.html
  step.html
  pullquote.html
  stats.html
  stat.html
  compare.html
  before.html
  after.html

The CSS goes in assets/css/extended/. PaperMod loads everything in that directory automatically; no import statements needed.

The shortcodes

Callout

A callout is a highlighted aside that draws the reader's attention. It accepts a type parameter: info, warning, tip, note, or success. Defaults to note.

Template (layouts/shortcodes/callout.html):

{{- $type := .Get "type" | default "note" -}}
{{- $emoji := dict "info" "💡" "warning" "⚠️" "tip" "✨" "note" "📝" "success" "✅" -}}
<div class="callout callout-{{ $type }}">
  <div class="callout-marker">{{ index $emoji $type }}</div>
  <div class="callout-body">{{ .Inner | markdownify }}</div>
</div>

Usage:

{{</* callout type="warning" */>}}
Run `git stash` before switching branches or you will lose your changes.
{{</* /callout */>}}

Rendered:

Run git stash before switching branches or you will lose your changes.

The markdownify call means you can use inline markdown inside the body: backtick code, bold, links. All render correctly.

Steps and step

The steps shortcode wraps a sequence of step shortcodes. Each step takes a title as its first positional argument and auto-numbers itself via CSS counters. No JavaScript, no manual numbering.

Templates (layouts/shortcodes/steps.html and step.html):

<!-- steps.html -->
<div class="steps">{{ .Inner }}</div>

<!-- step.html -->
<div class="step">
  <div class="step-badge"></div>
  <div class="step-body">
    <div class="step-title">{{ .Get 0 }}</div>
    <div class="step-content">{{ .Inner | markdownify }}</div>
  </div>
</div>

Usage:

{{</* steps */>}}
{{</* step "Create the shortcode file" */>}}
Add `layouts/shortcodes/callout.html` to your project.
{{</* /step */>}}
{{</* step "Add the CSS" */>}}
Create `assets/css/extended/components.css` with the component styles.
{{</* /step */>}}
{{</* /steps */>}}

Rendered:

Add layouts/shortcodes/callout.html to your project.

Create assets/css/extended/components.css with the component styles.

Stats and stat

The stats shortcode is a flex container for stat tiles. Each stat takes two positional arguments: the value and the label.

Templates (layouts/shortcodes/stats.html and stat.html):

<!-- stats.html -->
<div class="stats">{{ .Inner }}</div>

<!-- stat.html -->
<div class="stat">
  <div class="stat-number">{{ .Get 0 }}</div>
  <div class="stat-label">{{ .Get 1 }}</div>
</div>

Usage:

{{</* stats */>}}
{{</* stat "6" "shortcodes" */>}}
{{</* stat "1" "CSS file" */>}}
{{</* stat "0" "JS required" */>}}
{{</* /stats */>}}

Rendered:

The tiles flex-wrap on small screens, so they stack gracefully on mobile without extra media query work.

Compare, before, and after

Three files work together: compare.html wraps the pair, before.html and after.html render each panel. The before panel uses PaperMod's warning colour; after uses the success colour.

Templates (compare.html, before.html, after.html):

<!-- compare.html -->
<div class="compare">{{ .Inner }}</div>

<!-- before.html -->
<div class="compare-before">
  <div class="compare-marker">✕</div>
  <div class="compare-body">{{ .Inner | markdownify }}</div>
</div>

<!-- after.html -->
<div class="compare-after">
  <div class="compare-marker">✓</div>
  <div class="compare-body">{{ .Inner | markdownify }}</div>
</div>

Usage:

{{</* compare */>}}
{{</* before */>}}
Blockquote hacks repurposed as callouts.
{{</* /before */>}}
{{</* after */>}}
Purpose-built `callout` shortcode with five types.
{{</* /after */>}}
{{</* /compare */>}}

Rendered:

Blockquote hacks repurposed as callouts.

Purpose-built callout shortcode with five types.

On screens narrower than 600px the panels stack vertically.

Pullquote

A pullquote is a styled blockquote for emphasis. Use it to surface a key insight or memorable line from the surrounding text.

Template (layouts/shortcodes/pullquote.html):

<blockquote class="pullquote">
  {{ .Inner | markdownify }}
</blockquote>

Usage:

{{</* pullquote */>}}
Good writing tools get out of the way. Good components make the writing better.
{{</* /pullquote */>}}

Rendered:

Good writing tools get out of the way. Good components make the writing better.

CTA

A call-to-action box with a centred button. Takes three named parameters: title, button, and href. The inner body is optional copy.

Template (layouts/shortcodes/cta.html):

{{- $title := .Get "title" -}}
{{- $button := .Get "button" -}}
{{- $href := .Get "href" -}}
<div class="cta">
  <h3 class="cta-title">{{ $title }}</h3>
  <div class="cta-body">{{ .Inner | markdownify }}</div>
  <a class="cta-button" href="{{ $href }}">{{ $button }}</a>
</div>

Usage:

{{</* cta title="Try it yourself" button="View the source" href="https://github.com/jonesrussell/blog" */>}}
All six shortcodes and the CSS are in the repo.
{{</* /cta */>}}

Rendered:

All six shortcodes and the CSS are in the repo.

The proving ground

Before calling the system done, retrofit an existing post. I used Minoo Elders, replacing a flat numbered list with a steps block and a closing paragraph with a cta. If the shortcodes work in a real post with real content, they are ready.

The retrofit caught a line-height edge case in the step badge CSS and confirmed the dark mode colours held in both themes. Worth the ten minutes.

Vibe coding the component system

This system was built with Claude Code in one session. Describe the component you want, review the draft, push back on anything over-engineered. Nine files and the CSS came together without a lot of manual effort.

The real gain is in the iteration loop: see a render, request a tweak, get updated CSS in thirty seconds. That speed is the whole point.

Baamaapii

Day One of the Content Pipeline: What Broke and What I Fixed

Russell Jones — Mon, 06 Apr 2026 04:01:00 +0000

Ahnii!

Yesterday's post walked through automating a content pipeline with GitHub Actions and Issues. The idea: a daily scheduled job scans recent commits and closed issues across several repos, filters out the noise, and opens what's left as GitHub issues labeled stage:mined. One of those issues looks something like this:

Title: [content] feat: add SovereigntyProfile to Layer 0
Body:
  ## Source
  Commit `abc1234` in `waaseyaa/framework`
  ## Content Seed
  feat: add SovereigntyProfile to Layer 0
  ## Suggested Type
  text-post

Those issues are raw material. You curate them into drafts, produce the copy, and publish. That surfacing step is what the rest of this post calls mining. This post is about what happened the first time I actually ran that pipeline. The short version: it works, but the first real run turned up three problems no amount of planning could have caught. Here are the three fixes and the meta-lesson underneath them.

Day One Output: 20 Issues, Too Much Noise

The mining workflow fired on schedule and opened 20 stage:mined issues overnight, pulled from three repos. Good news: the pipeline saw everything it was supposed to see. Bad news: "everything" is not the same as "a usable drafting queue." The first run had more noise than I expected, and it had noise the filter couldn't see.

Fix 1: Tighten the Mining Filter

Even with the v1 noise filter, too many low-signal commits made it through. Things like fix: align FileRepositoryInterface usage with Waaseyaa\Media\File contract matter for the codebase and are boring as standalone posts. The first fix was to extend the exclude regex in content-mine.yml:

COMMITS=$(gh api "repos/$REPO/commits?since=$SINCE&per_page=50" \
  --jq '.[] | select(.commit.message | test("^(Merge |chore|docs|fix typo|bump|update dep|Bump |fix:.*([Pp]hp[Ss]tan|namespace|alignment|placeholder|phpunit|mock|ignore|typo))"; "i") | not) | {sha: .sha[0:7], message: (.commit.message | split("\n") | .[0]), date: .commit.author.date}' \
  2>/dev/null || echo "")

The new patterns (phpstan, namespace, alignment, placeholder, phpunit, mock, ignore, typo) catch categories of real work nobody wants to read about. A minimum message length of 25 characters cuts drive-by fixes. Fewer mined issues per run, and the ones that survive sit closer to "actually postable." That handled the mechanical noise. The next problem was harder because no regex could see it.

Fix 2: Merge-in-Curation

Filters are a blunt instrument. They cannot tell that eight separate commits all belong to the same post. On day one, the Giiken project alone produced eight mined issues: scaffold, entity types, RBAC, ingestion, wiki schema, query layer, plus two support commits. Every one of them was a valid feature commit. Together they were one post. No filter was going to catch that. Only a human reading them side by side could say "these are a story."

So curation got a new action: merge into target. Instead of picking one winner and closing the rest, you pick a canonical issue, roll the seeds from the others into its body, and close the sources. The target ends up carrying a combined seed (the whole story), and the sub-issues get a skipped label and a closed state.

The curation skill now runs like this:

→ Approve (move to stage:curated)
→ Skip   (close with skipped label)
→ Merge  (pick target, combine seeds, close sources)
→ Edit   (adjust seed, type, or channels before approving)

Running that over the 20 mined issues collapsed them to 4 curated posts: one about the pipeline itself, one about the Giiken project, one about a governance protocol suite in the framework, and one about a specific Symfony refactor. Signal up, count down. Two fixes done. The third was the embarrassing one.

Fix 3: Put the Blog First

The v1 production step went straight from a curated issue to Facebook, X, and LinkedIn copy. That read fine in the design doc. It fell apart the first time I tried to run it, because every one of those social posts had a placeholder where the URL should go. The URL had to point at a blog post. The blog post did not exist yet.

So I rewrote the /content-produce skill — a Claude Code workflow that turns queue issues into drafts. The new flow:

flowchart TD
    A[stage:curated issue] --> B[Draft Hugo post<br/>draft: true]
    B --> C[Draft social copy<br/>docs/social/slug.md]
    C --> D[Commit both to blog repo]
    D --> E{Human review}
    E -->|Flip draft: false| F[GitHub Actions deploys]
    F --> G[/content-pipeline/]
    G --> H[Buffer API → X, LinkedIn, Facebook]

The human controls publication. The skill commits drafts only and never flips draft: false. Once I flip the flag and push, GitHub Actions deploys the post, and a separate /content-pipeline skill handles the Buffer API for social distribution. Each step has one job. This post you're reading is the first one produced by the new flow.

Why Content Pipelines Need Continuous Refinement

You cannot design a content pipeline in the abstract. You ship v1, run it against one day of real input, and watch it lie to you. Then you fix the specific lies. That loop is the work.

Three days ago this pipeline did not exist. Two days ago it was a spec. Yesterday it shipped. Today it is already different. None of the three fixes in this post were things I could have known up front. They came from running the thing, staring at the output, and asking "what is this queue actually trying to tell me?"

If you are building your own version of this, expect the same arc. Your v1 will have noise you cannot see yet. Your first curation session will reveal merges a filter could not find. And your production step will probably be backwards, because writing the fun part first (the tweets) is more tempting than writing the part that does the work (the blog post). The refinement is not a sign something went wrong. It is the point.

Baamaapii

DEV Community: Russell Jones

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 question, not a conclusion

Agent-friendly JSON output for PHP CI tools

Why agent context windows hate CI output

What the package does

Three ways to flip a tool into agent mode

Coverage

PHPUnit is the awkward one

What the numbers say

Why not just use Laravel PAO?

Try it in your own monorepo

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

How to play

Why it exists

Bumping a PHP monorepo to 8.5: the mechanics

The starting state

Mission shape

What WP01 actually changed

The verification surface

Why split it into work packages at all

What the next posts cover

PHP 8.5 restraint: features we did not adopt

Property hooks: not in scope

The pipe operator: not used

array_find(): two adoptions, five rejections

The two adoptions

The five rejections

What was adopted, intentionally

The point

The PHP 8.5 deprecation sweep: from 34 warnings to zero

The starting number

Three categories, twenty-nine sites

1. Reflection*::setAccessible() — 22 sites

2. $http_response_header — 1 site

3. curl_close() — 6 sites

What did not get removed

The verification

Next post

Spec Kitty mission lifecycle: a domain modeling pass through Giiken

What "a mission" actually is

The phases

What this mission actually produced

Why this matters more than the output

Try it

Hugo blog shortcodes: adding a visual component system to PaperMod

What we're building

File locations

The shortcodes

Callout

Steps and step

Stats and stat

Compare, before, and after

`array_find()`: two adoptions, five rejections

1. `Reflection*::setAccessible()` — 22 sites

2. `$http_response_header` — 1 site

3. `curl_close()` — 6 sites