Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/agent/specs/2026-10-29-2038-guardian-package/meta.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
id: 2026-10-29-2038-guardian-package
title: 'Guardian package'
status: in-review
status: closed
created: '2026-10-29 20:38'
standards:
refactor-circus/standards:
Expand Down
58 changes: 58 additions & 0 deletions docs/agent/specs/2026-10-29-2038-guardian-package/post-mortem.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Post-mortem: Guardian package (2026-10-29-2038-guardian-package)

## Summary

Guardian is a new package that takes SSO and SCIM out of Roster, with the same behaviour apart from the accepted renames. The factory run `wf_e98c383c-d71` was approved in round 2 on 2026-10-30. PR: Refactor-Circus/Guardian#1. The build ran as seven task groups, then one review round, then a "Group 7" follow-up. The final gate was 546 Pest tests, PHPStan clean, Pint clean and 100% type coverage.

Most of the cost came from groups that needed retries or salvage, and from one Roster-boundary violation (criterion 9) that review round 1 found. No human PR comments or ticket comments exist for this job.

## Metrics

- Rounds: 2 (the run history records `approved` at round 2).
- Task groups: 7. Groups 1 to 4 were retried or salvaged, and group 5 and group 6 each started from earlier attempts' commits.
- Review round 1 findings that were fixed: 1 major (architecture/dependencies, criterion 9) and 2 minor (architecture/service-providers). The re-run of all four reviewers (code, compat, security, standards) passed with nits only.
- Nits that did not start a round: 4 from the standards reviewer, 1 from the security reviewer.
- Decisions: 22 recorded in `decisions.md` (D-020 to D-041; earlier ids are in `shape.md`). Spec review accepted all recommendations. Five came up during build or review: D-037 and D-038 (build, group 2), D-039 (security review), D-040 (code review) and D-041 (standards review).
- Deviations recorded in `build.md`: about 12. They include the `rosterPresent()` public method, `ScimException::$status` visibility, the HandoverPending suite using a stand-in Roster, and `Permissions::forgetCache()` in place of the spec's `forget()`.
- Final test count: 546 passed, 2043 assertions. Type coverage: 100%.
- Not run locally: the `standalone`, `without-atrium`, `mysql` and browser CI jobs.

## What went well

- The spec review (`spec-review.md` round 1) closed many testability gaps early. These included a pinned Roster SHA (`6b1833d`), a moved-tests manifest (`tests/moved-tests.json`) with a case-count test, and literal config defaults. Later groups moved Roster's tests by diffing against that SHA.
- Cross-spec decisions (D-020 to D-022) fixed the Atrium `conflict`, the config-malformation rule and the Roster handover gate before the build started.
- Each group's retry re-checked its work against Roster's sources and did not rewrite it. Group 4's retry caught the Keen symlink that someone had re-linked by hand to an unmerged job branch.
- The gate mapped all 31 criteria to test files. Four reviewers passed on the re-run.
- Security review checked SCIM bearer auth, OIDC verification, injection and bulk limits. It also drove the real behaviour change D-039 (OIDC requires `email_verified`). D-039 shipped with tests (`OidcEmailVerifiedTest`) and a "Changed from Roster" note in the docs, held there by `DocsTest`.

## What cost rounds

