@event4u/agent-config 1.12.0 → 1.14.0

package/.agent-src/commands/quality-fix.md

@@ -3,6 +3,10 @@ name: quality-fix
 skills: [quality-tools]
 description: Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix the quality errors, run PHPStan and fix issues, fix code style"
+  trigger_context: "PHPStan/Rector/ECS output in recent tool results"
 ---
 
 # quality-fix

package/.agent-src/commands/refine-ticket.md

@@ -3,6 +3,10 @@ name: refine-ticket
 skills: [refine-ticket]
 description: Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates validate-feature-fit and threat-modeling, ends with a close-prompt
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "refine PROJ-123, tighten the acceptance criteria, is this ticket clear"
+  trigger_context: "ticket key in prompt with vague acceptance criteria"
 ---
 
 # refine-ticket
@@ -78,4 +82,3 @@ persona voices) plus the close-prompt. Stop there. Do **not** chain into
 - [`jira-ticket`](jira-ticket.md) — ticket loader this command delegates to
 - [`estimate-ticket`](estimate-ticket.md) — sibling command — run after refining if you also need sizing
 - [`feature-plan`](feature-plan.md), [`feature-explore`](feature-explore.md) — downstream commands
-- [`road-to-ticket-refinement.md`](../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap

package/.agent-src/commands/review-changes.md

@@ -3,6 +3,10 @@ name: review-changes
 skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality]
 description: Self-review local changes before creating a PR — dispatches to four specialized judges (bug, security, tests, quality) and consolidates verdicts
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "self-review my changes, judge this diff before PR"
+  trigger_context: "uncommitted or staged changes pre-PR"
 ---
 
 # review-changes

package/.agent-src/commands/review-routing.md

@@ -3,6 +3,10 @@ name: review-routing
 skills: [review-routing, reviewer-awareness, review-routing-awareness]
 description: Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "who should review this, suggest reviewers for this PR"
+  trigger_context: "PR open without assigned reviewers"
 ---
 
 # review-routing

package/.agent-src/commands/roadmap-create.md

@@ -3,6 +3,10 @@ name: roadmap-create
 skills: [agent-docs-writing]
 description: Interactively create a new roadmap file in agents/roadmaps/
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create a roadmap for X, plan this work as a roadmap"
+  trigger_context: "multi-phase work without an existing agents/roadmaps/*.md"
 ---
 
 # roadmap-create
@@ -110,6 +114,9 @@ If yes → switch to the `roadmap-execute` command workflow with the newly creat
 
 - **Do NOT auto-generate content** — always ask the user for input.
 - **Do NOT commit or push.**
+- **Do NOT include commit steps** unless user explicitly requested them.
+  See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
+  Roadmaps plan **work**; commits are a separate delivery decision.
 - **Write the roadmap in English** (per project convention for `.md` files).
 - Follow the roadmap template from `.augment/templates/roadmaps.md`.
 - Keep the file focused: 500–1000 lines max. If larger, suggest splitting.

package/.agent-src/commands/roadmap-execute.md

@@ -3,6 +3,10 @@ name: roadmap-execute
 skills: [agent-docs-writing]
 description: Read and interactively execute a roadmap from agents/roadmaps/
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "execute the roadmap, work through the roadmap step by step"
+  trigger_context: "existing agents/roadmaps/*.md referenced in the prompt"
 ---
 
 # roadmap-execute
@@ -61,7 +65,14 @@ For each open step:
 
 ### Rules
 
-- **Do NOT commit or push** — only apply local changes and update the roadmap file.
+- **Commits per [`commit-policy`](../rules/commit-policy.md).** Default: only
+  apply local changes and update the roadmap file — no commits.
+  - Roadmap **without** commit steps → never commit, never ask.
+  - Roadmap **with** commit steps:
+    - **Non-autonomous** (`autonomy: off`, or `auto` before opt-in) → ask before each.
+    - **Autonomous** (`autonomy: on`, or `auto` after opt-in) → pre-scan **before
+      starting**, ask **once** upfront, then proceed silently per the answer.
+- **Push, merge, branch, PR, tag** stay permission-gated by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
 - **Always ask before implementing** a step — never auto-execute.
 - **Run quality checks** after each code change.
 - If a step is unclear or too large, suggest breaking it down further.

package/.agent-src/commands/rule-compliance-audit.md

