@cratis/pi 7.88.0 → 7.90.0

package/package/corpus/harnesses/copilot/instructions/ai-distribution.instructions.md

@@ -90,10 +90,9 @@ Cratis behavior. The `engineering-` prefix identifies the maintainer audience;
 it does not imply confidential package contents or a private registry.
 
 The consuming repository owns its project facts, confidential behavior, local
-skills, and minimal host bootstraps. Use repository-owned documentation as canonical
-project context when that migration is active, `.agents/skills/` for private or
-repository-specific local workflows, and repository-owned documentation only as the
-documented legacy context fallback. Never merge, overwrite, or remove these
+skills, and minimal host bootstraps. Project-specific context is the repository's own
+documentation plus `.cratis/ai/rules/project.md`; `.agents/skills/` holds private or
+repository-specific local workflows. Never merge, overwrite, or remove these
 local files as a side effect of installing, updating, rolling back, or
 uninstalling shared AI capabilities.
 

package/package/corpus/harnesses/copilot/instructions/authoring-skills.instructions.md

@@ -85,7 +85,9 @@ When changing a description, run trigger evaluations before and after when autho
 
 ## 11. Always-on content
 
-Keep `general.md` to facts needed in every session, at most 200 lines. Warn above 24,000 bytes and above 91,000 combined bytes for rules without `paths`; line length alone can hide context bloat. Review globally applied Copilot instructions above 4,000 characters. These budgets leave room for source and task context, rather than promising a token count.
+Keep `general.md` to facts needed in every session, at most 200 lines. Warn above 24,000 bytes and above 91,000 combined bytes for rules without `paths`; line length alone can hide context bloat. Review globally applied Copilot instructions above 4,000 characters. These budgets leave room for source and task context, rather than promising a token count. The corpus verification caps the rule bytes each harness loads at session start and fails above a cap: displace or demote text to an on-demand skill, or raise the cap in a reviewed change.
+
+Every proposed rule names its enforcement: analyzer-enforceable, CI-enforceable or judgment-shaped. The first two ship as the analyzer, lint or CI check, with at most a one-line pointer in prose; only judgment-shaped rules are written out, because prose does not enforce itself and costs context in every session that loads it.
 
 Use path-scoped rules for file-specific invariants and skills for particular operations. Hooks and CI enforce mechanical constraints; natural-language rules do not replace permission controls.
 

package/package/corpus/harnesses/copilot/instructions/frontend-quality.instructions.md

@@ -36,6 +36,7 @@ Stop-and-fix signals during implementation and review:
 | A reusable component reaches into domain strings, generated proxies, identity, query, command, or navigation | It is no longer a primitive | Move it to the slice, or make it explicitly Cratis-aware and test/story it as such |
 | Class/style string copied 3× or grown hard to scan | Styling changes become search-and-replace bugs | Extract to a shared style constant or a focused child component |
 | `style={{ ... }}` with static token names | Bypasses theming and review | Move to `className`; keep `style` only for runtime values |
+| A domain constant, threshold or eligibility rule in a `.ts`/`.tsx` file (`canApprove`, `maxAttempts = 2`) deciding whether an action shows | The client re-derives what the server knows, so the two drift and the UI breaks silently | Project the affordance as a read-model property server-side and render it. Judgment-shaped; no gate |
 
 ## Definition of done for a frontend change
 

package/package/corpus/harnesses/copilot/instructions/profiles.instructions.md

@@ -200,6 +200,7 @@ language policy always follows the consuming repository's `go.mod` minimum.
 | `cratis/content` | Release notes, social feed posts, voice review, content length, and developer marketing and distribution |
 | `cratis/review` | Code review, performance, security |
 | `cratis/codescene` | Opt-in CodeScene Code Health change gates, refactoring, debt prioritization and risk-based testing; requires an account and available MCP tools; each user registers the MCP server (see below) |
+| `cratis/playwright` | Opt-in Playwright browser automation MCP server declaration for exploratory checks; carries no skills or rules and each user registers the server (see below) |
 | `cratis/studio` | Studio MCP safety guidance |
 | `cratis/cli` | CLI operations |
 | `cratis/cli/terminal-workbench` | Human-operated terminal Workbench |