- **Boundary violation (round 1 major).** After groups 1 to 6, the implementation still named Roster classes that criterion 9 denies: `ManagesMemberships`, `Support\CaseInsensitive` and `Domains\User\Resources\UserSummaryResource`. The fix added `Domains\Sso\Concerns\JoinsOrganizations`, `ScimQuery::equals()` and Guardian's own `UserSummaryResource`, and widened `RosterBoundaryTest` to cover Roster's `Concerns`, `Resources` and `Support` classes. Until then the arch rule and grep test had missed these classes.
- **Salvage and retry churn.** Groups 1 to 4 were recorded as "already committed, retry changed no code" or "salvaged". Earlier agents left uncommitted work (group 2) or committed it unverified (groups 3 and 4). Group 4 then needed five fixes: a fatal readonly redeclare of `ScimException::$status`, the wrong audit surface (`http` instead of `scim`), a ten-tool test that read the wrong entry points, a stale route-name lookup, and a test asserting an entry Roster never wrote.
- **Roster moving underneath the build.** The linked Roster (`remove-sso-and-scim`) no longer ships SSO and SCIM. Group 5's run showed 26 failures and 18 skips, so group 6 rebuilt fixtures (`tests/Fixtures/roster-sso-scim/`, `tests/Fixtures/roster-6b1833d/`) and changed Group 2 to 4 tests. The spec said to run Roster's own migrations and models, which stopped being possible. Criteria 22 and 28 were met with stand-ins.
- **Late decisions.** D-038 (the `guardian.ui.enabled` key Keystone requires), D-039 and D-040 were each found after the code was written. D-040 changed migration `down()` semantics and four tests.
- **Environment drift.** The Keen symlink was hand-edited, so `PackageWiringTest` failed in group 4's retry. Group 5 could not run the browser suite because `composer update` was off limits.

## Root causes

1. `spec_gap` (criteria 9 and 22, D-024/D-036): The spec said "deny Roster's internal bases and its Atrium/HTTP/MCP layers" but did not list `Concerns`, `Resources` or `Support\*` classes. The first arch test covered only some of the denied namespaces, so three violations got through six groups. Evidence: `build.md` "Review round 1 fixes", `RosterBoundaryTest` widened.
2. `spec_gap` (criteria 22 and 28): The spec assumed the linked Roster would still ship SSO and SCIM for the real-migration and real-`Handover` tests. It did not, and the build recorded two deviations. Evidence: `build.md` Group 6 "Deviations".
3. `spec_gap` (criterion 6, D-038): Keystone's `registerAtriumPlugin()` needs `guardian.ui.enabled`, which criterion 6's key list omitted. Evidence: `build.md` Group 2 "Left" and D-038.
4. `spec_gap` (D-039, D-040): The OIDC `email_verified` gap and the `down()` check scope were not settled in the spec. Both surfaced only in review.
5. `implementer_error`: Group 4's five defects (readonly redeclare, surface registration, test wiring) and group 3's missing organization scope on the connection-created audit entry and unrun Pint. All were fixed within the build, but they came from unverified salvaged commits.
6. `tooling`: Interrupted agents left uncommitted or unverified work in groups 2 to 4 (salvaged and retried). The hand-relinked `vendor/refactor-circus/keen` symlink broke `PackageWiringTest`. The browser dependency could not be installed in the worktree. The salvage and gate steps did not catch either.
7. `standards_gap`: `actions-events.md` says read actions have no events, while Keystone's `Arch::actionEventGaps()` requires a pair on every action (D-041). The standards disagree with each other. Standards-feedback rows were also needed for `booting()` provider registration, the `JoinsOrganizations` departure and the second user summary serializer.
8. `reviewer_noise`: None significant. The four standards nits did not start a round. The gate noted scaffold leftovers as non-blocking, although the code review said they were deleted. That note looks stale, not an actual problem.

## What human review caught

Nothing. The record has no PR review comments and no ticket comments, so no human-found gap can be shown. See `human_review_delta`.

## Proposed follow-ups

