# D3 Audit & Risk-Management Tooling Integration Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Integrate the D3 top-5 (variant «а») — install #1 Trail of Bits Skills, formalize #2 `/security-review`, install #4 Anthropic Security Guidance, reuse #3 adr-kit (from the A6 plan) for the decision/risk register, spike #5 toolchain-auditor — and distill the project's 14-phase portal-audit method into a project skill, so the `D3 «Аудит и управление рисками»` map section becomes a populated, working playbook.

**Architecture:** Audit & risk-management is currently an **empty** functional section — `NODE_SECTION` in `docs/automation-graph.html` tags zero nodes `D3`. Two third-party tools are added: **Trail of Bits Skills** (marketplace plugin — 16 audit/vuln/supply-chain skills) and **Anthropic Security Guidance** (marketplace plugin — a warn-only PreToolUse hook). `/security-review` (Anthropic built-in) is customized via a project copy in `.claude/commands/`. The decision/risk register is **not** a new tool — it reuses **adr-kit** introduced by the A6 plan (`2026-05-17-a6-architecture-tooling-integration.md`); D3 only adds the risk-register convention. #5 (toolchain attack-surface auditor) is a **provenance spike** — community plugins are unvetted, so the default outcome is a documented manual procedure, not an install. Finally the project's own repeated 14-phase audit (#1/#2/#3) is distilled into an `audit-portal` project skill. All tools are non-UI → **audit-security** category, outside the PSR_v1 UI-pool. D3 artifacts live in `docs/audit/`.

**Tech Stack:** Trail of Bits Skills (marketplace `trailofbits/skills`, CC-BY-SA-4.0); `anthropics/claude-code-security-review` (Anthropic, the `/security-review` command); Anthropic Security Guidance (Anthropic-verified marketplace plugin, PreToolUse hook); adr-kit v0.13.1 (reused — see A6 plan); project normative docs; `docs/automation-graph.html` (vis.js); `skill-creator` (for the `audit-portal` skill).

**Sequencing (locked 2026-05-17):** the A6 plan (`2026-05-17-a6-architecture-tooling-integration.md`) runs to completion and pushes **first**; D3 Task 1 then forks from the updated `origin/main`. Rationale: D3 Task 5 reuses A6's adr-kit (AD1) and builds on its `docs/adr/ADR-000`; A6-first means D3 completes in one pass with no self-skip and no tool-number rework (NUM1). The two epics touch shared files (the map, 4 normative docs) → run strictly sequentially, never interleaved.

---

> **NB (исправлено 17.05.2026, нормативка v2.5):** #4 Security Guidance в этом плане описан как «warn-only / does not block» (строки ~21, ~251, ~542) — **фактически неверно**: хук делает `sys.exit(2)` → это **блокирующий** PreToolUse-хук (одноразовый speed-bump per «файл+правило» за сессию, retry проходит). Актуальная характеристика — Tooling §4.15 / ADR-003 / CLAUDE.md §3.3 #40. План оставлен как исторический снимок, тело не переписано.

## Tool Identity (verified 2026-05-17 via WebFetch/WebSearch)

| # | Tool | Install mode | Source / License | Hooks? |
|---|---|---|---|---|
| 1 | **Trail of Bits Skills** (16 skills: `differential-review`, `audit-context-building`, `supply-chain-risk-auditor`, `insecure-defaults`, `sharp-edges`, `fp-check`, `static-analysis`, `c-review`, `variant-analysis`, `semgrep-rule-creator`, …) | Marketplace plugin — `/plugin marketplace add trailofbits/skills` | GitHub `trailofbits/skills`, **CC-BY-SA-4.0**, 113 commits, reputable AppSec vendor | Verify on install — expected none (skills only) |
| 2 | **`/security-review`** | Built-in Claude Code command; customized via a project copy in `.claude/commands/security-review.md` | GitHub `anthropics/claude-code-security-review`, Anthropic | None (slash command) |
| 4 | **Security Guidance** | Marketplace plugin (Anthropic) | `claude.com/plugins/security-guidance`, **Anthropic Verified**, ~153k installs | **YES** — one PreToolUse `Write\|Edit\|MultiEdit` hook, **warn-only** (8 vuln categories, session-scoped, does not block) |
| 3 | **adr-kit** | **NOT installed by D3** — reused from the A6 plan | (see A6 plan) | (see A6 plan) |
| 5 | **toolchain attack-surface auditor** | **NOT installed by default** — Task 6 is a provenance spike | community (`geoffrey-young/anthropic-hackathon-2026` "Claude Code Canary"; "Plugin Security Auditor" on mcpmarket) — **provenance unverified** | TBD by spike |

**Verification status:** #1 and #4 — confirmed via WebFetch (skill list, license, install command / publisher, hook behaviour). #2 — present in this environment as the `/security-review` command; repo confirmed via search. #3 — defined by the A6 plan. #5 — **search-level only, provenance NOT verified** (this is by design — Task 6).

