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:

1. The floor moves (a policy change).
2. Deprecations get removed (a behavior change).
3. New features get adopted (a style change).
4. 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

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.

1. Specify. Compile a spec.md from the mission brief. Requirements get checklisted. Ambiguity gets surfaced before code touches the repo.
2. Plan. Choose an approach in plan.md. Inputs from spec. Output is the shape of the work.
3. Tasks. Break the plan into work packages (WPs). Each WP is independent enough to assign and review on its own.
4. Implement. Each WP runs through implement and review until approved. State transitions go through the orchestrator, not by hand.
5. Review. Per WP, against the spec. Reviewers can reject with structured feedback.
6. 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