- Standards: align `actions-events.md` with `Arch::actionEventGaps()` on read actions (D-041).
- Spec template: when a spec limits another package's API, require a full denied-namespace list (including `Concerns`, `Resources`, `Support\*`) and write the arch test in group 1.
- Spec template: when a spec depends on a sibling branch that another job is changing, such as Roster `remove-sso-and-scim`, pin its fixtures from the start. Do not rely on the live checkout.
- Factory: commit or discard partial work when a group's agent is interrupted. Run the group's tests plus Pint before a salvaged commit counts as done.
- Gate: add a check that `vendor/` sibling symlinks match `composer.local.lock`. Run the browser, `standalone`, `without-atrium` and `mysql` jobs, or record that they are unverified.
- Small items: make `Sso` final, cast `max_payload_bytes`, and give `SsoLoginRefused` a `forX()` named constructor. Re-check the Roster-comparison fixtures once Roster `remove-sso-and-scim` is tagged. Then add the Roster `conflict` entry (D-027) and remove `Handover` and the coexistence tests.
5 changes: 5 additions & 0 deletions docs/agent/specs/2026-10-29-2038-guardian-package/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -348,3 +348,8 @@ Both are recorded in `docs/agent/standards-feedback.md` (workspace root) by the
- D-038: `config/guardian.php` gains `ui.enabled` (default `true`); `GuardianPlugin` registers through Keystone's `registerAtriumPlugin()` behind `atriumInstalled()` (amends criterion 6 and group 5).
- D-039: OIDC sign-in refuses to link an existing account by email or create one just-in-time unless the id_token's `email_verified` claim is `true`; the refusal is a `SsoLoginRefused` with its own reason, documented in README and CHANGELOG as a change from Roster. SAML is unchanged.
- D-040: each create migration's `down()` checks only the tables it drops (amends criterion 21).

## Addendum 2026-10-30 (v0.1.0 release)

- Criterion 1: with the suite's first tagged release, Guardian requires `refactor-circus/keystone: ^0.1`, and develops against Roster, Atrium and Keen `^0.1` (Ringside and Standards stay `dev-main`). `laravel/mcp` is `^1.1` in `require-dev`, because the tool snapshots carry the title annotation 1.1 added.
- Criterion 28: Roster's seams branch merged, and Roster `remove-sso-and-scim` shipped with Roster v0.1.0, so Roster `^0.1` no longer carries its own SSO and SCIM. Coexistence was proven against the seams branch before merge; from v0.1.0 on, Guardian's suite runs with handover complete against Roster `^0.1`.
98 changes: 98 additions & 0 deletions docs/agent/standards-proposals/global/actions/actions-events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
key: actions/actions-events
action: amend
kind: architectural
package: refactor-circus/standards
from_spec: 2026-10-29-2038-guardian-package
status: queued
evidence:
- "/Users/jay/Projects/packages/Guardian--2026-10-29-2038-guardian-package-record/docs/agent/specs/2026-10-29-2038-guardian-package/decisions.md D-041"
- "/Users/jay/Projects/packages/Guardian--2026-10-29-2038-guardian-package-record/docs/agent/standards-feedback.md row actions/actions-events (read actions dispatch starting/finished events)"
- "/Users/jay/Projects/packages/Guardian--2026-10-29-2038-guardian-package-record/docs/agent/specs/2026-10-29-2038-guardian-package/round-1/review-standards.md: 'Decision for the user: read actions ... dispatch event pairs, which actions-events.md says they should not' and the nit 'SsoWebController dispatches SsoLoginFailedActionEvent itself ... outside the action'"
- "/Users/jay/Projects/packages/Keystone/src/Testing/Arch.php actionEventGaps() requires starting and finished events on every scanned file"
- "post-mortem root cause standards_gap (D-041)"
---

## Rationale

The standard contradicts the tool that enforces it. It says read actions have no events, but Keystone's Arch::actionEventGaps() scans every action file and requires a starting and a finished event, with no exception for reads. Roster's actions and Guardian's moved List*/Show* actions already dispatch the pair. The user decided to keep the events (D-041), which left a standards-feedback row and a review decision. This amendment makes the standard match the code and the arch rule. A review nit found a controller dispatching an action's failed event outside the action, so the amendment also says only the action dispatches its events.

## Proposed text

# Actions & Events