@@ -227,6 +228,27 @@ CodeScene needs an account and OAuth `login`; without an account or available
 CodeScene tools, skip its steps and say so rather than blocking contributors.
 The MCP catalog has no install-hints field and does not install the executable.
 
+### Browser automation with Playwright
+
+Select `cratis/playwright` explicitly to declare the `playwright` stdio server
+(`npx -y @playwright/mcp@0.0.83 --headless --isolated`) in `mcp-servers.json`.
+The flags keep the browser headless and isolated: no persistent profile, so no
+personal cookies or logins are reused. The profile carries no skills or rules, and
+no other profile composes it.
+
+Today `cratis ai install` registers only Screenplay and Pi's `cratis-mcp` extension
+loads only Screenplay, so Playwright, like CodeScene, is not registered for you.
+Each user registers it in their own user-level MCP configuration, never in committed
+project files. For Claude Code:
+
+```bash
+claude mcp add --scope user playwright -- npx -y @playwright/mcp@0.0.83 --headless --isolated
+```
+
+Pi users register it through a Pi MCP adapter or extension of their choice. Use it
+for exploratory browser checks; repeatable checks stay in the repository's own
+Playwright tests. Without the server registered, skip browser steps and say so.
+
 ### Event modeling with Screenplay
 
 **Model first.** Decide opt-in per `general.md` "Model first"; where `cratis-screenplay-modeling-lifecycle` is installed, run its `scripts/model-first-status.mjs` for the decision, model root and drafts. An accepted model under the root covering the scope is the contract and the source

package/package/corpus/harnesses/copilot/instructions/reactors.instructions.md

@@ -228,6 +228,8 @@ findings). Each reactor class should have a focused purpose. Multiple handler me
 7. **No state** — Reactors should be stateless. Inject dependencies via primary constructor, but do not store mutable state on the class.
 8. **A new side-effect reactor must not act on history.** A reactor that is new in a release (or has a new id) catches up from the start of the event log when it first registers, and `[OnceOnly]` does not cover that first catch-up because it is not a replay. If its handlers cause side effects (jobs, AI calls, external calls, notifications), start the observer at the tail on first registration or make the handler ignore facts that predate its registration, and specify that history causes nothing.
 9. **An unattended, irreversible pass reads the log, not the sink — and carries a fuse.** A reactor that deletes, revokes, bills or notifies *because a read model says something is absent* is trusting a materialized sink that is only as current as its observer: a paused partition, a replay in progress or a lagging projection makes "absent" true of the sink and false of the world. Decide from a **`[Passive]`** read model (computed on demand from the events at the moment the reactor runs) or from the events themselves. And the code shape cannot tell an **empty subject set** ("nothing to consider" — fail-safe) from an **empty qualifying set** ("nothing survived the filter" — fail-destructive: every subject is about to be acted on), so an unattended pass states its expected population, refuses when the count is implausible, and caps how many subjects one run may touch — the same discipline as [guards-and-fuses.md](./guards-and-fuses.instructions.md), applied to a reactor. A sweep that decides from a read model also refuses while that model's observer is replaying or behind, because a rebuilding model reads as "nothing was ever processed"; specify the replaying case.
+10. **Provider clients stay behind a translation or adapter reactor.** A `[Command]` or `IReactor` in a domain slice that injects or imports a provider client (GitHub, payment, mail SDK) is a finding: put the client behind one adapter slice and let domain slices work with our events and commands. Judgment-shaped today; a candidate for a namespace-boundary analyzer.
+11. **A reactor must not react to its own consequences.** A reactor that posts comments or creates artifacts must guard against re-triggering on what it created (marker, author check, or event-type filter), or one input loops. Judgment-shaped; no gate.
 
 ## Failure transitions **[convention]**
 

package/package/corpus/harnesses/copilot/instructions/vertical-slices.instructions.md