@@ -2,6 +2,10 @@
 name: rule-compliance-audit
 description: Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "audit my rules, check rule trigger quality"
+  trigger_context: "maintainer working on .augment/rules/ files"
 ---
 
 # rule-compliance-audit

package/.agent-src/commands/set-cost-profile.md

@@ -3,6 +3,9 @@ name: set-cost-profile
 description: Change the cost_profile in .agent-settings.yml — shows each profile's meaning and applies the selection
 skills: [file-editor]
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Settings mutation — must be deliberate."
 ---
 
 # /set-cost-profile

package/.agent-src/commands/sync-agent-settings.md

@@ -2,6 +2,9 @@
 name: sync-agent-settings
 description: Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Settings sync — must be deliberate."
 ---
 
 # /sync-agent-settings

package/.agent-src/commands/sync-gitignore.md

@@ -2,6 +2,9 @@
 name: sync-gitignore
 description: Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Settings sync — must be deliberate."
 ---
 
 # /sync-gitignore

package/.agent-src/commands/tests-create.md

@@ -3,6 +3,10 @@ name: tests-create
 skills: [pest-testing]
 description: Write meaningful tests for the changes in the current branch
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "write tests for these changes, add tests for this branch"
+  trigger_context: "code changes on the branch without matching test changes"
 ---
 
 # tests-create

package/.agent-src/commands/tests-execute.md

@@ -3,6 +3,10 @@ name: tests-execute
 skills: [pest-testing]
 description: Run PHP tests inside the Docker container
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "run the tests, execute the test suite"
+  trigger_context: "code changes pending verification"
 ---
 
 # tests-execute

package/.agent-src/commands/threat-model.md

@@ -3,6 +3,10 @@ name: threat-model
 skills: [threat-modeling, authz-review, security-sensitive-stop]
 description: Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and authorization gaps before the first line of code is written
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "threat model this change, what could go wrong security-wise"
+  trigger_context: "changes touching auth, webhooks, uploads, secrets, or public endpoints"
 ---
 
 # threat-model

package/.agent-src/commands/update-form-request-messages.md

@@ -3,6 +3,10 @@ name: update-form-request-messages
 skills: [laravel-validation]
 description: Sync the messages() method of a FormRequest class — add missing entries, link them to language keys, and clean up stale ones
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "sync the form request messages, update the validation messages"
+  trigger_context: "edits to app/Http/Requests/*.php referencing rules without messages"
 ---
 
 # update-form-request-messages

package/.agent-src/commands/upstream-contribute.md

@@ -3,6 +3,10 @@ name: upstream-contribute
 skills: [upstream-contribute, skill-writing, learning-to-rule-or-skill]
 description: Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "contribute this back to agent-config, upstream this learning"
+  trigger_context: "project-local skill/rule that fits the shared package"
 ---
 
 # /upstream-contribute

package/.agent-src/commands/work.md

