@event4u/agent-config 9.7.0 → 9.9.0

package/dist/agent-src/skills/schema-review/SKILL.md

@@ -0,0 +1,92 @@
+---
+model_tier: medium
+name: schema-review
+description: "Use when reviewing a migration diff or schema change for scale hazards — indexes, unsafe migrations, unbounded growth, N+1. Triggers on 'review this migration', 'will this scale'."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - scale-discipline
+trust:
+  level: professional
+install:
+  default: false
+  removable: true
+---
+
+# schema-review
+
+## When to use
+
+- A migration diff, new migration file, or schema change is under review
+  and the question is scale-shaped: indexes, reversibility, growth,
+  query patterns against the new columns.
+- The user asks "will this scale", "review this migration", "check the
+  schema", or a PR touches `migrations/`, `schema.prisma`, or raw `.sql`
+  migration files.
+- NOT for runtime performance analysis of live traffic (no APM here —
+  route to `performance-analysis`) and NOT for authoring a new migration
+  from scratch (route to `laravel-migration` or the stack-native tool,
+  then come back with the diff).
+
+## Procedure
+
+1. **Detect the stack surface** in the diff: Laravel migrations
+   (`database/migrations/*.php`), Prisma (`schema.prisma` +
+   `prisma/migrations/**/migration.sql`), raw SQL (`*.sql`). One diff can
+   carry several.
+2. **Run the deterministic linter** on the touched files plus the query
+   surface that references the changed tables:
+
+   ```bash
+   npx tsx node_modules/@event4u/agent-config/src/scripts/lint_persistence.ts -- --dir <path> [--stack eloquent|prisma|raw-sql] --format json
+   ```
+
+   The linter emits `gate` findings (pattern-detected: F1 N+1, F2
+   index-parity, F3 unbounded reads, F6 migration-safety, F7
+   growth-budget, F8 audit-coverage, F9 sync-in-handler, F11 non-durable
+   async) and `advice` findings (heuristics — never treat as blockers).
+3. **Walk the gap table** — for every `gate` finding decide: fix, or
+   waiver with a reason (`// no-index: <reason>`, `// sync-required:
+   <reason>`, `-- no-retention: <reason>`, …). An empty waiver reason is
+   itself a finding.
+4. **Check the R-A6/R-A7 invariants by hand** where the linter is blind:
+   reversibility of data transformations, retention policy for any new
+   append-only table (the `-- retention: <policy>` line), backfill plan
+   for new NOT NULL columns on large tables.
+5. **Report waiver density neutrally** — count waivers per rule; state
+   both readings (informed exceptions vs rule misfit) and let the human
+   decide. Density alone is never a verdict.
+
+## Output
+
+The review MUST contain:
+
+1. **Gap table** — one row per finding: `rule · file:line · finding ·
+   proposed action (fix | waiver | accepted)`, gate findings first,
+   advice findings clearly marked as advice.
+2. **Waiver-density line** — `N waivers across M findings` with the
+   two-reading note (informed exceptions vs rule misfit).
+3. A one-line verdict: ready / needs fixes / needs human schema decision
+   — never a bare "looks good" without the table.
+
+## Gotcha
+
+- The linter proves **pattern presence**, not instance-level correctness
+  — a flagged `Http::` call in a controller may be legitimately sync
+  (then it gets a `// sync-required:` waiver with a reason), and a clean
+  run does not prove the schema scales. Say what was checked, not more.
+- Prisma's `@relation` fields are indexed implicitly on some connectors
+  and not on others — when the linter reports a missing FK index on a
+  Prisma model, verify the connector before calling it a defect.
+
+## Do NOT
+
+- Do NOT gate a review on `advice`-tier findings (F4 denormalization,
+  F10 event-decoupling heuristics) — they are review inputs, not
+  blockers.
+- Do NOT strip or rewrite existing waivers — surface stale-looking ones
+  and ask.
+- Do NOT invent index recommendations for columns the query surface
+  never filters or orders by — index parity cuts both ways; unused
+  indexes cost write throughput.