@@ -245,6 +245,7 @@ Apply authorization attributes on the `[Command]` record or query method. **[con
 - **Events are not read models** — never append events for totals, counts, statuses, search indexes, or dashboards. Project those from source events into read models.
 - **Never duplicate one fact as an aggregate event *plus* a per-item fanout.** If a command fans out per item (one `RequestSentToPartner` per partner), don't also emit an aggregate event carrying the whole list. Keep the fanout as the single source of truth and project any aggregate from it; pick per-item vs. single-with-list event from how consumers read it — never both.
 - **Command rejection normally appends no event.** Validation and business-rule rejections are command results, not facts. Add a rejection/failed event only when the business must audit or react to that failure later.
+- **A settings event records the decision, not the whole blob.** Split composite configuration into one event per concern; a whole-object `…Set` event is last-writer-wins CRUD and turns every new field into a schema change. The tell is a `…Set`/`…Updated` event carrying a full settings record. Judgment-shaped; no gate.
 - **One event name = one meaning.** Don't reuse a vague event for several domain facts; if facts can occur, be absent, or have consumers independently, split them into separate event types.
 - **Never persist clock-relative state.** "Overdue", "expired", "due in 3 days" are true *now* and false later, and a projection only moves when an event arrives — so a projected `IsOverdue` is wrong the moment the clock crosses the line with no event to flip it. Store the **deadline** (a `DateOnly`/`DateTimeOffset` the business supplied) and compute the comparison at the query or UI edge, refreshing when time alone changes the answer. Only when *crossing* the deadline is itself a business fact (a fee is charged, a reminder goes out) does a scheduled process append an event for it.
 
@@ -308,6 +309,8 @@ query reference for versioned behavior and composition trade-offs.
 
 Ladder, first that fits: (1) direct read-model injection — guarded under read protection `On`, advisory under `Off`; keyed by the command's own event-source id, or by `[LookUpBy]`; (2) a `[Passive]` projection; (3) `IReadModels.GetInstanceById<T>((EventSourceId)key)` for a different/derived key; (4) a materialized projection. A lookup *interface* is justified **only** for a genuine non-key search (e.g. find-by-email) — never to wrap a keyed `GetInstanceById`.
 
+**[convention] One read model per consumer scenario, and dispatch never reads a UI model.** When a second consumer needs different semantics (board vs list vs count vs control flow), add a projection instead of extending the existing model; a command, reactor or job deciding what to do reads a model built for that decision, never a screen's listing model. The tell is a read model many slices import or one that projects many unrelated slices. Judgment-shaped; no gate.
+
 **[contract] Passive state is not sink state.** `IMongoCollection<T>` cannot
 compute a passive read model; any leftover documents are not maintained state.
 Read through Chronicle by key or supported injection. **[convention]** Never
@@ -420,6 +423,10 @@ Redaction is a system-event request that removes payload availability from the e
 
 Cross-slice access is **read-only and goes through Chronicle** — inject another slice's read model (validator/`Provide()`/`Handle()`), read by explicit key with `IReadModels.GetInstanceById`, mark a `[Passive]` projection for a current read (a rule that must hold under concurrency needs read protection `On`, a stream decision or a constraint, see the `cratis-chronicle-decision-reads` skill's `references/choosing-how-a-rule-holds.md`), or react to its events. **Never** instantiate or DI another slice's command/handler/service.
 
+**[convention] Prompts are content.** In an AI-backed feature, keep prompt bodies as resources (embedded files/templates) assembled by a typed composer, not as string literals in classes; the tell is a class dominated by multi-line prompt text. Judgment-shaped; no gate.
+
+**[convention] The third copy of a job shape is the deadline for the abstraction.** Two similar jobs or decision flows are fine; when a third appears, extract the shared template instead of copying again. Judgment-shaped; no gate.
+
 **DCB (Dynamic Consistency Boundary):** the boundary is the event state explicitly
 enrolled in guarded decisions, not every model a command reads. Use stream
 reads/exact scopes or read-model parameters under read protection `On`

package/package/corpus/mcp-servers.json

@@ -16,6 +16,14 @@
       "command": "cs-mcp",
       "args": [],
       "description": "Review Code Health changes and prioritize maintainability risks with CodeScene; requires a CodeScene account and OAuth login."
+    },
+    {
+      "id": "playwright",
+      "profiles": ["cratis/playwright"],
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@0.0.83", "--headless", "--isolated"],
+      "description": "Drive a headless, isolated browser with Playwright for exploratory checks; requires Node.js and downloads the package and a browser on first use."
     }
   ]
 }

package/package/corpus/rules/ai-distribution.md

