Repository navigation
Releases
v5.13 — A newer push cancels the older push's CI runs, and a gate keeps it that way
A newer push cancels the older push's CI runs, and a gate keeps it that way
2026-11-18 · v5.13
When you push a newer commit to a pull request, CI now ends the runs it had started for the commit you replaced, so the hosted macOS runners work only on commits that can still merge. A new pull-request check fails any workflow that runs on pull requests without that cancellation, written the one safe way.
Skip the rest unless you open pull requests on the platform repository or change its CI workflows.
Who this affects
- Anyone who opens a pull request on the platform repository, or pushes new commits to one.
- Anyone who adds or edits a CI workflow that runs on pull requests.
What you need to do
- After pulling this release, run
./update.sh --surfaces-onlyfrom the platform repository root, or a full./update.sh. It refreshes your install with this release's entries for the new workflow checker. - When you add or edit a workflow that runs on pull requests, put the cancellation block shown under Operator and engineering detail directly above its top-level
jobs:line, exactly as written.
What changed for everyone using the platform
- Superseded pull-request runs are cancelled. When a newer commit reaches a pull request, each of the 27 workflows that run on pull requests cancels the runs it still had in progress or waiting for the commit it replaced. Why it matters: the macOS runners stop spending hours on commits nobody will merge, so the checks on the current commit start sooner.
- Runs on the main branch are never cancelled. A run started by a push to the main branch, a tag, a schedule or a manual dispatch is grouped on its own, so a later push can neither cancel it nor make it wait. Why it matters: every merge to the main branch keeps its full set of results.
- A pull-request check keeps the setting in place. The new workflow concurrency check runs on every pull request and fails when a workflow that runs on pull requests lacks the cancellation block, writes it any other way, or adds a trigger whose runs would wrongly share the pull request's group. Why it matters: a new or edited workflow cannot quietly bring the queue back, and the check names the file and line to fix.
- A cancelled close-out smoke run gives its runner back at once. Five trailing steps of the release close-out smoke job now skip when the run is cancelled, and still run after an earlier step fails. Why it matters: a cancelled run releases its macOS runner straight away instead of after about five more minutes.
Known limits
- The check does not read the concurrency setting of a job inside a reusable workflow that other workflows call. No workflow of that kind exists in the repository today, and the release records the gap as a follow-up.
- The check does not read which pull-request activity types start a workflow. A trigger type that can fire more than once on the same commit, such as
labeled, lets each new event cancel the run before it. - A workflow that runs only on a push to the main branch, a tag, a schedule or a manual dispatch may carry any concurrency setting; the check does not grade it.
- Marking a pull request ready for review, or editing its description, re-runs some workflows on the same commit. The newer run replaces the older one, and the pull request shows the newer run's result.
- The check is not a required check, so a red result does not stop a merge by itself. It does hold the close-out tool's merge of a chore pull request, which merges only when every check is green.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
CHEAP / HIGH. Reverting the release merge restores the previous workflows; to revert in parts, revert the check's commits before the cancellation commits, because the check fails while any workflow that runs on pull requests lacks the block. Every workflow runs with read-only permissions, so a cancelled run leaves nothing half-written, and the version tag is kept as the record that the version was claimed.
Operator and engineering detail
The cancellation block. Every workflow with a pull_request or pull_request_target trigger carries one block at workflow level, immediately above its top-level jobs: line, with no job-level concurrency key. On a pull request the group is per workflow and per pull request, so a newer run cancels the older one; on any other event the key falls back to the run's own id, so the run never shares a group. The 28 workflow names are distinct after case-folding, so no two workflows share a group. The block, with its comment:
# Superseded-run cancellation: on a pull request, a newer run of this
# workflow for the same pull request (a new push, or a re-run on the same
# head) cancels this one. Any other event (a push to main, a tag, a
# schedule, a dispatch) keys on its own run id, so it is never cancelled
# and never waits behind another run.
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
cancel-in-progress: trueThe gate. The Workflow concurrency gate job in repo-integrity.yml runs core/deploy/tools/check-workflow-concurrency.py over the whole of .github/workflows/ on every pull request, with no paths filter. Equality is textual on the three canonical lines, located by a structural parse, so the gate and a fixed-string search for the group line cannot disagree. Its findings name a missing block (MISSING-GROUP), a key built any other way, github.ref included (NONCANONICAL-GROUP), a job-level key, a pull-request trigger beside workflow_call (CALLED-WITH-PR-TRIGGER), a review event beside a pull-request trigger (REVIEW-WITH-PR-TRIGGER), and a workflow-level key in a called workflow (CALLED-CARRIES-GROUP). Its --self-test grades every fixture case against its declared verdict and requires a failing scan to exit 1 with a finding; the job also fails a clean exit that prints a finding. It is advisory and enforcing: a finding turns the check red, and its context is not registered in branch protection. The gate-coverage register in core/standards/gate-efficacy-standard.md carries its row, core/rules/git-workflow.md names it among the non-blocking integrity jobs, and a short decision record, ADR-241, points at both.
What a cancelled job proves. The runtime-suite selection map now says that a job cancelled because a newer commit reached the pull request has no result for its commit, that a job which had already finished keeps its conclusion, and that a commit superseded within minutes is evidenced by a job that concluded before the next push or by the test-run event of its suite run locally.
At Stage 12. A sibling release merged first and added process-catalog-check.yml without the block, so the planned sibling-workflow branch fired: the release branch merged main in, gave that workflow the block, and its counts moved from 26 to 27 workflows. The version moved twice as siblings claimed first, and the atomic claim bound v5.13 with no collision. The four new allowlist entries for the checker sit in a composition surface the deployment manifest did not list; they were propagated after Stage 12 by the surfaces refresh on the operator's decision.
For the full implementation record see the release log entry and the release plan.
References
v5.12 — Stale hand-kept lists get caught, and every release close measures quality share
Stale hand-kept lists get caught, and every release close measures quality share
2026-11-17 · v5.12
The deploy check now reports a hand-kept list of files that has drifted from the files it names, and every release close reports the standing quality initiative's share of recent work against a written band, flagging a share outside it. Three written rules also settle questions that used to be decided case by case: when a release gets a version number, which side wins when a document and practice disagree, and where a decision that constrains code is recorded.
Who this affects
- Anyone who runs a release through the pipeline, or runs the deploy check.
- Anyone who edits the platform's governance, standards or reference documents.
What you need to do
- After pulling this release, run
./update.sh --surfaces-onlyfrom the platform repository root, or a full./update.sh. It refreshes two installed files this release changes, the workspace charter and the script allowlist, so the installed copies match the repository.
What changed for everyone using the platform
- Hand-kept file lists are checked. A list or count of files in a document can now carry a short marker naming the files it describes. The deploy check then reports any list whose entries, or count, no longer match those files. The hook lists in the module guide are the first ones marked, and they now match. Why it matters: a list that falls out of date is reported at the next deploy, instead of being found later by someone who relied on it.
- Every release close reports the quality share. The share of each release's shipped work that belongs to the standing quality initiative is now measured at close, over the last five releases. It is judged against a band of 15% to 35%, written in the platform configuration template. A reading outside the band is flagged, and nothing is blocked. This release's own reading is in band at 34.5%, just under the ceiling. Why it matters: whether quality work is getting its intended share is a number you can read at every close, not an impression.
- A written rule decides whether a release gets a version number. A release that changes what a skill, check, tool, template, setting or procedure does gets a version. A release that only adds records, such as a decision record or its own plan, ships without one. The operator can override the rule, with a reason. Why it matters: the version an install reports always names a change in how the platform behaves.
- When a document and practice disagree, the document says which side wins. The resolver reads the governing document first and brings practice into line with it. Where the document is silent, it is amended to name the winning side, and each resolution is recorded in the release plan. Why it matters: a disagreement is settled once and on the record, instead of being re-argued, or silently flipped, by each person who finds it.
- Decisions that constrain code are recorded where that code lives. A decision that fixes how a script, check or procedure must keep behaving now goes in that file's header or its governing section. A discussion thread can still carry the discussion, but it is never the only record. Why it matters: someone editing the file later can see the decision before they undo it.
Known limits
- The list check is logged but not blocking, and it reads only lists that carry a marker. A hand-kept list with no marker is not checked.
- The quality-share reading is advisory, and the band's values are revisited after three measured releases. The release that sets the band is the first measured one.
- Nothing yet confirms that the version rule was applied when a release was bundled. The release plan records the rule's citation, and a reviewer reads it.
- The release planner's own version step does not yet consult the new rule when it runs from its installed copy, outside the repository. That fix is a follow-up of this release.
- The configuration schema's general advice says to put a personal setting under an overrides section, which some readers do not read. Put a band value under the band's own section header, as its reference page says. Correcting the schema is a follow-up of this release.
Report issues on the platform repository's issue tracker, and report a suspected vulnerability privately, as the repository's security policy describes.
Reversibility
MODERATE / HIGH. Reverting the single release merge restores every file, including the release-protocol text the operator committed and the release note this release moved. The version tag is kept as the record that the version was claimed.
Operator and engineering detail
The enumeration-drift check. deploy.sh --check gains Check 83, backed by core/deploy/tools/check-enumeration-drift.py. It is a sibling of Check 63 rather than an arm of it, and the tool's module docstring records why. The check runs warn-mode on its own committed dial, and its shakedown was armed on 2026-11-13. The corpus scan runs at deploy time only; CI runs the tool's --self-test through the selftest-discovery job. Forty fixture cases, together with the self-test, kill 44 of 46 single-rule mutants, and the two survivors are equivalents. Two other enumerations, the build-philosophy bullet of the charter template and the suite steps of the install-tests workflow, now cite the files they describe instead of listing them. The marker sits on the line before the list it binds:
<!-- enumerates: core/hooks/block-*.sh list -->
<!-- enumerates: core/hooks/*.sh subset-of -->
The quality-share band and reading. The band is a new [quality_share_band] section of core/config/platform-config.toml.template, documented in the platform-config schema and reference. It resolves on two rungs, the template and the individual file under that section's own header, and an instance without the section reads NOT-EVALUATED, never a default. release/tools/compute-release-velocity.sh --quality-share reads the release log by first-parent ancestry, with a guard that every merged release in the window has its row. It judges the pooled share and prints the mean of shares beside it. Stage 13 Phase A14.2 writes the record it prints into the release plan's Verification Evidence, and a reading outside the band is a recorded finding, never a close verdict. The section as shipped:
[quality_share_band]
counted_label = "project:platform-quality"
scaffolding_label = "sub-task"
bug_type_label = "type:bug"
share_floor = 0.15
share_ceiling = 0.35
window_releases = 5
judged_on = "pooled"
values_set_at = "obligation-runners-declared"Three rules, each with its runner or a named gap. The when-to-version rule sits in release/governance/RELEASE_PROTOCOL.md § Versioning; the operator committed that text. release/references/pipeline/stage-03-bundle.md cites it on the milestone's release-identity line. The adjudication clause is core/standards/duplicate-source-discipline.md § 1.2, and the surface requirement for constraining decisions is core/disciplines/decision-discipline.md § 3.2. None of the three has an automatic runner. Each is a named gap in the gate-coverage register, with a population that Stage 13 Phase A14 measures at every close. This release's own close records each of its five new populations. One of them, the version rule's, has no members yet, so its parent epic carries it until it does.
A note moved to its standard location. One release note for a version-less release sat at the top of the notes folder, where the release-notes standard places every version-less note under release/releases/notes/_unversioned/. It moved there, and its index row followed. The notes folder's README records the decision not to add an automated placement check, and what would change that.
References
- Milestone:
obligation-runners-declared(milestone 400), under epic #5867. - Integration PR: #8995, merged at
59be7694. - Cards: #6227 · #6226 · #6225 · #7842.
- Follow-ups: two bug issues, for the release planner's version step and for the configuration schema's override advice, filed at this release's close.
v5.11 — The script guard reads each command the way the shell will run it
The script guard reads each command the way the shell will run it
2026-11-17 · v5.11
The guard that refuses to run a script your workspace has not listed now finds the interpreter and its script at more places in a command, reads each word as the shell will after it removes the quotes, and treats a command continued onto the next line as one command. A script that is not on your list, reached through any of those forms, is now refused as its plain form already was.
Skip the rest unless your sessions run scripts through a shell from the command line, or you review what the script guard refuses.
Who this affects
- Anyone whose sessions run shell commands on a workspace that has taken this release's guard bundle
- Operators who read the script guard's refusals, or who maintain the guards
What changed for everyone using the platform
-
The guard finds the command at more positions. When a command is written behind a leading redirection, with an escaped or quoted command word or wrapper word, inside a
casebranch, aftercoprocor a zsh precommand word, or inside a brace group, the guard now reaches the interpreter and the script it runs. Why it matters: writing a command one of these ways no longer lets an unlisted script run past the guard. -
Quotes are read the way the shell reads them. The guard judges each word after the shell would remove its quotes, and keeps track of quoting correctly past a comment or a quote nested inside another. That covers a quote or a space inside a script's path, a quoted value set just before the command, and a quoted or slash-bearing value handed to a wrapper that splits it. Why it matters: an apostrophe in a comment or an unusual quote placement can no longer hide a later command, or separate a script's path from the check.
-
A command continued onto the next line is judged as one command. An interpreter and its script on two lines joined by a line continuation are read together. Why it matters: breaking a command across lines no longer turns a refusal into a warning that is only logged.
-
A shell fed by
xargsstays refused whatever options it carries. Whenxargsstarts a shell that will read a script name from its input, adding one of the shell's own options no longer gets past the refusal. A shell asked only to check syntax, or given its program inline, is still allowed. Why it matters: one extra option can no longer let a script named on standard input run. -
Ten command forms the guard refused before are now allowed. Where the guard now reads a word as the shell does, ten forms in its test set move from refused to allowed, and each is declared and pinned by a test. Why it matters: the closer reading also lifts those ten refusals instead of only adding new ones.
Known limits
- Some forms are still logged or allowed rather than refused, and each is declared with an owner. A script reached inside a group or a substitution is logged, not refused, until that reading switches from logging to refusing, which #7637 tracks; the guard's readiness check warns on 2026-12-15 (Tue) and reports a finding on 2027-01-14 (Thu). One top-level form of the
xargscase is logged for the same reason. A path with a space inside its quotes is refused at the script's own position but not yet at three other positions; that remainder is item S-8 of the release's follow-up sweep, #9052. Thexargsrefusal covers shells only, by design. - Some commands that run nothing unlisted are now refused, and each is declared in the guard's readiness reference: a carrier command whose quoted text names an unlisted script on a line that also holds a comment the guard cannot trust, and a few costs of the wider position walk. The ones a user would plausibly hit are items S-13 and S-14 of the release's follow-up sweep, #9052.
- The added readings make the guard do more work on each command. A limit on the guard's work per command is tracked in #8327.
- Further gaps in what the guard covers, found during this release, are reported privately as the Security Policy describes and are not described here; the release's follow-up sweep, #9052, counts them.
- A workspace picks up this release when an update refreshes its guard bundle. The version a workspace reports changes to v5.11 on the first update after this release closes.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / MEDIUM. Reverting the single release merge restores the script guard as it was, and a workspace runs the restored guard only after an update refreshes its guard bundle; the version tag is kept as the record that the version was claimed. A revert reopens every gap this release closes.
Operator and engineering detail
The position walk (#8316). The walk now reaches the verb behind a leading redirection, an escaped or quoted verb, a quoted wrapper word, a case arm, coproc, a zsh precommand word and a brace group, in three slices (the words, the redirections and the compound positions). CP17 is the one declared precision move to allowed (PM-1); PC-1 and PC-2 are declared precision costs.
Quote state and the word after quote removal (#8317, #8318, #8319, #8491). The quote scanner carries comment state and nested-quote phasing, and the shared ANSI-C test reads an odd-length run of $ before a quote as opening one. The operand path reads the word the shell passes when a quote or a backslash sits inside the path; at the Stage 9 gate the operator accepted #8318's Decision 4, which closes a whitespace-bearing quoted path at the operand after the flag walk and leaves three other positions not joined, with a successor owner. The assignment-value step only withdraws fragment suppression, never grants it. #8491 reads a quoted or slash-bearing split-string value, with the canonicalizer's twin in the shared awk library and three declared divergences (D-1 to D-3).
The line continuation (#8320). A second first-view walk reads the joined logical line (M-CONT-WALK), and the here-document receiver test reads the logical line too, excising only when both readings name a carrier (M-CONT-RECV). After Stage 7 the join takes the segments' linear split, so a large continued command no longer outlasts the hook's timeout.
The xargs deny (#8492). The deny holds for an xargs-fed shell whose own flags leave no operand, no inline program and no parse-only grant. A closer-bearing segment takes the enclosure phase whichever view reads it, through a third router argument. PC-X1 and PC-X2 are declared, and PC-X2's Override Record is Accept, owned by the enclosure phase's graduation. The deny stays shell-only (N1).
The corpus differential. Each card adds one seed block to the tracked walk payload corpus, recorded at the base before its RED commit. No refused row moves to allowed except a declared precision row: WR134, WR135, AV19 to AV22, AV24, CP17, SV28 and SV30. The fixtures README's real-interpreter check was waived for this release, so those rows carry ground truth ? (DEV-10). In the hook harness job on the merge commit's push run, the block-destructive suite read 2088 of 2088, and the hook suites 4697 passing and 0 failing.
The corpus gained a newline placeholder, because a row is one line and two of the classes span lines. Row LC14, an allowlisted script after a line continuation, is one such row; its ground truth is ?, because it was not run under the real interpreter this release:
LC14|block-destructive|rt-cont-near|-|?|a|bash \@NL@@D@/ok.sh
How it shipped. Seven cards on one branch, built serially. Model-output safety classifiers stopped several spawned agents in the guard's region, so four cards and #8319's third pass were built in the orchestrating session, with Stage 7's dev test as their only independent check. The Stage 9 verdict was GO WITH CONDITIONS, with three conditions (the macOS install suite green at the merged head, four content reads confirming the build, and the operator's review of the diff), all of which held. The release merged at 20149aeb and claimed v5.11 with a signed annotated tag, after the provisional label was relabelled twice as sibling releases claimed v5.08, v5.09 and v5.10. The hook bundle was refreshed through ./update.sh, and the deployed guard and canonicalizer byte-equal the merged source. One procedure line in the hub-spoke bridge now sources the version-grammar library by its repository-relative path, because the new word reading refuses the old form (DEV-9).
For full implementation detail see the Deployment Log v5.11 entry in the release log, and the release plan.
References
- Milestone: script-guard-reads-every-token-as-the-shell-does
- Integration PR: #8993 at
20149aebe456223290d7363da642fe842334fcc3 - Stage 12 chore PR: #9049 at
450038bb3b527f6b94a13a12d4b2690b0d6d7d5e - Issues: #8317 · #8318 · #8319 · #8491 · #8320 · [#8316](https://githu...
v5.10 — The engineering harness has catalog pages, and CI fails when they go stale
The engineering harness has catalog pages, and CI fails when they go stale
2026-11-17 · v5.10
The process catalog now holds one page for each process in the engineering harness: install and update, the hooks, the deploy checks, the CI gates and the release tools. Planning and review steps for a harness change can now start from a current-state page instead of re-reading the scripts. A pull request that moves a line a page cites, or changes generated output without regenerating it, turns a catalog check red.
Who this affects
- Anyone who changes a hook, a deploy check, a CI workflow, the installer or a release tool.
- Planning, design and close-out work on the harness, which now reads these pages.
What you need to do
- After pulling this release, run
./update.sh --surfaces-onlyfrom the platform repository root, or a full./update.sh. It refreshes the script guard's allowlist with entries for the five catalog tools. Until it runs, the guard refuses those tools when an agent runs them.
What changed for everyone using the platform
- One page per harness process. The catalog's first universe holds 48 pages. Each describes one process: what triggers it, its inputs and outputs, its steps, who acts, and the files it is built from, cited by line. Why it matters: a harness change can be planned from a written description of how the harness works today, and a page that disagrees with the code is corrected rather than trusted.
- A generated index, graph and views. An index, a machine-readable graph and 13 views are built from the pages. The views cover structure, jobs, state, data flow, interfaces and the controls each process relies on. Why it matters: you can find every process that touches a given script or control without opening every page.
- A catalog check on every pull request. CI runs three catalog checks on each pull request and on the main branch. The first confirms the generated output matches a fresh build, the second that every cited line still says what its page cites, and the third that every page passes the catalog's rules. Why it matters: a page cannot quietly fall out of step with the code it describes, and each failure names the one command that repairs it.
- Pages name their measures, never one machine's numbers. A page says what is measured and which script measures it. The figures themselves are generated on each install into a folder that is never committed. Why it matters: the published pages read true on every install and never carry one machine's numbers.
- The tools that build and check the catalog ship with the platform. The builder, the checker, the element inventory and the pre-publication scan each come with a self-test. Why it matters: the next two universes reuse the same tools, definitions and registers instead of starting over.
Known limits
- Only the engineering-harness universe is published. The other two universes and the browse view come in later milestones.
- The three catalog checks are not required checks. A red run does not stop a release pull request from merging. It does hold the close-out tool's merge of a chore pull request, and the release's execute and close steps read the run on the main branch.
- A fresh clone shows each measure and the script that produces it, not a value. The value appears only after that install generates its own figures.
- Two comparison rows on one page and one measure were held out of this release, and one page states a self-test property more widely than its sources support. The release's follow-up sweep, #9046, carries each of them.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / MEDIUM. Reverting the single release merge restores the previous tree, because every change is a file addition or a bounded edit. Page text that reached the public repository stays in its history, and the version tag is kept as the record that the version was claimed.
Operator and engineering detail
Where the catalog tools live. The builder, the checker, the element inventory, the pre-publication scan and their shared library sit beside the deploy tools. They take this repository's paths as argument defaults. The placement is recorded on its card rather than in a new decision record.
The definitions pack. The catalog's vocabulary, its four page templates, the controls and identifier registers, and the tables the tools read are tracked together, with one machine-readable pack file the tools load. The published controls register carries only rows sourced to a tracked file. The sample below is the frontmatter of one published page, trimmed to its identity and link fields.
id: bootstrap-workspace
level: L3
universe: engineering-harness
parent: install-platform
precedes: [validate-install]
triggered_by: [external:fresh-clone]
owner: operator
last_verified_commit: 7fae37579a54714fa6c56f469ab067b389219ad6
pack_version: 2Publication was signed and held. Every push that changed page text, a generated file or the catalog README carried the operator's signature. The pre-publication scan is the step run before a push of catalog text. The execute stage checked the catalog and wrote nothing under it on its own. After the main branch moved, it carried two catalog repairs, each signed, that re-cited moved lines and re-verified the affected pages.
CI posture. The catalog checks fail from their first run and are deliberately not required contexts. The gate-efficacy standard records that posture, and the catalog README names the repair command for each check.
Exit checks on the merge commit. The milestone's own checks ran on the merge commit, each with a control that shows it can fail. The page validator read 0 errors over the 48 pages, while a planted invalid page read its planted error. The generator's self-test passed. Two regenerations matched each other and the committed output, and every link on the pages resolved. The depersonalization job and a project-name scan were clean, and the three catalog checks were green on the push to the main branch. The milestone's measured cost is recorded as the measure and the script that produces it; the figures stay with the install.
For the full implementation record see the release log entry and the release plan.
References
v5.09 — Usage is counted once per response and stated in one unit, so a release's cost can be recorded
Usage is counted once per response and stated in one unit, so a release's cost can be recorded
2026-11-16 · v5.09
The usage extractor now counts each API response once instead of once per transcript line, and flags a response whose output was only partly written. Usage is converted to one unit — weekly points of one account — through a single conversion, so the usage report, the release-cost row and the command-template ranking all state cost the same way.
Skip the rest unless you read the FinOps usage report, record or compare what a release cost, or run the usage scripts in your own sessions.
Who this affects
- Operators who read usage figures from the FinOps usage extractor or its report
- Anyone who records or compares what a release cost
- Operators whose sessions run the new conversion or ranking scripts, which the script guard allows only after the next update (see Known limits)
What changed for everyone using the platform
-
Each API response is counted once. The extractor used to count every assistant line in a transcript, which over-counted responses by 1.8 to 3.4 times. It now counts one row per response. Why it matters: usage figures are no longer inflated by how a response happened to be split across lines.
-
A partly written response is flagged, not quietly under-counted. When only part of a response's output count was written, the response is marked incomplete and the report says how many responses could not be fully read. Why it matters: a low output figure is shown as a lower bound rather than passed off as exact.
-
The usage report reads real stores. The report used to reject every real store because of how it checked start times. Why it matters: the report now runs on the data it was written for.
-
Cost is stated in one unit. Token usage converts to weekly points of one account through one conversion, at both ends of the cache-read weight range, and the decision is recorded in ADR-240. Why it matters: two figures from different tools can be compared, because they are the same unit computed the same way.
-
Each release can carry its own cost row. The release velocity tool builds a usage row by stage, role and token type through that one conversion. Why it matters: what a release cost can be recorded beside how long it took, instead of being estimated after the fact.
-
Retyped command templates are ranked by cost. A new ranking script lists the commands sessions retype most, with their cost in the same unit, as input for deciding which to turn into scripts. It keeps transcript text out of its output. Why it matters: the most expensive repeated work is visible without exposing what the sessions said.
Known limits
- The two new scripts — the usage conversion and the command-template ranking — are refused by the script guard until a workspace runs
./update.sh, which refreshes the guard's allowlist and its shared resolver library. - Writing the release-cost row automatically at close-out is not part of this release; until #9004 lands, the row is written by hand into the install's usage-telemetry home.
- The extractor does not yet count advisor and fallback sub-call usage (#9032), and a response repeated in a resumed or forked transcript file is counted again (#9033). The report does not yet show the lower-bound label or the count of unread responses (#9035), and thinking is counted inside output with no separate figure (#9036).
- The model-use decision and the probes it rests on moved to the next milestone with their two cards, #7935 and #8041, after the probe window read degraded.
- The usage store's schema moved to a new major version; an existing store is rebuilt the next time the extractor runs, because rebuilding is its default.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / MEDIUM. Reverting the single release merge and rebuilding the usage store restores the previous counting, because the store is a derived cache; ADR-240 would be superseded rather than deleted, and the version tag is kept as the record that the version was claimed.
Operator and engineering detail
Counting (#7937, #7938). extract-usage.sh keys each row on the response's message identifier, so a response written across several assistant lines is one row, and it marks a response incomplete when its final output count was never written. The store schema's major version advanced, with the measured corpus factors cited in core/schemas/finops-usage-store-schema.md.
The report (#7939). report-usage.sh accepts start times with fractional seconds, which every real store carries.
The unit (#7940, ADR-240). One account's weekly points, counted once per API response and attributed to the release run graph's four elements. convert-usage.sh is the one conversion from per-response token totals to weekly points, and it states both ends of the cache-read weight bracket. The release's first calibration revisit re-confirmed Decisions 1 and 3 and moved no calibrated value. ADR-240 was ratified at this release's Stage 13.
The cost row (#7943). compute-release-velocity.sh gains a cost-row mode built on convert-usage.sh. Under the Stage 9 Operator Override Record, the automatic write at close-out and its stage text moved to #9004, which is blocked by #8019 and #8022.
The ranking (#7945). rank-command-templates.sh ranks retyped command templates by cost. Its privacy controls run first: planted-leak fixtures in its self-test fail every privacy arm, and its report stays under the analysis home.
How it shipped. Six cards on one branch. Two further cards, the model-use decision (#8041) and its probe card (#7935), moved to the next milestone at Engineering when the probe window read degraded. A sibling release merged first and took ADR-239 and v5.08, so this release's decision record was renumbered to ADR-240, its provisional version stamps moved to v5.09, and the branch merged main twice before its merge at 1c2130c5. The release claimed v5.09 with a signed annotated tag, and the FinOps skill was deployed under the release's identity. The operator ran ./update.sh to publish the allowlist and the shared resolver to the guard tier.
For full implementation detail see the Deployment Log v5.09 entry in the release log, and the release plan.
References
- Milestone: release-usage-measured-right
- Integration PR: #8821 at
1c2130c500cd2447e9c5672650f2118647b8f2c3 - Stage 12 chore PR: #9030 at
d293361e3c99b9e3936b630e331374ce5ec46d57 - Issues: #7937 · #7938 · #7939 · #7940 · #7943 · #7945
- Decision record: ADR-240
- Follow-ups: #9031 (the release's follow-up sweep) · #9032 · #9033 · #9034 · #9035 · #9036 · the carried close-out write #9004 · evidence folded into the open owners #6407 · #8005; the close record is on #8748
v5.08 — The deletion guard judges every part of a command and the path it acts on
The deletion guard judges every part of a command and the path it acts on
2026-11-15 · v5.08
A command that deletes files or moves them to the Trash is now judged in every part of the line, on the path the shell will act on, so a harmless earlier part no longer lets a later deletion through. Deletion words that a command only carries as text, such as a commit message written through a quoted here-document, no longer get the command refused when nothing is deleted.
Skip the rest unless your sessions delete files or move them to the Trash from the command line, write commit messages or issue bodies through a here-document, or you review what the deletion guard refuses.
Who this affects
- Anyone whose sessions run shell commands on a workspace that has taken this release's guard bundle
- Operators who read the deletion guard's refusals, or who maintain the guards
What changed for everyone using the platform
-
Every part of a command is judged. A deletion or a move to the Trash is now judged wherever it sits on the line, including after a
gitcommand or after a deletion that names no target. Why it matters: a harmless first part of a command can no longer carry a deletion outside your workspace past the guard. -
A deletion that does not show all its targets on its line is refused. A deletion or Trash call with no target, or whose targets continue onto the next line, is refused rather than allowed. Why it matters: the guard no longer lets through a call whose targets it cannot see.
-
Text a command only reads is no longer treated as a deletion. When a quoted here-document is read by a program that only reads it, deletion words inside it no longer get the command refused. The readers are
cat, agit commitorgit tagmessage, a GitHub CLI issue, pull request, release or API body, and a Python program read from standard input. Why it matters: a commit message or an issue body that mentions a deletion command no longer fails when nothing is deleted. -
The outside-workspace check uses the path the command acts on. The Trash location the guard itself recommends is recognised, the target and your workspace root are compared in the same form, and a target word the shell would rewrite before acting on it is refused rather than guessed at. Why it matters: a link, a trailing slash or an unusual spelling of a path can no longer make a target outside your workspace read as inside it.
-
A home-relative path on a line that changes HOME is refused. Why it matters: the guard no longer judges a
~path against its own home when the command sets a different one.
Known limits
- Some safe commands are now refused, and each is declared in the guard's readiness reference or its decision record: a Trash call whose targets continue onto the next line, a quoted path that contains a space (the Finder delete is the remedy for a Trash move), a home-relative path on any line that names HOME, a commit message carried by a here-document inside a command substitution with a deletion word at a line start, and a continued line whose
#opens no comment, which is read as if it ended one. - Some classes remain declared limits of the guard's design rather than gaps this release closes: text written to a file that a later step runs, a Python program read from standard input that hands text to a shell, a HOME name built through an expansion, an empty-the-Trash option carried with an inside target, and a command carried as a string for another shell to run.
- Further gaps in what the guard covers, found during this release, are reported privately as the Security Policy describes and are not described here; the release's follow-up sweep, #9027, counts them.
- A workspace picks up this release when an update refreshes its guard bundle. The version this workspace reports changes to v5.08 on the first update after this release closes.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / MEDIUM. Reverting the single release merge restores the deletion guard as it was, and a workspace runs the restored guard only after an update refreshes its guard bundle; the version tag is kept as the record that the version was claimed. A revert reopens every gap this release closes.
Operator and engineering detail
The segment walk (#8122, ADR-239). core/hooks/block-rm-prefer-trash.sh no longer has an exit that allows a line on a match. A git segment exempts only itself, each rm-family verb is judged on its own segments, and a deletion or Trash segment that does not name all its targets on its line is refused under the strict policy. A line's continuation is read once per line, and a command's words are read past a redirection's ampersand, so every Trash target is judged or the call is refused, whichever redirection precedes the continuation. At the Stage 9 condition the continuation rule became comment-aware: the hook also reads the command after each continued line that carries a #. ADR-239 supersedes ADR-235's decision 3, the frozen view the removed exits read; ADR-235's other decisions stand, and the canonicalizer's code is unchanged.
The quoted-body reading (#7644). A private parser inside the hook removes a top-level quoted here-document body from the judged text only when its receiver is on a named list: cat, git commit or git tag after at most one -C <dir>, the built-in gh issue, gh pr, gh release and gh api, and python3 -. Every other receiver, a shell included, any enclosure in a command substitution, backtick or subshell, and any route to a program keep the body judged. git's edit option and zsh's definition tables decline the reading.
The target resolver (#8123). The keg-only Trash location is a Trash invocation. The target and the workspace root are compared in one normalized form, and a target that cannot be normalized is refused, never admitted. A target word that is not literal — a brace, a backslash, an inner quote, a quoted leading tilde, another tilde prefix or a zsh equals-word — is refused as unresolvable, and on a line that names HOME no home-relative word is expanded.
The differential. The release's declared verdict moves are named row by row in its two cross-issue criteria, one for refuse-to-allow moves and one for allow-to-refuse and rule-ID moves, and the suite differential is graded against them. At the Stage 9 GO the suites read 4222 passing and 0 failing across 25 suites, with 0 undeclared refuse-to-allow moves against main.
How it shipped. Three cards on one branch, built serially. After the scope lock, Stage 6 ran six fix-up passes returned from Stages 7 to 9, most of them on the line-continuation class. The Stage 9 GO carried one condition — the comment-continuation residual fixed in this release — which a re-verification confirmed before Stage 12. The release merged at 4e70b20f and claimed v5.08 with a signed annotated tag. Its decision record, claimed as 238 on the branch, was renumbered to ADR-239 before the merge because a sibling release had taken 238; its ratification is recorded in its own status field. The operator published the hook bundle through the targeted refresh, and both deployed files hash-equal the merged sources. Three comment-only corrections in a sibling release's files were handed to that release.
For full implementation detail see the Deployment Log v5.08 entry in the release log, and the release plan.
References
- Milestone: deletion-guard-judges-every-segment-and-target
- Integration PR: #8992 at
4e70b20faf6115ed47259b1f0520494fb1f0c88d - Stage 12 chore PR: #9024 at
e3c0f624ca167542a2f49156216a0cde7ccfb4c7 - Issues: #7644 · #8122 · #8123
- Decision records: ADR-239 · ADR-235 (superseded in part)
- Follow-up: #9027 (the release's follow-up sweep) · evidence folded into the open owners #9005 · #7651 · #7428 · #8102; the close record is on #8916
v5.07 — The filesystem guard refuses paths it cannot know in advance
The filesystem guard refuses paths it cannot know in advance
2026-11-10 · v5.07
The guard that limits where a session's file commands may read and write now refuses a path written with a shell feature that changes a value before it is used. The guard can't tell where such a path points until the shell has already run it, so it now refuses the path instead of letting it through. Ordinary file commands are unaffected.
Skip the rest unless your sessions write file paths using shell variable expansions, or you review what the guards refuse and log.
Who this affects
- Anyone whose sessions run file commands on a workspace that has taken this release's guard bundle
- Operators who read the filesystem guard's refusals and logged records, or who maintain the guards
What changed for everyone using the platform
-
A path built by a value-changing shell feature is refused. The shell can change a variable's value before using it, in ways that can even run other commands. A file path written that way is now refused, wherever it sits in the path, whether or not it is quoted. Why it matters: the guard no longer lets through a path it could not check.
-
A few similar-looking paths are refused on purpose. Some ordinary uses of shell variables end the same way as that feature, such as a default value or a pattern replacement containing an
@. Those are now refused too, and the guard's documentation lists each of them. Why it matters: when one of these is refused, you can find out why. Plain variables, and the common ways of listing several values, are not affected. -
Two refusals that used to happen by accident are now deliberate. Two other shell forms that can run commands were refused only because of how the guard happened to split them. Each now has a test that keeps it refused. Why it matters: a future change to the guard can no longer let them through without someone noticing.
Known limits
- Some shell forms get their value from outside the command, from the environment or a file the shell reads. No guard that reads only the command can see that value, so these stay a stated limit with no owner.
- Four places in a command are still never checked by this guard. They are owned by #8547.
- Four extra checks planned for this release could not be run, so the release relies on the guard's own tests for those cases. You accepted that at the release's final review.
- A workspace picks up this release when an update refreshes its guard bundle. The version this workspace reports changes to v5.07 on the first update after this release closes.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / HIGH. Reverting the single release merge restores the guard as it was, and a workspace runs the restored guard only after an update refreshes its guard bundle; the version tag is kept as the record that the version was claimed. A revert reopens the gap this release closes.
Operator and engineering detail
The guard (#8322). core/hooks/block-fs-boundary.sh gains a third limb at G2, _carries_transform_op: an operand carrying a ${ and, anywhere, the shape @, one character other than ] or }, then } is refused under BLOCK-FS-BOUNDARY-003, as $( and a backtick already are. The test is two one-star globs, linear in the operand's length (XFORM-COST-01). The span split gains _span_closed_inside_subscript (predicate P-2): a ${…} span whose text holds both a [ and a nested ${ is refused like an unterminated one, which closes the class of operator uses broken inside a subscript, whose pieces the token walk would otherwise hand over in separate words (XFORM-COST-02). The rationale is path-undecidability, not an execution control, which stays with the script-execution allowlist.
The suite and the fragment. The XFORM block in core/hooks/tests/block-fs-boundary.test.sh grows by 103 arms, to 322, with 19 pairing copies: each refusal pin is held red through the copy that lacks exactly its mechanism. The over-refusal classes are pinned as decisions (XFORM-OVER-01..11), and must-not-flag controls stay green (XFORM-NEAR-01..09). The fragment core/rules/bypass-mode-readiness/block-fs-boundary.md now reads "Parameter-transformation operators are REFUSED at G2", states the value-re-evaluating brace forms as a declared limit without an owner, and pins the two brace forms refused by where the operand breaks (XFORM-SPLIT-01/02). The registry index is regenerated.
How it shipped. One card on one branch. A model-output safety classifier stopped spoke work four times while escape-class test arms were authored or run, so Stage 6 ran hub-direct under the operator's authorization, and four Stage 7 measurements (S7-E1, S7-E3, S7-E4, S7-E5) were accepted at the Stage 9 GO WITH CONDITIONS as residuals bounded by the in-suite arms. The release merged at 2ce25400 and claimed v5.07 with a signed annotated tag. Stage 12 merged main into the branch twice before the merge, each time with no overlap. The operator published the hook bundle, and the deployed hook hash-equals the merged source.
For full implementation detail see the Deployment Log v5.07 entry in the release log, and the release plan.
References
- Milestone: fs-boundary-refuses-parameter-transformation
- Integration PR: #8832 at
2ce25400e196176b5f2ab5fb7381b471059e6591 - Stage 12 chore PR: #8843 at
375209930d0ddb816d8a8d581b9152666407cc5b - Issue: #8322
- Follow-up: #8547 (the four unexamined walk positions)
v5.06 — Every initiative in one live view, and dependencies read the right way round
Every initiative in one live view, and dependencies read the right way round
2026-11-08 · v5.06
You can now see every initiative and every epic that sits under none, with its epics and open work beneath it, in one view read live from the tracker. Milestone sequencing also stops guessing: a dependency written in an issue is read in the direction it points, so work is no longer ordered backwards.
Skip the rest unless you sequence milestones, read initiative progress, write dependencies into issue bodies, or run the platform's release tooling.
Who this affects
- Anyone who sequences milestones or reads which work must land first
- Anyone who reads initiative progress or decides which epics belong to which initiative
- Authors who write "Blocked by" or "Dependencies" sections in issue bodies
- Operators of an installed workspace (one step below)
What you need to do
- Only if you run an installed workspace: run
./update.sh --surfaces-onlyonce. The release added the two new tools to the list of scripts the platform's safety checks let run, and the normal deploy does not carry that list to an installed workspace.
What changed for everyone using the platform
-
Every chain head is in one live view. One command lists each initiative, and each epic that belongs to no initiative, with its epics and open work underneath, read from the tracker when you run it; the roadmaps guide shows how to run it. Read on 2026-11-08 it showed 10 initiatives, 9 with an end point and 1 ongoing, over 709 open issues. Why it matters: you no longer assemble initiative status by hand from separate lists, and the view cannot drift from the tracker because it keeps no copy.
-
The view never reports a count it could not read as zero. When a read fails, the count is marked unmeasured. An ongoing initiative, one whose tracker label description begins with the word "Standing", shows no completion percentage, because it never finishes. Why it matters: a zero or a percentage in the view is a real reading, never a failed read or a meaningless number.
-
Which initiative an epic belongs to comes from its labels. An initiative is any initiative label that has open work, so adding an epic to an initiative takes only the label. An epic with no initiative label joins an ongoing initiative only when more than half of its children carry that initiative's label. Why it matters: there is no separate list of initiatives to keep up to date, and an epic is not pulled into an initiative on a thin majority.
-
Dependencies are read in the direction they point. Previously every issue number in an issue's dependency section counted as something that issue waits on, including "blocks" lines, which point the other way, and links to parent or child items. Now only real waits-on edges count, and a negated line such as "does not block" counts as nothing. Why it matters: the milestone order and the cross-milestone dependency check no longer put work ahead of the work it depends on.
-
A dependency no longer disappears behind extra blank lines. A section in an issue body now ends only at the next heading or a horizontal rule, so a heading followed by two blank lines no longer reads as an empty section. Why it matters: a dependency you declared is never silently dropped.
-
The tools that read issue bodies now read them the same way. Section reading lives in one place that the milestone-ordering tool and the dependency-mirroring tool both use, and the check for epics ready to close counts an epic's children by the same rule as the new view. Why it matters: two tools can no longer disagree about what the same issue says.
Known limits
- The view reads the dependency sections written in issue bodies, not GitHub's native "blocked by" links. Reading native links for sequencing is proposed in the native-links card, which this release unblocks.
- The operator's interim board still shows its own portfolio map. Retiring that map in favor of this view is an operator step on that board that has not been taken yet; the board's milestone lanes stay until the standing sequencing layer ships.
- The check that finds epics ready to close still reads a failed child read as "no children" and leaves that epic out silently, tracked in this observation.
- The release planner's guidance on which phrases make a hard dependency still lists "blocks" without saying which way it points, so it can disagree with the parser, tracked in this observation.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / HIGH. Reverting the release merge restores the parser, both tools and the documents exactly; nothing outside the repository persists, because no milestone stores a position, the dependency mirror only ever adds links an author declared, and the view writes nothing. The two decision records are Accepted at this close, so changing what they decide now takes a superseding record, and the cost grows as later tools build on the parser's shared reading. The version tag is kept as the record that the version was claimed.
Operator and engineering detail
The view (#6398). python3 release/tools/compute-chain-head-rollup.py prints the Markdown view, and --json prints a versioned machine-readable rollup; --self-test runs offline fixtures. Each head carries its open-member count, a partition of members inside and outside its tree, its unparented members, progress, and a blocked count, and every count carries a status of measured, unmeasured or not-applicable. One head from the live read on 2026-11-08 (commit 6315b977), nodes elided:
{
"id": "project:pipeline",
"kind": "initiative",
"mode": "finite",
"members_open": 146,
"progress": {"status": "measured", "completed": 44, "not_planned": 10, "total": 168, "percent": 26},
"blocked": {"count": 12, "unmeasured": 0}
}The rollup's meta block records the commit anchor, the denominator (open issues read, checked against the search total) and the status of every read it made. The epic child-set rule (native sub-issues plus label-linked issues, the carrier excluded) moved into release/tools/_epic_child_set.py, shared by the view and audit-epic-rollup-close.sh. ADR-237 records the head derivation, the strict-majority absorption rule and the standing declaration; the label taxonomy and the initiative-roadmap framework now state the standing convention.
The direction grammar (#6397). parse_dependencies in release/tools/bundle-issues-parser.py returns directed blocked_by targets only, applies the negation rule, and treats a blank line as ending a run. Gate G3-07's new Edge source paragraph in the gate-criteria spec names that function as the authority, and compute-milestone-positions.py derives positions from the same edges and carries the parse status.
The single home (#7177). ADR-236 makes the bundle parser the one home of the issue-body section extractor and the dependency heading aliases; native-dep-mirror.py loads it by path instead of keeping its own copy and exits with its infrastructure-failure code when the parser cannot load. A section ends at a level-2 or level-3 heading or a --- rule.
How it shipped. Three cards on one branch, built in engineering slices. Each Stage 5 design went through an adversarial review before the operator's scope lock. Dev Testing and QA both ran. One required check went red because three new tool files were tracked without the executable bit; two were made executable and the third, an imported module, was exempted. Plan Review returned GO with conditions: the merge-order condition was met, and the condition to refresh the pull request's description before Execute was missed and made up at this close. Releases that merged first took the ADR numbers twice, so the records were renumbered from 230 and 231 to 234 and 235, then to 236 and 237, and the release claimed v5.06. It merged at b02fa16a with a signed annotated tag; the only deploy was the rules-mirror refresh. Both decision records were ratified Proposed → Accepted at this close on the operator's per-record decision.
For full implementation detail see the Deployment Log v5.06 entry in the release log, and the release plan.
References
v5.05 — Guards now give a command the same verdict however it is spelled
Guards now give a command the same verdict however it is spelled
2026-11-08 · v5.05
The platform's command guards now read a guarded command the way the shell will run it, so writing that command differently no longer gets it past a guard that refuses, or logs, its plain form. Ordinary commands are unaffected: a command changes verdict only when it is another way of writing one the guards already judge, or when it only looked like one and never ran it.
Skip the rest unless your sessions run shell commands through wrapper programs or inside conditions, use the GitHub API from a session, or you review what the guards refuse and log.
Who this affects
- Anyone whose sessions run shell commands on a workspace that has taken this release's guard bundle
- Operators who read the guards' refusals and their logged-but-not-blocking records, or who maintain the guards
What changed for everyone using the platform
-
A wrapper in front of a command no longer hides it. When a command runs through a wrapper program, the guards now step over the wrapper's own options and arguments, recognise the wrapper by its name even when it is written with its full path, and know three wrapper programs they used to miss. Why it matters: putting a wrapper in front of a command the guards refuse no longer turns the refusal into a silent run.
-
A command used as a condition is checked like any other. A command that decides an
if,whileoruntilblock is now read as a command in its own right. Why it matters: a guarded command gets the same verdict whether it stands alone or decides a branch. -
The guards that protect your settings judge a setting however it is placed. The guard that stops a session from changing where programs are looked up, and the guard that stops a session from changing the guards' own bypass and boundary settings partway through, now refuse the same setting when it is handed to a wrapper, written after another setting, placed inside a group or a condition, given to a declaration command, or added to rather than replaced. Why it matters: the protection no longer depends on where in a command the setting is written.
-
Another spelling of a guarded GitHub write gets the plain spelling's verdict. The outbound guard now reads a GitHub API write the way the shell resolves it, whether its words are escaped, quoted, split, braced, broken across lines or written in different letter case, whether a redirection comes first, or whether its method option is written in short form. At the start of a command, such a write to an unlisted path is refused, as the plain spelling is; behind a prefix command it is logged, as the plain spelling is. Why it matters: the outbound guard's verdict no longer depends on how the command is typed.
-
Commands that only looked guarded are judged by what actually runs. Some commands named a guarded program only as a setting's value or as a wrapper's argument, and never ran it, yet were refused; each such class is now declared and gets the verdict of the command that does run. Why it matters: fewer false refusals for commands that never run what the guards protect.
Known limits
- Some spellings still reach a guard without the plain form's verdict, and each is owned by an open card: settings that the two settings guards do not yet judge, such as one carried as a program's own option or reached indirectly (#8652), and the spellings of a GitHub write that the outbound guard still admits without a record (#8650).
- Behind a prefix command, the outbound guard logs a GitHub write rather than refusing it, for every spelling, as it does for the plain one. When those logged writes start being refused is owned by #6195.
- A command carried as a string for another shell to run, and a few positions the shared command reader does not reach, are declared limits of its design rather than gaps this release closes.
- Two classes found in review are carried to public follow-up cards filed at this release's close: a command run inside a nested shell, and a guarded command word written in different letter case in the guards other than the outbound one.
- A declared class of commands still costs the guards more work than before this release. It is accepted, and its general remedy is owned by #8660; the work bound on the script check that predates this release is owned by #8327.
- A workspace picks up this release when an update refreshes its guard bundle. The version this workspace reports changes to v5.05 on the first update after this release closes.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / HIGH. Reverting the single release merge restores the four guards and the shared command reader as they were, and a workspace runs the restored guards only after an update refreshes its guard bundle; the version tag is kept as the record that the version was claimed. A revert reopens every gap this release closes, and the two decision records, Accepted at this close, change only through records that supersede them.
Operator and engineering detail
The shared command reader (#8314, ADR-235). The command-position canonicalizer, core/hooks/lib/command-position.awk, which four always-on hooks consume, now walks each transparent wrapper's own option grammar from a field-for-field copy of the script-execution rule's getopt rows, which a suite arm holds equal to the rule's own. It matches a prefix word on its basename, adds nice, stdbuf, timeout and the if/while/until condition keywords, steps over the append form of a prefix assignment as it steps over the plain form, and reads a prefix-run assignment or redirection before it looks a word up as a wrapper. The deletion hook's two allow-on-match exits read a frozen exit view, so they keep the verdicts they had, and one run of the canonicalizer now serves both of the views that hook reads.
The settings rules (#8444). BLOCK-DESTRUCTIVE-020 and -023 ride the canonicalizer's assignment branch, so a PATH assignment, or a mid-session setting of the hook-bypass or scope-guard variable, is judged at every position the canonicalizer resolves, in a declaration builtin's argument list, and with the append operator. The positions and spellings -023 newly refuses are a declared tightening. Each rule's registry row states a verdict for every spelling the card named, and routes the rest to #8652.
The egress rule (#8315, ADR-234). BLOCK-EGRESS-007 keeps its own walk and reads a respelled gh api write as the shell resolves it, across ten spelling classes. A respelling takes the rung of the position the shell resolves it to: refused on day one at the head of a segment, and recorded at the unchanged shadow phase behind a prefix command. A respelled invocation counts on its own first-invocation counter, so no day-one refusal of a later plain write is withdrawn, and the unparseable branch and the fast-path gate read the same spellings. The respellings still admitted with no record are routed to #8650, and the graduation of the recorded writes to #6195.
Cost on a long command. Most of the return passes decided at Stage 7 went to cost rather than to verdicts. The egress scanner's substitutions, quote walk, continuation join, ANSI-C decode and word normalization, the script-execution rule's segment split and quote scan, the filesystem guard's refusal renderer and the canonicalizer's own walks now read a long command once, as linear passes that equivalence arms hold byte for byte to the code they stand in front of, so their work grows with the command as main's does. The egress brace step bounds the expansion it builds and reads a group past the bound as written, as main reads every brace group. A class that costs a constant multiple more than main is an accepted residual, with #8660 its systemic remedy; main's own sites of the cost class are routed to #8327 and to the filesystem guard's later milestone.
The differential. The tracked corpus core/hooks/tests/fixtures/walk-payload-corpus.txt gained seed blocks for #8444 and #8315, and for the later passes on #8314 and #8315, and the destructive and egress suites re-grade every row on each run. #8314's own wrapper faces are graded by the suite arms of all four consuming hooks rather than by a corpus block, which the operator accepted at Stage 9 under an override. The release's differentials recorded no refused shape moving to allow apart from the declared precision classes, the shapes that never run the guarded program.
How it shipped. Three cards on one branch, built serially, then fourteen return passes to Engineering from Stages 7 to 9, most of them on cost and on how the release's public text describes it. Stage 8 returned all three cards as conditional, and the operator accepted each card's residual set with its successor owners at a Stage 9 GO WITH CONDITIONS. The release merged at e58a77f0 and claimed v5.05 with a signed annotated tag on the first attempt; its provisional display had been v4.82, and sibling releases claimed the versions between first. The two decision records were renumbered as sibling releases too...
v5.04 — Grouping backlog items into epics now has a decided home and one way in
Grouping backlog items into epics now has a decided home and one way in
2026-11-08 · v5.04
A decision record, Accepted at this close, says where the method for grouping many backlog items into epics lives and how it will be started. Nothing is built in this release and there is nothing you need to do: the method, its starting point and its filing step come in a later release that can now be planned against this decision.
Skip the rest unless you group backlog items into epics or initiatives, plan the work that builds the composition method, or review designs that touch the release planner, the release executor or the intake desk.
Who this affects
- Anyone who groups loose backlog items into epics, or works out which epics an initiative needs
- Whoever plans the follow-on work that builds the method, the design-axis toolkit or the decomposition method, all three of which this decision answers
- Reviewers of designs that touch the release planner, the release executor or the intake desk
What changed for everyone using the platform
-
Where epic composition lives is decided. The method for grouping many backlog items into epics will be one shared method document in the platform core, cited by the skills that run it and copied by none; the decision record explains why the core is the only home every part of the platform can cite. Why it matters: the work that builds the method can now be planned against a named home instead of an open question.
-
There will be one way in, reached by plain requests. The method will be started through one mode on the release planner, which picks what to run from what you are grouping — a milestone, a set of work items, or an initiative — and five phrasings such as "compose an epic from these items" are recorded for it. Why it matters: once it is built, you can start a composition without knowing which skill hosts it.
-
Nothing is filed until you approve the exact drafts. The mode only proposes: it writes one proposal holding the groupings, the reasoning and the literal draft of every new card, each draft checked for readiness first, and a separate step that you start files exactly those drafts and reads them back. Why it matters: what reaches the tracker is word for word what you approved.
-
Groupings are kept in every methodology. Where your methodology has no grouping kind of work item — Kanban today, and Scrum until its epic is declared as one — each member is tagged with a grouping label instead of the grouping being lost. Why it matters: composition does not depend on one methodology's vocabulary.
-
Two related questions get the same answer on where a method lives. The decomposition method, which splits large items, will also be a core method document, and the design-axis toolkit will be a separate core reference that both methods point to. Why it matters: the follow-on work for both can cite this one decision instead of deciding the question again.
Known limits
- Nothing is built in this release. The method document, the release-planner mode and the filing step are the work of the codification story, which this decision unblocks for planning; until it ships, the five phrasings reach nothing new.
- The Scrum methodology does not yet declare its epic as a grouping kind. Until that declaration lands, Scrum groupings will be carried on a label rather than a native parent, and in Kanban they stay on a label for as long as it declares only cards.
- Above the epic, nothing is filed as an item: an initiative stays a grouping label plus a roadmap, as an earlier Accepted decision requires.
- The check that the five phrasings do not compete with other skills compares words, so a request phrased differently with the same meaning can still reach another skill.
Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.
Reversibility
MODERATE / MEDIUM. Before this close the record could be revised in place, or the release merge reverted. Now that it is Accepted, the decision changes only through a record that supersedes it, at a cost that grows as the follow-on work builds on it. Confidence is high on the home and medium on the entry point, which was a judgment between two candidates that both survived review. The version tag is kept as the record that the version was claimed.
Operator and engineering detail
The decision record (#6390). ADR-233 places the composition method in core/disciplines/ on the root-cause-analysis precedent. Its extend-before-create determination reads net-new because in-place is infeasible (ADR-094; build-philosophy row 3): the one covering surface, the bundle-composition doctrine, is a release-module standard scoped to milestone bundles, and the module boundary (ADR-007) admits a surface citable from both consumer modules only in core. The entry is one thin, read-only, altitude-dispatching mode on release-planner that persists one composition proposal as a handoff file; every write sits in one operator-explicit execute step on release-executor, which validates the proposal, snapshots, files each approved body verbatim, wires membership, reads both back and routes the rest to a disposition queue. The altitude parameter reads ADR-211's ladder, refined at the Work Item level by the kind's declared level_role (ADR-180), and never branches on a kind name. ADR-049 governs the tier above the epic, so a kind there is conditional on the deferred grouping-tier card reconciling with ADR-049 Decision 1, or on a superseding record. The record also carries the per-capability boundary table (ADR-019), the three entry points it does not change, and the codification story's edit set — with the Scrum level_role = "grouping" declaration, and every reader it moves, as a precondition.
The trigger phrasing. The five phrases were scored with the ADR-114 trigger-collision gate's own primitives over all 56 skills: as a skill of their own they peak at 0.048, and added to the release planner its highest pair is 0.094, against an escalate threshold of 0.30. QA re-ran the measurement independently and reproduced every figure.
How it shipped. One card on one branch. The Stage 5 design went through an adversarial review whose two Major findings — the record omitted ADR-049's representation of the tier above the epic, and its write path named the planner-to-executor precedent without adopting that precedent's persisted handoff and verbatim filing — were resolved by a bounded revision under the operator's scope lock. Dev Testing ran reduced to document-conformance checks by operator decision; QA graded all six acceptance criteria MET; Plan Review returned GO with one condition, every required check green before the merge, which was met at Execute. Three releases opened after this one's first commit merged ahead of it and took ADR-230 to ADR-232 and versions v5.02 and v5.03, so the record was renumbered from 230 to 233 at merge and the release claimed v5.04. It merged at 60e2369c with a signed annotated tag; the only deploy was the rules-mirror refresh, because no skill, package, hook or rules-mirror member changed. The record was ratified Proposed → Accepted at this close under the operator's standing close-out direction.
For full implementation detail see the Deployment Log v5.04 entry in the release log, and the release plan.