@@ -0,0 +1,161 @@
+---
+name: work
+skills: [refine-prompt, command-routing]
+description: Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "build this, implement this, drive this end-to-end"
+  trigger_context: "free-form prompt without a ticket key"
+---
+
+# work
+
+## Instructions
+
+### 1. Resolve the prompt
+
+`/work` accepts the user's request as a free-form prompt. Resolve the
+input in this order:
+
+1. **Inline argument** — `/work <prompt>` (everything after the verb is
+   the prompt; quoting is not required).
+2. **Pasted block** — markdown block under the command in the same turn.
+3. **No input** — ask once, with numbered options:
+
+   ```
+   > 1. I'll type the prompt now — paste it on the next line
+   > 2. Load from a file — give me a path
+   > 3. Abort — never mind
+   ```
+
+   On `1`, wait for the user. On `2`, ask for the path and read it. On
+   `3`, stop.
+
+Strip leading/trailing whitespace at the boundary, but preserve casing
+and internal spacing — the scorer reads the original text when grading
+goal clarity.
+
+### 2. Prepare the state file
+
+The engine persists everything in `.work-state.json` (same envelope as
+`/implement-ticket`, different `input.kind`). Two cases, in this order:
+
+- **Resume** — `.work-state.json` exists with `input.kind="prompt"`. Do
+  not pass `--prompt-file` or `--persona`; mid-flight switches are
+  refused by the engine.
+- **Fresh run** — no state file. Write the resolved prompt to
+  `prompt.txt` (raw text, single file, UTF-8) and pass it via
+  `--prompt-file prompt.txt`. Honour `roles.active_role` from
+  `.agent-settings.yml` via `--persona`.
+
+If a `.work-state.json` exists but carries a ticket envelope
+(`input.kind="ticket"`), that's an `/implement-ticket` flow in
+progress. Stop and ask:
+
+```
+> A ticket-flow state file is already in `.work-state.json`. Pick one:
+> 1. Resume the ticket flow — re-run /implement-ticket
+> 2. Discard it — delete the state file and start /work fresh
+> 3. Abort
+```
+
+### 3. Drive the Option-A dispatch loop
+
+Run the engine with the state file on every iteration:
+
+```bash
+./agent-config work \
+    --state-file .work-state.json \
+    [--prompt-file prompt.txt --persona <name>]   # first call only
+```
+
+The dispatcher wires `PYTHONPATH` and routes to the engine module
+internally. `./agent-config` is the only supported entry point in
+consumer repos — do not call the engine module directly.
+
+Branch on the exit code:
+
+| Exit | Meaning | Action |
+|---|---|---|
+| `0` | SUCCESS — final report on stdout | Go to step 5 |
+| `1` | BLOCKED — halt surface on stdout, state persisted | Inspect `questions[0]` |
+| `2` | Config/IO error | Surface the stderr message to the user, stop |
+
+On exit `1`, look at the first line after `[halt] outcome=… step=…`:
+
+- **Starts with `@agent-directive: refine-prompt`** — invoke the
+  [`refine-prompt`](../skills/refine-prompt/SKILL.md) skill against
+  `state.input.data.raw`, write the resulting `reconstructed_ac` and
+  `assumptions` arrays back onto `state.input.data`, then re-run.
+- **Starts with `@agent-directive:` (other verbs)** — see §4.
+- **Starts with `>`** — user question per
+  [`user-interaction`](../rules/user-interaction.md). Emit verbatim,
+  wait for the user, write their answer back onto `state.input.data`
+  (or the matching slice), then re-run. Never guess.
+
+### 4. Confidence-band semantics
+
+The engine's `refine` step scores the reconstructed envelope and routes
+on the resulting band. Never attempt to flip the band yourself — the
+engine owns the verdict.
+
+| Band | Outcome | What the agent does |
+|---|---|---|
+| `high` | SUCCESS | Engine proceeds silently; the breakdown lands on `state.input.data.confidence` and is included in the delivery report |
+| `medium` | PARTIAL halt | Engine emits the assumptions report; surface verbatim, wait for the user. On confirm, write `state.input.data.confidence_confirmed=true` and re-run. On refine, replace `state.input.data.raw` with the new prompt, clear `reconstructed_ac` + `assumptions`, and re-run |
+| `low` | BLOCKED halt | Engine emits exactly one clarifying question on the weakest dimension (per [`ask-when-uncertain`](../rules/ask-when-uncertain.md) Iron Law). Surface verbatim, wait for the user, append their answer to `state.input.data.raw`, clear `reconstructed_ac` + `assumptions`, and re-run |
+
+Once the gate releases, the rest of the loop is identical to
+`/implement-ticket`: `create-plan`, `apply-plan`, `run-tests`,
+`review-changes` directives flow through the same dispatch table.
+
+### 5. Final report + close-prompt
+
+On exit `0`, the engine prints the delivery report. Surface it
+unchanged, then append:
+
+```
+> 1. /commit — stage + commit per the delivery report
+> 2. /create-pr — open a pull request from this branch
+> 3. Keep working — I'll hold the state file for the next /work
+> 4. Discard — delete .work-state.json
+```
+
+Per [`scope-control`](../rules/scope-control.md), git operations are
+permission-gated. Never run `/commit` or `/create-pr` without the user
+choosing them.
+
+### Rules
+
+- Honour [`scope-control`](../rules/scope-control.md),
+  [`minimal-safe-diff`](../rules/minimal-safe-diff.md), and
+  [`verify-before-complete`](../rules/verify-before-complete.md) inside
+  every directive.
+- Never bypass the engine. Don't skip steps, don't rewrite outcomes,
+  don't flip `confidence_confirmed` without the user's explicit OK.
+- The low-band halt emits **one** question. If you find yourself
+  surfacing two, you reformatted the engine output — stop and surface
+  it verbatim.
+- Persona is session-global. Read it from `.agent-settings.yml` on the
+  fresh run; never accept a `--persona` flag from the user mid-flight.
+- When `telemetry.artifact_engagement.enabled: true` in
+  `.agent-settings.yml`, emit one `./agent-config telemetry:record` per
+  boundary (per phase-step or per task — see `granularity`) with the
+  consulted+applied artefact ids. Full contract in
+  [`artifact-engagement-recording`](../rules/artifact-engagement-recording.md).
+  Default-off; absent setting is a silent no-op.
+
+## Examples
+
+```
+/work fix the failing login test under tests/feature/auth
+/work                                # asks for the prompt
+/work add a CSV export endpoint to the audit-log controller
+```
+
+## See also
+
+- [`refine-prompt`](../skills/refine-prompt/SKILL.md) — fills `reconstructed_ac` + `assumptions` on the rebound from the first-pass halt
+- [`implement-ticket`](implement-ticket.md) — sibling command for ticket-shaped input; same engine, different envelope
+- [`commit`](commit.md), [`create-pr`](create-pr.md) — post-delivery commands the user runs explicitly

