@gempack/squad-mcp 0.5.0 → 0.6.0

package/README.md

@@ -75,20 +75,31 @@ node dist/index.js
 
 ### Tools (deterministic, pure functions)
 
-| Tool | Purpose |
-|------|---------|
-| `detect_changed_files` | Hardened `git diff --name-status --no-renames` for a workspace. Allowlisted refs, 10s timeout, 1MB stdout cap. |
-| `classify_work_type` | Heuristic `WorkType` from prompt + paths (`Feature` / `Bug Fix` / `Refactor` / `Performance` / `Security` / `Business Rule`) with Low/Medium/High confidence. |
-| `score_risk` | Compute Low/Medium/High from boolean signals (auth, money, migration, files_count, new_module, api_change). |
-| `select_squad` | Select advisory agents for a work type. Combines matrix + path hints + content sniff. Returns evidence per file. |
-| `slice_files_for_agent` | Filter a file list to those owned by a single agent. Used to build sliced advisory prompts. |
-| `validate_plan_text` | Advisory check for inviolable-rule violations in a plan (commit/push fences, emojis in code blocks, non-English identifiers, impl-before-approval). |
-| `compose_squad_workflow` | One-call pipeline: `detect_changed_files` → `classify_work_type` → `score_risk` → `select_squad`. |
-| `compose_advisory_bundle` | One-call full bundle: `compose_squad_workflow` + `slice_files_for_agent` per selected agent + `validate_plan_text`. |
-| `apply_consolidation_rules` | Aggregate advisory reports → final verdict (APPROVED / CHANGES_REQUIRED / REJECTED). |
-| `list_agents` | List configured agents with role, ownership, naming conventions. |
-| `get_agent_definition` | Return the full markdown system prompt for an agent (local override → embedded default). |
-| `init_local_config` | Copy embedded defaults to the local override directory so they can be edited. |
+| Tool                        | Purpose                                                                                                                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `detect_changed_files`      | Hardened `git diff --name-status --no-renames` for a workspace. Allowlisted refs, 10s timeout, 1MB stdout cap.                                                                                                           |
+| `classify_work_type`        | Heuristic `WorkType` from prompt + paths (`Feature` / `Bug Fix` / `Refactor` / `Performance` / `Security` / `Business Rule`) with Low/Medium/High confidence.                                                            |
+| `score_risk`                | Compute Low/Medium/High from boolean signals (auth, money, migration, files_count, new_module, api_change).                                                                                                              |
+| `select_squad`              | Select advisory agents for a work type. Combines matrix + path hints + content sniff. Returns evidence per file.                                                                                                         |
+| `slice_files_for_agent`     | Filter a file list to those owned by a single agent. Used to build sliced advisory prompts.                                                                                                                              |
+| `validate_plan_text`        | Advisory check for inviolable-rule violations in a plan (commit/push fences, emojis in code blocks, non-English identifiers, impl-before-approval).                                                                      |
+| `compose_squad_workflow`    | One-call pipeline: `detect_changed_files` → `classify_work_type` → `score_risk` → `select_squad`.                                                                                                                        |
+| `compose_advisory_bundle`   | One-call full bundle: `compose_squad_workflow` + `slice_files_for_agent` per selected agent + `validate_plan_text`.                                                                                                      |
+| `apply_consolidation_rules` | Aggregate advisory reports → final verdict (APPROVED / CHANGES_REQUIRED / REJECTED). Returns weighted rubric scorecard when reports carry per-dimension scores.                                                          |
+| `score_rubric`              | Pure rubric calculator. Takes per-agent scores (0-100) + optional weight overrides, returns weighted score, per-dimension breakdown, and pre-formatted ASCII scorecard.                                                  |
+| `read_squad_config`         | Read and resolve `.squad.yaml` (or `.squad.yml`) at workspace_root. Returns effective weights, threshold, min_score, skip_paths, disable_agents.                                                                         |
+| `read_learnings`            | Load past accept/reject decisions from `.squad/learnings.jsonl`. Filters by agent / decision / changed-file scope. Returns entries plus a markdown block ready to inject into agent or consolidator prompts.             |
+| `record_learning`           | Append one accept/reject decision to `.squad/learnings.jsonl`. Side-effecting; the skill (or CLI) is responsible for per-finding user authorisation.                                                                     |
+| `compose_prd_parse`         | Build a prompt + JSON schema for the host LLM to decompose a PRD into atomic tasks. Pure-MCP: server does NO LLM calls. Caller (skill) feeds the prompt to its model, then calls `record_tasks` after user confirmation. |
+| `list_tasks`                | Read tasks from `.squad/tasks.json`. Filters: status, agent (matches `agent_hints`), changed_files (glob match against task `scope`).                                                                                    |
+| `next_task`                 | Pick the next ready task: candidate status (default pending), all dependencies done, optional agent / changed_files filter. Tiebreak priority then id. Returns null + reason when none ready.                            |
+| `record_tasks`              | Bulk-create tasks. Allocates ids sequentially, validates dependencies resolve (forward refs in batch ok), rejects duplicates and self-deps. Atomic write.                                                                |
+| `update_task_status`        | Flip a task or subtask status: pending / in-progress / review / done / blocked / cancelled.                                                                                                                              |
+| `expand_task`               | Append subtasks to an existing task. Mechanical only — caller (skill or LLM) supplies the subtask inputs.                                                                                                                |
+| `slice_files_for_task`      | Filter a file list to those matching a task's `scope` glob. Same glob primitive as `skip_paths` and learnings scope.                                                                                                     |
+| `list_agents`               | List configured agents with role, ownership, naming conventions.                                                                                                                                                         |
+| `get_agent_definition`      | Return the full markdown system prompt for an agent (local override → embedded default).                                                                                                                                 |
+| `init_local_config`         | Copy embedded defaults to the local override directory so they can be edited.                                                                                                                                            |
 
 ### Prompts
 
