@event4u/agent-config 9.8.0 → 9.10.0

package/dist/agent-src/skills/judge-synthesis/SKILL.md

@@ -11,28 +11,39 @@ packs:
 
 # judge-synthesis
 
-> The **synthesizer** across an already-run set of judges. Does **not** run or
-> re-judge — **consumes** their verdict blocks and produces one structured
-> report: a side-by-side verdict table, **consensus** findings (≥2 judges =
-> highest confidence), **conflicts** (judges disagree), and a synthesized
+> You are the **synthesizer** across an already-run set of judges. You do **not**
+> run the judges and you do **not** re-judge — you **consume** their emitted
+> verdict blocks and produce one structured report: a side-by-side verdict
+> table, the **consensus** findings (flagged by ≥2 judges = highest confidence),
+> the **conflicts** (judges that disagree), and a synthesized
 > **must-fix / should-fix / advisory** split with per-finding judge provenance.
 > No opaque single score. Never auto-gates — the human decides.
 
 ## When to use
 
-* Two+ judges ran on the same target; their verdict blocks need to become one decision-ready report.
-* A **mixed** review spanning code judges + artifact/defence judges (PR shipping a roadmap + code + an injection fixture) — no single command consolidates across all seven lenses.
-* `/review-changes` step 5 wants the canonical synthesis format instead of an ad-hoc merge.
+* Two or more judges have run on the same target and their verdict blocks need
+  to become one decision-ready report.
+* A **mixed** review spanning code judges + the artifact/defence judges (e.g. a
+  PR that ships a roadmap + code + an injection-defense fixture) — no single
+  existing command consolidates across all seven lenses.
+* `/review-changes` step 5 (consolidation) wants the canonical synthesis format
+  instead of an ad-hoc merge.
 
 Do NOT use when:
 
