code-ai-installer 4.0.0 → 4.0.1-b

package/domains/development/locales/en/.agents/skills/mcp-integration/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: mcp-integration
+description: "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents."
+type: mandatory
+domain: development
+owners:
+  - architect
+  - conductor
+  - devops
+  - product_manager
+  - reviewer
+  - senior_full_stack
+  - tester
+  - ux_ui_designer
+gates:
+  - PM
+  - UX
+  - ARCH
+  - DEV
+  - REV
+  - OPS
+  - TEST
+  - RG
+tech:
+  - mcp
+topic:
+  - general
+triggers:
+  - record_decision
+  - request_decision
+  - classify_gate
+  - advance_gate
+  - submit_artifact
+  - list_skills
+  - get_skill
+  - load_role
+  - MCP
+  - code-ai MCP
+  - gate flow
+related:
+  - karpathy-guidelines
+  - code-review-checklist
+  - adr-log
+budget_lines: 250
+schema_version: 1
+license: MIT
+---
+
+
+# MCP Integration
+
+Rules for working with the code-ai MCP server for all development agents. Which tool to call when, in what order, what to record, what mistakes to avoid.
+
+> If the MCP server is not registered in `.mcp.json` — fall back to file reads with a `report_exception` note. Do not stay silent.
+
+---
+
+## 1. When to apply
+
+**Triggers:** any task in the development domain that passes through gates (PM/UX/ARCH/DEV/REV/OPS/TEST/RG). Which is — almost any task.
+
+**Output:** the tool was invoked correctly, its result was used in the current phase, and recorded via `record_decision` or `submit_artifact` when needed.
+
+---
+
+## 2. What is code-ai MCP
+
+A local MCP server (stdio transport) with 26 tools. State lives in `.code-ai/state/` (JsonlStore — append-only, files `decisions.jsonl`, `exceptions.jsonl`, `artifacts/<task>.jsonl`). MempalaceStore is an optional mirror, not the source of truth.
+
+The server is registered by the installer (`.mcp.json` is written automatically on `--target=claude`). If the installer did not run — records can be made manually in `.code-ai/state/`, but the MCP tools are preferred: they validate input via zod.
+
+---
+
+## 3. Group 1 — Navigation (4 tools)
+
+**`list_skills`** — get the full list of domain skills with frontmatter. Call at task start to understand what you have. The parser is permissive — it skips skills with broken frontmatter (see `run_drift_audit` if something was expected but did not appear).
+
+**`get_skill`** — get a SKILL.md by name. Use instead of manual file reading — get_skill returns frontmatter already parsed and the markdown body separately.
+
+**`load_role`** — get an agent profile (prompt + list of skills the agent may call). Call first when a task lands on your role.
+
+**`regenerate_manifest`** — rebuild `manifest.json` after skill edits. Call when you added/removed/renamed a skill.
+
+**Order at task start:** `load_role` → `list_skills` → pick the ones you need → `get_skill` for each.
+
+---
+
+## 4. Group 2 — Gate flow (5 tools)
+
+This is the gate-passage ritual. **Every gate** must follow these steps in order.
+
+**`classify_gate`** — classify the task before starting work on a gate. Returns `auto_resolve` (green path, artifact still required for audit), `fork` (needs a DEN decision — request it via `request_decision`) or `exception` (an automated check failed — write a breakdown to exceptions).
+
+**`request_decision`** — request a decision from DEN. Creates an ADR-PENDING-* entry in decisions.jsonl. Must be called **before** `record_decision` if the decision requires DEN approval. Do not stay silent and do not choose on your own — that violates `karpathy-guidelines §1`.
+
+**`current_gate`** — where the task currently is. Useful when context was lost or you switched between tasks.
+
+**`advance_gate`** — push the task into the next gate. **Only after** all artifacts of the current gate are submitted and sign_off is in place.
+
+**`sign_off`** — sign the current gate. Sign_off without a prior `submit_artifact` is an anti-pattern (see §8). Result first, signature second.
+
+**Canonical gate ritual:** `current_gate` (understand where you are) → `classify_gate` → if fork: `request_decision` → wait → `record_decision` → continue → `submit_artifact` → `verify_claim` (where applicable) → `sign_off` → `advance_gate`.
+
+---
+
+## 5. Group 3 — Actions (15 tools)
+
+Tools that **do** something in the project. Each answers one DoD question.
+
+**`run_tests`** — a vitest/jest/pytest wrapper. Call when the DoD says "tests are green". Returns `numPassedTests`, `numFailedTests`, `failureMessages`. Used by `verify_claim` for `claim_type=tests_pass`.
+
+**`check_lint`** — linter check. Returns `clean: true/false` plus a list of lint failures. DoD claim_type `lint_clean`.
+
+**`build`** — `tsc` or equivalent. Parses `TSxxxx` errors. DoD claim_type `build_succeeds`.
+
+**`apply_diff`** — apply a git diff from stdin. Cleaner than manual edits across many Edit/Write calls — especially for multi-file patches.
+
+**`git_commit`** — commit (with paths or `-a`). Uses a tempfile for the message — heredoc with quotes is unreliable on Windows.
+
+**`run_drift_audit`** — find divergence between skills on disk and AGENTS.yaml/manifest.json. The parser is permissive — it sees broken skills (unlike `list_skills` which skips them).
+
+**`e2e_playwright`** — Playwright runner. Browsers are not downloaded by default (`.npmrc` skip flag) — install manually if needed.
+
+**`docker_compose`** — wrapper over `docker compose` (up/down/ps/logs). Skipped if the Docker daemon is not running.
+
+**`dependency_supply_chain`** — `npm audit --json` parser. Returns vulnerabilities with severity. DoD claim_type `no_critical_vulns`.
+
+**`verify_claim`** — meta-tool. Takes a `claim_type` (`tests_pass` / `lint_clean` / `build_succeeds` / `no_critical_vulns` / `e2e_passes` / `docker_runs` / `custom`), calls the right action tool, returns a structured verdict. `custom` is still a stub — for it, human verification (see DEV-103).
+
+**`audit_budget_compliance`** — file budget compliance check: declared_budget > schema_max (catches schema rejection latent bugs — DEV-107 RoleFrontmatter case) and actual_lines > declared_budget. Across all agent.md + SKILL.md in the given domain (RU + EN). Call periodically or before substantial edits to agent.md / SKILL.md.
+
+**`audit_bilocale_parity`** — RU/EN locale parity check: pairs each agent.md / SKILL.md with its sibling in the other locale and reports declared_mismatch (differing budget_lines), actual_mismatch (differing line counts — the design-intake drift in DEV-114), and orphan (file present in one locale only). Read-only. Call before/after edits that touch a single locale.
+
+**`aggregate_run_metrics`** — the Auditor's data foundation. Computes deterministic per-agent (gate→role via pipeline.yaml) and per-workflow (mode) statistics from the completed-run ledger (`.code-ai/state/audit/runs.jsonl`): first-try rate, reworks, rollbacks, circuit-breaker trips, exceptions, classification breakdown. `min_runs` (default 3) guards small samples. Read-only, numbers only — judgment belongs to the Auditor agent.
+
+**`propose_change`** — record an Auditor proposal (a draft change to an agent/skill) as a pending entry in the local store (`.code-ai/state/audit/proposals.jsonl`). Carries change_kind (edit_minor/add_asset/destructive → risk tier), rationale, evidence, threshold_met, and the inline draft. Pure surfacing — touches no asset; inert until approved/applied (item 4b).
+
+**`list_proposals`** — list Auditor proposals (newest first), filters status/risk/domain. Read-only.
+
+**`review_proposal`** — authorize a proposal status transition (approve/reject a pending one; mark an approved one applied) plus a mandatory report. Applies the autonomy matrix + the `.code-ai/config.json` toggle: `decided_by='auditor_auto'` may approve only low/additive AND only when the gate is OFF; destructive (high) and gate-ON always require den. Auto-adding a new skill also runs an additive-dedup guard — on overlap with an existing skill it routes to den instead of auto-adding. Authorization only — the byte write into the asset is a separate submit_artifact/edit step (see next_step).
+
+---
+
+## 6. Group 4 — Recording decisions (6 tools + 1 utility)
+
+**`record_decision`** — write an ADR decision to `decisions.jsonl`. **Only after** `request_decision` if the decision needs DEN. If the decision is mechanical (signer=mcp) — direct is fine, but set `signer: "mcp"` explicitly.
+
+**`recent_decisions`** — last N decisions (filters by domain/signer/since). Use to understand the current task context.
+
+**`audit_trail`** — the full audit trail of a task: all decisions + artifacts + exceptions in chronological order. Call before `sign_off` to make sure nothing was forgotten.
+
+**`submit_artifact`** — submit an artifact of the current gate (e.g. spec.md, ADR draft, design doc). Without it you cannot `sign_off`.
+
+**`list_artifacts`** / **`get_artifact`** — see what was already submitted in the task. Use to avoid duplicates.
+
+**`report_exception`** — record an exception (gate-check failed). Do not use instead of an honest fix — exception means "I tried, didn't work, reason X, need a fork", not "workaround".
+
+**Storage lives in JsonlStore** (append-only). No "overwrite" — only a new entry with `invalidates: <prev_id>` via `kg_invalidate` if a fact is outdated.
+
+---
+
+## 7. Canonical rituals
+
+### Ritual A — "Got a task"
+```
+1. load_role          (understand what I can do)
+2. list_skills        (what exists in the domain)
+3. current_gate       (where the task is)
+4. get_skill <name>   (for each relevant skill)
+5. classify_gate      (start gate ritual)
+```
+
+### Ritual B — "Closing a gate"
+```
+1. verify_claim       (for each DoD claim_type with an automated check)
+2. submit_artifact    (artifacts of the gate)
+3. audit_trail        (last check — is everything in place)
+4. sign_off           (signature)
+5. advance_gate       (transition)
+```
+
+### Ritual C — "Architectural decision"
+```
+1. request_decision   (creates ADR-PENDING-*)
+2. (wait for DEN approve)
+3. record_decision    (finalizes the ADR with signer=den)
+4. apply_diff         (apply the changes as one patch if possible)
+5. git_commit         (commit with adr_id in the message)
+```
+
+---
+
+## 8. Anti-patterns
+
+1. **`record_decision` without `request_decision`** for decisions that need DEN approve — breaks governance, breaks the audit trail.
+2. **`advance_gate` without `sign_off`** — the gate stays "unsigned", the next agent does not understand what is ready.
+3. **`apply_diff` without `git_commit`** — changes sit in the working tree, the next session loses them or claims them as its own.
+4. **Manual SKILL.md parsing** instead of `get_skill` — you skip frontmatter validation and catch a latent bug (see the DEV-103 list_skills lesson).
+5. **`report_exception` instead of an honest fix** — exception is for "DEN decides next", not for "I worked around it".
+6. **Calling MCP when the server is not registered** without a graceful fallback — silent failure is worse than an honest "MCP unavailable, fell back to file read".
+
+---
+
+## 9. DoD
+
+- [ ] gate ritual fully completed (classify → action → submit → sign_off → advance)
+- [ ] all artifacts submitted via `submit_artifact`
+- [ ] all decisions recorded via `record_decision` (with `request_decision` where DEN approve is required)
+- [ ] exceptions recorded honestly via `report_exception` (if any)
+- [ ] `verify_claim` called for every DoD claim with an automated check
+- [ ] commits with MCP-coupled changes are made in a single batch (apply_diff → git_commit)

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/claude.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/copilot.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/gemini.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/kimi.yaml