@@ -98,20 +109,27 @@ node dist/index.js
 
 ### Resources
 
-- `agent://po`, `agent://tech-lead-planner`, `agent://tech-lead-consolidator`, `agent://senior-architect`, `agent://senior-dba`, `agent://senior-developer`, `agent://senior-dev-reviewer`, `agent://senior-dev-security`, `agent://senior-qa`.
+- `agent://product-owner`, `agent://tech-lead-planner`, `agent://tech-lead-consolidator`, `agent://senior-architect`, `agent://senior-dba`, `agent://senior-developer`, `agent://senior-dev-reviewer`, `agent://senior-dev-security`, `agent://senior-qa`. (Renamed from PascalCase / `po` in v0.6.0 — older 0.5.x consumers must use `agent://po` instead.)
 - `severity://_severity-and-ownership` — severity matrix + ownership rules.
 - `severity://skill-squad-dev`, `severity://skill-squad-review` — full skill specs.
 
 ### Bundled skills
 
-The plugin auto-registers these skills via `skills/` (or sync them to `~/.claude/skills/` for non-plugin clients with `node tools/sync-agents.mjs`):
+The plugin auto-registers these skills via `skills/`:
 
-| Skill | Trigger | Purpose |
-|-------|---------|---------|
-| `/squad` | implementation workflow | Builds an approved plan, distributes work to specialist agents in parallel, implements the change, consolidates via tech-lead. Optional `--codex` second-opinion. New `--quick` mode reduces to 1 specialist + tech-lead with terse prompts (mutually exclusive with `--codex`; auto-fallback to normal mode on security/data-layer scope). |
-| `/squad-review` | multi-perspective review | Auto-detects affected domains, spawns specialist agents in parallel, scores on a weighted rubric (Code Quality 20%, Security 20%, Maintainability 20%, Performance 20%, Async/Concurrency 8%, Error Handling 7%, Architecture Fit 5%), tech-lead consolidates the verdict. New `--quick` mode for fast iteration. |
-| `/brainstorm` | pre-implementation research | Web research in parallel + specialist agent perspectives → options matrix with cited sources and a recommendation. Produces no code. Position: `/brainstorm` decides what to build, `/squad` implements, `/squad-review` reviews. |
-| `/commit-suggest` | commit message generator | Read-only suggester for Conventional Commits messages. Runs only an allowlist of git commands; never executes mutations; never adds AI co-author trailers. The user runs the commit themselves. |
+| Skill             | Trigger                     | Purpose                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/squad`          | implementation workflow     | Single skill, two modes. `/squad <task>` builds an approved plan, distributes work to specialist subagents in parallel, implements the change, consolidates via tech-lead. `/squad-review [target]` is the same skill in review mode — never implements, just produces an advisory verdict on an existing diff/branch/PR. Optional `--codex` second-opinion. |
+| `/brainstorm`     | pre-implementation research | Web research in parallel + specialist agent perspectives → options matrix with cited sources and a recommendation. Produces no code. Position: `/brainstorm` decides what to build, `/squad` implements, `/squad-review` reviews.                                                                                                                            |
+| `/commit-suggest` | commit message generator    | Read-only suggester for Conventional Commits messages. Runs only an allowlist of git commands; never executes mutations; never adds AI co-author trailers. The user runs the commit themselves.                                                                                                                                                              |
+
+### Bundled subagents
+
+The plugin's `agents/` directory registers nine native Claude Code subagents you can also dispatch directly via `Task(subagent_type=…)`:
+
+`product-owner`, `senior-architect`, `senior-dba`, `senior-developer`, `senior-dev-reviewer`, `senior-dev-security`, `senior-qa`, `tech-lead-planner`, `tech-lead-consolidator`.
+
+The `/squad` skill orchestrates them. For non-Claude-Code MCP clients (Cursor, Claude Desktop, Warp), the same role markdowns are accessible through the MCP `agent://…` resources and `get_agent_definition` tool.
 
 Workflow positioning:
 