-* Only one judge ran — nothing to synthesize; surface that block directly.
-* You need to **produce** a verdict — that is the individual judge's job ([`judge-bug-hunter`](../judge-bug-hunter/SKILL.md), [`judge-artifact-completeness`](../judge-artifact-completeness/SKILL.md), [`judge-injection-defense`](../judge-injection-defense/SKILL.md)).
-* You are tempted to compute a single quality number — forbidden (Do NOT).
+* Only one judge ran — there is nothing to synthesize; surface that judge's
+  block directly.
+* You need to **produce** a verdict — that is the individual judge's job
+  ([`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),
+  [`judge-artifact-completeness`](../judge-artifact-completeness/SKILL.md),
+  [`judge-injection-defense`](../judge-injection-defense/SKILL.md), etc.).
+* You are tempted to compute a single quality number — forbidden (see Do NOT).
 
 ## Inputs
 
-The verdict blocks judges already emit (judge name + verdict + findings with severity). Three verdict vocabularies map onto one ordered axis:
+The verdict blocks the judges already emit. Each carries at minimum a judge
+name, a verdict, and zero or more findings with a severity. The three verdict
+vocabularies in the suite map onto one ordered severity axis:
 
 | Judge family | Verdict vocabulary |
 |---|---|
@@ -46,32 +57,49 @@ Ordered worst→best: **`reject`/`incomplete`/`breached` > `revise`/`partial` >
 
 ### 1. Inspect the inputs and tabulate
 
-Check ≥2 judge verdict blocks are present (only one → stop, nothing to synthesize). Tabulate one row per judge: judge · target · verdict · finding count. Preserve each judge's own verdict word (don't normalise `breached` into `reject`); add a severity tier (worst/mid/clean) only as a sort key.
+First check that ≥2 judge verdict blocks are present (if only one, stop — nothing
+to synthesize). Then tabulate one row per judge: judge · target · verdict ·
+finding count. Preserve each
+judge's own verdict word (do not normalise away `breached` into `reject`); add a
+severity tier (worst/mid/clean) only as a sort key.
 
 ### 2. Find consensus (highest confidence)
 
-A finding flagged by **≥2 judges** (same file:line / dimension / technique) is a **consensus finding** — highest confidence. List first. By overlap of the finding, never by counting votes for a score.
+A finding flagged by **≥2 judges** (same file:line / same dimension / same
+technique) is a **consensus finding** — the highest-confidence item. List these
+first. Consensus is by overlap of the finding, never by counting votes for a
+score.
 
 ### 3. Find conflicts
 
-Two judges with opposite verdicts on one target (one `apply`, another `reject`) is a **conflict**. **Surface both verdicts + the disagreement explicitly — never silently resolve by averaging or vote-count.** Human adjudicates. Only deterministic rule: for the **must-fix list**, the most severe verdict wins (one `reject` → must-fix even if four said `apply`) — but the conflict is still shown.
+Two judges reaching opposite verdicts on the same target (one `apply`, another
+`reject`) is a **conflict**. **Surface both verdicts and the disagreement
+explicitly — never silently resolve it by averaging or vote-count.** The human
+adjudicates. The only deterministic rule: for the **must-fix list**, the most
+severe verdict wins (a single `reject` puts the target in must-fix even if four
+judges said `apply`) — but the conflict is still shown so the human sees it was
+contested.
 
 ### 4. Synthesize the action split
 
-- **Must-fix** — every worst-tier (`reject`/`incomplete`/`breached`) finding + every highest-severity consensus finding.
-- **Should-fix** — mid-tier (`revise`/`partial`) findings.
+- **Must-fix** — every finding from a worst-tier verdict (`reject` / `incomplete`
+  / `breached`) + every consensus finding at the highest severity.
+- **Should-fix** — mid-tier (`revise` / `partial`) findings.
 - **Advisory** — single-judge low-severity suggestions.
 
-Each entry carries **provenance** (which judge(s) raised it). Never merge two judges' findings into one unattributed line.
+Each entry carries **provenance**: which judge(s) raised it. Never merge two
+judges' findings into one unattributed line.
 
 ### 5. Overall recommendation
 
-One sentence, not a number: `block` (any worst-tier), `revise` (any mid-tier, no worst-tier), or `proceed` (all clean). A recommendation the human acts on — it does not gate.
+One sentence, not a number: `block` (any worst-tier verdict), `revise` (any
+mid-tier, no worst-tier), or `proceed` (all clean). This is a recommendation the
+human acts on — it does not gate anything.
 
 ## Validation
 
 1. Every judge that ran appears exactly once in the table.
-2. Every action entry names its source judge(s).
+2. Every must-fix/should-fix/advisory entry names its source judge(s).
 3. No single numeric quality score appears anywhere.
 4. Conflicts are shown, not silently resolved.
 5. The recommendation follows the severity rule (worst-tier → block), not a vote.
@@ -112,10 +140,15 @@ Required fields (ordered):
 
 ## Gotcha
 
-* **No opaque score** — the value is the *structure* (consensus + conflict + provenance), not a rolled-up number that hides which lens objected.
-* **Don't normalise verdict words away** — `breached` and `reject` sort the same but mean different things; keep each judge's own word.
-* **A single reject blocks** — even against a majority of `apply`; but show the conflict, never bury it.
-* **Consume, don't dispatch** — no judge blocks yet → stop, run the judges first (or hand back to `/review-changes`).
+* **No opaque score** — the value is the *structure* (consensus + conflict +
+  provenance), not a rolled-up number that hides which lens objected.
+* **Don't normalise verdict words away** — `breached` and `reject` sort the same
+  but mean different things; keep each judge's own word in the table.
+* **A single reject blocks** — even against a majority of `apply`; but show the
+  conflict so the human sees it was contested, never bury it.
+* **Consume, don't dispatch** — if no judge blocks exist yet, stop and run the
+  judges first (or hand back to `/review-changes`); synthesis has nothing to do
+  on empty input.
 * **Recommendation ≠ gate** — surface it; the human decides.
 
 ## Do NOT
@@ -128,8 +161,19 @@ Required fields (ordered):
 
 ## References
 
-- Code judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md), [`judge-code-quality`](../judge-code-quality/SKILL.md), [`judge-security-auditor`](../judge-security-auditor/SKILL.md), [`judge-test-coverage`](../judge-test-coverage/SKILL.md), [`architecture-review-lens`](../architecture-review-lens/SKILL.md).
-- Artifact / defence judges: [`judge-artifact-completeness`](../judge-artifact-completeness/SKILL.md), [`judge-injection-defense`](../judge-injection-defense/SKILL.md).
-- Dispatchers that feed this: [`/review-changes`](../../commands/review/changes.md) (5 code judges), [`subagent-orchestration`](../subagent-orchestration/SKILL.md) (parallel judge fan-out).
-- Cross-model review families (disambiguation): [`ai-council`](../ai-council/SKILL.md) (independent breadth), [`/team`](../../commands/team.md) (collaborative repo-access depth) — this skill consolidates in-session same-weights judges.
-- **LLM-as-a-Judge** — Zheng et al. (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685); the consolidation layer over the specialized-judge pattern, with consensus/conflict surfacing instead of a single aggregate score.
+- Code judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),
+  [`judge-code-quality`](../judge-code-quality/SKILL.md),
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
+  [`judge-test-coverage`](../judge-test-coverage/SKILL.md),
+  [`architecture-review-lens`](../architecture-review-lens/SKILL.md).
+- Artifact / defence judges: [`judge-artifact-completeness`](../judge-artifact-completeness/SKILL.md),
+  [`judge-injection-defense`](../judge-injection-defense/SKILL.md).
+- Dispatchers that feed this: [`/review-changes`](../../commands/review/changes.md)
+  (5 code judges), [`subagent-orchestration`](../subagent-orchestration/SKILL.md)
+  (parallel judge fan-out).
+- Cross-model review families (disambiguation): [`ai-council`](../ai-council/SKILL.md)
+  (independent breadth), [`/team`](../../commands/team.md) (collaborative repo-access
+  depth) — this skill consolidates in-session same-weights judges.
+- **LLM-as-a-Judge** — Zheng et al. (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685);
+  this skill is the consolidation layer over the specialized-judge pattern, with
+  consensus/conflict surfacing instead of a single aggregate score.

package/dist/agent-src/skills/laravel-horizon/SKILL.md

@@ -29,6 +29,11 @@ For **writing queue jobs** themselves, see [jobs-events](../jobs-events/SKILL.md
 
 ## Procedure: Configure Horizon
 
+1. **Inspect current queue setup** — Read `config/queue.php`, `config/horizon.php` (if present), and `composer.json` to identify the current driver, supervisors, and queues in use.
+2. **Pick environments and balance strategy** — Decide per-env `maxProcesses`, `balance`, `tries`, `timeout` based on workload; review the config block below.
+3. **Apply configuration** — Edit `config/horizon.php`, register supervisors and queue priority.
+4. **Verify** — Run `php artisan horizon` locally, hit `/horizon` dashboard, confirm jobs flow and metrics appear.
+
 ### config/horizon.php
 
 ```php

package/dist/agent-src/skills/laravel-mail/SKILL.md

@@ -29,10 +29,11 @@ Use Mailables when you need full control over the email template.
 
 ## Procedure: Create a Mailable
 
-1. **Generate class** — `php artisan make:mail InvoiceMail --markdown=emails.invoice`.
-2. **Configure** — Set subject, from, attachments, queuing (`ShouldQueue`).
-3. **Create template** — Markdown template in `resources/views/emails/`.
-4. **Verify** — Send test email, confirm rendering and delivery.
+1. **Inspect existing mailables** — Review `app/Mail/` for naming, base class, queueing convention, and the templates in `resources/views/emails/` for the project's markdown style.
+2. **Generate class** — `php artisan make:mail InvoiceMail --markdown=emails.invoice`.
+3. **Configure** — Set subject, from, attachments, queuing (`ShouldQueue`).
+4. **Create template** — Markdown template in `resources/views/emails/`.
+5. **Verify** — Send test email, confirm rendering and delivery.
 
 ### Example
 

package/dist/agent-src/skills/laravel-middleware/SKILL.md

@@ -26,10 +26,11 @@ Use this skill when working with HTTP middleware:
 
 ## Procedure: Create middleware
 
-1. **Generate class** — `php artisan make:middleware EnsureCustomerIsActive`.
-2. **Implement logic** — Handle request in `handle()`, return response or pass to next.
-3. **Register** — Add to route group or global middleware stack.
-4. **Verify** — Run tests covering both allowed and blocked request scenarios.
+1. **Inspect existing middleware** — Read `app/Http/Middleware/` and `bootstrap/app.php` (or `app/Http/Kernel.php`) to identify naming conventions, aliases, and current group/global registration.
+2. **Generate class** — `php artisan make:middleware EnsureCustomerIsActive`.
+3. **Implement logic** — Handle request in `handle()`, return response or pass to next.
+4. **Register** — Add to route group or global middleware stack.
+5. **Verify** — Run tests covering both allowed and blocked request scenarios.
 
 ### Example
 

package/dist/agent-src/skills/laravel-notifications/SKILL.md

@@ -19,7 +19,7 @@ install:
 ## When to use
 
 Use this skill when sending notifications to users or external systems:
-- Email, Slack, SMS, or DB notifications
+- Email, Slack, SMS, or database notifications
 - Custom notification channels
 - On-demand notifications (to non-user recipients)
 - Notification preferences and opt-out logic
@@ -28,11 +28,12 @@ For **Mailables** (complex email templates, attachments), see [laravel-mail](../
 
 ## Procedure: Create a notification
 
-1. **Generate class** — `php artisan make:notification InvoiceCreated`.
-2. **Choose channels** — Mail, DB, Slack, or custom. Implement `via()`.
-3. **Build content** — Implement `toMail()`, `toArray()`, etc. for each channel.
-4. **Queue it** — Add `ShouldQueue` interface for non-blocking delivery.
-5. **Verify** — Send test notification, confirm delivery on all channels.
+1. **Inspect existing notifications** — Read `app/Notifications/` and the notifiable models for current channels, queue defaults, and per-user preferences.
+2. **Generate class** — `php artisan make:notification InvoiceCreated`.
+3. **Choose channels** — Mail, database, Slack, or custom. Implement `via()`.
+4. **Build content** — Implement `toMail()`, `toArray()`, etc. for each channel.
+5. **Queue it** — Add `ShouldQueue` interface for non-blocking delivery.
+6. **Verify** — Send test notification, confirm delivery on all channels.
 
 ### Example
 
@@ -164,15 +165,15 @@ public function via(object $notifiable): array
 - Notifiable
 - MailMessage
 - SlackMessage
-- DB notification
+- database notification
 
 ## Gotcha
 
 - Don't send notifications synchronously in request lifecycle — always queue them.
-- The model forgets to implement `toArray()` for DB notifications — it throws silently.
+- The model forgets to implement `toArray()` for database notifications — it throws silently.
 - `via()` method must return an array even for a single channel — `return ['mail']`, not `return 'mail'`.
 
 ## Do NOT
 
-- Do NOT store large objects in DB notification `data` — use IDs and fetch on read.
+- Do NOT store large objects in database notification `data` — use IDs and fetch on read.
 - Do NOT use notifications for complex emails — use [Mailables](../laravel-mail/SKILL.md) instead.

package/dist/agent-src/skills/laravel-pennant/SKILL.md

@@ -186,7 +186,7 @@ Feature::for($users)->load(['new-dashboard', 'advanced-reporting']);
 
 ## Gotcha
 
-- Feature flags in DB driver require migration — don't forget `php artisan pennant:purge` for cleanup.
+- Feature flags in database driver require migration — don't forget `php artisan pennant:purge` for cleanup.
 - The model tends to check flags without a scope — always pass the authenticated user or a default scope.
 - Don't nest feature flag checks — it makes the logic impossible to reason about.
 

package/dist/agent-src/skills/laravel-pulse/SKILL.md

@@ -26,10 +26,11 @@ Use this skill when working with Laravel Pulse:
 
 ## Procedure: Set up Pulse
 
-1. **Install** — `composer require laravel/pulse`, publish config, run migrations.
-2. **Configure** — Set up recorders in `config/pulse.php`.
-3. **Add dashboard** — Register route and authorize access.
-4. **Verify** — Visit `/pulse` dashboard, confirm data is being recorded.
+1. **Inspect current monitoring** — Check `composer.json`, existing telemetry packages, and `config/` for Pulse, Telescope, or Horizon already installed; identify gaps.
+2. **Install** — `composer require laravel/pulse`, publish config, run migrations.
+3. **Configure** — Set up recorders in `config/pulse.php`.
+4. **Add dashboard** — Register route and authorize access.
+5. **Verify** — Visit `/pulse` dashboard, confirm data is being recorded.
 
 ### Installation
 
@@ -136,9 +137,9 @@ Pulse::record('api_call', 'stripe', 250)  // type, key, value
 
 ## Core rules
 
-- **Trim old data** — configure retention to prevent DB bloat.
+- **Trim old data** — configure retention to prevent database bloat.
 - **Use sample rates** in production — not every request needs recording.
-- **Separate DB** — consider a dedicated DB connection for Pulse data.
+- **Separate database** — consider a dedicated DB connection for Pulse data.
 - **Restrict access** — always gate the dashboard behind authentication.
 - **Monitor what matters** — don't enable all recorders if you don't need them.
 
@@ -158,7 +159,7 @@ Pulse::record('api_call', 'stripe', 250)  // type, key, value
 
 ## Gotcha
 
-- Pulse stores data in the same DB by default — configure a separate connection for production.
+- Pulse stores data in the same database by default — configure a separate connection for production.
 - The model forgets that Pulse data is sampled, not exact — don't use it for billing or exact counts.
 - Custom recorders must be registered in a service provider — they don't auto-discover.
 
@@ -167,4 +168,4 @@ Pulse::record('api_call', 'stripe', 250)  // type, key, value
 - Do NOT expose the Pulse dashboard without authentication.
 - Do NOT set sample rate to 1.0 on high-traffic production — use 0.1 or lower.
 - Do NOT forget to run `pulse:check` for server metrics.
-- Do NOT store Pulse data in the main application DB on large apps.
+- Do NOT store Pulse data in the main application database on large apps.

package/dist/agent-src/skills/laravel-reverb/SKILL.md

@@ -29,11 +29,12 @@ and Laravel Echo client setup, see the [laravel-websocket](../laravel-websocket/
 
 ## Procedure: Set up Reverb
 
-1. **Install** — `php artisan install:broadcasting` or manual setup (see below).
-2. **Configure** — Set environment variables for Reverb host, port, app credentials.
-3. **Start server** — `php artisan reverb:start`.
-4. **Connect client** — Configure Laravel Echo with Reverb credentials.
-5. **Verify** — Confirm WebSocket connection in browser console, test event delivery.
+1. **Inspect current broadcasting** — Check `config/broadcasting.php`, `.env`, and `composer.json` for Pusher / Reverb / Soketi presence and current driver.
+2. **Install** — `php artisan install:broadcasting` or manual setup (see below).
+3. **Configure** — Set environment variables for Reverb host, port, app credentials.
+4. **Start server** — `php artisan reverb:start`.
+5. **Connect client** — Configure Laravel Echo with Reverb credentials.
+6. **Verify** — Confirm WebSocket connection in browser console, test event delivery.
 
 Laravel Reverb is Laravel's first-party, blazing-fast WebSocket server. It uses the
 **Pusher protocol**, making it compatible with Laravel Echo and any Pusher-compatible client.

package/dist/agent-src/skills/laravel-scheduling/SKILL.md

@@ -26,6 +26,11 @@ Use this skill when scheduling recurring tasks:
 
 ## Procedure: Create a scheduled task
 
+1. **Inspect existing schedule** — Read `routes/console.php` (Laravel 11+) or `app/Console/Kernel.php` to identify current cadence, overlap-prevention patterns, and output handling.
+2. **Pick frequency and concurrency policy** — Choose a frequency helper (see table) or a cron expression; decide whether `withoutOverlapping()` / `onOneServer()` is required.
+3. **Register the task** — Add the `Schedule::command(...)` / `Schedule::job(...)` entry; wire log destinations and `runInBackground()` if needed.
+4. **Verify** — Run `php artisan schedule:test` (or `schedule:list`) and confirm timing, output path, and overlap behavior.
+
 ### In routes/console.php (Laravel 11+)
 
 ```php
@@ -174,4 +179,4 @@ Schedule::command('reports:weekly')->weeklyOn(1, '07:00');
 - Do NOT add multiple cron entries — use Laravel's scheduler for everything.
 - Do NOT schedule heavy work directly — dispatch a queued job instead.
 - Do NOT forget `withoutOverlapping()` for tasks that may run longer than their interval.
-- Do NOT hardcode times — use environment-based config when schedules vary per env.
+- Do NOT hardcode times — use environment-based config when schedules vary per environment.

package/dist/agent-src/skills/laravel-validation/SKILL.md

@@ -73,6 +73,18 @@ Do NOT use when:
 - Do NOT use `$request->all()` — use `$request->validated()`.
 - Do NOT put business logic in validation classes.
 
+## Verification
+
+Confirm new rules with a concrete probe: a Pest feature test that POSTs with `curl`-shaped payloads through the browser/HTTP client, or a `phpunit`/`pest` run against the FormRequest. Add at least one negative case per rule (missing, wrong type, boundary). Never claim rules work without running them.
+
+## Anti-bruteforce — diagnose before retry
+
+When a rule fires unexpectedly, do not blindly toggle `required` / `nullable` / `sometimes` until tests pass. Print `$request->all()` once, compare against the rule set, identify the root cause, then make a targeted fix.
+
+## Clarification guard — ambiguous field → ask
+
+If a field's intent is unclear (is `tags` a CSV string, an array, or JSON? is `email` required at create or only at update?), ask the user or check the existing schema / API contract before guessing. Hidden assumptions in validation rules surface as production 422s.
+
 ## Auto-trigger keywords
 
 - validation

package/dist/agent-src/skills/launch-readiness/SKILL.md

@@ -78,7 +78,7 @@ report per [`docs/contracts/prelaunch-diagnostics.md`](../../../docs/contracts/p
   (`prelaunch-areas.yml`): auth · migrations · secrets · observability ·
   rollback · agent-governance. No ad-hoc areas.
 - **Every area gets one state:** `pass` (cited evidence REQUIRED) ·
-  `finding` (IDs listed) · `unknown` (honest default — **absence of
+  `finding` (IDs listed) · `unknown` (the honest default — **absence of
   findings is Unknown, never an automatic Pass**) · `not-applicable`
   (reason required).
 - **Findings carry immutable IDs** (`AC-<AREA>-NNN`) — retitle freely,
@@ -89,7 +89,7 @@ report per [`docs/contracts/prelaunch-diagnostics.md`](../../../docs/contracts/p
 - **Questions section** — list the questions that would change the
   diagnosis; the next run converts them into evidence or findings.
 - Validate + verdict via
-  `./scripts-run src/scripts/prelaunch_diagnostics validate <report.json>`;
+  `npx tsx node_modules/@event4u/agent-config/src/scripts/prelaunch_diagnostics.ts validate <report.json>`;
   regression-gate against the committed baseline via
   `… diff <baseline> <current> --ci` (contract § 4–6).
 

package/dist/agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -68,8 +68,8 @@ Do not use this skill when:
 * One-off or too narrow → do not create anything yet
 * Standard tool knowledge (jq, docker, git basics) → **Nothing** — the model knows this
 * If unsure between skill and guideline: does it need step-by-step decisions? → Skill. Just conventions? → Guideline
-* If unsure between guideline and pattern: prose convention ("how to write code in X")? → Guideline. Keyed recipe ("problem P → recipe + verification + reliability")? → **Pattern**
-* When a related workflow fires, **surface** a matching `src/patterns/` recipe (never auto-apply) — the human decides
+* If unsure between guideline and pattern: is it *"how to write code in X"* (prose convention)? → Guideline. Is it *"I have problem P — here's the proven recipe + a verification step + how reliable it is"*? → **Pattern**
+* When a related workflow fires, **surface** a matching `src/patterns/` recipe (never auto-apply) — the human decides whether to use it
 
 ## Procedure
 
@@ -238,8 +238,8 @@ to stage `gated`.
 If the learning came from an `agents/knowledge/procedures/skill-candidates.md`
 entry or any other `agents/knowledge/` page (see § "Knowledge-candidate
 learnings" below), promotion is **not complete** until the source is
-degraded to a pointer — this prevents double-maintenance between the
-knowledge page and the new artifact:
+degraded to a pointer — this is what prevents double-maintenance between
+the knowledge page and the new artifact:
 
 ```bash
 ./scripts-run src/scripts/degrade_to_pointer \
@@ -249,9 +249,9 @@ knowledge page and the new artifact:
 ```
 
 This rewrites the source entry to `Promoted to <artifact> on <date>; see
-<path>.` and regenerates `agents/knowledge/INDEX.md`. Skip when the
-learning's source was NOT a knowledge page (direct user request,
-audit-log pattern, one-off observation).
+<path>.` and regenerates `agents/knowledge/INDEX.md`. Skip this step
+only when the learning's source was NOT a knowledge page (e.g. a direct
+user request, an audit-log pattern, or a one-off observation).
 
 ## Output format
 

package/dist/agent-src/skills/learning-tutor/SKILL.md

@@ -12,15 +12,15 @@ packs:
 # learning-tutor
 
 > Structured tutoring modes for learning WITH the agent instead of consuming
-> explanations FROM it. Default agent behavior on "teach me X" = prose
+> explanations FROM it. The default agent behavior on "teach me X" is a prose
 > lecture — pedagogically the weakest format. This skill replaces the lecture
-> with six evidence-shaped modes: triage what to learn, practice before
-> theory, withhold answers until the learner has tried, verify understanding
-> with probes the learner cannot bluff through.
+> with six evidence-shaped modes: triage what to learn, practice before theory,
+> withhold answers until the learner has tried, verify understanding with
+> probes the learner cannot bluff through.
 
 ## When to use
 
-Use when the user:
+Use this skill when the user:
 
 - Wants to get functional in a new tool, framework, language or topic fast
   ("teach me X", "get me productive in X", "crash course").
@@ -28,32 +28,32 @@ Use when the user:
   "let me apply it", "give me exercises").
 - Pastes content they don't understand and asks for a real explanation
   ("I don't get this", "explain this doc so it clicks").
-- Has a concrete goal with a deadline, wants a learning plan
-  ("learning plan for X", "need to ship Y in two weeks, don't know Z").
-- Wants existing knowledge stress-tested ("quiz me", "do I actually
+- Has a concrete goal with a deadline and wants a learning plan
+  ("learning plan for X", "I need to ship Y in two weeks and don't know Z").
+- Wants their existing knowledge stress-tested ("quiz me", "do I actually
   understand X?", "find my blind spots").
-- Just learned something, wants to verify it stuck ("check my
+- Just learned something and wants to verify it stuck ("check my
   understanding", "let me explain it back to you").
 
 Do NOT use when:
 
-- User asks a direct factual or how-to question — answer it
+- The user asks a direct factual or how-to question — answer it
   (per `direct-answers`); don't convert a question into a curriculum.
-- User wants the agent to DO the task, not to learn it.
-- "Learning" target is this package's own artifacts (rules/skills) —
+- The user wants the agent to DO the task, not to learn it.
+- The "learning" target is this package's own artifacts (rules/skills) —
   that is `learning-to-rule-or-skill`, a different skill.
-- User wants a plan/idea stress-tested — that is `adversarial-review`
+- The user wants a plan/idea stress-tested — that is `adversarial-review`
   or `/challenge-me`, not knowledge tutoring.
 
 ## Procedure
 
-1. **Select the mode** from user intent (table below). Pick ONE; if two fit,
-   pick the one matching the user's verb ("learn" → teach modes 1–4,
+1. **Select the mode** from the user's intent (table below). Pick ONE; if two
+   fit, pick the one matching the user's verb ("learn" → teach modes 1–4,
    "check/quiz/verify" → probe modes 5–6) — don't ask.
-2. **State the chosen mode** in one line, freeze the target
+2. **State the chosen mode** in one line and freeze the target
    (skill/topic/goal).
 3. **Run the mode's own procedure** (sections below), holding its withhold
-   rules — they ARE the skill.
+   rules — they are the skill.
 4. **Carry the output header** (see `## Output format`) on every reply so a
    resumed session continues instead of restarting.
 5. **Close the session** with the mode's closing analysis and exactly one
@@ -72,16 +72,16 @@ Do NOT use when:
 
 ## Mode 1 — Rapid competence
 
-Frame: one time-boxed session (default 4 focused hours unless user names a
-budget), never met again — every minute must transfer skill. No theory block
-without immediate practical use.
+Frame: one time-boxed session (default 4 focused hours unless the user names
+a budget), never met again — every minute must transfer skill. No theory
+block without an immediate practical use.
 
 1. Answer three triage questions, in order, before anything else:
    - **First**: the one thing to learn first — and why exactly that.
    - **Ignore**: what to skip entirely for now — and why skipping is safe.
    - **Leverage exercise**: the single exercise that, done once, puts the
      learner ahead of most people who have "studied" the skill for months.
-2. Run the session practice-first: each concept introduced only at the
+2. Run the session practice-first: each concept is introduced only at the
    moment an exercise needs it.
 3. Close with the next leverage exercise for the learner's own follow-up.
 
@@ -97,25 +97,26 @@ mistake.
 3. Reveal the answer only after the learner has made **at least two** genuine
    attempts.
 4. Repeat the cycle with variations until the learner applies the concept
-   without hesitation; then say so explicitly, stop.
+   without hesitation; then say so explicitly and stop.
 
 ## Mode 3 — Keystone decoding
 
-Frame: user supplied content (doc, text, code, spec) that doesn't click.
+Frame: the user supplied content (doc, text, code, spec) that doesn't click.
 
 1. Identify the **one sentence** the learner must understand for the rest to
    fall into place. Name it verbatim from the content.
-2. Explain only that sentence first — with an everyday analogy, no technical
-   term left unexplained in the same breath.
-3. Ask exactly **3 comprehension questions** designed so only someone who
-   actually understood can answer (no yes/no, no recall of wording).
+2. Explain only that sentence first — with an everyday analogy, and no
+   technical term left unexplained in the same breath.
+3. Ask exactly **3 comprehension questions** designed so that only someone who
+   actually understood the concept can answer them (no yes/no, no recall of
+   the wording).
 4. Continue into the rest of the content only after all three are answered
-   correctly; on a wrong answer, re-explain from a different angle, re-ask.
+   correctly; on a wrong answer, re-explain from a different angle and re-ask.
 
 ## Mode 4 — Goal-backward sprint
 
-Frame: user has a specific outcome, a time frame, a current level. Plan
-targets the OUTCOME, not the subject in general.
+Frame: the user has a specific outcome, a time frame and a current level. The
+plan targets the OUTCOME, not the subject in general.
 
 1. Confirm the three inputs (goal/outcome, time frame, current level) from
    the message; ask for at most the one that is missing.
@@ -124,12 +125,12 @@ targets the OUTCOME, not the subject in general.
    - **One task**, completable in ~45 minutes.
    - **One success criterion** — how the learner verifies they did it right.
    - **One exclusion rule** — what they deliberately do NOT touch that day.
-3. Self-check the path against the goal: a day that doesn't causally move the
-   learner toward the stated outcome → rework before presenting.
+3. Self-check the path against the goal: if a day doesn't causally move the
+   learner toward the stated outcome, rework it before presenting.
 
 ## Mode 5 — Gap probe
 
-Frame: user believes they already know the subject. Job: prove otherwise.
+Frame: the user believes they already know the subject. Job: prove otherwise.
 
 1. Ask **5 questions** that look deceptively simple but expose the classic
    gaps of someone who never went deep — edge cases, "why" behind defaults,
@@ -142,8 +143,8 @@ Frame: user believes they already know the subject. Job: prove otherwise.
 
 ## Mode 6 — Feynman check
 
-Frame: user explains the freshly learned topic as if the agent were a
-10-year-old. Agent listens and interrupts.
+Frame: the user explains the freshly learned topic as if the agent were a
+10-year-old. The agent listens and interrupts.
 
 1. Invite the explanation; interrupt immediately when the learner:
    - uses a technical term without being able to say what it means,
@@ -151,7 +152,7 @@ Frame: user explains the freshly learned topic as if the agent were a
    - oversimplifies to the point of being factually wrong.
 2. Each interruption is one pointed question, not a correction.
 3. Close with a precise analysis: what the accumulated stumbles reveal about
-   which parts of the understanding are not yet solid — and which held.
+   which parts of the understanding are not yet solid — and which parts held.
 
 ## Output format
 
@@ -167,7 +168,7 @@ Next:     <what the learner does next>
 
 Required fields (ordered):
 
-1. **Mode line** — mode number + name, stated in the first reply, kept on
+1. **Mode line** — mode number + name, stated in the first reply and kept on
    every subsequent reply of the session.
 2. **Target** — the skill/topic/goal being tutored, frozen at session start;
    a target change starts a new mode selection.
@@ -180,14 +181,14 @@ Required fields (ordered):
 
 - **Lecture relapse** — after 2–3 turns the agent drifts back into
   explaining instead of asking. The withhold rules (mode 2: answer only
-  after 2 attempts; mode 3: proceed only after 3/3 correct) ARE the skill;
+  after 2 attempts; mode 3: proceed only after 3/3 correct) are the skill;
   dropping them silently turns every mode back into mode zero.
-- **Solving instead of tutoring** — learner pastes their broken attempt,
-  agent fixes it. In modes 2/5/6 the fix is withheld; the question comes
-  first. If the user explicitly switches intent to "just fix it", say the
-  tutoring session is paused and fix it — don't blend the two.
+- **Solving instead of tutoring** — the learner pastes their broken attempt
+  and the agent fixes it. In modes 2/5/6 the fix is withheld; the question
+  comes first. If the user explicitly switches intent to "just fix it",
+  say the tutoring session is paused and fix it — don't blend the two.
 - **Flattery corrupts the probe** — modes 5 and 6 only work blunt. "Great
-  answer!" on a shallow answer defeats the mode (`direct-answers`
+  answer!" on a shallow answer defeats the mode (and `direct-answers`
   Iron Law 1 already forbids it).
 - **Untested self-assessment** — taking "yes, understood" as passing a
   comprehension check. Only a correct answer to a probe question counts;