package/dist/agent-src/skills/schema-review/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+    "skill": "schema-review",
+    "last_eval": "2026-07-27",
+    "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers DE+EN phrasings for reviewing a migration/schema diff for scale hazards. Should-not-trigger covers near-miss neighbours: authoring a migration (laravel-migration), live-traffic performance (performance-analysis), audit-tier selection (history-design), generic code review.",
+    "queries": [
+        { "q": "review this migration for missing indexes before I merge", "trigger": true },
+        { "q": "will this schema change scale to 100k rows?", "trigger": true },
+        { "q": "prüfe meine Migration auf Skalierungsprobleme", "trigger": true },
+        { "q": "check the new schema.prisma diff for unsafe changes", "trigger": true },
+        { "q": "does this ALTER TABLE need CONCURRENTLY and a default?", "trigger": true },
+        { "q": "create a migration that adds a status column to orders", "trigger": false },
+        { "q": "the dashboard endpoint is slow in production, profile it", "trigger": false },
+        { "q": "which audit log mechanism should we use for tenants?", "trigger": false },
+        { "q": "review my pull request for code quality", "trigger": false },
+        { "q": "wie lege ich einen Index in MySQL an?", "trigger": false }
+    ]
+}

package/dist/agent-src/skills/screenshot-hygiene/SKILL.md