@@ -127,6 +145,236 @@ Workflow positioning:
 
 See [INSTALL.md](INSTALL.md#bundled-skills) for trigger examples and the optional `commit-msg` git hook + `permissions.deny` snippet that hard-enforce the read-only and no-AI-attribution invariants at the OS / Claude Code layer.
 
+## Repo configuration — `.squad.yaml`
+
+Drop a `.squad.yaml` (or `.squad.yml`) at the repo root to override defaults per-project. Versioned with the code, picked up automatically by `compose_squad_workflow` and `compose_advisory_bundle`.
+
+```yaml
+# .squad.yaml — example for a regulated fintech backend
+
+# Rubric weights (must sum to 100 across the agents you list).
+# Agents NOT listed are zeroed out — listing weights is an explicit choice
+# of which dimensions count for this repo.
+weights:
+  senior-dev-security: 30 # PCI compliance — security weighted higher
+  senior-dba: 22 # double-entry ledger, money on the line
+  senior-developer: 20
+  senior-architect: 15
+  senior-qa: 13
+
+# Per-dimension flag threshold (default 75). Below this, the dimension is
+# marked with ⚠ in the scorecard.
+threshold: 80
+
+# Quality floor: APPROVED with weighted score below this becomes
+# CHANGES_REQUIRED. Severity rules (Blocker/Major) take precedence.
+min_score: 75
+
+# Files excluded from advisory. Glob syntax: ** for any depth, * for one
+# segment, ? for one char. Useful for docs-only or generated paths.
+skip_paths:
+  - "docs/**"
+  - "**/*.md"
+  - "**/generated/**"
+  - "vendor/**"
+
+# Agents not relevant for this repo (e.g. internal tool, no PO involved).
+disable_agents:
+  - product-owner
+```
+
+All keys are optional; partial files merge with package defaults. `force_agents` in tool calls still wins over `disable_agents` (config is a default policy, not a veto over explicit caller intent). Validation is strict: weights that don't sum to 100, unknown agent names, or invalid threshold ranges are rejected with a clear error.
+
+The reader is cached by mtime — long-running MCP servers automatically pick up edits without a restart.
+
+## Learnings — persistent accept/reject memory
+
+Each time the team accepts or rejects an advisory finding, the decision can be appended to `.squad/learnings.jsonl`. Future runs of the squad load recent decisions and inject them into per-agent and consolidator prompts so the squad stops re-raising findings the team has already considered.
+
+```jsonl
+{"ts":"2026-04-12T15:02:31Z","pr":42,"agent":"senior-dev-security","severity":"Major","finding":"missing CSRF on POST /api/refund","decision":"reject","reason":"CSRF terminated at API gateway, see infra/edge.tf","scope":"src/api/**"}
+{"ts":"2026-04-15T09:18:11Z","pr":47,"agent":"senior-architect","severity":"Major","finding":"cross-module coupling Auth → Billing","decision":"accept","reason":"refactored to event bus"}
+```
+
+The file lives in git. Decisions are auditable in PR diffs.
+
+### Recording decisions
+
+Inside Claude Code, after `/squad-review` produces the verdict, tell the skill to record:
+
+```
+record reject senior-dev-security "missing CSRF on POST /api/refund"
+  reason: CSRF terminated at API gateway
+  scope: src/api/**
+```
+
+The skill confirms each decision and calls the `record_learning` MCP tool. **Per-finding authorisation is required** — silence or "thanks" is not authorisation.
+
+For non-MCP environments, use the CLI helper:
+
+```bash
+node tools/record-learning.mjs --reject \
+  --agent senior-dev-security \
+  --finding "missing CSRF on POST /api/refund" \
+  --reason "CSRF terminated at API gateway" \
+  --scope "src/api/**" \
+  --pr 42
+```
+
+### How the squad uses them
+
+In Phase 5 (per-agent advisory) the skill calls `read_learnings(workspace_root, agent, changed_files)` and injects the rendered `## Past team decisions` block into the agent's prompt. In Phase 10 (consolidator) it does the same without an agent filter — the consolidator sees the full picture across agents.
+
+Each agent is told: when a current finding matches a previously **rejected** decision (similar agent + similar finding text + matching scope), suppress or downgrade severity unless the diff materially changes the rationale. When a finding contradicts a previously **accepted** decision, flag the contradiction explicitly.
+
+### Configuration
+
+Override defaults via `.squad.yaml`:
+
+```yaml
+learnings:
+  path: .squad/learnings.jsonl # default
+  max_recent: 50 # how many recent entries to inject (hard cap 200)
+  enabled: true # set false to disable injection without deleting the journal
+```
+
+The store reader is mtime-cached. The journal is append-only by design — the skill never amends or deletes past entries; correcting a stale decision means appending a new one.
+
+## Tasks — PRD-decomposed atomic work units
+
+The biggest source of token bloat in a long-running squad session is the squad re-analysing the whole repo for every prompt. The tasks store fixes that by decomposing a PRD into atomic tasks up front, then running the squad on ONE task's narrowed scope at a time.
+
+```jsonc
+// .squad/tasks.json (excerpt)
+{
+  "version": 1,
+  "tasks": [
+    {
+      "id": 1,
+      "title": "Add CSRF token to checkout flow",
+      "status": "done",
+      "dependencies": [],
+      "priority": "high",
+      "scope": "src/api/checkout/**",
+      "agent_hints": ["senior-dev-security", "senior-developer"],
+      "test_strategy": "POST without token → 403; POST with token → 200.",
+      "subtasks": [],
+      "created_at": "2026-05-08T12:00:00Z",
+      "updated_at": "2026-05-09T15:30:00Z"
+    },
+    {
+      "id": 2,
+      "title": "Wire CSRF middleware into refund endpoint",
+      "status": "pending",
+      "dependencies": [1],
+      "priority": "high",
+      "scope": "src/api/refund/**",
+      "subtasks": [],
+      ...
+    }
+  ]
+}
+```
+
+`scope` (glob) and `agent_hints` are squad-mcp-specific additions on top of the claude-task-master shape — they let `slice_files_for_task` and `compose_squad_workflow` narrow the advisory automatically.
+
+### Decomposing a PRD
+
+Inside Claude Code:
+
+```
+/squad-tasks docs/prd-payments-refactor.md
+```
+
+The skill (Phase 0.5):
+
+1. Calls `compose_prd_parse` with the PRD text.
+2. Receives a prompt + JSON schema and runs them through Claude.
+3. Shows you the parsed tasks — title, deps, priority, scope, agent_hints — for review.
+4. Calls `record_tasks` only after you say "record" / "go" / "yes".
+
+The parse is **pure-MCP**: the squad-mcp server never makes LLM calls. The host (Claude Code, Cursor, Warp) does the inference. No provider keys in the server, no surprises for non-Claude clients.
+
+### Working tasks
+
+```
+/squad-next                # picks the highest-priority ready task
+/squad-task 5              # explicit pick by id
+```
+
+For each task:
+
+- `slice_files_for_task` narrows the changed-files list to the task's `scope`.
+- `compose_squad_workflow` runs against that slice; if `agent_hints` is set, only those agents wake up.
+- Phase 1 onward proceeds normally, just with much less context.
+- When done, the skill flips status to `done` via `update_task_status`.
+
+### Configuration
+
+Override defaults via `.squad.yaml`:
+
+```yaml
+tasks:
+  path: .squad/tasks.json # default
+  enabled: true # set false to silence reads without deleting the file
+```
+
+Writes (`record_tasks`, `update_task_status`, `expand_task`) stay open even when reads are disabled — same policy as learnings. Disabling injection should not throw away the journal.
+
+### CLI for non-MCP environments
+
+Mirroring the post-review and record-learning helpers:
+
+```bash
+# decompose offline (you generate the JSON yourself or via another tool)
+echo '[{"title":"Add CSRF","scope":"src/api/**"}]' | node tools/record-tasks.mjs
+
+# inspect
+node tools/list-tasks.mjs --status pending
+node tools/next-task.mjs --json
+
+# flip status from CI
+node tools/update-task-status.mjs --task 5 --status done
+```
+
+The CLIs share `tools/_tasks-io.mjs` for read/write and require only node 18+. Schema validation is lighter than the MCP tool — production use should prefer the MCP path.
+
+## Posting reviews to GitHub PRs
+
+Once the squad runs, you can post the verdict + scorecard as a `gh pr review` directly. The skill `/squad-review #42` runs the advisory and offers to post the result; default behaviour is **dry-run + confirmation** — Claude shows the exact `gh` command and the markdown body, then waits for your "go" before posting.
+
+```bash
+# manual usage (outside the skill)
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42 --dry-run
+# prints: gh pr review 42 --approve --body-file - <<'EOF' ... EOF
+
+# actually post
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42
+```
+
+The CLI maps verdict → `gh` action deterministically:
+
+| Verdict                                            | Score signal           | `gh` action                        |
+| -------------------------------------------------- | ---------------------- | ---------------------------------- |
+| `REJECTED`                                         | —                      | `--request-changes` (blocks merge) |
+| `CHANGES_REQUIRED`                                 | —                      | `--comment` (advisory)             |
+| `APPROVED` + `downgraded_by_score: true`           | weighted < `min_score` | `--comment`                        |
+| `APPROVED` + score < `request_changes_below_score` | (opt-in floor)         | `--request-changes`                |
+| `APPROVED` otherwise                               | passes threshold       | `--approve`                        |
+
+### Auto-post (opt-in)
+
+If `.squad.yaml` has `pr_posting.auto_post: true`, the skill posts without the second confirmation prompt — but **always shows the body first**. Auto-post means "skip the second yes/no", not "skip the preview".
+
+```yaml
+pr_posting:
+  auto_post: true # default false — always asks
+  request_changes_below_score: 50 # below this, post --request-changes instead of --approve
+  omit_attribution_footer: false # default false — footer present
+```
+
+Requires `gh` CLI in PATH and authenticated (`gh auth login`). The CLI exits 3 with a clear message if `gh` is missing.
+
 ## Detection strategy (`select_squad` / `slice_files_for_agent`)
 
 Three layers, in order of strength:
@@ -158,12 +406,17 @@ Run the `init_local_config` tool once to seed the local directory with editable
 squad-mcp/
 ├── .claude-plugin/             # Claude Code plugin manifest + marketplace
 ├── .github/workflows/          # CI + release workflows
-├── agents/                     # Bundled agent markdown defaults
-├── commands/                   # Plugin slash commands (/squad, /squad-review, /brainstorm, /commit-suggest)
-├── skills/                     # Bundled skills (commit-suggest, brainstorm)
+├── agents/                     # Native subagents + shared docs
+│   ├── *.md                    # 9 subagent definitions (kebab-case, with frontmatter)
+│   └── _shared/                # severity matrix + skill specs (not loaded as subagents)
+├── commands/                   # Slash commands (/squad, /squad-review, /brainstorm, /commit-suggest)
+├── skills/                     # Bundled skills
+│   ├── squad/                  # single skill, two modes (implement | review)
+│   ├── brainstorm/
+│   └── commit-suggest/
 ├── src/
 │   ├── index.ts                # stdio entry
-│   ├── tools/                  # MCP tools (12 deterministic functions)
+│   ├── tools/                  # MCP tools (23 deterministic functions)
 │   ├── resources/              # MCP resources + agent loader
 │   ├── prompts/                # MCP prompt templates
 │   ├── exec/git.ts             # hardened git execution layer
@@ -173,7 +426,6 @@ squad-mcp/
 │       └── ownership-matrix.ts # agents, work types, content/path patterns
 ├── tests/                      # vitest unit + integration + stdio smoke
 ├── tools/
-│   ├── sync-agents.mjs         # mirror agents + skills into ~/.claude/ for non-plugin clients
 │   └── git-hooks/commit-msg    # opt-in hook rejecting AI-attribution trailers
 └── dist/                       # compiled JS (gitignored, shipped via npm)
 ```

package/agents/{PO.md → product-owner.md}

@@ -1,6 +1,12 @@
+---
+name: product-owner
+description: Product Owner. Validates business value, functional requirements, and UX. Use for features, business-rule changes, and user-facing surfaces.
+model: inherit
+---
+
 # PO (Product Owner)
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Business representative in technical review. Ensures every implementation delivers real value to the end user and aligns with product goals.
@@ -82,3 +88,29 @@ Objective summary of the evaluation.
 - Be pragmatic: not every gap is a blocker, classify by severity
 - Frame impact in business terms, not technical ones
 - Without a user story, judge by observable behavior and product common sense
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Business & UX`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: requirement matches the change; UX clear; business value evident.
+- 70-89: minor mismatch with stated requirement or UX awkwardness.
+- **50-69: one Major — business rule contradicted, UX broken on critical flow, requirement absent.**
+- 30-49: change does not deliver claimed value; conflicts with PO intent.
+- 0-29: should not be built; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.

package/agents/{Senior-Architect.md → senior-architect.md}

@@ -1,6 +1,12 @@
+---
+name: senior-architect
+description: Senior Architect. Guards module boundaries, coupling, dependency direction, DI lifetimes, and scalability. Use for structural changes and new modules.
+model: inherit
+---
+
 # Senior-Architect
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Guardian of architectural integrity. Evaluates design decisions with a long-term lens and keeps the solution from eroding boundaries.
@@ -119,3 +125,29 @@ Summary of the diagnosis and long-term view.
 - Distinguish "ideal" from "acceptable for now"
 - Avoid astronaut architecture — prefer pragmatic solutions
 - If the issue is implementation (not design), forward to the right agent
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Architecture`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: clean module/domain boundaries, DI lifetimes correct, no coupling regression, extensibility clear.
+- 70-89: minor issues (over-eager abstraction, ambiguous responsibility split) but no actionable Major.
+- **50-69: at least one Major (cross-module coupling, wrong DI lifetime, hidden mutable state).**
+- 30-49: multiple Majors or one Blocker that endangers structural integrity.
+- 0-29: architecture-level break; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.

package/agents/{Senior-DBA.md → senior-dba.md}

@@ -1,6 +1,12 @@
+---
+name: senior-dba
+description: Senior DBA. Reviews queries, migrations, EF mappings, cache, concurrency, and persistence stack. Use for data-layer changes.
+model: inherit
+---
+
 # Senior-DBA
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Data specialist. Ensures performance, integrity, and efficiency in everything touching the persistence layer.
@@ -135,3 +141,29 @@ Summary and prioritized risks.
 - Be conservative with migrations — prefer additive operations
 - Challenge every query without WHERE or with SELECT *
 - Validate suggested indexes do not degrade write performance
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Data Layer`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: queries efficient, migrations safe and reversible, EF mappings correct, no concurrency hazard.
+- 70-89: minor inefficiencies or missing indexes; no data-integrity risk.
+- **50-69: one Major — N+1 query, missing transaction, broken concurrency control, mismatched stack mix.**
+- 30-49: data integrity at risk (race, lost update, irreversible migration without backout).
+- 0-29: data corruption likely; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.

package/agents/{Senior-Dev-Reviewer.md → senior-dev-reviewer.md}

@@ -1,6 +1,12 @@
+---
+name: senior-dev-reviewer
+description: Senior code reviewer. Focuses on readability, code smells, naming, idioms, async/await correctness, and error handling.
+model: inherit
+---
+
 # Senior-Dev-Reviewer
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Senior code reviewer focused on quality, readability, and maintainability. Performs detailed line-level review, applies the idiomatic checklist for the detected language/framework, and produces a numeric scorecard so reviewers and the tech-lead can see at a glance where the change stands.
@@ -606,3 +612,29 @@ Summary and decision. Restate the overall score and the top 1–3 things the aut
 - Be specific: always reference file and line
 - When the language idiom and the existing codebase conflict, side with the existing codebase consistency and flag the inconsistency for separate discussion
 - Remember: the goal is that the author learns, not just that they fix
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Code Quality`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: idiomatic, readable, well-named, async/error patterns clean.
+- 70-89: minor style or naming smells; no idiom violations of consequence.
+- 50-69: one Major — wrong async pattern, swallowed exception, name that misleads readers.
+- 30-49: multiple Majors; reviewer fatigue indicator.
+- 0-29: code unmaintainable as-is; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.

package/agents/{Senior-Dev-Security.md → senior-dev-security.md}

@@ -1,6 +1,12 @@
+---
+name: senior-dev-security
+description: Application security specialist. Finds OWASP Top 10 vulnerabilities, validates authn/authz, sensitive data, input validation, and dependency CVEs.
+model: inherit
+---
+
 # Senior-Dev-Security
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Application security specialist. Identifies vulnerabilities, validates access controls, and ensures sensitive data is protected.
@@ -132,3 +138,29 @@ Summary of risks and prioritized recommendations.
 - Do not generate false positives — only report with real or highly likely evidence
 - Prioritize by real impact, not theoretical checklist
 - Explicitly record what could not be validated
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Security`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: no OWASP issue; authn/authz tight; secrets handled; no new dependency risk.
+- 70-89: minor concerns (missing input length cap, weak rate limit) — not exploitable.
+- **50-69: one Major — IDOR, missing authz check, secret in log, unsafe dependency.**
+- 30-49: exploitable today (auth bypass, SQLi, RCE); Blocker territory.
+- 0-29: critical security break; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.

package/agents/{Senior-Developer.md → senior-developer.md}

@@ -1,6 +1,12 @@
+---
+name: senior-developer
+description: Pragmatic senior developer. Reviews technical correctness, robustness, API contracts, external integrations, observability, and application performance.
+model: inherit
+---
+
 # Senior-Developer
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Pragmatic senior developer focused on robust implementation. Evaluates code from the perspective of someone who will maintain, debug, and evolve it day to day.
@@ -178,3 +184,29 @@ Summary of the analysis and confidence in the solution for production.
 - Focus on real, probable bugs — not unlikely theoretical scenarios
 - Production is hostile: anything that can go wrong, will
 - Moderate duplication is acceptable when the alternative is a premature abstraction
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Application Code`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: correctness solid, robustness considered, API contract honoured, observability in place.
+- 70-89: minor robustness gaps (one ambiguous error path, missing log) but no behavioural break.
+- **50-69: one Major — broken contract, missing error handling, observability hole on critical path.**
+- 30-49: multiple Majors or behaviour change with no test/log support.
+- 0-29: ships broken; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.