package/.agent-src/guidelines/agent-infra/engineering-memory-data-format.md

@@ -16,9 +16,8 @@ matching the existing pattern established by `review-routing-data-format`.
 ## File locations
 
 Each schema lives under `agents/memory/<type>/<hash>.yml` (content-addressed,
-merge-safe — see [`road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md))
-**or** in a single `agents/memory/<type>.yml` file for projects that prefer
-one file per type.
+merge-safe) **or** in a single `agents/memory/<type>.yml` file for projects
+that prefer one file per type.
 
 | Type | Single-file path | Sharded path |
 |---|---|---|
@@ -111,7 +110,4 @@ active — the report is informational, not a gate.
 
 ## See also
 
-- [`road-to-engineering-memory.md`](../../../agents/roadmaps/road-to-engineering-memory.md) — roadmap this guideline implements
-- [`road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md) — why content-addressed files
 - [`review-routing-data-format.md`](review-routing-data-format.md) — sibling format for ownership + bug patterns
-- [`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md) — role modes that consume these files

package/.agent-src/guidelines/agent-infra/layered-settings.md

@@ -198,4 +198,3 @@ the next explicit settings edit.
 
 - [`agent-settings.md`](../../templates/agent-settings.md) — dev-layer schema
 - [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml) — team-layer template
-- [`road-to-project-memory.md`](../../../agents/roadmaps/road-to-project-memory.md) — roadmap this guideline implements

package/.agent-src/guidelines/agent-infra/memory-access.md

@@ -9,11 +9,6 @@ package adapter (when present). The status helper
 `scripts/memory_status.py` decides which path to take and caches the
 result for the session.
 
-Referenced by
-[`road-to-agent-memory-integration.md`](../../../agents/roadmaps/road-to-agent-memory-integration.md)
-Phase 0. The retrieval contract itself lives in
-[`agent-memory/road-to-retrieval-contract.md`](../../../agents/roadmaps/agent-memory/road-to-retrieval-contract.md).
-
 ## The contract
 
 ```python
@@ -117,5 +112,3 @@ Other types remain accessible on demand via
   — the on-disk schema
 - [`../../rules/context-hygiene.md`](../../rules/context-hygiene.md)
   — token budget that `max_entries_per_task` protects
-- [`../../../agents/roadmaps/road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md)
-  — why intake is append-only JSONL with `merge=union`

package/.agent-src/guidelines/agent-infra/role-contracts.md

@@ -117,9 +117,8 @@ do not pretend verification happened.
 ## Structured mode markers
 
 Every contract output MUST begin with a one-line HTML comment so
-session captures, log scrapers, and the measurement hook in
-[`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md#phase-4--measurement-hook-closes-q2-of-master-frame)
-can count contract-conformant outputs per mode:
+session captures, log scrapers, and the measurement hook can count
+contract-conformant outputs per mode:
 
 ```
 <!-- role-mode: developer | contract: goal,plan,changes,tests,open-questions -->
@@ -206,6 +205,5 @@ finding. See the Q4 rule in `road-to-personas.md`.
 
 ## See also
 
-- [`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md) — roadmap this guideline implements
 - [`output-patterns.md`](output-patterns.md) — generic output conventions modes inherit
 - [`agent-interaction-and-decision-quality.md`](agent-interaction-and-decision-quality.md) — how modes interact with the numbered-options protocol

package/.agent-src/guidelines/agent-infra/self-improvement-pipeline.md

@@ -129,7 +129,6 @@ unreviewed upstream changes is not.
 
 ## See also
 
-- [`road-to-curated-self-improvement.md`](../../../agents/roadmaps/road-to-curated-self-improvement.md) — roadmap this guideline implements
 - [`proposal.example.md`](../../templates/agents/proposal.example.md) — the template every proposal derives from
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — Understand → Research → Draft sequence used inside Stage 3
 - [`preservation-guard`](../../rules/preservation-guard.md) — invoked by the gate to check replacement proposals

package/.agent-src/guidelines/php/patterns/strategy.md

@@ -15,6 +15,25 @@ Select the implementation based on context (config, user input, enum value).
 - Notification channels (Email, SMS, Push)
 - Import parsers (JSON, XML, CSV)
 
+## Sniff test — when an enum/string discriminator wants to become a Strategy
+
+Run these three questions **before** writing a second `match`/`switch` arm,
+a second `if/elseif` branch, or a second hardcoded class per provider/type.
+Two "yes" answers → extract Strategy + Registry. Three "yes" → it is
+already overdue.
+
+1. **Same-shape branches?** Do two or more branches/classes implement the
+   *same operation* on the *same data*, differing only in provider-specific
+   details (URL, field mapping, credentials, response parsing)?
+2. **Closed-list edits?** Adding a new case requires editing an enum, a
+   `match` block, an allowlist constant, *and* a service class — i.e. the
+   change is mechanical but spans ≥3 files?
+3. **Discriminator leakage?** Does the discriminator (`Type::FOO`,
+   `'stripe'`, an `is_csv()` check) appear in ≥3 places that should not
+   have to know about `FOO` specifically?
+
+If yes → see *Refactoring recipe* below.
+
 ## Example
 
 ```php
@@ -62,8 +81,167 @@ enum DiscountType: string
 }
 ```
 
+## Refactoring recipe — from discriminator to Strategy
+
+Two anti-patterns appear in real codebases and both refactor into the same
+Strategy + Registry shape. Each step is a separate commit so reviewers can
+follow the safety chain.
+
+### Sub-pattern A — *hardcoded single provider per class*
+
+Each provider gets its own `FooImportService`, `FooJob`, `FooCommand`,
+and every method body repeats `Provider::FOO->value` or
+`Provider::FOO->getId()`. Adding a new provider means copy-pasting an
+entire class tree.
+
+```php
+// Before — one class per provider, discriminator hardcoded.
+final class StripeImportService
+{
+    public function id(): int     { return Provider::STRIPE->getId(); }
+    public function name(): string { return Provider::STRIPE->value; }
+    public function import(): void { /* Stripe-specific logic */ }
+}
+
+final class PaypalImportService
+{
+    public function id(): int     { return Provider::PAYPAL->getId(); }
+    public function name(): string { return Provider::PAYPAL->value; }
+    public function import(): void { /* PayPal-specific logic */ }
+}
+```
+
+```php
+// After — one interface, N strategies, one registry.
+interface ImportStrategy
+{
+    public function provider(): Provider;
+    public function import(): void;
+}
+
+final class StripeImport implements ImportStrategy
+{
+    public function provider(): Provider { return Provider::STRIPE; }
+    public function import(): void       { /* Stripe-specific logic */ }
+}
+// ...PaypalImport implements ImportStrategy similarly.
+```
+
+Recipe (one commit per step):
+
+1. Extract the interface (`ImportStrategy`) and move one provider class
+   to implement it. Existing call sites keep using the old class.
+2. Repeat for the remaining providers — still no callers changed.
+3. Introduce the Registry (next section). Migrate call sites one by one
+   from `new StripeImportService()` to `$registry->for(Provider::STRIPE)`.
+4. Delete the old per-provider classes.
+
+### Sub-pattern B — *allowlist constant on a single coordinator*
+
+A central service holds an allowlist of supported discriminator values.
+Every new provider edits the constant *and* a method that branches on it.
+
+```php
+// Before — closed-list edit per new provider.
+final class EquipmentImportService
+{
+    private const FULL_SYNC_PROVIDERS = [
+        Provider::STRIPE,
+        Provider::PAYPAL,
+        Provider::INVOICE,
+    ];
+
+    public function supportsFullSync(Provider $p): bool
+    {
+        return in_array($p, self::FULL_SYNC_PROVIDERS, true);
+    }
+}
+```
+
+The fix is a **capability flag on the strategy interface** — the strategy
+declares its own capabilities, and the coordinator asks the strategy
+instead of consulting an allowlist.
+
+```php
+interface ImportStrategy
+{
+    public function provider(): Provider;
+    public function import(): void;
+    public function supportsFullSync(): bool;   // capability flag
+}
+```
+
+A new provider now adds itself by implementing the interface — no central
+list to edit, no in_array call to maintain. The coordinator becomes:
+
+```php
+$strategy = $registry->for($provider);
+if ($strategy->supportsFullSync()) {
+    $strategy->fullSync();
+}
+```
+
+## Registry companion
+
+A Registry resolves the discriminator → strategy lookup that previously
+lived in the `match` block. It owns the only place the enum is mapped to
+classes; everything downstream sees only the interface.
+
+```php
+final class ImportStrategyRegistry
+{
+    /** @var array<string, ImportStrategy> */
+    private array $byProvider;
+
+    /** @param iterable<ImportStrategy> $strategies */
+    public function __construct(iterable $strategies)
+    {
+        foreach ($strategies as $strategy) {
+            $this->byProvider[$strategy->provider()->value] = $strategy;
+        }
+    }
+
+    public function for(Provider $provider): ImportStrategy
+    {
+        return $this->byProvider[$provider->value]
+            ?? throw new InvalidArgumentException(
+                "No import strategy registered for {$provider->value}"
+            );
+    }
+}
+```
+
+Wire-up in Laravel — tag the strategies, inject the tag into the registry:
+
+```php
+// In a ServiceProvider::register()
+$this->app->tag([
+    StripeImport::class,
+    PaypalImport::class,
+    InvoiceImport::class,
+], 'import.strategies');
+
+$this->app->bind(
+    ImportStrategyRegistry::class,
+    fn ($app) => new ImportStrategyRegistry($app->tagged('import.strategies')),
+);
+```
+
+A new provider now adds itself by:
+
+1. Implementing `ImportStrategy`.
+2. Adding one line to the `tag()` call.
+
+No `match` block grows. No allowlist edits. No coordinator method changes.
+
 ## When NOT to Use
 
-❌ Only two cases with trivial logic — a simple `match` or ternary is enough
-❌ The "strategies" share no common interface or behavior
+❌ Only two cases with **trivial logic** — a simple `match` or ternary is
+   enough. *"Trivial"* means the two arms each fit on one line and share
+   no structural shape. Two arms that each call a method on a service
+   are not trivial — see the sniff test.
+❌ The "strategies" share no common interface or behavior — if the
+   operations differ, you do not have a Strategy candidate.
+❌ The discriminator is set once at boot and never re-evaluated — a
+   single binding in the container is simpler than a Registry.
 

package/.agent-src/personas/README.md

@@ -99,6 +99,5 @@ cast (usually Core-6 for review skills, empty for others).
 
 ## Related
 
-- [`../../agents/roadmaps/archive/road-to-personas.md`](../../agents/roadmaps/archive/road-to-personas.md) — roadmap + rationale (shipped 2026-04-22)
 - [`../guidelines/agent-infra/role-contracts.md`](../guidelines/agent-infra/role-contracts.md) — workflow modes personas compose with
 - [`../rules/artifact-drafting-protocol.md`](../rules/artifact-drafting-protocol.md) — mandatory per new persona

package/.agent-src/rules/artifact-drafting-protocol.md

@@ -39,8 +39,13 @@ If the user skips Q1 or Q5, stop and surface the ambiguity — don't guess.
 
 ## Phase B — Research
 
-Scan `.agent-src.uncompressed/` for overlap. Report the top 3-5
-most-similar artifacts and ask (numbered options):
+Run the **search protocol** from
+[`learning-to-rule-or-skill` § 4](../skills/learning-to-rule-or-skill/SKILL.md#4-check-for-overlap--search-protocol-mandatory)
+— `ls` all four surfaces (`skills/`, `rules/`, `guidelines/`, `commands/`),
+grep with **solution-words AND problem-words**, scan sub-directory
+taxonomies, then **open and skim** the 3 nearest matches. A negative grep
+alone is not proof of no overlap. Report the top 3-5 most-similar
+artifacts and ask (numbered options):
 
 - Extend an existing one?
 - Create a new one — gap is real?