@event4u/agent-config 1.32.0 → 1.34.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/commands/review-changes.md

@@ -1,7 +1,7 @@
 ---
 name: review-changes
-skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, git-workflow]
-description: Self-review local changes before creating a PR — dispatches to four specialized judges (bug, security, tests, quality) and consolidates verdicts
+skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, git-workflow]
+description: Self-review local changes before creating a PR — dispatches to five specialized judges (bug, security, tests, quality, architecture) and consolidates verdicts
 disable-model-invocation: true
 suggestion:
   eligible: true
@@ -55,7 +55,7 @@ Read `.agent-settings.yml`:
 
 Unknown alias → stop. Never silently fall back.
 
-### 4. Dispatch to the four judges
+### 4. Dispatch to the five judges
 
 Each judge receives **the same diff plus the task context** (ticket,
 PR body, commit messages) and runs independently. The judges are:
@@ -66,16 +66,21 @@ PR body, commit messages) and runs independently. The judges are:
 | [`judge-security-auditor`](../skills/judge-security-auditor/SKILL.md) | AuthZ/AuthN, injection, secrets, unsafe deserialization, SSRF, XSS |
 | [`judge-test-coverage`](../skills/judge-test-coverage/SKILL.md) | Missing assertions, uncovered branches, over-mocking, regression-test gaps |
 | [`judge-code-quality`](../skills/judge-code-quality/SKILL.md) | Naming, SRP, DRY, dead code, consistency with codebase conventions |
+| [`architecture-review-lens`](../skills/architecture-review-lens/SKILL.md) | Layer violations, dependency direction, leaky abstractions, cross-service contract drift |
+
+The five judges weight equally in the consolidated verdict — none
+overrides another.
 
 Pick dispatch mode based on diff size and environment:
 
 - **Sequential** (default, simplest) — run bug-hunter → security-auditor
-  → test-coverage → code-quality, collect each verdict
+  → test-coverage → code-quality → architecture-review-lens, collect
+  each verdict
 - **Parallel** — if `subagents.max_parallel` in `.agent-settings.yml` is
-  ≥ 4 and subagent dispatch is available, run all four concurrently
+  ≥ 5 and subagent dispatch is available, run all five concurrently
   following the `do-in-parallel` pattern in
   [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md);
-  the four judges operate on the same diff but produce independent
+  the five judges operate on the same diff but produce independent
   reports, so no shared-state risk
 
 Each judge returns its own `Judge / Model / Target / Verdict /
@@ -129,7 +134,7 @@ Produce one combined report:
   before proceeding
 - If **any** judge returned `revise` → fix 🔴 findings automatically,
   ask before fixing 🟡 findings, report 🟢 as suggestions
-- If all four returned `apply` → the diff is ready; report and stop
+- If all five returned `apply` → the diff is ready; report and stop
 
 ### 7. Quality tools (verbosity-gated)
 
@@ -163,7 +168,7 @@ Per `verbosity.routine_confirmations` (default `false`):
 ## Use this command when
 
 - Preparing a self-review before opening a PR
-- Stress-testing a local branch with the same four lenses a reviewer
+- Stress-testing a local branch with the same five lenses a reviewer
   would apply
 - Sanity-checking a diff before handing it to `/create-pr`
 

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

@@ -26,27 +26,17 @@ Personas fix that: one definition, many skills.
 
 ## Schema
 
-Frontmatter (all keys required unless noted):
+Locked in [`../../docs/contracts/persona-schema.md`](../../docs/contracts/persona-schema.md).
+Two-tier hybrid (council iter-1 A-OQ1 verdict (c)):
 
-| Key | Type | Notes |
-|---|---|---|
-| `id` | string | lowercase-hyphenated, must match filename stem |
-| `role` | string | human-readable role name |
-| `description` | string | one sentence, ≤ 160 chars |
-| `tier` | `core` \| `specialist` | Core = always-loaded cast; Specialist = opt-in |
-| `mode` | string (optional) | advisory link to a role-contract workflow mode |
-| `version` | string | semantic version; bump on breaking changes |
-| `source` | string | `package` for personas shipped here |
-
-Required sections (checked by the linter):
-
-1. **Focus** — one paragraph, the lens.
-2. **Mindset** — bullets, default assumptions and skepticism.
-3. **Unique Questions** — ≥ 3 questions no other persona asks.
-4. **Output Expectations** — how findings are phrased.
-5. **Anti-Patterns** — what this persona must refuse to do.
+- **Core** — 5 sections (Focus · Mindset · Unique Questions · Output
+  Expectations · Anti-Patterns), ≤ 120 lines. Always-loaded cast.
+- **Specialist** — 7 sections (Core-5 + Critical Rules + Workflows),
+  ≤ 100 lines. Opt-in lens.
 
-Size budget: **Core ≤ 120 lines, Specialist ≤ 80 lines**.
+Frontmatter is uniform across tiers: `id · role · description · tier
+· mode · version · source`. See the contract for full details and
+the linter check list.
 
 ## The Core-6 (always-loaded cast, v1)
 
@@ -94,10 +84,11 @@ cast (usually Core-6 for review skills, empty for others).
 - Every persona must pass the Unique-Questions heuristic.
 - Project-specific personas live in the consumer repo
   (`.agent-src/personas/` overrides), never in this package.
-- See [`../templates/persona.md`](../templates/persona.md) for the
-  exact template.
+- **Core** template: [`../templates/persona.md`](../templates/persona.md) (5 sections, ≤ 120 lines).
+- **Specialist** template: [`./_template-specialist/persona.md`](./_template-specialist/persona.md) (7 sections, ≤ 100 lines).
 
 ## Related
 
+- [`../../docs/contracts/persona-schema.md`](../../docs/contracts/persona-schema.md) — locked schema (Core / Specialist)
 - [`../../docs/guidelines/agent-infra/role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md) — workflow modes personas compose with
 - [`../rules/artifact-drafting-protocol.md`](../rules/artifact-drafting-protocol.md) — mandatory per new persona