@@ -89,10 +89,9 @@ Cratis behavior. The `engineering-` prefix identifies the maintainer audience;
 it does not imply confidential package contents or a private registry.
 
 The consuming repository owns its project facts, confidential behavior, local
-skills, and minimal host bootstraps. Use repository-owned documentation as canonical
-project context when that migration is active, `.agents/skills/` for private or
-repository-specific local workflows, and repository-owned documentation only as the
-documented legacy context fallback. Never merge, overwrite, or remove these
+skills, and minimal host bootstraps. Project-specific context is the repository's own
+documentation plus `.cratis/ai/rules/project.md`; `.agents/skills/` holds private or
+repository-specific local workflows. Never merge, overwrite, or remove these
 local files as a side effect of installing, updating, rolling back, or
 uninstalling shared AI capabilities.
 

package/package/corpus/rules/authoring-skills.md

@@ -84,7 +84,9 @@ When changing a description, run trigger evaluations before and after when autho
 
 ## 11. Always-on content
 
-Keep `general.md` to facts needed in every session, at most 200 lines. Warn above 24,000 bytes and above 91,000 combined bytes for rules without `paths`; line length alone can hide context bloat. Review globally applied Copilot instructions above 4,000 characters. These budgets leave room for source and task context, rather than promising a token count.
+Keep `general.md` to facts needed in every session, at most 200 lines. Warn above 24,000 bytes and above 91,000 combined bytes for rules without `paths`; line length alone can hide context bloat. Review globally applied Copilot instructions above 4,000 characters. These budgets leave room for source and task context, rather than promising a token count. The corpus verification caps the rule bytes each harness loads at session start and fails above a cap: displace or demote text to an on-demand skill, or raise the cap in a reviewed change.
+
+Every proposed rule names its enforcement: analyzer-enforceable, CI-enforceable or judgment-shaped. The first two ship as the analyzer, lint or CI check, with at most a one-line pointer in prose; only judgment-shaped rules are written out, because prose does not enforce itself and costs context in every session that loads it.
 
 Use path-scoped rules for file-specific invariants and skills for particular operations. Hooks and CI enforce mechanical constraints; natural-language rules do not replace permission controls.
 

package/package/corpus/rules/frontend-quality.md

@@ -35,6 +35,7 @@ Stop-and-fix signals during implementation and review:
 | A reusable component reaches into domain strings, generated proxies, identity, query, command, or navigation | It is no longer a primitive | Move it to the slice, or make it explicitly Cratis-aware and test/story it as such |
 | Class/style string copied 3× or grown hard to scan | Styling changes become search-and-replace bugs | Extract to a shared style constant or a focused child component |
 | `style={{ ... }}` with static token names | Bypasses theming and review | Move to `className`; keep `style` only for runtime values |
+| A domain constant, threshold or eligibility rule in a `.ts`/`.tsx` file (`canApprove`, `maxAttempts = 2`) deciding whether an action shows | The client re-derives what the server knows, so the two drift and the UI breaks silently | Project the affordance as a read-model property server-side and render it. Judgment-shaped; no gate |
 
 ## Definition of done for a frontend change
 

package/package/corpus/rules/general.md

@@ -47,10 +47,8 @@ repository. Individual projects need extra context that does not belong here,
 such as product composition, approved environment names, directions for
 obtaining credentials, and other local conventions ("Product policy" above).
 
-- Read repository-owned documentation as the canonical project-specific context when it
-  exists.
-- Read repository-owned documentation only as the documented legacy fallback when
-  repository-owned documentation does not exist; never merge both contexts.
+- Project-specific context is the repository's own documentation plus
+  `.cratis/ai/rules/project.md`.
 - Project context may explain which approved secret mechanism or local setup to
   use, but it must never contain credential values, tokens, keys, passwords, or
   other secrets.

package/package/corpus/rules/profiles.md

@@ -199,6 +199,7 @@ language policy always follows the consuming repository's `go.mod` minimum.
 | `cratis/content` | Release notes, social feed posts, voice review, content length, and developer marketing and distribution |
 | `cratis/review` | Code review, performance, security |
 | `cratis/codescene` | Opt-in CodeScene Code Health change gates, refactoring, debt prioritization and risk-based testing; requires an account and available MCP tools; each user registers the MCP server (see below) |