@@ -0,0 +1,171 @@
+---
+model_tier: high
+name: screenshot-hygiene
+description: "Use when creating and embedding a documentation screenshot — detect and redact sensitive data, human-gate data-bearing shots before ship. Triggers 'screenshot for docs', 'screenshot admin panel'."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# screenshot-hygiene
+
+The executable workflow behind [`doc-screenshot-hygiene`](../../rules/doc-screenshot-hygiene.md).
+A screenshot embedded into shipped docs is an **irreversible published egress** —
+once committed and hosted, any PII, secret, or revealing local path on it is out.
+This skill makes agents create doc screenshots that are as neutral as possible,
+with a conservative, err-on-the-side-of-redaction posture.
+
+## When to use
+
+- Generating or updating documentation (a docs site, feature docs, a README)
+  where a screenshot genuinely helps and you are about to capture + embed one.
+- A screenshot is about to land under `docs/media/` (or a docs image folder).
+
+Do NOT use for:
+- Image **generation** (route to `image-generation` / `image-editing` /
+  `media-governance-routing` for likeness/rights).
+- A user-supplied screenshot used only as a **design spec** to compare against
+  (route to `design-fidelity` / `cross-source-consistency`).
+- Terminal / CLI / IDE output — that is **forbidden** as a screenshot (see the
+  workflow). Use a text code block with text redaction instead.
+
+## Procedure
+
+### 1. Decide — screenshot, or a safer alternative?
+
+Classify the risk tier first (symmetric friction):
+
+| Tier | Examples | Path |
+|---|---|---|
+| Illustrative / no data | architecture diagram, logo, icon, wireframe, placeholder-only UI | Embed with a one-line justification. |
+| Data-bearing | dashboard, admin panel, form/list with content, any real-looking data | Full workflow + **human gate** before embed. |
+| Terminal / CLI / IDE | shell output, editor, path bars | **Forbidden.** Use a text code block; redact the text. |
+
+Prefer a diagram or a placeholder-data screenshot over a real-data one whenever
+it conveys the same thing. Terminal output → copy the text into a fenced block
+and redact the text (cheaper and safer than a pixel screenshot). Respect
+`screenshots.forbid_terminal_capture` (default `true`).
+
+### 2. Capture — via the host, never a bundled engine
+
+Use the host's capability (`claude-in-chrome` for web UI, Playwright's
+`page.screenshot` inside a test harness). Record which tool captured it. The
+package ships no capture engine (no-runtime-floor). Capture into a working file
+under the scratchpad or `docs/media/` — do not embed yet.
+
+### 3. Detect — flag candidate sensitive regions (a helper, not a clearance)
+
+OCR the image (host OCR, or the `image-analyser` skill's text read) and scan the
+extracted text against the taxonomy below and `screenshots.identity_allowlist`.
+Produce a **flagged-regions report**: for each hit, the text, the bounding box,
+and the reason. Detection **reduces** the human's work — it never certifies the
+screenshot as safe (it cannot see semantic leaks: aggregate counts that reveal
+real users, real-vs-fake data tells, re-identification via name structure).
+
+**Anonymization taxonomy** — always redact / refuse:
+- Real person's name, postal address, birthdate, phone number.
+- Passwords, API tokens, secrets, session cookies, bearer tokens, private keys.
+- Real email addresses (anything not `@example.{com,org,net}` / a fake-data domain).
+- Absolute local paths revealing a real identity (`/Users/<realname>/…`,
+  `/home/<realname>/…`).
+- Client / customer / project identifiers; internal hostnames (`*.internal`).
+- Anything GDPR-sensitive; aggregate counts / data tells that reveal real users.
+
+Allowed (no redaction): well-known fake data (Max Mustermann, Musterstraße,
+`@example.com`); the maintainer's OWN public handle shown as a username, and a
+path rooted at that handle (`/Users/<handle>/…`). The maintainer's **real name
+is never allowed**, even co-located with the handle. The safe set lives in
+`screenshots.identity_allowlist` (default empty → every identity is human-decided).
+
+### 4. Redact — deterministic opaque cover, never lossy inpaint
+
+Draw an **opaque box (or heavy blur/pixelation)** over each flagged region.
+Deterministic, visible, and non-reversible — never AI inpaint (lossy;
+reconstructs, may hallucinate; docs need visual accuracy). Redaction is
+tool-agnostic — use whatever image tool is present in the environment:
+
+- **ImageMagick** (if `magick`/`convert` present): draw a filled rectangle over
+  each region, e.g.
+  `magick in.png -fill black -draw "rectangle X1,Y1 X2,Y2" out.png` (repeat
+  `-draw` per region), or `-region … -blur 0x18` for a blur.
+- **sharp** (if a project already depends on it, e.g. the `/site` workspace):
+  `composite` an opaque rectangle over each region.
+
+If **no image tool is available** → `missing-tool-handling`: STOP, surface the
+flagged regions, and hand off to the maintainer to redact manually. **Never ship
+an unredacted screenshot because a tool was missing.** Never silently downgrade
+the guarantee.
+
+### 5. Pre-embed audit — the human gate (data-bearing tier)
+
+For a data-bearing screenshot, embedding is a published egress → **this-turn
+human confirmation** per [`non-destructive-by-default`](../../rules/non-destructive-by-default.md).
+Present the redacted candidate + the checklist; wait for the answer.
+
+**Pre-embed audit checklist:**
+- [ ] No real names, addresses, birthdates, phone numbers.
+- [ ] No passwords, API tokens, secrets, cookies, bearer tokens, private keys.
+- [ ] No real email addresses (fake-data / `@example.com` only).
+- [ ] No identity-revealing absolute paths (only a public-handle-rooted path).
+- [ ] No client / customer / project identifiers; no internal hostnames.
+- [ ] No terminal / CLI / IDE output.
+- [ ] No aggregate-count / data tell revealing real users (semantic leak).
+- [ ] Any realistic-looking data is justified as safe (known-fake / allowlist).
+
+Unresolved / uncertain on any line → **redact or refuse**, never ship-and-hope.
+An illustrative / no-data screenshot skips the confirmation but still passes the
+checklist and carries a one-line "no sensitive data" justification.
+
+### 6. Embed — into the docs surface
+
+Place the reviewed, redacted file under `docs/media/` (or the docs image folder)
+and reference it from a canonical `docs/*.md`. For the Starlight site,
+`site/sync-docs.mjs` auto-copies `docs/media/*` into `site/public/media/` and
+rewrites `](media/…)` links — so the embed flows to the site on build. Add
+descriptive alt text. Generalize the same discipline to a README or any other
+docs surface.
+
+## Output
+
+- **A redacted screenshot file** under the docs image folder with every
+  taxonomy item covered by an opaque box/blur (or an explicit
+  no-sensitive-data justification for the illustrative tier).
+- **A one-line provenance + review note** stating: capture tool, risk tier,
+  what was redacted (or "none — illustrative"), and — for data-bearing shots —
+  that human confirmation was obtained this turn.
+
+## Gotcha
+
+- **Detection "passing" is not safety.** OCR + patterns miss semantic leaks
+  (aggregate counts, real-vs-fake tells, name-structure re-identification) and
+  misread garbled text. Never treat a clean automated scan as clearance — the
+  human gate stands for data-bearing shots.
+- **A public handle does not whitelist a co-located real name.** `matze4u` is
+  fine; "Matthias Müller" next to it is still redacted.
+- **Missing tool ≠ ship anyway.** No image tool → hand off, never embed
+  unredacted.
+- **Terminal screenshots feel harmless and are the worst.** A single shell line
+  can leak an absolute path with a real name plus a live token. Use text.
+
+## Do NOT
+
+- Do NOT ship a screenshot with unredacted sensitive data — that is an
+  irreversible published egress.
+- Do NOT treat a clean automated scan as clearance; the gate for a data-bearing
+  shot is human confirmation.
+- Do NOT embed unredacted "because no image tool was available" — hand off instead.
+- Do NOT screenshot terminal / CLI / IDE output — use a text code block with text
+  redaction.
+- Do NOT use lossy AI inpaint to redact — use a deterministic opaque box/blur.
+- Do NOT assume a public handle whitelists a co-located real name — redact the name.
+
+## See also
+
+- [`doc-screenshot-hygiene`](../../rules/doc-screenshot-hygiene.md) — the rule that routes here (Iron Law + taxonomy + risk tiers).
+- [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) — the published-egress gate the data-bearing embed routes into.
+- [`domain-safety-pii`](../../rules/domain-safety-pii.md) — the text-surface sibling (drafts / logs / exports).
+- [`image-analyser`](../image-analyser/SKILL.md) — OCR-reads text in an image (the detection helper).
+- [`image-editing`](../image-editing/SKILL.md) — region editing (only for deterministic redaction, never lossy inpaint here).
+- [`readme-writing`](../readme-writing/SKILL.md) — flags unrequested data-bearing screenshots.

package/dist/agent-src/skills/secrets-management/SKILL.md

@@ -99,6 +99,48 @@ Error responses     → never echo the secret back, even on failure.
 Telemetry / APM     → strip from request/response captures; allowlist headers.
 ```
 
+### Step 6 — Runtime guard: block before the secret lands
+
+The scanning gates (Step 4) are the CI/pre-commit nets. The **earliest** gate is
+the agent itself: before it writes a credential into a tracked file or stages a
+commit, the [`secret-vcs-guard`](../../rules/secret-vcs-guard.md) rule runs the
+`secret_detector` library and, on a hit,
+STOPS → shows the match (`file:line` · kind · masked · why) → asks via numbered
+options → offers the tiered alternative below. It never silently commits and
+never silently strips. VCS-agnostic: the same detector runs against the diff for
+git, SVN, and Mercurial (SVN/hg native hooks are server-side, a stronger but
+later net). The deterministic CI backstop is `check_secret_leak` — the agent
+gate is one layer, not the whole defense.
+
+**False positives — audited allowlist, never a global mute.** Suppress a
+confirmed non-secret with an inline `# secret-allow` marker on the line, or a
+narrow entry (`path` or `path:line`) in a repo-root `.secret-allow` file. Each
+`.secret-allow` entry SHOULD carry a one-line justification comment (`#  …`) so it
+is reviewable in the diff; the entry is line-scoped, so it cannot mute a *new*
+secret elsewhere in the same file.
+
+**Tiered alternative to suggest when a secret is caught** (refines Step 1 for the
+in-the-moment fix; cite OWASP Secrets Management Cheat Sheet + CWE-798 + 12-factor):
+
+```
+Solo / local, dev-only        → gitignored .env + committed .env.example (keys, no values).
+Team / production app         → cloud secret manager (AWS/GCP/Azure) or Vault / Doppler.
+Kubernetes / GitOps           → SOPS (encrypt values in the committed file) or Sealed Secrets.
+CI / deploy                   → OIDC federation to the cloud — no long-lived stored credential.
+```
+
+## Remediation — a secret already reached VCS
+
+Order matters; a history rewrite does **not** un-leak an already-pushed secret:
+
+1. **Rotate / revoke the credential now.** Immediate, and the only step that
+   actually stops the damage — assume it is compromised the moment it was pushed.
+2. **`git rm` / a deletion commit is insufficient** — the secret stays in history
+   (`git log`, blame, prior commits, clones, forks, CI logs).
+3. **Purge history** with `git filter-repo` (preferred) or BFG Repo-Cleaner.
+4. **Force-push + coordinate** re-clones; forks and existing clones still hold the
+   old objects — which is why step 1 is the real fix.
+
 ## Procedure: Apply to a new secret
 
 1. **Inspect** the existing secret inventory and IaC for store conventions; run Step 1 and lock the store decision in code/IaC.
@@ -142,7 +184,7 @@ Telemetry / APM     → strip from request/response captures; allowlist headers.
 
 ## Provenance
 
-- Adopted from: an external reference (MIT, © 2025 an external reference) — **Sunset Policy applied**: 346-line provider cookbook reduced to a ~140-line decision framework; per-provider deep-dives externalized to upstream docs below.
+- Adopted from: an external reference (internal provenance, redacted) — **Sunset Policy applied**: a large provider cookbook reduced to a ~140-line decision framework; per-provider deep-dives externalized to upstream docs below.
 - Externalized provider docs:
   - HashiCorp Vault: https://developer.hashicorp.com/vault/docs · https://developer.hashicorp.com/vault/docs/secrets/databases
   - AWS Secrets Manager: https://docs.aws.amazon.com/secretsmanager/ · rotation: https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html

package/dist/agent-src/skills/security-audit/SKILL.md

@@ -148,7 +148,7 @@ After findings, add **Rejected candidates** section: one line per look-dangerous
 ## Gotcha
 
 - Don't report theoretical vulnerabilities without a concrete attack vector — false positives erode trust.
-- The model tends to flag framework-handled security as issues (e.g., Laravel's CSRF is already handled).
+- The model tends to flag framework-handled security as issues (e.g., Laravel's CSRF or Rails' `protect_from_forgery` is already handled).
 - Always check if a finding is already mitigated by middleware or configuration before reporting it.
 
 ## Do NOT

package/dist/agent-src/skills/security-maturity-assessment/SKILL.md

@@ -55,7 +55,7 @@ Do NOT use when:
 
 1. **Scope** — name the module/paths under assessment; list entry points (routes, jobs, commands, webhooks). Scorecard without stated scope is not reproducible.
 2. **Assess each category** — inspect the code the category names. Every rating cites evidence:
-   - Positive evidence: `file:line` of the control (`app/Http/Requests/…:12`).
+   - Positive evidence: `file:line` of the control (`app/Http/Requests/…:12`, `src/guards/auth.guard.ts:12`).
    - Absence evidence: the searches run that came back empty (name the grep patterns) — "not found" beats "probably missing".
    - Multi-tenant N/A: single-tenant systems rate category 8 `N/A`; drops out of the roll-up.
 3. **Roll up deterministically** — overall rating is computed, not vibed:

package/dist/agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -115,8 +115,8 @@ Decide what to create:
 > the exact wording is recoverable, and verify against it rather than trusting
 > the summary.
 
-- **New rule** → create in `.agent-src.uncondensed/rules/`, follow rule conventions
-- **New skill** → use `skill-writing` skill, create in `.agent-src.uncondensed/skills/`
+- **New rule** → create in `src/rules/`, follow rule conventions
+- **New skill** → use `skill-writing` skill, create in `src/skills/`
 - **Update existing** → use `skill-management` skill
 
 After creation:
@@ -175,7 +175,7 @@ Ask the user:
 - Do NOT skip the promotion gate — it prevents skill/rule bloat
 - Do NOT create both a rule AND a skill for the same learning
 - Do NOT auto-push without user permission
-- Do NOT create project-specific content in `.agent-src.uncondensed/`
+- Do NOT create project-specific content in `src/`
 - Do NOT run this pipeline for trivial learnings
 
 ## References

package/dist/agent-src/skills/skill-writing/SKILL.md

@@ -189,7 +189,7 @@ approval-gated propose / pick loop with at most two rounds.
 ### 1c. Propose a trigger-eval stub (new skills only)
 
 When creating a new skill, propose a stub
-`.agent-src.uncondensed/skills/{name}/evals/triggers.json` before writing
+`src/skills/{name}/evals/triggers.json` before writing
 the body. Draw the queries from Phase A of the drafting protocol (the
 user's "should trigger" and "must not trigger" answers).
 
@@ -531,7 +531,7 @@ content).
 
 ## Do NOT
 
-* Write documentation-style, pointer-only, or too-broad skills ("Laravel skill")
+* Write documentation-style, pointer-only, or too-broad skills ("Laravel skill", "Django skill")
 * Skip Procedure or use vague validation
 * Exceed size limits (see `docs/guidelines/agent-infra/size-and-scope.md`)
 * Duplicate rules

package/dist/agent-src/skills/source-discovery/SKILL.md

@@ -38,9 +38,9 @@ discover the real source  →  Evidence Report (Verified / Assumed / Gaps)  →
 Scaffold the report cheaply so it never gets skipped:
 
 ```bash
-./scripts-run src/scripts/evidence_report git-state            # fail-fast: abort if a rebase/merge/cherry-pick is in progress
-./scripts-run src/scripts/evidence_report init --task "<task>" # writes the gitignored session report
-./scripts-run src/scripts/evidence_report add --bucket verified --claim "users.email is unique" --source "db/schema/users.sql:23"
+npx tsx node_modules/@event4u/agent-config/src/scripts/evidence_report.ts git-state            # fail-fast: abort if a rebase/merge/cherry-pick is in progress
+npx tsx node_modules/@event4u/agent-config/src/scripts/evidence_report.ts init --task "<task>" # writes the gitignored session report
+npx tsx node_modules/@event4u/agent-config/src/scripts/evidence_report.ts add --bucket verified --claim "users.email is unique" --source "db/schema/users.sql:23"
 ```
 
 **Provenance on every item** (`observed_at` / `source` / `version`). Within a
@@ -175,10 +175,10 @@ the per-session Evidence Report above. Append to the knowledge intake —
 never write a tracked page mid-task:
 
 ```bash
-./scripts-run src/scripts/emit_knowledge_event --type api_shape_learned \
+npx tsx node_modules/@event4u/agent-config/src/scripts/emit_knowledge_event.ts --type api_shape_learned \
     --endpoint "<path>" --method "<verb>" --request-schema '<json>' --response-schema '<json>'
 
-./scripts-run src/scripts/emit_knowledge_event --type convention_detected \
+npx tsx node_modules/@event4u/agent-config/src/scripts/emit_knowledge_event.ts --type convention_detected \
     --pattern "<pattern>" --evidence "file:line" --sample-size <N> --scope project
 ```
 

package/dist/agent-src/skills/subagent-orchestration/SKILL.md

@@ -111,6 +111,15 @@ Rules:
   or `none`) so the gate's value is measurable inside the ADR-117
   prove-or-drop window.
 
+## Severity-conditioned team composition — conditions pattern
+
+Incident-style severity tiers (Critical / High / Medium / Low) refine
+composition and activation **within** the form the static gate already
+picked — severity never overrides the form gate, the Iron Law, or any
+safety floor. Guidance, not a new object class (persona-catalog
+disposition). Severity→composition table + escalation rule →
+[`subagent-modes-detail` § Severity-conditioned team composition](../../agent-src/contexts/execution/subagent-modes-detail.md).
+
 ## The nine modes
 
 Each mode has a decision row: when to use, when not, and the expected
@@ -124,42 +133,23 @@ glossary) lives in
 [`subagent-topologies`](../../agent-src/contexts/execution/subagent-topologies.md) —
 pull it for capacity planning; it is metadata, not runtime-enforced.
 