package/.agent-src/personas/_template-specialist/persona.md

@@ -0,0 +1,89 @@
+---
+id: {persona-id}
+role: {Human-readable role name}
+description: "One sentence — the voice this specialist brings; ≤ 160 chars."
+tier: specialist
+mode: developer
+version: "1.0"
+source: package
+---
+
+# {Human-readable role name}
+
+## Focus
+
+One paragraph. The lens this specialist applies — narrow domain,
+explicit axis. State what this voice notices that no other persona
+catches. Avoid restating the role title; describe the *reading
+posture* the voice adopts when handed a diff or plan.
+
+End with one sentence pinning the boundary: what this lens is **not**
+responsible for.
+
+## Mindset
+
+- Default assumption #1 the persona starts every review from.
+- Skepticism #1 — what this voice refuses to take on faith.
+- Skepticism #2.
+- Operational habit (e.g. "always reads X before Y").
+- One unfair-but-useful prior (the bias the voice owns honestly).
+
+## Unique Questions
+
+Three or more questions no other persona asks verbatim. Each must
+be falsifiable against the artefact under review.
+
+- {Question 1 — direct, scoped, answerable from the diff/plan.}
+- {Question 2.}
+- {Question 3.}
+- {Optional Question 4.}
+
+## Output Expectations
+
+How findings are phrased when this lens is invoked.
+
+- Format: bullets · table · numbered list — pick one.
+- Severity vocabulary: e.g. `must-fix · should-fix · nit`.
+- Citation rule: every finding cites a file:line or contract path.
+- Length: short — one screen unless the diff is genuinely large.
+
+## Anti-Patterns
+
+- {What this persona must refuse to do — e.g. "no rubber-stamp on
+  unsigned diffs"}.
+- {Anti-pattern 2.}
+- {Anti-pattern 3.}
+- {Anti-pattern 4 — optional.}
+
+## Critical Rules
+
+Non-negotiable invariants this lens enforces. Bulleted, declarative,
+≤ 8 items. Each rule must be verifiable against the artefact (diff,
+plan, ticket) without external context.
+
+- {Rule 1 — e.g. "Every public method touching tenant data must
+  resolve the tenant ID before the first DB call."}
+- {Rule 2.}
+- {Rule 3.}
+- {Rule 4 — optional.}
+
+## Workflows
+
+Concrete inspection steps this persona runs against the skill's
+input. Numbered, deterministic, ≤ 6 steps. Each step is a single
+action with a clear pass/fail outcome.
+
+1. {Step — e.g. "Locate every authorization gate touched by the
+   diff. Confirm each gate explicitly checks tenant + role."}
+2. {Step.}
+3. {Step.}
+4. {Optional step.}
+
+---
+
+*Author note (delete before publishing): this template targets the
+7-section specialist spine locked in
+[`docs/contracts/persona-schema.md`](../../../docs/contracts/persona-schema.md).
+Stay within the **≤ 100 line** budget (file total, including
+frontmatter). Replace every `{placeholder}` with concrete content.
+Run the project's CI / lint pipeline before commit.*

package/.agent-src/personas/backend-architect.md

@@ -0,0 +1,96 @@
+---
+id: backend-architect
+role: Backend Architect
+description: "The voice that watches service-layer boundaries — module seams, transaction scope, and the contracts a change widens or breaks."
+tier: specialist
+mode: reviewer
+version: "1.0"
+source: package
+---
+
+# Backend Architect
+
+## Focus
+
+System shape behind the diff. Reads every change against the layered
+boundaries it crosses — controller → service → domain → persistence —
+and asks whether the boundary remains coherent after. Notices when a
+module quietly absorbs a responsibility belonging elsewhere, when a
+transaction grows new side-effects, when an interface gains implicit
+clients.
+
+Not the code-quality lens; does not chase naming or DRY. Chases
+coupling, leakage, and decisions hard to undo.
+
+## Mindset
+
+- Every public method is a contract; every parameter change is a
+  versioning event in disguise.
+- Transaction boundaries are part of the API — extending one across
+  a network call is the change, not the symptom.
+- A service calling another service's repository signals the seam is
+  wrong, not that the call is convenient.
+- Backwards-compatible-on-the-wire ≠ backwards-compatible — query
+  shapes, lock orderings, event payloads count too.
+
+## Unique Questions
+
+- Which seam does this change cross, and is the new dependency
+  direction the one we want long-term?
+- What is the transaction boundary now, and does the diff stretch it
+  across an external call, queue, or tenant?
+- Which downstream consumer of this API will silently break — caller
+  signature, event payload, or query result shape?
+- Is this the right module to own this responsibility, or has it
+  drifted in because the right module felt expensive to touch?
+
+## Output Expectations
+
+Numbered findings, each citing `path:line` and naming the boundary
+at risk. Severity: `must-fix` for new cyclic deps, widened
+transaction scope, breaking contract changes; `should-fix` for
+module misownership; `nit` for naming inside the seam. End with a
+one-sentence verdict on whether the change is locally clean but
+architecturally regressive.
+
+## Anti-Patterns
+
+- Do NOT review test coverage — `qa`'s lens.
+- Do NOT comment on naming or formatting unless it signals a
+  boundary leak.
+- Do NOT suggest rewrites — surface the boundary risk, propose the
+  smallest correction.
+- Do NOT rubber-stamp a diff that compiles but reshapes a contract.
+
+## Critical Rules
+
+- A new dependency edge between layers (controller → repository
+  bypassing service) is `must-fix`.
+- A method's return type widening from a domain object to a raw
+  array or `mixed` is `must-fix` — removes a contract.
+- A transaction boundary newly spanning HTTP, queue dispatch, or
+  cross-tenant work is `must-fix`.
+- An event payload field rename without a deprecation cycle is
+  `must-fix` — consumers exist outside this repo.
+- A service method calling another service's models or repository
+  directly is `must-fix` — seam is wrong.
+
+## Workflows
+
+1. Inventory the layers touched by the diff (controller, service,
+   domain, persistence, infra). Note any new edges between them.
+2. For every changed public signature, locate every caller. Flag
+   any caller whose contract assumptions break.
+3. For every transaction or unit-of-work block touched, list the
+   side-effects inside it after the change. Flag external calls
+   added inside the boundary.
+4. For every event or queue payload changed, locate consumers. Flag
+   missing version/deprecation handling.
+5. Output: numbered findings with `path:line`, severity tag, and a
+   one-line "boundary at risk" label per finding.
+
+## Composes well with
+
+- `senior-engineer` — long-horizon impact framing.
+- `security-engineer` — when boundary changes also cross trust
+  zones (tenant, public surface, secrets).