+| `cratis/playwright` | Opt-in Playwright browser automation MCP server declaration for exploratory checks; carries no skills or rules and each user registers the server (see below) |
 | `cratis/studio` | Studio MCP safety guidance |
 | `cratis/cli` | CLI operations |
 | `cratis/cli/terminal-workbench` | Human-operated terminal Workbench |
@@ -226,6 +227,27 @@ CodeScene needs an account and OAuth `login`; without an account or available
 CodeScene tools, skip its steps and say so rather than blocking contributors.
 The MCP catalog has no install-hints field and does not install the executable.
 
+### Browser automation with Playwright
+
+Select `cratis/playwright` explicitly to declare the `playwright` stdio server
+(`npx -y @playwright/mcp@0.0.83 --headless --isolated`) in `mcp-servers.json`.
+The flags keep the browser headless and isolated: no persistent profile, so no
+personal cookies or logins are reused. The profile carries no skills or rules, and
+no other profile composes it.
+
+Today `cratis ai install` registers only Screenplay and Pi's `cratis-mcp` extension
+loads only Screenplay, so Playwright, like CodeScene, is not registered for you.
+Each user registers it in their own user-level MCP configuration, never in committed
+project files. For Claude Code:
+
+```bash
+claude mcp add --scope user playwright -- npx -y @playwright/mcp@0.0.83 --headless --isolated
+```
+
+Pi users register it through a Pi MCP adapter or extension of their choice. Use it
+for exploratory browser checks; repeatable checks stay in the repository's own
+Playwright tests. Without the server registered, skip browser steps and say so.
+
 ### Event modeling with Screenplay
 
 **Model first.** Decide opt-in per `general.md` "Model first"; where `cratis-screenplay-modeling-lifecycle` is installed, run its `scripts/model-first-status.mjs` for the decision, model root and drafts. An accepted model under the root covering the scope is the contract and the source

package/package/corpus/rules/reactors.md

@@ -227,6 +227,8 @@ findings). Each reactor class should have a focused purpose. Multiple handler me
 7. **No state** — Reactors should be stateless. Inject dependencies via primary constructor, but do not store mutable state on the class.
 8. **A new side-effect reactor must not act on history.** A reactor that is new in a release (or has a new id) catches up from the start of the event log when it first registers, and `[OnceOnly]` does not cover that first catch-up because it is not a replay. If its handlers cause side effects (jobs, AI calls, external calls, notifications), start the observer at the tail on first registration or make the handler ignore facts that predate its registration, and specify that history causes nothing.
 9. **An unattended, irreversible pass reads the log, not the sink — and carries a fuse.** A reactor that deletes, revokes, bills or notifies *because a read model says something is absent* is trusting a materialized sink that is only as current as its observer: a paused partition, a replay in progress or a lagging projection makes "absent" true of the sink and false of the world. Decide from a **`[Passive]`** read model (computed on demand from the events at the moment the reactor runs) or from the events themselves. And the code shape cannot tell an **empty subject set** ("nothing to consider" — fail-safe) from an **empty qualifying set** ("nothing survived the filter" — fail-destructive: every subject is about to be acted on), so an unattended pass states its expected population, refuses when the count is implausible, and caps how many subjects one run may touch — the same discipline as [guards-and-fuses.md](./guards-and-fuses.md), applied to a reactor. A sweep that decides from a read model also refuses while that model's observer is replaying or behind, because a rebuilding model reads as "nothing was ever processed"; specify the replaying case.
+10. **Provider clients stay behind a translation or adapter reactor.** A `[Command]` or `IReactor` in a domain slice that injects or imports a provider client (GitHub, payment, mail SDK) is a finding: put the client behind one adapter slice and let domain slices work with our events and commands. Judgment-shaped today; a candidate for a namespace-boundary analyzer.
+11. **A reactor must not react to its own consequences.** A reactor that posts comments or creates artifacts must guard against re-triggering on what it created (marker, author check, or event-type filter), or one input loops. Judgment-shaped; no gate.
 
 ## Failure transitions **[convention]**
 

package/package/corpus/rules/vertical-slices.md