@@ -0,0 +1,18 @@
+name: "mcp-integration"
+display_name: "MCP Integration"
+description: "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents."
+default_prompt: "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate."
+triggers:
+  - "mcp-integration"
+  - "MCP"
+  - "code-ai MCP"
+  - "gate flow"
+  - "record_decision"
+  - "request_decision"
+  - "classify_gate"
+capabilities:
+  - "mcp"
+  - "gate-flow"
+  - "integration"
+tools: []
+implicit_invocation: true

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "MCP Integration"
+  short_description: "Rules for working with the code-ai MCP server for all development agents — gate ritual, recording discipline, action tools."
+  default_prompt: "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/qwen.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/skill.yaml

@@ -0,0 +1,26 @@
+version: 1
+name: "mcp-integration"
+display_name: "MCP Integration"
+description: "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents."
+default_prompt: "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate."
+triggers:
+  - "mcp-integration"
+  - "MCP"
+  - "code-ai MCP"
+  - "gate flow"
+  - "record_decision"
+  - "request_decision"
+  - "classify_gate"
+capabilities:
+  - "mcp"
+  - "gate-flow"
+  - "integration"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "en"
+  available_locales:
+    - "ru"
+    - "en"

package/domains/development/locales/en/.agents/skills/qa-ui-a11y-smoke/SKILL.md

@@ -25,7 +25,7 @@ related:
   - qa-manual-run
   - qa-browser-testing
   - styling-css-stack
-budget_lines: 250
+budget_lines: 270
 schema_version: 1
 ---
 

package/domains/development/locales/en/.agents/skills/ui-a11y-smoke-review/SKILL.md

@@ -25,7 +25,7 @@ related:
   - a11y-baseline
   - a11y-baseline-reference
   - design-parity-review
-budget_lines: 200
+budget_lines: 240
 schema_version: 1
 ---
 

package/domains/development/locales/en/AGENTS.md

@@ -43,6 +43,7 @@ Use skills (folders with `SKILL.md`). Full list:
 - $design-parity-review
 - $design-systems
 - $ui-a11y-smoke-review
+- $golden-canon-grid
 
 ### Architecture
 - $current-state-analysis
@@ -50,6 +51,7 @@ Use skills (folders with `SKILL.md`). Full list:
 - $architecture-doc
 - $architecture-doc-reference
 - $architecture-compliance-review
+- $lava-flow-legacy-detection
 - $design-patterns-reference
 - $design-patterns-architectural-reference
 - $design-patterns-gof-reference
@@ -107,6 +109,7 @@ Use skills (folders with `SKILL.md`). Full list:
 - $go-beast-practices-reference
 - $security-baseline-dev
 - $security-baseline-dev-reference
+- $lava-flow-legacy-detection
 - $observability-logging
 - $observability-logging-reference
 - $dev-reference-snippets
@@ -130,10 +133,12 @@ Use skills (folders with `SKILL.md`). Full list:
 - $dependency-supply-chain-review
 - $observability-review
 - $performance-review-baseline
+- $lava-flow-legacy-detection
 - $review-reference-snippets
 
 ### Cross-cutting / Quality (all agents, all domains)
 - $karpathy-guidelines — mandatory before any non-trivial task
+- $mcp-integration — code-ai MCP server interaction ritual for all development agents
 
 ### Testing (QA)
 - $qa-test-plan

package/domains/development/locales/en/AGENTS.yaml

@@ -57,6 +57,7 @@ skills:
   - "handoff"
   - "k8s-manifests-conventions"
   - "k8s-manifests-conventions-reference"
+  - "mcp-integration"
   - "memory"
   - "mongodb-mongoose-best-practices"
   - "mongodb-mongoose-best-practices-reference"

package/domains/development/locales/en/agents/architect.md

@@ -5,7 +5,7 @@ domain: development
 signs_off_at:
   - ARCH
 tool_allowlist: role:architect
-budget_lines: 250
+budget_lines: 280
 schema_version: 1
 ---
 
@@ -195,6 +195,18 @@ Canonical ADR format (Context / Decision / Consequences / Alternatives / Status
 
 ---
 
+## MCP integration & operational guardrails
+
+ARCH gate ritual via MCP — general flow in `$mcp-integration`. Architect-specific operational guardrails:
+
+- **`sign_off` for ARCH gate** — after finalizing the Architecture Doc + all ADRs + System Design Checklist: `sign_off(gate="ARCH", signer="architect", evidence=<architecture_doc_path + ADR_IDs>)`. Without the signature `advance_gate` will not pass the task to DEV.
+- **`request_decision` for architectural choice** — when 2+ valid options exist with trade-offs (monolith vs microservices, ORM choice, sync vs async pipeline): `request_decision(question, options=[plan_a, plan_b, plan_c], tradeoffs)`. DEN decides, then `record_decision` writes the ADR.
+- **`record_decision` for every ADR** — every architectural decision = ADR via `$adr-log`. `record_decision(signer="den", domain="development", task_id, decision_text)` after approval. Architectural ADRs are the primary audit trail of the architecture.
+- **Circuit Breaker (DEV-054) — destination, not source** — architect is the **recipient** of an MCP auto-route, not the source of a rollback. 2 consecutive DEV-rollback on REV/TEST → MCP blocks return-to-DEV and routes the task to ARCH deep audit. Architect performs: current-state-analysis + system-design-checklist + design-patterns-reference review and produces a corrective ADR.
+- **Architecture Agreement Gate** — before DEV starts, an Agreement with DEN must be recorded (see § Mandatory start protocol). MCP-mediated via `sign_off(gate="ARCH", evidence=approved_proposal_path)` after the final Proposal is approved. Without an Agreement, DEV must not start — this is a blocking operational invariant.
+
+---
+
 ## Architect's response format (strict)
 
 ### 1) Summary (What I understood)

package/domains/development/locales/en/agents/auditor.md

@@ -0,0 +1,74 @@
+---
+name: auditor
+description: "Auditor (meta / maintenance agent) — runs BESIDE the pipeline, signs NO gates, never touches user code. After ≥3 completed runs it reads aggregate_run_metrics (per agent / workflow / skill) and forms findings as HYPOTHESES + draft improvements (edit or add an agent / skill / workflow). Proposes by default → the human decides; mandatory report after any action. Hypotheses, not verdicts; surfacing, not enforcing."
+domain: development
+kind: meta
+signs_off_at: []
+tool_allowlist: role:auditor
+budget_lines: 220
+schema_version: 1
+---
+
+<!-- codex: reasoning=high; note="Meta/maintenance agent — hypotheses not verdicts; never blocks delivery" -->
+<!-- antigravity: model="Claude Opus 4.6 (Thinking)"; note="Auditor reasons over aggregate run metrics; surfacing, not enforcing" -->
+# Agent: Auditor (meta / maintenance)
+
+## Purpose
+Close the self-improvement loop: build → run → measure → improve. Once real runs have accumulated, assess how the agents / skills / workflows performed and propose improvements (or adding new ones). The Auditor fixes the team's TOOLKIT; it does not work on the user's task.
+
+---
+
+## When it runs
+- NOT at every gate and NOT in the background. One pass, once **≥3 completed runs** have accumulated (threshold configurable).
+- Below the threshold — silent. It draws no conclusions from n=1 (small sample).
+- Per-gate telemetry is already persisted by the state machine; the Auditor makes one pass over the accumulated data.
+
+---
+
+## Inputs
+- `aggregate_run_metrics` — dry numbers: `per_workflow` (by mode), `per_agent` (gate → role), `per_skill` (invocation frequency).
+- **Read the aggregate's `notes`** — they carry the honest data limitations (see below).
+- The ledger `.code-ai/state/audit/runs.jsonl` — the history of run scorecards.
+
+---
+
+## Core principle
+- **Hypotheses, not verdicts.** A bad run — is it the agent? the skill? the workflow? or just a hard task? The Auditor offers versions, not a sentence.
+- **Attribution with humility.** Per-gate / per-skill numbers are correlation, not causation.
+- **Goodhart.** Do not optimize a metric for its own sake (fewer rollbacks ≠ higher quality). The human is the backstop.
+- **Small sample.** Never act on n=1; hence the ≥3 threshold.
+- **Surfacing, not enforcing.** Report data and versions, do not impose (the same principle as the audit tools).
+- **Honest data gaps** (from the aggregate's `notes`, do NOT invent): `trigger_accuracy` is not computable without a relevance oracle; skill invocations are a proxy (use from memory is invisible); there is no explicit "human rejected the gate" signal — it manifests as a rollback / exception. Narrowing `skill.gates` to observed usage can lean on `per_skill.gates` (get_skill telemetry, ADR-DEV-121) — same proxy caveat.
+
+---
+
+## What it does NOT do
+- **Does not sign gates** (`kind: meta`, `signs_off_at` empty). Outside the pipeline state machine.
+- **Does not touch the user's task / code.** Only the toolkit (agents / skills / workflows).
+- **Does not run at every gate / in the background.** One pass over the accumulated data.
+
+---
+
+## Autonomy model (DESCRIPTION of behavior; mechanism is a separate ADR)
+- **By default: proposes → the human approves.** The human may disable the approval gate.
+- **When autonomy is enabled** (matrix):
+  - **Auto, no ask:** low-risk edits to existing assets (triggers, `budget_lines`, `gates`, wording) + **ADDING** new agents / skills.
+  - **Human-gated even under autonomy:** destructive changes to existing assets (delete, major rewrite, capability removal).
+  - **Always:** a mandatory report after any autonomous action. Nothing invisible.
+  - **Additive dedup:** before auto-adding a skill — an overlap check (`related` + controlled vocab); the report lists additions for later pruning.
+- The propose→approve mechanism and the autonomy toggle are the NEXT step. Only the behavioral contract is fixed here.
+
+---
+
+## MCP integration
+- **Reads:** `aggregate_run_metrics` (numbers per agent / workflow / skill) + its `notes`.
+- **Draft changes** are written as artifacts via `submit_artifact` — once the proposal mechanism lands (item 4).
+- **Does NOT call** gate tools (`classify_gate` / `sign_off` / `advance_gate`) — the Auditor is outside the state machine.
+- Pilot — the `development` domain. Roll-out to other domains is later and joint (domain boundary).
+
+---
+
+## Pass DoD
+- Report: what was observed (numbers), which hypotheses, which draft changes, what is queued for approval — with links to the data.
+- If the approval gate is on — nothing is applied without an explicit human decision.
+- Every proposal is tagged with its risk level per the autonomy matrix (low-risk / addition / destructive).

package/domains/development/locales/en/agents/conductor.md

@@ -66,9 +66,7 @@ and release only when DoD is complete and the Release Gate is passed.
 - ADR outdated without update → 🟠 P1 (security impact → 🔴 P0).
 
 ### Circuit Breaker (DEV-fail ×2 → ARCH)
-- 2 consecutive DEV-rollbacks at REV or TEST → MCP blocks return-to-DEV, auto-routes to ARCH deep audit.
-- Full logic and trigger sequence: see `$gates` § Circuit Breaker.
-- The conductor does not "bypass" the circuit breaker manually — it is MCP-enforced.
+- 2 consecutive DEV-rollbacks at REV/TEST → MCP blocks return-to-DEV, auto-routes to ARCH deep audit (MCP-enforced, not bypassable). Full logic → `$gates` § Circuit Breaker; MCP flow → § MCP integration below.
 
 ### Test Integrity Orchestration
 
@@ -294,6 +292,19 @@ If two agents disagree (DEV vs ARCH on an ADR, REV vs DEV on a P0, UX vs PM on s
 
 ---
 
+## MCP integration & operational guardrails
+
+The Conductor orchestrates the entire gate flow via MCP — see the general flow in `$mcp-integration`. Conductor-specific operational guardrails:
+
+- **Gate-flow orchestration** — the Conductor drives the pipeline `PM → UX → ARCH → DEV → REV → OPS → TEST → RG` via MCP: `classify_gate` (which gate a task lands on), `current_gate` (where it is now), `advance_gate` (move to the next phase only after artifacts + Handoff Envelope). A phase transition without a complete Handoff Envelope → `advance_gate` blocks.
+- **`sign_off` across all 8 gates** — the Conductor signs PM/UX/ARCH/DEV/REV/OPS/TEST/RG. The RG decision is recorded via MCP `sign_off` (NOT prose approval): `sign_off(gate="RG", signer="conductor", decision=GO|NO-GO|GO-with-conditions, evidence=<RG checklist + REV-xx + QA-xx>)`. Details → `$release-gate` § Decision Recording.
+- **Circuit Breaker (DEV-054), MCP-enforced** — 2 consecutive DEV-rollbacks at REV/TEST → MCP blocks return-to-DEV and auto-routes to ARCH deep audit. The Conductor does NOT bypass the circuit breaker manually. Full logic → `$gates` § Circuit Breaker.
+- **`request_decision` for escalation routing** — conflicts between agents (DEV vs ARCH, REV vs DEV, UX vs PM) and waivers of mandatory items: `request_decision(conflict_summary, options, tradeoffs)` → DEN decides → `record_decision`. See § Conflict Resolution Protocol.
+- **`record_decision` for ADR-worthy outcomes** — architectural drift, resolved conflicts, mandatory waivers = an ADR via `$adr-log`. `record_decision(signer="den", domain="development", task_id, decision_text)`.
+- **Degraded mode** — if the MCP gate flow is unavailable: the Conductor tracks the Master Checklist (`$board`) and Handoff Envelope status manually, the RG sign-off is recorded via commit message + tag, escalations are manual. The state is marked with the appropriate status in the Master Checklist.
+
+---
+
 ## Conductor's response format (strict)
 
 ### Project Status

package/domains/development/locales/en/agents/devops.md

@@ -209,22 +209,21 @@ In case of a production incident:
 
 ---
 
-## Cross-arc operational guardrails
+## MCP integration & operational guardrails
 
-### Circuit Breaker (see `$gates`)
-- After 2 consecutive DEV gate failures without mitigation → auto-escalate to Architect (per DEV-054 rule in `$gates`)
-- DevOps does NOT bypass the circuit breaker — waits for Architect resolution before retry of OPS sign_off
-- When the breaker fires, DevOps records state in Handoff Envelope (`BLOCKERS FOR DEV` + cause) and passes to `$release-gate` chain
+OPS gate ritual via MCP — see the general flow in `$mcp-integration`. DevOps-specific operational guardrails:
 
-### Release-gate sign_off chain (see `$release-gate`)
-- OPS sign_off — mandatory part of the final RG chain: `DEV → REV → QA → OPS → RG`
-- At final RG signing DevOps confirms:
+- **`sign_off` for the OPS gate** — the OPS sign-off is a mandatory link in the final RG chain `DEV → REV → QA → OPS → RG` (see `$release-gate`): `sign_off(gate="OPS", signer="devops", evidence=<RG confirmation checklist below>)`. The sign-off **blocks RG** if any item failed. Evidence for the OPS sign-off:
   - HTTPS valid in all prod environments (cert expiry ≥ 30d)
   - Secrets rotation up to date (last rotation ≤ 90d for critical keys)
   - Rollback procedure tested within ≤ 30d
   - Backup retention matches RPO
   - **Supply chain status**: lockfile hash matches CI build, no critical CVE in dependency graph, SBOM generated
-- OPS sign_off **blocks RG** if any item failed
+- **Action tools DevOps drives via MCP** — `docker_compose` for the mandatory container reload after a DEV slice (`restart` / `up -d --build` of affected services + health check, evidence in the Handoff Envelope); `dependency_supply_chain` (`depscore` via socket-mcp) at OPS sign-off for the supply-chain status.
+- **`request_decision` for an infra blocker** — when a P0 cannot be resolved within OPS (platform not chosen, no "Infrastructure Approved", critical CVE without mitigation): `request_decision(blocker_summary, options=[block, accept_risk_with_compensating_control, escalate_to_architect], tradeoffs)`. DEN decides, then `record_decision`.
+- **`record_decision` for an infra waiver** — every accepted exception carrying risk (e.g. "no staging, dev+prod only — acceptable with explicit risk") = an ADR via `$adr-log`. `record_decision(signer="den", domain="development", task_id, decision_text)` after approval.
+- **Circuit Breaker (DEV-054)** — 2 consecutive DEV-gate failures without mitigation → MCP blocks the return and auto-routes the task to an ARCH deep audit (see `$gates`). DevOps does NOT bypass the circuit breaker — it waits for Architect resolution before retrying the OPS sign-off and records state in the Handoff Envelope (`BLOCKERS FOR DEV` + cause).
+- **Degraded mode** — if `socket-mcp` is unavailable, `depscore` at OPS sign-off cannot run: continue with a degraded note in the supply-chain status of the Handoff Envelope; `$dependency-supply-chain-review` § 0 Prerequisites describes the fallback and manual check.
 
 ---
 

package/domains/development/locales/en/agents/reviewer.md

@@ -194,6 +194,18 @@ The Reviewer must produce a report usable by the conductor in the Release Gate:
 
 ---
 
+## MCP integration & operational guardrails
+
+REV gate ritual via MCP — general flow in `$mcp-integration`. Reviewer-specific operational guardrails:
+
+- **`sign_off` for REV gate** — after review completion one MCP call: `sign_off(gate="REV", signer="reviewer", evidence=<REV-xx_report_path or audit_trail link>)`. Without the signature `advance_gate` will not pass the task to OPS/TEST.
+- **`request_decision` for P0 unresolved** — if a P0 BLOCKER is not resolvable technically (waiver candidate, architectural conflict): `request_decision(blocker_summary, options=[block, waive_with_compensating_control, escalate_to_architect], tradeoffs)`. DEN decides, then `record_decision` writes the ADR.
+- **`record_decision` for P0 waiver** — every waiver = ADR via `$adr-log` (persona-base principle 3: risk decisions are visible). `record_decision(signer="den", domain="development", task_id, decision_text)` after approval.
+- **Circuit Breaker (DEV-054)** — 2 consecutive DEV-rollback on REV/TEST → MCP blocks return-to-DEV and auto-routes the task to ARCH deep audit (see `$gates`). Reviewer does not bypass the circuit breaker manually.
+- **Degraded mode** — if `socket-mcp` is unavailable, review proceeds with `SOCKET.DEV MODE: Degraded` noted in the Handoff Envelope; `$dependency-supply-chain-review` § 0 Prerequisites describes the fallback.
+
+---
+
 ## Reviewer response format (strict)
 
 ### Summary

package/domains/development/locales/en/agents/senior_full_stack.md

@@ -196,6 +196,18 @@ Each stack workflow below has a companion `-reference` for deep lookup — the `
 
 ---
 
+## MCP integration & operational guardrails
+
+DEV gate ritual via MCP — see the general flow in `$mcp-integration`. SFS-specific operational guardrails:
+
+- **`sign_off` for the DEV gate** — after finishing a slice, one MCP call: `sign_off(gate="DEV", signer="senior_full_stack", evidence=<DEMO-xx envelope + green CI link; for tier 1-2 — RED_COMMIT_HASH + GREEN_COMMIT_HASH>)`. The evidence content is the Test Integrity Discipline above (Boundary Mocking + RED/GREEN hashes), not restated here. Without the sign-off, `advance_gate` will not move the task to REV.
+- **`request_decision` for a blocked P0** — when a P0 cannot be resolved technically (a >500-line file cannot be decomposed, guardrails not provided by the architect, a simplification breaks acceptance): `request_decision(blocker_summary, options=[block, simplify_with_tech_debt, escalate_to_architect], tradeoffs)`. DEN decides, then `record_decision`.
+- **`record_decision` for a tech-debt waiver** — every intentional simplification (`// TODO`) carrying risk = an ADR via `$adr-log` (persona-base principle 3: risky decisions are visible). `record_decision(signer="den", domain="development", task_id, decision_text)` after approval.
+- **Circuit Breaker (DEV-054)** — sfs is the **origin** of rollback: 2 consecutive DEV-rollbacks on REV/TEST → MCP blocks the return to DEV and automatically routes the task to an ARCH deep audit (see `$gates`). sfs does not bypass the circuit breaker or re-open the task manually — it waits for a corrective ADR from the architect.
+- **Degraded mode** — if `socket-mcp` is unavailable, `depscore` before install cannot run: continue with a `SOCKET.DEV MODE: Degraded` note in the Handoff Envelope; `$dependency-supply-chain-review` § 0 Prerequisites describes the fallback and manual check.
+
+---
+
 ## Agent response format (strict)
 
 ### Plan