+Per-mode decision rows (when to use / when not / model pairing) and the
+mode-2 stage-routing contract live in
+[`subagent-modes-detail` § Modes 1–6](../../agent-src/contexts/execution/subagent-modes-detail.md) —
+pull them at dispatch time.
+
 ### 1. do-and-judge
 
 Implementer produces a diff; judge reviews; loop applies, revises, or
 hands off. Hard ceiling: **two revision cycles**, then stop and hand
 back to the user.
 
-| When to use | When not | Model pairing |
-|---|---|---|
-| Single-change task with non-trivial risk | Tiny fix, or spike/exploration | implementer = session; judge = one tier up |
-
 ### 2. do-and-judge-two-stage
 
-Implementer produces a diff; **two judges run sequentially** — first a
-spec-compliance reviewer (does the diff satisfy the stated spec /
-acceptance criteria?), then a code-quality reviewer (is the diff well-
-written for the codebase it lands in?). The orchestrator only proceeds
-to stage two if stage one returns `DONE` or `DONE_WITH_CONCERNS`. A
-stage-one `BLOCKED` shortcuts the loop — there is no point quality-
-reviewing a diff that does not satisfy the spec.
-
-| When to use | When not | Model pairing |
-|---|---|---|
-| Spec is contested or AC are detailed; diff size makes one judge prone to missing one axis (correctness vs craft) | Spec is one sentence, or the diff is one line (collapse to mode 1) | implementer = session; spec-judge = one tier up; quality-judge = same tier as spec-judge, fresh context |
-
-**Why two stages, not one judge with both rubrics:** combining the
-rubrics in one prompt reliably regresses one of them — the judge "spends
-attention" on whichever rubric appears last. Splitting the prompts
-forces each judge to commit fully to its rubric.
-
-**Stage-routing rule:**
-- Stage-1 returns `DONE` → run stage-2.
-- Stage-1 returns `DONE_WITH_CONCERNS` → run stage-2; concerns carry
-  forward to the final envelope.
-- Stage-1 returns `NEEDS_CONTEXT` → pause; stage-2 does not run.
-- Stage-1 returns `BLOCKED` → final verdict is `BLOCKED`; stage-2
-  does not run (saves cost).
+Implementer produces a diff; **two judges run sequentially** — spec
+compliance first, code quality second. Stage-one `BLOCKED` shortcuts the
+loop (no point quality-reviewing a diff that misses the spec). Stage
+routing + why-two-stages rationale → modes-detail § Mode 2.
 
 ### 3. do-in-steps
 
@@ -167,40 +157,24 @@ Plan is split into N steps; judge runs **between** steps. A step that
 fails judgment is revised before the next step starts. Used for
 multi-file changes where a mid-plan mistake would cascade.
 
-| When to use | When not | Model pairing |
-|---|---|---|
-| Multi-step plan with ordered dependencies | Single-step change, or when steps are independent (use `do-in-parallel`) | implementer = session; judge = one tier up |
-
 ### 4. do-in-parallel
 
 Independent slices run concurrently. No judge per slice — judge runs
 once on the aggregated result. Parallelism capped by
 `subagents.max_parallel` in `.agent-settings.yml`.
 
-| When to use | When not | Model pairing |
-|---|---|---|
-| Independent slices (different files, non-overlapping) | Any slice touches shared state | implementer = session; judge = one tier up, run once |
-
 ### 5. do-competitively
 
 Multiple implementers produce candidate diffs for the **same** slice.
 Judge picks the winner and rejects the losers. Expensive — use only
 when the solution space is genuinely broad.
 
-| When to use | When not | Model pairing |
-|---|---|---|
-| Broad solution space (algorithm choice, API shape) | Well-defined problem with one good answer | implementers = same tier (≥2 instances); judge = one tier up |
-
 ### 6. judge-with-debate
 
 Two judges each produce a verdict; a meta-judge reconciles
 disagreements. Used for high-stakes changes (security, data
 migration, public API) where a single judge is too easy to fool.
 
-| When to use | When not | Model pairing |
-|---|---|---|
-| Security, data integrity, public API change | Routine internal refactor | judges = same tier (2x); meta-judge = one tier up |
-
 Mode 6 = **go/no-go** (strict-er verdict wins); for defect-FINDING coverage (the
 *union* of what diverse models catch) use Mode 9.
 
@@ -238,34 +212,25 @@ opt-in high-risk changes only; registered claim + high-risk tier need
 cross-*vendor* skeptics. Invariants, skeptic prompt, reconciliation, prove-or-drop
 gate → [`subagent-modes-detail`](../../agent-src/contexts/execution/subagent-modes-detail.md) § Mode 9
 + [`prompts/adversarial-verification-council.md`](prompts/adversarial-verification-council.md)
+
+> **Disposition (2026-07-28, honest null).** Adversarial-council
+> finding-coverage benchmark resolved as published null (`docs/benchmark.md`)
+> — mode NOT sold as defect-detection capability. Stays default-off bound to
+> that null; removal at next major unless external evidence (consumer-filed
+> case where the panel surfaced a real defect the single verifier missed)
+> appears first. Remaining honest value: perspective diversity + decision
+> documentation, nothing more.
 (ADR-122).
 
 ## Status taxonomy — every subagent return uses one envelope
 
 Every implementer or judge return must conform to
-[`schemas/subagent-status.json`](schemas/subagent-status.json). Four
-statuses, no free-form alternatives:
-
-| Status | Meaning | Required keys (beyond `status`, `summary`) |
-|---|---|---|
-| `DONE` | Work shipped, all gates green. | `evidence[]` |
-| `DONE_WITH_CONCERNS` | Work shipped but caller must act on concerns. | `evidence[]`, `concerns[]` |
-| `NEEDS_CONTEXT` | Paused; caller can unblock by answering. | `blocking_question` |
-| `BLOCKED` | No path forward exists. | `blocking_reason` |
-
-**Why a fixed taxonomy:** orchestrators (`/do-and-judge`, `/do-in-steps`)
-route on status. Free-form "kind of done" returns force the orchestrator
-to interpret prose, which silently regresses the two-revision ceiling and
-the judge-rejected-do-not-apply rule. The schema makes routing mechanical.
-
-**Tests:** `tests/test_subagent_status_schema.py` exercises all four
-statuses plus rejection cases (missing required keys, unknown status,
-extra fields, conditional-key violations).
-
-**Distinguishing `NEEDS_CONTEXT` from `BLOCKED`:** `NEEDS_CONTEXT` means
-*"you, the caller, can fix this by telling me X"*. `BLOCKED` means
-*"no input from you unblocks this — escalate or rescope"*. If a subagent
-is unsure, it picks `BLOCKED` and the caller can downgrade.
+[`schemas/subagent-status.json`](schemas/subagent-status.json). Exactly
+four statuses — `DONE` · `DONE_WITH_CONCERNS` · `NEEDS_CONTEXT` ·
+`BLOCKED` — no free-form alternatives; orchestrators route on status
+mechanically. Meaning/required-keys table, why-fixed rationale, and the
+`NEEDS_CONTEXT`-vs-`BLOCKED` distinction →
+[`subagent-modes-detail` § Status taxonomy](../../agent-src/contexts/execution/subagent-modes-detail.md).
 
 ## Dispatch prompts — externalized
 
@@ -273,9 +238,12 @@ Each mode's literal dispatch template lives under
 [`prompts/{mode}.md`](prompts/README.md). The orchestrator loads the
 matching prompt at dispatch time and substitutes `{{placeholders}}`.
 Edits to a prompt do not bloat this skill against the 400-line sunset
-trigger; `tests/test_subagent_prompt_loading.py` confirms each of the
-nine modes resolves to a loadable prompt that cites all four taxonomy
-statuses.
+trigger. Eight prompt files cover modes 1–7 and 9 (the standalone judge
+reuses [`prompts/do-and-judge.md`](prompts/do-and-judge.md); mode 8's
+live-app rubric lives in
+[`subagent-modes-detail` § Mode 8](../../agent-src/contexts/execution/subagent-modes-detail.md));
+each prompt cites all four taxonomy statuses — see
+[`prompts/README.md`](prompts/README.md).
 
 ## Procedure
 
@@ -339,21 +307,13 @@ the judge verdict.
 
 ### 6. Emit telemetry
 
-After every auto-dispatched run, write one telemetry line to
-`agents/runtime/state/audit/YYYY-MM.jsonl` (current UTC month — use
-`new Date().toISOString().slice(0, 7)` to compute the filename).
-The line is a standard audit-log-v1 object with `input_kind:
-"orchestration"` and an `orchestration` sub-object per
-[`orchestration-telemetry.md`](../../agent-src/contexts/execution/orchestration-telemetry.md).
-
-Minimal emit (fill what is observable; `token_delta_provenance: "estimated"` if
-host usage metadata is unavailable):
-
-```json
-{"schema_version":1,"id":"<ulid>","ts":"<iso>","work_id":"<work_id>","phase":"implement","outcome":"success","confidence_band":"high","risk_class":"low","input_kind":"orchestration","type":"phase","orchestration":{"task_size_estimate":<int>,"spawn_count":<int>,"tiers":[...],"token_delta":<int>,"token_delta_provenance":"estimated","wall_clock_ms":<int>,"outcome":"DONE","verify_mode":"deterministic"}}
-```
-
-Skip emit when `subagents.enabled: false` or `spawn_count == 0` (in-session run).
+After every auto-dispatched run, write one audit-log-v1 line
+(`input_kind: "orchestration"`) via the `orchestration_record` recorder —
+never hand-author the JSON. Line shape, field semantics, recorder
+invocation, and `token_delta` sourcing priority →
+[`orchestration-telemetry` § Emit procedure](../../agent-src/contexts/execution/orchestration-telemetry.md).
+Skip emit when `subagents.enabled: false` or `spawn_count == 0`
+(in-session run).
 
 ## Gotcha
 

package/dist/agent-src/skills/subagent-orchestration/prompts/README.md

@@ -21,7 +21,7 @@ skill above the 400-line sunset trigger.
 Every prompt cites the status taxonomy in
 [`../schemas/subagent-status.json`](../schemas/subagent-status.json) and
 ends with the **return-envelope** instruction so the subagent's reply
-validates against `tests/test_subagent_status_schema.py`.
+validates against that schema.
 
 ## Prompt-cache discipline
 
@@ -47,6 +47,7 @@ dispatch. Verify a cohort is actually reading, not re-writing, by checking
 
 ## Loading
 
-`tests/test_subagent_prompt_loading.py` asserts that every mode named
-in `SKILL.md` § *The nine modes* has a loadable prompt file under this
-directory and that each prompt mentions all four status enum values.
+Every dispatchable mode named in `SKILL.md` § *The nine modes* maps to a
+prompt file in the table above (mode 8 is gated/experimental — its
+live-app rubric lives in the `subagent-modes-detail` context, not here);
+each prompt mentions all four status enum values.