@@ -244,6 +244,7 @@ Apply authorization attributes on the `[Command]` record or query method. **[con
 - **Events are not read models** — never append events for totals, counts, statuses, search indexes, or dashboards. Project those from source events into read models.
 - **Never duplicate one fact as an aggregate event *plus* a per-item fanout.** If a command fans out per item (one `RequestSentToPartner` per partner), don't also emit an aggregate event carrying the whole list. Keep the fanout as the single source of truth and project any aggregate from it; pick per-item vs. single-with-list event from how consumers read it — never both.
 - **Command rejection normally appends no event.** Validation and business-rule rejections are command results, not facts. Add a rejection/failed event only when the business must audit or react to that failure later.
+- **A settings event records the decision, not the whole blob.** Split composite configuration into one event per concern; a whole-object `…Set` event is last-writer-wins CRUD and turns every new field into a schema change. The tell is a `…Set`/`…Updated` event carrying a full settings record. Judgment-shaped; no gate.
 - **One event name = one meaning.** Don't reuse a vague event for several domain facts; if facts can occur, be absent, or have consumers independently, split them into separate event types.
 - **Never persist clock-relative state.** "Overdue", "expired", "due in 3 days" are true *now* and false later, and a projection only moves when an event arrives — so a projected `IsOverdue` is wrong the moment the clock crosses the line with no event to flip it. Store the **deadline** (a `DateOnly`/`DateTimeOffset` the business supplied) and compute the comparison at the query or UI edge, refreshing when time alone changes the answer. Only when *crossing* the deadline is itself a business fact (a fee is charged, a reminder goes out) does a scheduled process append an event for it.
 
@@ -307,6 +308,8 @@ query reference for versioned behavior and composition trade-offs.
 
 Ladder, first that fits: (1) direct read-model injection — guarded under read protection `On`, advisory under `Off`; keyed by the command's own event-source id, or by `[LookUpBy]`; (2) a `[Passive]` projection; (3) `IReadModels.GetInstanceById<T>((EventSourceId)key)` for a different/derived key; (4) a materialized projection. A lookup *interface* is justified **only** for a genuine non-key search (e.g. find-by-email) — never to wrap a keyed `GetInstanceById`.
 
+**[convention] One read model per consumer scenario, and dispatch never reads a UI model.** When a second consumer needs different semantics (board vs list vs count vs control flow), add a projection instead of extending the existing model; a command, reactor or job deciding what to do reads a model built for that decision, never a screen's listing model. The tell is a read model many slices import or one that projects many unrelated slices. Judgment-shaped; no gate.
+
 **[contract] Passive state is not sink state.** `IMongoCollection<T>` cannot
 compute a passive read model; any leftover documents are not maintained state.
 Read through Chronicle by key or supported injection. **[convention]** Never
@@ -419,6 +422,10 @@ Redaction is a system-event request that removes payload availability from the e
 
 Cross-slice access is **read-only and goes through Chronicle** — inject another slice's read model (validator/`Provide()`/`Handle()`), read by explicit key with `IReadModels.GetInstanceById`, mark a `[Passive]` projection for a current read (a rule that must hold under concurrency needs read protection `On`, a stream decision or a constraint, see the `cratis-chronicle-decision-reads` skill's `references/choosing-how-a-rule-holds.md`), or react to its events. **Never** instantiate or DI another slice's command/handler/service.
 
+**[convention] Prompts are content.** In an AI-backed feature, keep prompt bodies as resources (embedded files/templates) assembled by a typed composer, not as string literals in classes; the tell is a class dominated by multi-line prompt text. Judgment-shaped; no gate.
+
+**[convention] The third copy of a job shape is the deadline for the abstraction.** Two similar jobs or decision flows are fine; when a third appears, extract the shared template instead of copying again. Judgment-shaped; no gate.
+
 **DCB (Dynamic Consistency Boundary):** the boundary is the event state explicitly
 enrolled in guarded decisions, not every model a command reads. Use stream
 reads/exact scopes or read-model parameters under read protection `On`

package/package/corpus/skills/cratis-engineering-regression-cluster/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.

