particle-academy/change-council
A consumer-agent voting ledger for major package changes: a zero-dependency change detector for CI and pre-push, and a Laravel ledger with two voting rounds, per-consumer silence policy, a hash-chained audit log and signed decision records.
composer require particle-academy/change-councilAPI surface
Headless package — drive it from code or an agent. No component grid.
change-council
A consumer-agent voting ledger for major package changes. Before a package ships a change its consumers can feel (a third-party major, a raised platform floor, a removed export, a schema change, a deprecation), the agents that run the apps depending on it are asked, and every answer is kept.
Two halves, one repo:
- The detector,
council/check.mjs: zero-dependency Node that compares two git refs and reports what a consumer could feel. The same file runs in a local pre-push hook, in GitHub Actions on public repos, and behindphp artisan council:detect. - The ledger,
particle-academy/change-council: a Laravel package for a lab. Proposals, two voting rounds, per-consumer silence policy, owner decisions, an append-only hash-chained audit log, Ed25519-signed decision records, a JSON API, an Overwatch feed, and lab pages built from react-fancy.
Pre-1.0, and report-only. Phases 1 and 2 of the design. Nothing gates a release yet: the detector exits 0 whatever it finds, and decision records are written and verified but not required. The gate is Phase 3. Breaking changes land in minor releases; read the CHANGELOG.
For agents. This package is listed on the Fancy MCP catalog server at
https://ui.particle.academy/mcp(streamable HTTP, no API key; MCP idfancy-ui), with install commands and docs, alongside the rest of the kit. How an agent installs and uses this package is in AGENTS.md.
The rules it encodes
- Silence is not consent. A required voter's silence escalates to the owner,
unless the owner has set that consumer to
proceed_and_notify(it proceeds, and the consumer's late vote is still recorded). - Agents petition; the owner decides. A whitelisted agent's finding or request, or an issue from a whitelisted author, opens round 1. Anything non-whitelisted waits for the owner with the initiating agent's pros and cons. No petition leaves first. Owner decisions are made in the authenticated lab UI only; no artisan command can record one.
- Replies are data. Strict JSON, bound to the round by nonce and digest, identified by the Genie-stamped sender, flagged for injection, rendered as text, never applied.
- The ledger never calls Genie. The lab's own agent (the clerk) sends the petitions it queues and pipes the replies back.
- The detector is a floor, not a ceiling. A behaviour change behind an unchanged signature is invisible to it. Declare those.
Quick look
node council/check.mjs # previous v* tag -> HEAD, human summary
node council/check.mjs --json --out r.json # structured report
change-council detector 0.1.0 (REPORT-ONLY: Phase 1 never fails a release)
compare: v1.0.0 -> HEAD (3f2a9c1e0b7d) kind: library
MAJOR (2)
[platform-floor] composer:php ^8.3 -> ^8.4 (composer.json)
[third-party-major] composer:acme/http ^2.1 -> ^3.0 (composer.json)
...
use ChangeCouncil\Facades\Council;
Council::authorizeOwners(); // [email protected]; an empty list allows nobody
Council::routes();
Owner-only on purpose: on a host with open registration, "any signed-in user" is anyone. See the quick start.
Optional: name the owner the way your app does. Owner actions are recorded as
owner:<email> (the user's key when it has no email). Council::resolveActorUsing()
maps the authenticated user to a different id instead, recorded as
owner:<id> in the audit log and the decision:
Council::resolveActorUsing(fn ($user): string => 'github:'.$user->github_login);
The answer must be a non-empty string of at most 191 characters with no
control characters or newlines. A bad answer refuses the owner action with
invalid_actor (HTTP 500) and records nothing; it never falls back to the
email, because the audit log is append-only.
Step-up before owner actions (optional)
A host can require a fresh proof (a passkey ceremony, a TOTP, a second device)
before any OWNER action runs: approve or reject an initiation, override,
revoke, the silence policies, a member's weight or project, removing a member,
inviting an agent, and the blocking threshold. The council does not know what the proof is; it
calls the host's ChangeCouncil\StepUp\StepUp:
Council::requireStepUpUsing(new MyPasskeyStepUp); // default: NoStepUp
interface StepUp {
public function required(mixed $principal, OwnerAction $action): bool;
public function challenge(mixed $principal, OwnerAction $action): array; // for the client
public function verify(mixed $principal, OwnerAction $action, array $proof): array; // evidence, or throw StepUpRefused
}
OwnerAction is {action, ref, address, params} (params = the validated body)
and digest() is sha256: of its canonical JSON, so a proof bound to it cannot
approve another Change, another member, or the same action with other params.
The proof travels in the body's reserved step_up key. After authorization and
body validation:
| Request | Answer | Audit log |
|---|---|---|
no step_up |
428 {"error": {"code": "step_up_required", "step_up": <challenge>, "action": {action, ref, address, params, digest}}} |
nothing |
| a refused proof | 403 {"error": {"code": "step_up_failed", "reason": "<code>"}} |
owner.step_up_refused {action, ref, address, digest, reason, evidence} |
| a verified proof | the action's usual answer | owner.step_up {action, ref, address, digest, evidence}, then the action's own events, in one transaction |
A step-up whose action the ledger then refuses rolls back with it. The default,
NoStepUp, requires nothing, and a step_up key is then ignored.
The pages answer a 428 through a handler the host sets once in its browser entry; the request is re-sent once with the proof:
import { setStepUpHandler } from './Pages/Council/parts/api';
setStepUpHandler(async (challenge, action) => ({ /* the proof */ }));
Optional, and off by default: Council::notifyGenie() (or
COUNCIL_NOTIFY_GENIE=true) sends owner events to Genie's app inbox after
commit. These are a proposal awaiting the owner, initiation approved or
rejected, override, revoke, a closed tally and escalation. The notice carries refs and counts only, and a failure is
audited, never thrown. See the
quick start.
Your first-party packages (the census)
A census keeps only the packages your estate publishes and
drops the rest as not_first_party. Which names count is host configuration,
council.census.first_party, per ecosystem (composer, npm, pypi). The
defaults are Fancy's (particle-academy/*, @particle-academy/*, fancy-*),
so a council for any other estate must set its own:
// config/council.php
'census' => [
'publisher' => 'Prism', // named in the census request
'first_party' => [
'composer' => ['patterns' => ['prism-php/*']],
'npm' => ['patterns' => ['@prism-ai/*']],
'pypi' => ['patterns' => ['prism-ai-*'], 'names' => ['prism-conformance']],
],
],
- A pattern is an exact name, or a literal prefix with ONE trailing
*. It is never a regex: matching is a prefix or exact comparison, so no configured pattern is ever run against a member's reply.nameslists exact names. PyPI entries are written in PEP 503 normalised form (lower case,-only), because reply names are normalised before the check. - When
first_partyis set it is the whole rule. An ecosystem it leaves out has no first-party packages, and the census request does not ask for it. - The rule is validated once, when the service provider boots. A bad entry (a
regex, a bare
*, a*anywhere but the end, a character outside the ecosystem's name alphabet, an unknown key or ecosystem, more than 50 patterns or 200 names, or anything over 214 characters) throws anInvalidArgumentExceptionnaming the entry, such ascouncil.census.first_party.pypi.patterns.0. It is never skipped silently. - The census request lists the configured patterns and names, and names the
publisher, so a member is asked for your packages rather than Fancy's.
Docs
- Laravel quick start: install, authorization, pages, commands, API
- The detector: classes, waivers, surface snapshots, what it cannot see
- CI usage: GitHub Actions and pre-push, pinned SHA plus content hash, never in an id-token job
- Petitions and replies: initiation, the clerk loop, wire formats, tally and silence
- The census: members list what their lockfiles install;
COUNCIL-CENSUS v1 - Decision records:
decision.v1, signing, verification, the audit chain - The Overwatch feed:
feed.v1, the signed webhook, open questions for civi - Lab UI: the pages, and how they were checked in a real browser
Requirements
- Detector: Node 22+ and git. PHP on PATH for the PHP API comparison (it says so in the report when it is missing).
- Ledger: PHP 8.4 with sodium, Laravel 13. inertia-laravel and react-fancy for the pages (both labs have them).
Testing
node --test "council/test/*.test.mjs" # detector: a must-fire and a must-not-fire repo per class
vendor/bin/pest # ledger: hermetic, no network, a fake petition transport
php tests/lint.php
License
MIT