---

## Design Decisions & Conflict Audit

Pattern follows the K1–K8 / AK1–CC1 audits used for claude-mem and the A6 plan. Verified against the three sources, project `.claude/settings.json`, `.mcp.json`, and the A6 plan.

| # | Tool | Sev | Conflict | Resolution (locked) |
|---|---|---|---|---|
| TB1 | ToB Skills | 🟡 | `static-analysis` / `semgrep-rule-creator` overlap the existing **Semgrep MCP** (#25, section A8) → CLAUDE.md §5 п.6 "не два инструмента на одну задачу". | Boundary, documented in the Tooling entry (Task 8): **Semgrep MCP** = inline SAST during routine dev / CI; **ToB Skills** = deep on-demand *audit campaigns*. Different cadence, not the same task. |
| TB2 | ToB Skills | 🟡 | `differential-review` / `c-review` overlap `superpowers:requesting-code-review` (§12) and `/security-review`. | Different depth/scope: `/security-review` = quick diff scan; `requesting-code-review` = general review; ToB `differential-review` = security-focused *deep* audit of a change-set. §12.2 task-map **unchanged** — ToB skills are not added to it. |
| TB3 | ToB Skills | 🟢 | Could the plugin register CC lifecycle hooks? | Verify on install (Task 3 Step 4). Skills-only plugins register none; if it does → stop and re-audit. |
| TB4 | ToB Skills | 🟢 | CC-BY-SA-4.0 (ShareAlike) — could obligate the project. | None — ToB stays a **marketplace plugin** (cache outside the repo, not vendored, not modified). ShareAlike triggers only on redistribution/derivative works. Do **not** vendor ToB skill files into the repo. Noted in the Tooling entry. |
| SG1 | Security Guidance | 🟡 | Adds a PreToolUse `Write\|Edit\|MultiEdit` hook → coexists with the project `CLAUDE.md`-direct-edit-warn hook (`.claude/settings.json`) and the economy/skill-discipline PreToolUse hooks (in `.claude/settings.local.json` / `~/.claude/settings.json`). | Verified **warn-only** — it prints session-scoped warnings, never blocks (WebFetch). Task 4 Steps 3-4 verify: the SG hook fires AND the economy + ruflo + CLAUDE-warn chain still fire, no `decision:block`. Accept +~34 ms/edit latency (memory: per-hook median). |
| SG2 | Security Guidance | 🟢 | Overlaps ToB `insecure-defaults` / Semgrep. | None — SG = real-time inline warn *during the edit* (8 fixed categories); ToB/Semgrep = on-demand audit. Different timing. Additive. |
| SG3 | Security Guidance | 🟡 | Anthropic-verified marketplace plugin, unregistered = PSR_v1 R0.2/R10 violation on use. | Register in 4 normative homes (Task 8). |
| SR1 | `/security-review` | 🟢 | A customized `.claude/commands/security-review.md` shadows the built-in command. | Intended — this is the documented Anthropic customization path. Note in the Tooling entry that the project copy replaces the built-in. |
| AD1 | ADR / risk register | 🟡 | D3 needs a decision/risk register. Installing a *second* ADR tool collides with **adr-kit** (A6 plan, Tooling #36) → §5 п.6. | D3 **reuses adr-kit** — installs nothing. The risk register = adr-kit `## Consequences` (risks + mitigations) + the `Открытые_вопросы` registry (open risks). Task 5 only adds the convention. |
| AD2 | ADR / risk register | 🟢 | D3 Task 5 depends on the A6 plan having installed adr-kit. | **Locked sequencing** — A6 runs to completion first; D3 Task 1 forks from the updated `origin/main`. Task 5 therefore always finds adr-kit present; there is no self-skip path. |
| TA1 | #5 toolchain auditor | 🟡 | Community plugin-auditors are unvetted. Installing an unverified plugin to *do risk management* is itself a D3 risk-management failure. | Task 6 = provenance spike (`superpowers:systematic-debugging` style). **Default outcome = defer** + a documented manual `docs/audit/toolchain-attack-surface.md` procedure. Install only if provenance clears the bar in the spike. |
| AP1 | `audit-portal` skill | 🟢 | A new project skill duplicating `superpowers` or ToB skills. | None — `audit-portal` encodes the project's *own* 14-phase methodology (run 3× as audits #1/#2/#3), distilled per the E8 triada policy (workflow ≥3× → skill). It *orchestrates* `/security-review` + ToB skills, it does not reimplement them. |
| CC1 | all | 🟡 | Bus-factor. | ToB = reputable firm (low risk); Security Guidance = Anthropic (low risk); #5 = community (high risk → spike, default defer). Noted in the Tooling entry. |
| NUM1 | normative sync | 🟡 | The A6 plan (untracked, not yet executed) claims Tooling slots **#36-#38**, PSR_v1 R10.1 rows, and plugin slots #10/#11. D3 must not collide. | Task 8 Step 1 reads the **live** `docs/Tooling_v8_3.md` §0 counter and assigns D3's entries sequentially after whatever is current (≥#36 if A6 has not landed, ≥#39 if it has). Never hard-code a number before reading. |

**Severable scope.** Minimal D3 = Tasks 1-3 + 8-10 (formalize `/security-review`, install ToB, normative sync, map, finish) — already populates the section. Independently severable: **Task 4** (Security Guidance hook — env change), **Task 5** (ADR risk register — depends on A6), **Task 6** (#5 spike), **Task 7** (`audit-portal` skill). Primary path below = everything. **Selected 2026-05-17: full integration — all 10 tasks, no task severed.**

---

## File Structure

| File | Created / Modified | Responsibility |
|---|---|---|
| `.claude/commands/` | Create dir | Project slash-command overrides |
| `.claude/commands/security-review.md` | Create | Customized `/security-review` — project false-positive filter |
| `docs/audit/` | Create dir | D3 home — audit procedures & artifacts |
| `docs/audit/README.md` | Create | Index — defines `docs/audit/` purpose, links D3 + the toolset |
| `docs/audit/toolchain-attack-surface.md` | Create | #5 deliverable — manual toolchain attack-surface audit procedure |
| `.claude/skills/audit-portal/` | Create | The distilled 14-phase portal-audit project skill (`SKILL.md`) |
| `docs/adr/ADR-003-audit-risk-tooling.md` | Create (conditional — AD2) | Seed risk-ADR documenting the D3 tooling decision; only if adr-kit present |
| `~/.claude/settings.json` | Modify | `enabledPlugins` += Trail of Bits + Security Guidance; `extraKnownMarketplaces` += 1-2 |
| `docs/Tooling_v8_3.md` | Modify | Прил. Н — new audit-security subsection(s) + §0 counter bump |
| `docs/Plugin_stack_rules_v1.md` | Modify | R10.1 — new audit-security rows |
| `docs/Pravila_raboty_Claude_v1_1.md` | Modify | §13.2 — audit-security category note |
| `CLAUDE.md` | Modify (**via claude-md-management only**) | §3 title count, §1 row 2b count, new §3.3 audit-security rows |
| `docs/CHANGELOG_claude_md.md` | Modify | CLAUDE.md version-bump entry |
| `docs/automation-graph.html` | Modify | New D3 nodes → `NODE_SECTION` D3; header metrics |
| `cspell-words.txt` | Modify (conditional) | New audit/security vocabulary |

---

## Task 1: Pre-flight — baseline, snapshot, fact-check

**Files:** none modified (read-only) except a new branch

- [ ] **Step 1: Confirm tree state and create the working branch**

```bash
cd "c:/моя/проекты/портал crm/Документация"
git status --short
git rev-parse --short HEAD
git fetch origin && git checkout -b feat/d3-audit-risk-tooling origin/main
```

Expected: record `origin/main` HEAD SHA as the regression baseline; new branch `feat/d3-audit-risk-tooling` created off it. (Push pattern at the end: `git push origin feat/d3-audit-risk-tooling:main`.)

- [ ] **Step 2: Snapshot the hook chain**

Read `.claude/settings.json`, `.claude/settings.local.json` (if present), and `~/.claude/settings.json`. Record every hook on `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`. This is the SG1 baseline — Task 4 compares against it.
Expected (project `.claude/settings.json`): 2× UserPromptSubmit (ruflo-recall, ruflo-queen), 1× PreToolUse (CLAUDE.md-warn), 2× PostToolUse (markdownlint-fix, schema-CHANGELOG-reminder). Economy/skill-discipline/Stop-verifier hooks live in the local/global file — record them too.

- [ ] **Step 3: Baseline regression**

```
/regression quick
```

Expected: GREEN. Also record current Pest / Vitest counts from the last green run (memory `project_state.md`: Pest 891/888/3sk/0, Vitest 102f/849/3sk/0) — D3 touches no `app/` code, so the final run must match.

- [ ] **Step 4: Check whether the A6 plan has landed (AD2 / NUM1)**

```bash
git log --oneline origin/main | grep -iE "adr-kit|architecture-patterns|mermaid" | head
ls ~/.claude/plugins/cache/ | grep -i adr-kit
```

Read `docs/Tooling_v8_3.md` Прил. Н §0 — record the **live** tool counter.
Record: **A6 landed?** yes/no — drives Task 5 (conditional) and Task 8 numbering.

- [ ] **Step 5: Fact-check the tools**

Confirm assumptions still hold:

- `https://github.com/trailofbits/skills` — marketplace `trailofbits/skills`, CC-BY-SA-4.0, skills-only (no CC lifecycle hooks).
- `https://claude.com/plugins/security-guidance` — Anthropic-verified; confirm the exact `/plugin marketplace add …` + `/plugin install …` strings (the marketplace org/name).
- `https://github.com/anthropics/claude-code-security-review` — confirm the path of `security-review.md` in the repo.

If ToB Skills or Security Guidance now differs materially (e.g. ToB registers lifecycle hooks) → **stop**, re-audit TB3/SG1.

No repo files changed → no commit.

---

## Task 2: Formalize `/security-review` — customized project copy (#2)

**Files:**

- Create: `.claude/commands/` (dir), `.claude/commands/security-review.md`

- [ ] **Step 1: Create the commands directory**

```bash
mkdir -p ".claude/commands"
```

- [ ] **Step 2: Fetch the upstream command file**

```bash
git clone --depth 1 https://github.com/anthropics/claude-code-security-review.git /tmp/ccsr-src
cp /tmp/ccsr-src/security-review.md ".claude/commands/security-review.md"
rm -rf /tmp/ccsr-src
```

(If `security-review.md` lives in a subfolder — confirmed in Task 1 Step 5 — copy from that path.)

- [ ] **Step 3: Add the project false-positive filter**

Append to `.claude/commands/security-review.md` a `## Project false-positive guidance (Лидерра)` section with these concrete directions:

```markdown
## Project false-positive guidance (Лидерра)

When filtering findings for this repository, treat the following as expected, not findings:
- Missing application-layer tenant checks where the table has PostgreSQL RLS — tenant
  isolation is enforced at the DB layer (`SET LOCAL app.current_tenant_id`, 5 roles,
  39 policies; see ADR-002 / CLAUDE.md §2). DO still flag queued jobs running as
  `crm_supplier_worker` (BYPASSRLS) that lack an explicit `where('tenant_id', …)`.
- `tools/*.mjs` economy/ruflo hook scripts using `child_process.spawnSync` / `process.env`
  — these are intentional local CLI hooks, not user-facing code paths.
- Secrets: gitleaks already gates secrets at pre-commit + pre-push; do not re-report
  unless a NEW hardcoded credential appears in the diff.
- Test factories / seeders using `Faker` and predictable values — test-only.

DO prioritise: HMAC/webhook verification gaps, signed-URL handling, auth/tenant
middleware on `/api/*` routes, ПДн handling (152-ФЗ), and mass-assignment on Eloquent models.
```

- [ ] **Step 4: Smoke-test the customized command**

Stage the new file, then run the command:

```bash
git add .claude/commands/security-review.md
```

Invoke `/security-review`. Expected: it runs, reads the customized `.claude/commands/security-review.md`, and produces a structured findings report (a docs/command change → expected result "no security-relevant findings"). Functional smoke only.

- [ ] **Step 5: Commit**

```bash
git commit -m "feat(audit): customize /security-review with project FP-filter (D3 #2)"
```

---

## Task 3: Install Trail of Bits Skills (#1)

**Files:** Modify `~/.claude/settings.json` (the `Edit` triggers the `ask` permission — expected). No repo file changed.

- [ ] **Step 1: Add the marketplace and install**

```
/plugin marketplace add trailofbits/skills
/plugin install <plugin-name>@trailofbits-skills
```

(Resolve the exact plugin name from the marketplace listing shown after `add` — likely `skills@trailofbits-skills` or per the repo's `plugin.json`.)

- [ ] **Step 2: Reload**

```
/reload-plugins
```

- [ ] **Step 3: Verify the skills loaded**

```bash
ls ~/.claude/plugins/cache/trailofbits-skills/*/skills/
```

Expected: ~16 skill directories including `differential-review`, `supply-chain-risk-auditor`, `audit-context-building`, `insecure-defaults`, `fp-check`, `static-analysis`. Read `~/.claude/settings.json` — `enabledPlugins` contains the ToB entry.

- [ ] **Step 4: Verify NO lifecycle hooks were added (TB3)**

Read the `hooks` block of `~/.claude/settings.json` AND project `.claude/settings.json`. Both must be **unchanged** vs the Task 1 Step 2 snapshot. If ToB injected a `hooks` entry → stop and re-audit TB3.

- [ ] **Step 5: Smoke-test a ToB audit skill**

Invoke the `differential-review` skill against the last commit's diff (`git show HEAD`). Expected: the skill activates and returns a security-focused review of the change-set. Functional smoke — no file output, no findings expected on a docs change.

- [ ] **Step 6: Confirm economy/ruflo chain intact**

Submit a trivial prompt; the economy marker still appears, no hook errors. No repo files changed in Task 3 → no commit.

---

## Task 4: Install Security Guidance (#4) — *severable*

**Files:** Modify `~/.claude/settings.json`. No repo file changed.

> Skip this task for the minimal D3 scope (see "Severable scope"). It is the only env-changing step that adds a hook.

- [ ] **Step 1: Install the plugin**

Run the exact strings confirmed in Task 1 Step 5, e.g.:

```
/plugin marketplace add <anthropic-marketplace>
/plugin install security-guidance@<anthropic-marketplace>
/reload-plugins
```

- [ ] **Step 2: Verify the plugin and its hook**

Read `~/.claude/settings.json` — `enabledPlugins` contains `security-guidance…: true`. Confirm the plugin contributes exactly one PreToolUse `Write|Edit|MultiEdit` hook (via the plugin's own `hooks/`, merged at runtime — it may not appear literally in `settings.json`).

- [ ] **Step 3: Verify warn-only behaviour + chain integrity (SG1)**

Make a trivial edit to a scratch file containing an obvious pattern (e.g. `eval("x")` in a `.js` temp file). Expected:

- The Security Guidance warning prints to stderr.
- The edit **still applies** — the hook does NOT block (`decision:block` absent).
- The project `CLAUDE.md`-warn hook, the economy hooks, and the ruflo hooks **all still fire** — compare to the Task 1 Step 2 snapshot.

If the SG hook blocks an edit, or any pre-existing hook stops firing → **stop**, document, and treat Task 4 as deferred.

- [ ] **Step 4: Clean up the scratch file**

```bash
rm <scratch-file>
```

No repo files changed in Task 4 → no commit.

---

## Task 5: ADR risk-register convention — reuse adr-kit (#3)

**Files:** Create `docs/adr/ADR-003-audit-risk-tooling.md`

> Sequencing is locked — A6 runs first, so adr-kit is present when D3 starts. Step 1 is a confirmation, not a branch. If adr-kit is somehow absent, the locked sequencing was violated → stop and run A6 to completion before continuing.

- [ ] **Step 1: Confirm adr-kit is available**

```bash
ls ~/.claude/plugins/cache/*adr-kit*/
ls docs/adr/
```

Expected: the adr-kit plugin cache exists and `docs/adr/ADR-000-adr-process.md` exists (created by the A6 plan). If absent → the locked sequencing was violated; stop and run A6 to completion first.

- [ ] **Step 2: Write the D3 risk-ADR**

Create `docs/adr/ADR-003-audit-risk-tooling.md`:

```markdown
# ADR-003: Audit & risk-management tooling (D3)

- **Status:** Accepted
- **Date:** 2026-05-17
- **Deciders:** Дмитрий

## Context
The `D3 «Аудит и управление рисками»` map section had zero tooling. Audits #1/#2/#3
were run ad-hoc. There was no standing decision/risk register.

## Decision
- Security/code audit — `/security-review` (customized) + Trail of Bits Skills.
- Inline risk warnings — Anthropic Security Guidance.
- Decision/risk register — **adr-kit ADRs** (this directory). An ADR's
  `## Consequences` section records risks + mitigations; the `Открытые_вопросы`
  registry holds *open, unresolved* risks. No separate risk-register tool.
- Toolchain attack-surface — manual procedure `docs/audit/toolchain-attack-surface.md`
  (community auto-auditors deferred — unverified provenance).
- The 14-phase portal-audit method is encoded as the `audit-portal` project skill.

## Consequences
- Positive: D3 section populated; audits repeatable.
- Risk: ToB / Security Guidance are third-party — bus-factor; mitigated by
  marketplace-cache pinning. Mitigation: re-verify on `/plugin` upgrades.
- Risk: +1 PreToolUse hook latency (~34 ms/edit) — accepted.

## Enforcement
None — D3 tools are advisory; verified by audits and code review.
```

- [ ] **Step 3: Lint + commit**

```bash
npx markdownlint-cli2 "docs/adr/ADR-003-audit-risk-tooling.md"
git add docs/adr/ADR-003-audit-risk-tooling.md
git commit -m "feat(adr): ADR-003 — D3 audit & risk-management tooling decision"
```

---

## Task 6: #5 toolchain attack-surface — provenance spike + manual procedure (TA1) — *severable*

**Files:** Create `docs/audit/` (dir), `docs/audit/README.md`, `docs/audit/toolchain-attack-surface.md`

- [ ] **Step 1: Provenance spike on the community auto-auditors**

Use `superpowers:systematic-debugging` discipline — 3 hypotheses, falsify each:

- H1 "Claude Code Canary (`geoffrey-young/anthropic-hackathon-2026`) is install-safe" — check: stars/maintenance, hackathon-only?, does it register hooks / read secrets?
- H2 "`Plugin Security Auditor` (mcpmarket) is install-safe" — check: real GitHub source, license, maintainer.
- H3 "neither clears the bar; a manual procedure is sufficient for D3 now."
Record the verdict. **Default expectation: H3** — defer the install.

- [ ] **Step 2: Create the audit directory + index**

```bash
mkdir -p "docs/audit"
```

Create `docs/audit/README.md`:

```markdown
# docs/audit — audit procedures & artifacts

Home of the `D3 «Аудит и управление рисками»` section. Holds repeatable audit
procedures. Toolset: `/security-review` (customized), Trail of Bits Skills,
Security Guidance, the `audit-portal` skill. Decisions/risks → `docs/adr/`.
Open product/business/legal risks → `docs/Открытые_вопросы_v8_3.md`.
```

- [ ] **Step 3: Write the manual toolchain attack-surface procedure (#5 deliverable)**

Create `docs/audit/toolchain-attack-surface.md` — a checklist covering the post-ruflo attack surface (20 ruflo plugins + ~210 MCP tools + 7 `.mcp.json` servers), motivated by the May-2026 MCP-MITM / ClaudeBleed disclosures:

```markdown
# Toolchain attack-surface audit (manual procedure)

Run quarterly, or after any new plugin / MCP server is added.

## 1. MCP servers
- Review every server in `.mcp.json` — command, args, env. Flag any non-pinned
  `npx` package and any server reachable over the network.
- Confirm no MCP URL was rewritten (npm postinstall MITM vector).

## 2. Plugins
- List `enabledPlugins` in `~/.claude/settings.json`. For each: source repo,
  license, last commit, hooks contributed.
- Flag plugins that register `PreToolUse` hooks with `decision:block`.

## 3. Hooks
- Diff `.claude/settings.json` + `.claude/settings.local.json` hook blocks vs
  the last audited snapshot. Any unexplained change → investigate.

## 4. Permissions
- Review `permissions.allow` / `deny` — no broadened wildcard, no new `Bash(*)`.

## 5. Secrets
- `gitleaks detect` full history; confirm no token in a gitignored cache file.

## Outcome
Record findings as P0-P3 in `docs/Открытые_вопросы_v8_3.md` (via `q-item-add`)
or as an ADR if a tooling decision results.
```

If Step 1 cleared a community auditor, additionally note it here as an optional accelerator.

- [ ] **Step 4: Lint + commit**

```bash
npx markdownlint-cli2 "docs/audit/*.md"
git add docs/audit/
git commit -m "docs(audit): toolchain attack-surface procedure + audit/ home (D3 #5)"
```

---

## Task 7: Distill the 14-phase portal audit into the `audit-portal` skill — *severable*

**Files:** Create `.claude/skills/audit-portal/SKILL.md`

- [ ] **Step 1: Gather the source material**

Read the three prior audit plans/findings as the methodology source:
`docs/superpowers/plans/2026-05-12-portal-full-audit.md`, `2026-05-13-portal-full-audit-2.md`, `2026-05-14-portal-full-audit-3.md` (and their `docs/superpowers/audits/` findings). Extract the stable 14-phase structure and the P0-P3 severity convention.

- [ ] **Step 2: Author the skill via skill-creator**

Invoke `skill-creator`. Create `.claude/skills/audit-portal/SKILL.md` — a project skill (auto-discovered like `rls-check` / `regression`) whose body:

- Lists the 14 audit phases in order, each with its concrete check.
- Maps each phase to the tool that runs it (`/security-review`, ToB `audit-context-building` / `static-analysis` / `supply-chain-risk-auditor`, `regression` skill, Pa11y, `rls-reviewer`).
- States the P0-P3 severity rubric and that findings are filed via `q-item-add`.
- `description:` frontmatter triggers on "audit the portal" / "full audit" / "портальный аудит".

- [ ] **Step 3: Verify the skill is discoverable**

```
/reload-plugins
```

Confirm `audit-portal` appears among available skills. Confirm no `hooks` block changed.

- [ ] **Step 4: Lint + commit**

```bash
npx markdownlint-cli2 ".claude/skills/audit-portal/SKILL.md"
git add .claude/skills/audit-portal/
git commit -m "feat(audit): distill 14-phase portal audit into audit-portal skill (D3)"
```

---

## Task 8: Normative registry sync (TB1/SG3/NUM1)

**Files:** Modify `docs/Tooling_v8_3.md`, `docs/Plugin_stack_rules_v1.md`, `docs/Pravila_raboty_Claude_v1_1.md`, `CLAUDE.md`, `docs/CHANGELOG_claude_md.md`

- [ ] **Step 1: Read the registry homes and the live counter (NUM1)**

Read for exact insertion points and the **current** counter: `docs/Tooling_v8_3.md` Прил. Н §0 + the last §4.x subsection; `docs/Plugin_stack_rules_v1.md` R10.1; `docs/Pravila_raboty_Claude_v1_1.md` §13.2. Assign D3's numbers sequentially from `counter + 1` — **after** any A6 entries already present. Record the two assigned numbers as `#N` (Trail of Bits Skills) and `#N+1` (Security Guidance).

- [ ] **Step 2: Add the Tooling Прил. Н audit-security subsection(s)**

Edit `docs/Tooling_v8_3.md`: add a new subsection for `#N Trail of Bits Skills` and `#N+1 Security Guidance`, category **audit-security** (off-phase). Per tool record: ToB Skills (marketplace `trailofbits/skills`, CC-BY-SA-4.0; **not vendored** — TB4; boundary vs Semgrep MCP — TB1); Security Guidance (Anthropic-verified marketplace plugin, one warn-only PreToolUse hook — SG1). Also document `/security-review` (Anthropic built-in, customized at `.claude/commands/security-review.md`) as a sub-bullet of the same subsection — it is a built-in, not an installed tool, so no numbered slot. Add the bus-factor note (CC1). Bump §0 counter and the Прил. Н version header.

- [ ] **Step 3: Add PSR_v1 R10.1 rows**

Edit `docs/Plugin_stack_rules_v1.md`: add Trail of Bits Skills + Security Guidance rows to R10.1, category **audit-security** (off-phase) — explicitly *outside* the UI-pool → no R6.0/R6.1 stack-filter, no R14 pipeline (same treatment as `claude-md-management` and the A6 architecture-tooling category). Bump the PSR_v1 version header.

- [ ] **Step 4: Add the Pravila §13.2 note**

Edit `docs/Pravila_raboty_Claude_v1_1.md` §13.2: add a one-line audit-security category note covering the two tools + `/security-review`, alongside the existing infrastructure / debug-runtime notes. Re-read Pravila §0/§13 first to keep numbering consistent. Bump the Pravila version header.

- [ ] **Step 5: Update CLAUDE.md via the governed channel**

Invoke `/claude-md-management:claude-md-improver`. Apply: §3 title count bump, §1 priority-chain row 2b count bump, new §3.3 audit-security rows for `#N`/`#N+1` + the `/security-review` sub-note. The plugin also writes the `docs/CHANGELOG_claude_md.md` entry and bumps §0 cross-ref versions (Tooling / PSR_v1 / Pravila). **Do not** edit `CLAUDE.md` directly (§5 п.10).

- [ ] **Step 6: Lint + commit**

```bash
npx markdownlint-cli2 "docs/Tooling_v8_3.md" "docs/Plugin_stack_rules_v1.md" "docs/Pravila_raboty_Claude_v1_1.md" "docs/CHANGELOG_claude_md.md"
npx cspell --no-progress --no-summary --no-gitignore "docs/Tooling_v8_3.md" "docs/Plugin_stack_rules_v1.md" "docs/Pravila_raboty_Claude_v1_1.md"
git add docs/Tooling_v8_3.md docs/Plugin_stack_rules_v1.md docs/Pravila_raboty_Claude_v1_1.md CLAUDE.md docs/CHANGELOG_claude_md.md cspell-words.txt
git commit -m "docs(audit): register Trail of Bits + Security Guidance (D3 audit-security)"
```

---

## Task 9: Reflect D3 on the map — close the section

**Files:** Modify `docs/automation-graph.html`

- [ ] **Step 1: Read the structures to replicate**

In `docs/automation-graph.html` read, as templates: an existing plugin node (`claude_md_mgmt`) and a project-skill node (`sk_rls`) across `NODES`, `NODE_DETAILS`/`nd(...)`, `NODE_SECTION`, and the "Паспорт узла" date fields. Record the current node/edge counts from the header (memory: 103 nodes / 106 edges).

- [ ] **Step 2: Add the D3 nodes**

Add to `NODES`, replicating the template shapes:

- `tob_skills` — label `Trail of Bits\nskills`, plugins group.
- `sec_guidance` — label `Security\nGuidance`, plugins group. *(omit if Task 4 was severed)*
- `sk_security_review` — label `security-review`, skills group (the customized Anthropic command).
- `sk_audit_portal` — label `audit-portal`, project-skills group. *(omit if Task 7 was severed)*

Add matching `nd(...)` / `NODE_DETAILS` entries (Russian, per the file's convention) with Паспорт `since: '2026-05-17'`. Add edges where real: `sk_audit_portal → sk_security_review` / `→ tob_skills` ("оркеструет"); `sec_guidance` as a PreToolUse-hook node if the file models hooks that way.

- [ ] **Step 3: Map the new nodes to section D3**

In `NODE_SECTION` add (omit any severed node):

```js
tob_skills: 'D3', sec_guidance: 'D3', sk_security_review: 'D3', sk_audit_portal: 'D3',
```

`D3 «Аудит и управление рисками»` goes from 0 → up to 4 nodes — the section is no longer empty.

- [ ] **Step 4: Update header metrics + group-count comments**

Bump the node count (and edge count if edges were added) in the map header/legend. Update the `NODE_SECTION` group-count comments (plugins, skills).

- [ ] **Step 5: Smoke-test the map**

```bash
npx stylelint docs/automation-graph.html
```

Open `docs/automation-graph.html` (Playwright MCP or local `http.server` — quirk 90: `file://` rejected). Expected: 0 JS console errors; the new nodes render; clicking section `D3` highlights them.

- [ ] **Step 6: Commit**

```bash
git add docs/automation-graph.html
git commit -m "feat(map): D3 nodes — closes section «Аудит и управление рисками»"
```

---

## Task 10: Final regression & branch finish

**Files:** none modified

- [ ] **Step 1: Full regression**

```
/regression full
```

Expected: GREEN. D3 changed no `app/` code → Pest / Vitest counts must match the Task 1 Step 3 baseline (0 regressions). Record exact counts; write out any failure with file:line.

- [ ] **Step 2: Confirm the hook chain is intact**

Economy marker still appears; Stop verifier still runs; ruflo + `CLAUDE.md`-warn hooks fire. If Task 4 ran, the Security Guidance hook is present and warn-only. Compare to the Task 1 Step 2 snapshot.

- [ ] **Step 3: Pre-push checks**

```bash
./bin/gitleaks.exe detect --source . --no-banner --redact
./bin/lychee.exe --config .lychee.toml "docs/**/*.md" "*.md"
```

Expected: gitleaks 0 leaks; lychee 0 broken (new `docs/audit/*.md`, `docs/adr/ADR-003*.md`, `.claude/commands/security-review.md` are scanned — fix or `.lychee.toml`-exclude any link).

- [ ] **Step 4: Finish the branch**

Invoke `superpowers:finishing-a-development-branch` — present the standard options. Do **not** push without an explicit user choice. Push pattern: `git push origin feat/d3-audit-risk-tooling:main`.

---

## Self-Review

**1. Spec coverage (D3 top-5, variant «а»).** #1 ToB Skills — install (Task 3). #2 `/security-review` — formalize (Task 2). #3 ADR/risk register — reuse adr-kit (Task 5, conditional). #4 Security Guidance — install (Task 4). #5 toolchain auditor — spike + manual procedure (Task 6). Bonus `audit-portal` skill (Task 7). Section closure: normative (Task 8), map (Task 9), regression/finish (Task 10). Conflict audit: TB1→T8.2, TB2→no task (map note), TB3→T3.4, TB4→T8.2, SG1→T4.3, SG2→no task, SG3→T8, SR1→T8.2, AD1→T5, AD2→T5 Step 1 (conditional), TA1→T6, AP1→no task, CC1→T8.2, NUM1→T8.1. No gaps.

**2. Placeholder scan.** `#N`/`#N+1` (Task 8) and the exact `/plugin install` plugin names (Tasks 3-4) are **runtime-resolved by design** — the live Tooling counter and the marketplace listing are not knowable before Task 1 Step 5 / Task 8 Step 1, which carry concrete resolution criteria (matches the A6 plan's "read the current node count" pattern). All file contents (security-review FP-filter, ADR-003, audit READMEs, the toolchain procedure) are shown in full. No "TBD"/"handle edge cases".

**3. Consistency.** Branch `feat/d3-audit-risk-tooling` consistent T1↔T10. Node ids `tob_skills` / `sec_guidance` / `sk_security_review` / `sk_audit_portal` consistent T9 Steps 2-3. Category name **audit-security** consistent T8 Steps 2-4. Severable tasks (4, 5, 6, 7) flagged at the header, in "Severable scope", and inline. `docs/audit/` / `docs/adr/` paths consistent.

---

## Execution Handoff

Plan complete and saved to `docs/superpowers/plans/2026-05-17-d3-audit-risk-tooling-integration.md`. Two execution options:

1. **Subagent-Driven (recommended for the doc-heavy tasks)** — fresh subagent per task, two-stage review. *Caveat:* Tasks 3, 4, 7 (`/plugin …`, `/reload-plugins`, `skill-creator`), Task 2 Step 4 + Task 3 Step 5 (skill/command invocations) and Task 8 Step 5 (`claude-md-management`) are main-session-bound — those steps stay with the controller.
2. **Inline Execution** — `superpowers:executing-plans`, batch with checkpoints. **Recommended here** — install/config/docs-heavy with many interactive main-session steps (same as the A6 plan).

**Decided 2026-05-17:** scope = **full integration** (all 10 tasks); sequencing = **A6 plan first, then D3** (locked — see "Sequencing" in the header).

One open item before execution: execution method — **1** (Subagent-Driven) or **2** (Inline, recommended here). And: D3 cannot start until the A6 epic is complete and pushed — confirm who runs A6.