Actions hold business logic. Each one announces itself with an event pair: one event when it starts and, after the data is committed, one when it finishes. Read actions do this too.

## Entry point: `execute()` calls a protected `handle()`

- Actions live in their domain's `Actions/` and are named `{Verb}{Entity}Action`; see [[domain-modules]] and [[naming]].
- Callers call `execute()`. The action implements a **`protected handle(...)`** that `execute()` delegates to. Never make `handle()` public: a single entry point leaves a place to add cross-cutting behavior later.
- No static constructors (`::run()`/`::make()`). Resolve through the container: `app(XAction::class)->execute(...)`.
- Input is an `{Action}Data` object, never an array; see [[data-objects]]. Bound models arrive as further `handle()` parameters.

```php
final class Create{Entity}Action extends Action
{
protected function handle(Create{Entity}Data $data, ?Model $owner = null): {Entity}Model
{
{Entity}CreatingActionEvent::dispatch($data, $owner);

${entity} = $this->perform($data, $owner);

{Entity}CreatedActionEvent::dispatch(${entity});

return ${entity};
}

private function perform(Create{Entity}Data $data, ?Model $owner): {Entity}Model
{
return DB::transaction(fn (): {Entity}Model => {Entity}Model::query()->create([...]));
}
}
```

## Signatures

- **Always a concrete return type, never `mixed`.** Create and update return the model, delete returns `void`, and list returns a paginator or collection.

## Read actions

- Read actions (`List{Entities}Action`, `Show{Entity}Action`) open no transaction, but they still dispatch the pair: `{Entities}ListingActionEvent` with the input and `{Entities}ListedActionEvent` with the result. Audit trails and listeners see every action the same way, and one arch rule covers them all.

```php
protected function handle(List{Entities}Data $data): LengthAwarePaginator
{
{Entities}ListingActionEvent::dispatch($data);

$page = {Entity}Model::query()->paginate($data->perPage);

{Entities}ListedActionEvent::dispatch($page);

return $page;
}
```

## Transactions & events

- `handle()` dispatches the **starting** event with the input, calls a private `perform()`, dispatches the **finished** event with the result, and returns that result.
- Every write in a mutating `perform()` goes inside `DB::transaction()`, even a single write.
- Finished events dispatch after commit (`ShouldDispatchAfterCommit`). They wait for the outermost transaction and never fire on rollback. An action that throws fires its starting event and no finished event.
- Only the action dispatches its events. Controllers, requests and tools never dispatch an action's event themselves.
- When a caller needs column values after the commit, `return $model->refresh();` **outside** the transaction.

## Dependency injection

- **Do not constructor-inject the model**: pass it through `handle()`. Constructor promotion is only for injected services.

## Events

- Events are `final` classes in the domain's `Events/`, using `Dispatchable` and `SerializesModels`, with no base class. Each is a plain data carrier with promoted constructor properties and may carry more than one value.
- Every action, read or write, has exactly one pair: a starting `{Entity}{Verb-ing}ActionEvent` that carries the input and a finished `{Entity}{Verb-ed}ActionEvent` that carries the result, for example `{Entity}SavingActionEvent` / `{Entity}SavedActionEvent`.
- Action events are distinct from model lifecycle events. Use action events for business logic by default; see [[lifecycle-events]].

## Reference implementation (Refactor Circus)

- Actions extend `RefactorCircus\Keystone\Actions\Action`, whose `execute(mixed ...$args)` forwards to `handle()`.
- Starting events implement `Keystone\Contracts\ActionStartingEvent`. Finished events implement `Keystone\Contracts\ActionFinishedEvent`, which extends `ShouldDispatchAfterCommit`.
- `tests/ArchTest.php` enforces the pairing on every action file, read actions included (`Arch::actionEventGaps()`). It also enforces that writes happen only inside a transaction (`Arch::writesOutsideTransactions()`) and that `handle()` takes no array parameter; see [[arch-tests]].

Loading
Loading