package/package/corpus/skills/cratis-engineering-regression-cluster/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: cratis-engineering-regression-cluster
+description: Stop fixing instances when one surface keeps breaking - name the failure class, add the gate that owns it, prove the gate fails, then fix the instance. Use when a third bug, regression, revert or review finding lands on the same screen, endpoint, command, workflow or module, when the same kind of fix keeps being reapplied, or when asked why something keeps breaking. Not for a first or isolated bug (fix it with a regression specification), for proving a consolidation dropped nothing (use cratis-engineering-consolidation-guard), or for a boundary that reports success after failing (use cratis-engineering-effect-boundaries).
+license: LICENSE
+---
+
+# The third issue on one surface names a failure class
+
+Each bug fixed alone adds one specification for one symptom. When the same
+**surface** (one screen, endpoint, command, query, workflow, module or rule
+area) breaks a third time, the instances share a cause that no specification
+owns yet, and the fourth instance is already on its way. Stop fixing instances:
+name the **failure class**, give it an **owning gate**, then fix the instance.
+
+## Count first
+
+Before fixing an issue, count the earlier ones on its surface:
+
+```bash
+gh issue list --state all --search "<surface> in:title,body" --limit 50
+git log --oneline -- <paths of the surface>
+```
+
+Count bugs, regressions, reverts and review findings, open or closed. Fewer
+than three: fix the instance with a regression specification. Three or more:
+follow the steps below before writing the fix.
+
+## Steps
+
+1. **Name the failure class** in one sentence that states the property being
+   violated, not the symptom. Each earlier issue must be an instance of it, and
+   a reader must be able to recognize the next one by it. "Owner filter shows
+   archived items" is a symptom; "list filters are not exercised through the
+   rendered list by any test" is a class.
+2. **Choose the owning gate by enforcement kind**, preferring the earliest that
+   can catch the class: an analyzer (compile time), a lint rule, a CI check or
+   verification script, or one specification suite that covers every member of
+   the class (every filter, every endpoint), not one specification per bug. A
+   class that only judgment can catch gets a review checklist entry, and the
+   choice is stated as judgment-shaped; see the enforcement rule in
+   [authoring-skills.md](../../rules/authoring-skills.md).
+3. **Prove the gate fails** on the current broken instance, or on the earlier
+   instances with their fixes reverted, before fixing anything. A gate that
+   passes on the broken code owns nothing; follow
+   [guards-and-fuses.md](../../rules/guards-and-fuses.md) so it cannot pass
+   vacuously.
+4. **Register the class.** When the repository keeps a failure-class table or
+   gate inventory, add one row: class, owning gate, where it runs. Otherwise
+   put the class name in the gate's failure message and the specification or
+   check name, so the next failure names its class.
+5. **Fix the instance**; the gate turns green. Run it with the repository's
+   normal gates, and make it a required CI check when it lives in CI.
+6. **Close the loop.** Link the earlier issues to the class in the pull request
+   comment, and leave a prose rule only for the judgment-shaped part.
+
+## Report
+
+State the surface and the issues counted, the class sentence, the gate and
+where it runs, that it failed before the fix and passes after, and anything
+left judgment-shaped.
+
+## Pitfalls
+
+- **A fourth instance specification.** Copying the third fix's specification
+  for the new symptom covers the symptom, not the class.
+- **A prose rule instead of a gate.** Rules nobody enforces were already in
+  place for the earlier instances; text costs context and catches nothing.
+- **A class named after the symptom.** If the next instance would not be
+  recognized by the sentence, the class is still too narrow.
+- **A gate that never ran red.** Without the failing run, nothing shows it can
+  catch the class.
+- **A loose surface.** Three unrelated bugs in one large module are not a
+  cluster; narrow the surface until the issues share a cause.

package/package/profile-catalog.json

@@ -629,6 +629,13 @@
         "language-agnostic"
       ]
     },
+    {
+      "id": "cratis/playwright",
+      "availableTargets": [],
+      "languages": [
+        "language-agnostic"
+      ]
+    },
     {
       "id": "cratis/components",
       "availableTargets": [
@@ -986,6 +993,7 @@
         "cratis-engineering-decision-record",
         "cratis-engineering-docs-authoring",
         "cratis-engineering-effect-boundaries",
+        "cratis-engineering-regression-cluster",
         "cratis-release-notes",
         "cratis-technical-examples"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.88.0",
+  "version": "7.90.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [