@event4u/agent-config 1.31.0 → 1.33.0

package/.agent-src/commands/research/deep.md

@@ -0,0 +1,149 @@
+---
+name: research:deep
+cluster: research
+sub: deep
+description: "Read `outline.yaml`, research each item in batches, write per-item JSON validated against the project-local research-schema. No Python runtime, no `~/.claude/` paths."
+disable-model-invocation: true
+skills: [deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "deep research, populate the research scaffold, fill outline.yaml items"
+  trigger_context: "user has run `/research <topic>` and now wants per-item depth"
+---
+
+# /research:deep
+
+Reads the `outline.yaml` produced by [`/research`](../research.md), launches
+batched per-item research, and writes one JSON per item under
+`{output_dir}/`. Each JSON is self-validated against the
+[`research-schema`](../../contexts/contracts/research-schema.md)
+contract before write — **no `validate_json.py` script, no Python
+runtime, no `~/.claude/` paths**.
+
+## Trigger
+
+`/research:deep [--batch-confirm=each|once|auto]`
+
+`--batch-confirm` controls user gating between batches:
+
+- `each` (default) — confirm before every batch.
+- `once` — confirm only the first batch, then run the rest.
+- `auto` — no confirmation, run all batches (only honoured under
+  explicit `/roadmap process-full` autonomy).
+
+## Workflow
+
+### Step 1 — Auto-locate outline
+
+Search `$PROJECT_ROOT/agents/research/*/outline.yaml` (single match) or
+ask via numbered options if multiple `outline.yaml` files exist. Read:
+
+- `topic`, `topic_slug`, `items[]`, `execution.batch_size`,
+  `execution.items_per_agent`, `execution.output_dir` (default
+  `./results` relative to the topic dir).
+
+### Step 2 — Resume check
+
+Scan `{output_dir}/` for `*.json` files; mark items whose
+`{slug(item.name)}.json` exists as **complete**. Slugify by lowercasing,
+replacing whitespace with `_`, and stripping characters outside
+`[a-z0-9_-]`.
+
+### Step 3 — Batch execution
+
+Group remaining items by `batch_size` (each batch holds
+`batch_size × items_per_agent` items at most). For each batch:
+
+1. Show the batch summary: `[N/M] items: a, b, c …`.
+2. Apply the `--batch-confirm` policy (default `each` — wait for the
+   user; `once` after the first; `auto` skips).
+3. For every item in the batch, run the per-item research using the
+   agent's **native web-search** (no `web-search-agent` persona).
+
+#### Per-item prompt template
+
+Variables in `{xxx}` only — **do not modify structure or wording**.
+
+```text
+## Task
+Research {item_related_info}, output structured JSON to {output_path}.
+
+## Field definitions
+Read {fields_path} to get all field definitions.
+
+## Output requirements
+1. Output JSON whose top-level keys map to the categories in
+   `fields.yaml` (or to the `{slug(category)}` form — both are
+   accepted by `/research:report`).
+2. Mark uncertain field values with the literal string `[uncertain]`.
+3. Append an `uncertain` array at the end of the JSON listing all
+   field names whose value contains `[uncertain]` or could not be
+   sourced.
+4. All field values in English.
+
+## Output path
+{output_path}
+
+## Validation (no Python, no host paths)
+Self-validate the JSON against
+`<package>/.agent-src.uncompressed/contexts/contracts/research-schema.md`
+in memory before writing. The well-formedness escape hatch is
+`jq -e '.[]' {output_path}` — agent runs it after write and re-tries
+once on failure. Task is complete only after both checks pass.
+```
+
+#### Variable bindings
+
+| Variable | Source |
+|---|---|
+| `{topic}` | `outline.yaml#/topic` |
+| `{item_related_info}` | the item's full YAML block (`name`, `category`, `description`, etc.) |
+| `{output_dir}` | `outline.yaml#/execution/output_dir` (default `./results`) |
+| `{fields_path}` | `$PROJECT_ROOT/agents/research/{topic_slug}/fields.yaml` |
+| `{output_path}` | `{output_dir}/{slug(item.name)}.json` |
+
+### Step 4 — Wait and monitor
+
+Wait for the current batch to finish (all per-item JSON files written
++ validated). Display per-item status (`✅ done`, `⚠️ uncertain`,
+`❌ failed`) before moving on.
+
+### Step 5 — Summary report
+
+After all batches complete, print:
+
+- Total items · completed · uncertain · failed.
+- Output directory.
+- Pointer to `/research:report` for the next phase.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── outline.yaml
+  ├── fields.yaml
+  └── {output_dir}/
+        ├── {slug(item_a)}.json
+        ├── {slug(item_b)}.json
+        └── …
+```
+
+## Portability notes
+
+- **No Python runtime** — validator dropped at adoption, replaced by
+  the in-memory JSON-Schema check + `jq -e` escape hatch (`jq` is
+  optional; agents skip it gracefully if not installed and report
+  `⚠️ jq missing — well-formedness not verified`).
+- **No `~/.claude/` paths** — every reference is rooted at
+  `$PROJECT_ROOT/agents/research/`.
+- **No `web-search-agent` persona** — uses the host agent's native
+  web-search tool.
+
+## ADOPT citation
+
+Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
+`@dc18cf4:skills/research-en/research-deep/SKILL.md` · MIT License.
+Refactored:
+dropped Pydantic validator + `~/.claude/` paths + `web-search-agent`
+persona, added `--batch-confirm` flag, kept the per-item prompt
+structure verbatim except for the validation block.

package/.agent-src/commands/research/report.md

@@ -0,0 +1,134 @@
+---
+name: research:report
+cluster: research
+sub: report
+description: "Summarise per-item JSON results from `/research:deep` into `report.md`. Agent renders directly + emits an optional `jq` template for deterministic regeneration. No Python runtime."
+disable-model-invocation: true
+skills: [deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "summarise research results, build research report, render outline.yaml results"
+  trigger_context: "user has finished `/research:deep` and wants a single markdown summary"
+---
+
+# /research:report
+
+Reads the per-item JSON files emitted by
+[`/research:deep`](deep.md), asks the user which fields to surface in
+the table of contents, then writes `{topic_slug}/report.md` directly.
+Optionally emits `{topic_slug}/report-template.jq` so the same report
+can be regenerated deterministically without re-invoking the agent.
+
+## Trigger
+
+`/research:report`
+
+## Workflow
+
+### Step 1 — Locate results
+
+Find `$PROJECT_ROOT/agents/research/*/outline.yaml` (single match) or
+ask via numbered options. Read `topic`, `topic_slug`, and
+`execution.output_dir`.
+
+### Step 2 — Scan summary-field candidates
+
+Read every `*.json` in `{output_dir}/`. Collect field names whose
+values are short / numeric (e.g. `github_stars`,
+`google_scholar_cites`, `swe_bench_score`, `user_scale`, `valuation`,
+`release_date`). Filter:
+
+- numeric scalars (int / float),
+- short strings (≤ 40 chars), or
+- ISO-8601 dates.
+
+### Step 3 — Ask user (numbered options)
+
+Per [`user-interaction`](../../rules/user-interaction.md) Iron Law,
+offer numbered options for **TOC summary fields** drawn from the
+candidate list. Allow multi-select (e.g., *"1, 3, 5"*) plus *"none"*.
+
+### Step 4 — Render `report.md` directly
+
+The agent itself reads each JSON + `fields.yaml` + the user's TOC
+choices, then writes `{topic_slug}/report.md`. **No `generate_report.py`
+script, no Python runtime.**
+
+#### Required structure
+
+1. **Title** — `# {topic} — Research Report`.
+2. **TOC** — every item, anchor-linked, with the chosen summary fields
+   inline. Example:
+   `1. [GitHub Copilot](#github-copilot) — Stars: 10k · Score: 85%`.
+3. **Detailed sections** — one `## {item.name}` per item, then
+   `### {category}` per category from `fields.yaml`, then field
+   key/value rows.
+
+#### Rendering rules
+
+| Rule | Behaviour |
+|---|---|
+| **JSON shape** | Support flat (`{"name": "…"}`) and nested (`{"basic_info": {"name": "…"}}`) layouts. Lookup order: top-level → category mapping → recursive walk. |
+| **Category mapping** | Maintain a bidirectional alias map between `fields.yaml` category labels and JSON keys (e.g. `"Basic info" ↔ "basic_info"`). Use language-neutral keys, no hard-coded English/Chinese. |
+| **List of dicts** | One row per dict, `key:value` pairs joined with ` \| `. |
+| **Plain list** | Short → comma-joined; long (> 5 items) → bullet list. |
+| **Nested dict** | Recurse; render with `;` between sibling keys or hard-break on long values. |
+| **Long text** | Strings > 100 chars → wrap in a blockquote or insert `<br>`. |
+| **Extra fields** | JSON keys not declared in `fields.yaml` → group under `### Other info`. Filter `_source_file`, `uncertain`, and category-container keys. |
+| **`uncertain` array** | Render each entry on its own line under `### Uncertain fields`; never compress to a one-liner. |
+| **Skip conditions** | Field value contains `[uncertain]` · field name in `uncertain` · value is `null` / empty string. |
+
+### Step 5 — Optional `jq` template (deterministic regenerate)
+
+Also emit `{topic_slug}/report-template.jq` capturing the user's TOC
+choices + rendering rules as a `jq` program. Document the regenerate
+command in the file's leading comment:
+
+```text
+# Regenerate report.md without re-invoking the agent:
+#   jq -rsf report-template.jq results/*.json > report.md
+# Requires: jq ≥ 1.6. Skip this file if jq is unavailable —
+# `report.md` from step 4 is the canonical artefact.
+```
+
+The template is **best-effort**. Agents that cannot fully express
+the rendering rules in `jq` may emit a stub with a `# TODO` comment
+and a pointer back to step 4. The primary deliverable is `report.md`;
+the `jq` template is a power-user convenience.
+
+### Step 6 — Confirm
+
+Print:
+
+- Path to `report.md`.
+- Whether `report-template.jq` was emitted.
+- Item count · category count · skipped-uncertain count.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── report.md             # primary artefact (agent-rendered)
+  └── report-template.jq    # optional, deterministic regen
+```
+
+## Portability notes
+
+- **No Python runtime** — upstream's `generate_report.py` was a
+  Python conversion script; this port shifts the transformation to
+  the agent (primary) + a `jq` template (optional). `augment-portability`
+  Iron Law upheld.
+- **No `~/.claude/` paths** — every reference is rooted at
+  `$PROJECT_ROOT/agents/research/`.
+- **`jq` is optional** — agents skip the template gracefully and
+  surface `⚠️ jq template not emitted` in the summary if generation
+  fails or the dependency is missing.
+
+## ADOPT citation
+
+Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
+`@dc18cf4:skills/research-en/research-report/SKILL.md` · MIT License.
+Refactored: dropped the `generate_report.py` Python script (replaced
+with agent-side rendering + optional `jq` template), kept the
+multilingual category mapping + complex-value formatting rules,
+re-anchored every path under `$PROJECT_ROOT/agents/research/`.

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

@@ -12,15 +12,43 @@ suggestion:
 
 # /research
 
-Entry point for **preliminary research**: pick the objects to study, name
-the fields to fill, and emit a YAML scaffold that a downstream deep-research
-run will populate. Use this when the user names a topic and wants a
-structured plan, not an immediate answer.
+Top-level entry point for the `/research` family. Bare `/research <topic>`
+runs the preliminary scaffolder described under `## Default flow`. Sub-commands
+drive the downstream phases (`:deep` populates the scaffold, `:report`
+summarises the results).
 
 Routes thinking-framework support to
 [`deep-reading-analyst`](../skills/deep-reading-analyst/SKILL.md) (SCQA
 for narrative structure, mental-models lens for object selection).
 
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/research <topic>` (bare) | this file (`## Default flow`) | Pick objects, define fields, emit `outline.yaml` + `fields.yaml` |
+| `/research:deep` | `commands/research/deep.md` | Read scaffold, research each item in batches, write per-item JSON |
+| `/research:report` | `commands/research/report.md` | Summarise per-item JSON into a markdown report (+ optional `jq` template) |
+
+## Dispatch
+
+1. Parse the user's argument: `/research[:<sub>] [args]`.
+2. Bare `/research <topic>` → run the `## Workflow` below verbatim.
+3. `/research:deep` → load `commands/research/deep.md` and follow its
+   `## Workflow` section verbatim.
+4. `/research:report` → load `commands/research/report.md` and follow its
+   `## Workflow` section verbatim.
+5. Unknown sub-command → print the table above and ask which one.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/research[:<sub>]` per turn.
+- If the user invokes `/research` with no argument, **show the menu** —
+  do not guess whether they meant the bare workflow or a sub-command.
+- **Edit `.agent-src.uncompressed/` only.** `.agent-src/` and `.augment/`
+  regenerate from source.
+
 ## Trigger
 
 `/research <topic>`
@@ -126,17 +154,19 @@ $PROJECT_ROOT/agents/research/{topic_slug}/
   └── fields.yaml     # field definitions
 ```
 
-## Out of scope (Phase 2)
+## Out of scope
 
-`/research-deep`, `/research-add-items`, `/research-add-fields`, and the
-Python `validate_json.py` validator are **not** ported in Phase 1 — they
-are queued as follow-up cluster sub-commands.
+`/research:add-items` and `/research:add-fields` are **not** ported —
+the existing scaffolder + sub-commands cover the round-trip; the
+upstream incremental-edit commands are too thin to justify their own
+sub-command. Re-run `/research <topic>` and merge by hand if the
+field framework needs a follow-up adjustment.
 
 ## ADOPT citation
 
 Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
-@ commit `dc18cf4` · upstream file research/SKILL.md inside skills/research-en/ · MIT License.
-Refactored: dropped `web-search-agent` persona (portability), dropped
-Pydantic validator (replaced with JSON-Schema reference), repathed
-`./` → `$PROJECT_ROOT/agents/research/`, deferred `/research-deep` +
-`/research-add-*` to Phase 2.
+`@dc18cf4:skills/research-en/research/SKILL.md` · MIT License.
+Refactored: dropped `web-search-agent` persona
+(portability), dropped Pydantic validator (replaced with JSON-Schema
+reference), repathed `./` → `$PROJECT_ROOT/agents/research/`. Phase 2
+ported `/research:deep` and `/research:report` as cluster sub-commands.

package/.agent-src/skills/feature-planning/SKILL.md

@@ -67,7 +67,7 @@ Explore → Plan → Refine → Roadmap → Implement
 ### Full workflow (complex features, 7 phases)
 
 Use the full workflow for features that span multiple files, require architecture decisions,
-or have unclear requirements. Trigger with `/feature-dev`.
+or have unclear requirements. Trigger with `/feature:dev`.
 
 ```
 Discovery → Exploration → Questions → Architecture → Implementation → Review → Summary
@@ -100,7 +100,7 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 - **Wait for answers before proceeding.**
 
 #### Phase 4: Architecture Design
-- Design 2-3 impl approaches with different tradeoffs:
+- Design 2-3 implementation approaches with different tradeoffs:
   - **Minimal changes** — smallest change, maximum reuse.
   - **Clean architecture** — maintainability, elegant abstractions.
   - **Pragmatic balance** — speed + quality.
@@ -114,7 +114,7 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 - Track progress via task list or roadmap.
 
 #### Phase 6: Quality Review
-- Review the impl for:
+- Review the implementation for:
   - Simplicity, DRY, elegance.
   - Bugs and correctness.
   - Convention adherence.
@@ -136,9 +136,45 @@ Maintain a running **decision log** throughout the planning process. For each de
 Include the decision log in the feature plan file under a `## Decisions` section.
 This ensures future developers (and agents) understand the reasoning, not just the outcome.
 
+## Bite-sized task granularity (structural roadmaps only)
+
+When a feature plan's generated roadmap declares `complexity: structural` in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks ("Add login endpoint", "Update tests") are correct when the work is well-scoped and low-risk.
+
+Structural roadmap tasks must include:
+
+1. **Exact file path** — `app/Modules/Auth/Services/LoginService.php`, never *"the login service"*.
+2. **Complete code** — every method body, import, and signature ready to paste; no `// existing code` ellipses, no `…`.
+3. **Exact command** — `php artisan migrate --path=database/migrations/2026_05_09_create_logins.php`, never *"run the migration"*.
+4. **Expected output** — what success looks like (`Migrated: 2026_05_09_create_logins`) and the exit code.
+5. **No placeholders** — angle-bracket placeholders, `TODO`, `FIXME`, `tbd`, and `???` are blockers; resolve before the task ships.
+
+The complexity flag lives in the roadmap's YAML frontmatter:
+
+```yaml
+---
+complexity: structural   # triggers bite-sized granularity
+# or
+complexity: lightweight  # default — skips bite-sized granularity
+---
+```
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Task Structure + § No Placeholders (v5.1.0); complexity-gating is our addition (Council Round 1, Q4 — mitigates UX pushback for senior engineers on well-scoped work).
+
+## Self-review (3-scan checklist)
+
+Before presenting any plan, run these three scans in order. Each is a fast pass — not a deep review. Failures block presentation; fix and re-scan.
+
+1. **Spec coverage** — every requirement, AC bullet, or constraint from the input has a corresponding section / AC / scope item in the plan. Walk the input top-to-bottom; tick each requirement against the plan; missing items become open questions or new AC.
+2. **Placeholder / TODO scan** — grep the draft for `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX`. Either resolve them now or surface them in the *Open questions* section. No placeholder ships unflagged.
+3. **Type / shape consistency** — proposed data structures, API shapes, file paths, and module names match existing codebase patterns. Cite at least one existing file per new structure as the convention anchor.
+
+This scan is **separate from** adversarial-review (below). Self-review catches mechanical gaps (missing AC, leftover placeholders, mis-shaped types); adversarial-review challenges the plan's reasoning.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Adversarial self-review
 
-After completing a plan, run the **`adversarial-review`** skill before presenting it.
+After the 3-scan self-review passes, run the **`adversarial-review`** skill before presenting.
 Focus on the "Feature plans / Architecture" attack questions. See that skill for the full process.
 
 ## Feature plan format
@@ -183,7 +219,7 @@ module's `agents/` directory:
 Before creating a feature plan, always:
 1. **Search the codebase** for related code, existing patterns, and affected areas.
 2. **Read module docs** if the feature touches a specific module.
-3. **Check existing features** in `agents/features/` for overlap or deps.
+3. **Check existing features** in `agents/features/` for overlap or dependencies.
 
 ### Be collaborative
 
@@ -194,7 +230,7 @@ Before creating a feature plan, always:
 
 ### Keep it navigational
 
-Feature plans are decision documents, not impl guides.
+Feature plans are decision documents, not implementation guides.
 Implementation details belong in roadmaps.
 
 ## Output format
@@ -221,6 +257,6 @@ Implementation details belong in roadmaps.
 
 - Do NOT create feature plans without user input — always collaborate.
 - Do NOT skip codebase research — always check what exists.
-- Do NOT put impl steps in the feature plan — that's the roadmap's job.
+- Do NOT put implementation steps in the feature plan — that's the roadmap's job.
 - Do NOT commit or push without permission.
 - Do NOT duplicate information from `AGENTS.md` or module docs.

package/.agent-src/skills/judge-test-coverage/SKILL.md

@@ -147,6 +147,10 @@ as a follow-up for the implementer — the judge does not execute tools.
   model-pairing rules (`subagents.judge_model` one tier above implementer).
 - [`test-driven-development`](../test-driven-development/SKILL.md) —
   the write-the-test-first workflow that prevents most findings this judge makes.
+- [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) and its
+  sibling [`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md) —
+  prevention layer this judge backs up; rationalization-table row numbers
+  are valid review citations.
 - Sibling judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),
   [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
   [`judge-code-quality`](../judge-code-quality/SKILL.md) — dispatched

package/.agent-src/skills/pest-testing/SKILL.md

@@ -22,6 +22,13 @@ Use this skill for all Laravel testing tasks, especially when working with:
 
 This skill extends `php-coder`, `laravel`, and `eloquent`.
 
+For prevention layers that fire **before** writing a test — TDD
+discipline, mock-isolation gates, and the 12 process rationalizations
+("I'll add the test after", "patch first, test later") — see
+[`test-driven-development`](../test-driven-development/SKILL.md),
+[`testing-anti-patterns`](../testing-anti-patterns/SKILL.md), and
+[`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md).
+
 ## Procedure: Write Pest tests
 
 1. **Read the base skills first** — apply `php-coder`, `laravel`, and `eloquent` where relevant.
@@ -53,9 +60,9 @@ For bug fixes and new features, prefer test-driven development:
 
 ### Why test-first matters
 
-Tests written **after** impl pass immediately. Passing immediately proves nothing:
+Tests written **after** implementation pass immediately. Passing immediately proves nothing:
 - The test might test the wrong thing.
-- The test might test impl, not behavior.
+- The test might test implementation, not behavior.
 - You never saw it catch the bug — so you don't know if it would.
 
 ### Bug fix TDD
@@ -120,7 +127,7 @@ The test proves the fix works AND prevents regression.
 - For JSON APIs, assert:
     - exact relevant fields
     - error structure when applicable
-    - DB state after the request
+    - database state after the request
 - Do not only assert `200` — verify meaningful behavior.
 
 ## Validation tests
@@ -258,7 +265,7 @@ When reviewing or auditing existing tests, check for these anti-patterns:
 
 - Do not test private methods directly.
 - Do not over-mock Laravel internals.
-- Do not assert impl details when behavior assertions are enough.
+- Do not assert implementation details when behavior assertions are enough.
 - Do not write brittle tests tied to formatting or irrelevant response noise.
 - Do not create giant tests that cover many behaviors at once.
 - Do not skip authorization or validation coverage for important endpoints.
@@ -285,7 +292,7 @@ When generating Pest tests:
 - Don't use `readonly` or `final` on Pest test helper classes — it breaks mocking.
 - Don't add `use` statements for global classes (`Exception`, `DateTimeImmutable`) in Pest files — they're auto-imported.
 - The model forgets `$this->travel(5)->seconds()` for time-dependent tests — never rely on `now()` differing between lines.
-- Parallel tests share the DB — don't assume column values are null unless you explicitly set them.
+- Parallel tests share the database — don't assume column values are null unless you explicitly set them.
 
 ## Do NOT
 
@@ -297,7 +304,7 @@ When generating Pest tests:
 When generating new tests, focus on:
 - **Business logic**: calculations, status transitions, validation rules, data transformations
 - **Edge cases**: null, empty string, zero, negative numbers, boundary values, max length
-- **Error paths**: invalid input, missing deps, exception handling
+- **Error paths**: invalid input, missing dependencies, exception handling
 - **Different code branches**: if/else, early returns, fallback behavior
 
 What NOT to test:

package/.agent-src/skills/quality-tools/SKILL.md

@@ -34,6 +34,10 @@ If both PHP and JS/TS files changed → run **both** pipelines.
 - `verify-before-complete` rule — timing: run quality tools ONCE at the end, not after each edit
 - `php-coding` rule → PHPStan section — inline ignores, PHPDoc rules
 - `verify-before-complete` rule — must run quality checks before claiming work is done
+- [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) and
+  [`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md) —
+  test-side rationalizations these tools cannot catch (e.g. "CI is red,
+  patch first, test later").
 
 ---
 

package/.agent-src/skills/refine-prompt/SKILL.md

@@ -126,6 +126,16 @@ The rubric (5 dimensions × 0–2, sum / 10) and band thresholds
 (`high ≥ 0.8`, `medium 0.5–0.79`, `low < 0.5`) are owned by
 `confidence.py`. Do not re-derive them in prose.
 
+### 6. Self-review (3-scan checklist)
+
+Before emitting the envelope, run these three scans. Each is a fast pass; failure blocks emission.
+
+1. **Spec coverage** — every concrete signal from step 2 (constraints) and step 3 (assumptions) is reflected somewhere in the AC list. Walk the constraint list top-to-bottom; each must anchor at least one AC bullet or appear in the *Assumptions* block.
+2. **Placeholder / TODO scan** — the rendered envelope contains no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings. The literal angle-bracket placeholders in the template (`<one sentence …>`, `<bullet>`) must be replaced with concrete text before emission.
+3. **Type / shape consistency** — every named file, module, route, or command in the AC matches the project's existing conventions. If the prompt names `auth.service.ts` but the codebase uses `AuthService.php`, surface the mismatch in *Assumptions* rather than adopting the prompt's spelling.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Band-action mapping
 
 The `refine` dispatcher step in `directives/backend/refine.py` reads

package/.agent-src/skills/refine-ticket/SKILL.md

@@ -250,6 +250,18 @@ open questions surfaced>
 The "Refined ticket" section is wrapped in a **copyable Markdown box**
 so the user can grab it verbatim.
 
+## Self-review (3-scan checklist)
+
+Run these three scans on the rendered output before the close-prompt. Each is a fast pass; failure blocks emission and forces a fix.
+
+1. **Spec coverage** — every AC bullet and constraint from the original ticket (and every parent-AC line surfaced via `fold_parent_context`) is reflected in the rewritten ticket, the Top-5 risks, or the *Open questions* section. Nothing from the input vanishes silently.
+2. **Placeholder / TODO scan** — no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings remain. The angle-bracket placeholders in the template (`<rewritten title>`, `<risk>`, `<one paragraph>`) must be replaced with concrete prose before the close-prompt fires.
+3. **Type / shape consistency** — every module, file, route, or domain term cited in the rewritten ticket and Top-5 risks matches `repo_context.context_docs` and `recent_branches` vocabulary. Invented terms are flagged in *Open questions* or replaced with the project's actual term.
+
+Self-review is mechanical (gaps, leftovers, naming drift); persona voices and orchestration outputs handle reasoning critique. Both run; neither replaces the other.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Close-prompt (mandatory final step)
 
 **Probe write access first (Phase F6).** Before rendering, do a