diff --git a/cspell-words.txt b/cspell-words.txt index 003af75b..38687278 100644 --- a/cspell-words.txt +++ b/cspell-words.txt @@ -1318,4 +1318,6 @@ MMM Nygard DDD mmdc +inertiajs +Sev вендоренный diff --git a/docs/superpowers/plans/2026-05-17-a6-architecture-tooling-integration.md b/docs/superpowers/plans/2026-05-17-a6-architecture-tooling-integration.md new file mode 100644 index 00000000..5a4febca --- /dev/null +++ b/docs/superpowers/plans/2026-05-17-a6-architecture-tooling-integration.md @@ -0,0 +1,659 @@ +# A6 Architecture 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:** Install three tools from the A6 top-5 — #1 `adr-kit` (architecture decisions + enforcement), #3 `mermaid-skill` (C4 / architecture diagrams), #4 `architecture-patterns` (patterns playbook) — and integrate them into Лидерра so the `A6 «Архитектура систем»` map section becomes a populated, working playbook. + +**Architecture:** Three tools, three install modes. **adr-kit** = marketplace plugin; its git pre-commit hook and `init` CLAUDE.md write are bypassed (lefthook job 9 + manual bootstrap). **architecture-patterns** = marketplace plugin, knowledge-only skill, zero machinery. **mermaid-skill** = standalone skill vendored into `.claude/skills/mermaid/` (no plugin, no marketplace, no hooks). All three are non-UI → architecture-tooling category, outside the PSR_v1 UI-pool. ADRs live in `docs/adr/`; C4 diagrams in `docs/architecture/`. + +**Tech Stack:** adr-kit v0.13.1 (marketplace `rvdbreemen/adr-kit`, MIT); mermaid-skill (`WH-2099/mermaid-skill`, standalone skill, MIT); architecture-patterns (`secondsky/claude-skills`, marketplace plugin, MIT); lefthook 2.x; project normative docs; `docs/automation-graph.html` (vis.js). + +--- + +## Tool Identity (verified 2026-05-17) + +| # | Tool | Install mode | Source | Hooks? | +|---|---|---|---|---| +| 1 | **adr-kit** v0.13.1 | Marketplace plugin — `rvdbreemen/adr-kit` → `adr-kit@rvdbreemen-adr-kit` | GitHub `rvdbreemen/adr-kit`, MIT | No CC lifecycle hooks; ships a git pre-commit hook (not used) | +| 3 | **mermaid-skill** | Standalone skill — vendored copy into `.claude/skills/mermaid/` | GitHub `WH-2099/mermaid-skill`, MIT | None (skill files only) | +| 4 | **architecture-patterns** | Marketplace plugin — `secondsky/claude-skills` → `architecture-patterns@claude-skills` | GitHub `secondsky/claude-skills`, MIT | None disclosed (verify on install) | + +Dropped from the top-5 by user: #2 `wshobson/agents` (agent sprawl, UI-pool overlap), #5 Anthropic baseline (narrow). + +--- + +## Design Decisions & Conflict Audit + +Pattern follows the K1–K8 audit used for claude-mem. Verified against the three repos, project `.claude/settings.json`, `~/.claude/settings.json`, `lefthook.yml`, `cspell.json`, `.markdownlintignore`. + +| # | Tool | Sev | Conflict | Resolution (locked) | +|---|---|---|---|---| +| AK1 | adr-kit | 🔴 | `/adr-kit:install-hooks`/`init` writes `.git/hooks/pre-commit`; lefthook owns that file → mutual clobber. | Never run `install-hooks`. Vendor `adr-judge`, wire as **lefthook pre-commit job 9** (Task 5). | +| AK2 | adr-kit | 🔴 | `/adr-kit:init` modifies root `CLAUDE.md` — violates CLAUDE.md §5 п.10 (edits only via `claude-md-management`). | Never run full `init`. Bootstrap manually (Task 4). The CLAUDE.md stub = the `§3.3 #36` row via `claude-md-management` (Task 7). | +| AK3 | adr-kit | 🟡 | `docs/adr/` overlaps the `Открытые_вопросы` registry. | Boundary in ADR-000 (Task 4): ADR = *closed technical/architecture* decision; registry = *open* product/business/legal questions. | +| AK4 | adr-kit | 🟡 | `adr-judge` `## Enforcement` rules could duplicate larastan/eslint/squawk. | Enforcement = architecture-level rules only ("no Inertia/Tailwind/React imports"); never re-encode lint/style rules. | +| AK5 | adr-kit | 🟢 | Lifecycle-hook collision with the 6 economy + 2 ruflo + skill-discipline hooks. | None — adr-kit registers zero CC lifecycle hooks. Re-verified Task 2 Step 5. | +| AK6 | adr-kit | 🟢 | `adr-judge` cost vs economy. | None — declarative regex, no LLM. No ADR will be flagged `llm_judge: true`. | +| AK7 | adr-kit | 🟡 | Plugin #10, Tooling #36 — unregistered = PSR_v1 R0.2/R10 violation on use. | Register in 4 normative homes (Task 7). | +| AK8 | adr-kit | 🟢 | `/adr-kit:judge` vs `superpowers:requesting-code-review` (§12). | None — different scope (ADR-compliance vs general review); §12.2 map unchanged. | +| MK1 | mermaid | 🟡 | Vendored `.claude/skills/mermaid/**/*.md` (third-party English refs) gets caught by the cspell + markdownlint pre-commit jobs. | Add `.claude/skills/mermaid/**` to `cspell.json` `ignorePaths` and `.markdownlintignore` (Task 3). Project's own skills stay linted. | +| MK2 | mermaid | 🟢 | Plugin/marketplace/hook footprint. | None — vendored skill = SKILL.md + references only. No `enabledPlugins` entry, no hooks. Re-verify Task 3 Step 4. | +| MK3 | mermaid | 🟢 | Overlap with the vis.js automation-graph. | None — different purpose: vis.js = the live "карта"; Mermaid = static C4/architecture diagrams in docs. Additive. | +| AP1 | arch-patterns | 🟢 | Hook/overlap footprint. | Knowledge-only skill; no overlap with Superpowers (no architecture skill) or Frontend Design (UI only). Verify hooks unchanged Task 2 Step 5. | +| AP2 | arch-patterns | 🟡 | Plugin #11, Tooling #38 — registration. | Register in 4 normative homes (Task 7). | +| CC1 | all 3 | 🟡 | Bus-factor — three small community projects (adr-kit pre-1.0; mermaid/arch-patterns single-maintainer). | mermaid is **vendored** (immune to upstream loss). adr-kit + arch-patterns are marketplace-cache-pinned. Note in Tooling §4.x as a known risk. No alpha-substrate spike needed — none has a known-broken core (unlike ruflo K7). | + +**Severable scope:** Task 5 (lefthook enforcement) is the only part touching the commit pipeline. **Knowledge-only** integration = skip Task 5 entirely — Tasks 1-4, 6-9 still deliver a working ADR store + diagram skill + patterns skill + populated map. Primary path below = full integration. + +--- + +## File Structure + +| File | Created / Modified | Responsibility | +|---|---|---| +| `docs/adr/` | Create dir | ADR document store, `ADR-XXX-kebab-title.md` | +| `docs/adr/ADR-000-adr-process.md` | Create | Meta-ADR: ADR vs registry vs `docs/architecture/` boundaries | +| `docs/adr/ADR-001-frontend-stack-vue-vuetify.md` | Create | Seed ADR with an `Enforcement` block (testable rule for Task 5) | +| `docs/adr/ADR-002-multitenancy-postgres-rls.md` | Create | Seed ADR, documentation-only | +| `docs/architecture/` | Create dir | C4 / system diagrams (Mermaid), models | +| `docs/architecture/README.md` | Create | Index — defines `docs/architecture/` purpose, links A6 | +| `docs/architecture/c4-context.md` | Create | Seed C4 Context diagram of Лидерра (proof + initial A6 content) | +| `.claude/skills/mermaid/` | Create (vendored) | The mermaid-skill — `SKILL.md` + `references/` | +| `.claude/adr-kit-guide.md` | Create | adr-kit canonical guide (manual copy from plugin cache) | +| `tools/adr-judge.mjs` | Create (vendored) | Project-local `adr-judge` runner — decouples lefthook from plugin cache | +| `lefthook.yml` | Modify | Add pre-commit job 9 `adr-judge` | +| `cspell.json` | Modify | `ignorePaths` += `.claude/skills/mermaid/**` | +| `.markdownlintignore` | Modify | += `.claude/skills/mermaid/` | +| `cspell-words.txt` | Modify (conditional) | New ADR/architecture vocabulary | +| `~/.claude/settings.json` | Modify | `enabledPlugins` += adr-kit + architecture-patterns; `extraKnownMarketplaces` += 2 | +| `docs/Tooling_v8_3.md` | Modify | Прил. Н — new §4.11/§4.12/§4.13 + §0 counter 35 → 38 | +| `docs/Plugin_stack_rules_v1.md` | Modify | R10.1 — 3 new rows | +| `docs/Pravila_raboty_Claude_v1_1.md` | Modify | §13.2 — architecture-tooling note | +| `CLAUDE.md` | Modify (**via claude-md-management only**) | §3 title count, §1 row 2b count, §3.3 rows #36/#37/#38 | +| `docs/CHANGELOG_claude_md.md` | Modify | CLAUDE.md version-bump entry | +| `docs/automation-graph.html` | Modify | 3 new nodes (`adr_kit`, `mermaid_skill`, `arch_patterns`) → `NODE_SECTION` A6 | + +--- + +## Task 1: Pre-flight — baseline, snapshot, fact-check + +**Files:** none modified (read-only) + +- [ ] **Step 1: Confirm clean tree and HEAD** + +```bash +cd "c:/моя/проекты/портал crm/Документация" +git status --short +git rev-parse --short HEAD +git branch --show-current +``` + +Expected: working tree shows only known untracked items; record HEAD SHA as the regression baseline. + +- [ ] **Step 2: Snapshot the git-hook owner** + +```bash +git config core.hooksPath +head -5 .git/hooks/pre-commit +``` + +Expected: pre-commit references `lefthook`. Task 5 must NOT change `.git/hooks/`. + +- [ ] **Step 3: Baseline the pre-commit chain** + +```bash +npx lefthook run pre-commit +``` + +Expected: all 8 jobs (gitleaks, markdownlint, cspell, stylelint, pint, larastan, squawk, eslint-vue) green / "no staged files". + +- [ ] **Step 4: Fact-check the 3 tools** + +Open and confirm assumptions still hold: + +- `https://github.com/rvdbreemen/adr-kit` — v0.13.x, no CC lifecycle hooks, marketplace `rvdbreemen/adr-kit`. +- `https://github.com/WH-2099/mermaid-skill` — standalone skill, files under `.claude/skills/mermaid/`, supports C4 + Architecture diagram types, MIT. +- `https://github.com/secondsky/claude-skills` — `architecture-patterns` installable as `architecture-patterns@claude-skills`, MIT. + +If any tool now registers CC lifecycle hooks → **stop**, re-audit AK5/MK2/AP1 before continuing. + +--- + +## Task 2: Install the two marketplace plugins (adr-kit, architecture-patterns) + +**Files:** Modify `~/.claude/settings.json` (the `Edit` triggers the `ask` permission — expected) + +- [ ] **Step 1: Add both marketplaces** + +``` +/plugin marketplace add rvdbreemen/adr-kit +/plugin marketplace add https://github.com/secondsky/claude-skills +``` + +- [ ] **Step 2: Install both plugins** + +``` +/plugin install adr-kit@rvdbreemen-adr-kit +/plugin install architecture-patterns@claude-skills +``` + +- [ ] **Step 3: Reload** + +``` +/reload-plugins +``` + +- [ ] **Step 4: Verify `enabledPlugins`** + +Read `~/.claude/settings.json` — `enabledPlugins` must now contain `adr-kit@rvdbreemen-adr-kit: true` and `architecture-patterns@claude-skills: true`, alongside the existing 9 → **11 plugins total**. + +- [ ] **Step 5: Verify NO lifecycle hooks were added (AK5 / AP1)** + +Read the `hooks` block of `~/.claude/settings.json` AND project `.claude/settings.json`. Both must be **unchanged** — still only the economy/skill-discipline/ruflo entries. If either plugin injected a `hooks` entry → stop and re-audit. + +- [ ] **Step 6: Verify adr-kit skills loaded** + +```bash +ls ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/skills/ +``` + +Expected: 8 skill directories (`adr`, `init`, `judge`, `install-hooks`, `upgrade`, `setup`, `lint`, `migrate`). + +- [ ] **Step 7: Confirm economy/ruflo chain intact** + +Submit a trivial prompt; confirm the economy marker still appears, no hook errors. No repo files changed in Task 2 → no commit. + +--- + +## Task 3: Install the mermaid-skill (standalone, vendored) + +**Files:** + +- Create: `.claude/skills/mermaid/` (vendored skill tree) +- Modify: `cspell.json`, `.markdownlintignore` + +- [ ] **Step 1: Clone the source to a temp location** + +```bash +git clone --depth 1 https://github.com/WH-2099/mermaid-skill.git /tmp/mermaid-skill-src +ls /tmp/mermaid-skill-src/.claude/skills/mermaid/ +``` + +Expected: `SKILL.md` + a `references/` directory. + +- [ ] **Step 2: Vendor the skill into the project** + +```bash +mkdir -p ".claude/skills/mermaid" +cp -r /tmp/mermaid-skill-src/.claude/skills/mermaid/. ".claude/skills/mermaid/" +ls -R ".claude/skills/mermaid/" +rm -rf /tmp/mermaid-skill-src +``` + +Expected: `.claude/skills/mermaid/SKILL.md` + `references/*.md` present. (Vendoring — not a submodule — keeps it on Windows+Cyrillic paths and immune to upstream loss, CC1.) + +- [ ] **Step 3: Exclude the vendored skill from the doc-lint chain (MK1)** + +Edit `.markdownlintignore` — append: + +``` +.claude/skills/mermaid/ +``` + +Edit `cspell.json` — add `.claude/skills/mermaid/**` to the `ignorePaths` array (create the array if absent). Do **not** ignore `.claude/skills/` wholesale — the project's own skills (`q-item-add`, `rls-check`, `regression`) stay linted. + +- [ ] **Step 4: Reload and verify the skill is discoverable** + +``` +/reload-plugins +``` + +Confirm a `mermaid` skill is now listed among available skills (project `.claude/skills/` is auto-discovered, like the existing 3 project skills). Confirm neither `settings.json` `hooks` block changed (MK2). + +- [ ] **Step 5: Verify lint exclusion works** + +```bash +git add .claude/skills/mermaid/ cspell.json .markdownlintignore +npx lefthook run pre-commit +``` + +Expected: cspell + markdownlint jobs do NOT report errors from `.claude/skills/mermaid/**`; all 8 jobs green. + +- [ ] **Step 6: Commit** + +```bash +git commit -m "feat(arch): vendor mermaid-skill into .claude/skills + lint-ignore (MK1)" +``` + +--- + +## Task 4: adr-kit controlled bootstrap (no `init`, no CLAUDE.md write) + +**Files:** + +- Create: `docs/adr/ADR-000-adr-process.md`, `ADR-001-frontend-stack-vue-vuetify.md`, `ADR-002-multitenancy-postgres-rls.md` +- Create: `.claude/adr-kit-guide.md` +- Modify (conditional): `cspell-words.txt` + +- [ ] **Step 1: Create the ADR directory** + +```bash +mkdir -p "docs/adr" +``` + +- [ ] **Step 2: Copy the adr-kit canonical guide** + +```bash +cp ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/skills/adr/SKILL.md ".claude/adr-kit-guide.md" +``` + +If the guide lives elsewhere (e.g. `references/guide.md`), copy that. Reference-only — this replaces what `init` would write, without touching `CLAUDE.md` (AK2). + +- [ ] **Step 3: Write ADR-000 — process / boundary meta-ADR** + +Create `docs/adr/ADR-000-adr-process.md`: + +```markdown +# ADR-000: ADR process and boundaries + +- **Status:** Accepted +- **Date:** 2026-05-17 +- **Deciders:** Дмитрий + +## Context +Лидерра tracks open product/business/legal questions in +`docs/Открытые_вопросы_v8_3.md`. Adding adr-kit introduces `docs/adr/`, and the +mermaid-skill introduces `docs/architecture/`. Without boundaries they overlap. + +## Decision +- **ADR (`docs/adr/`)** — a *closed technical/architecture decision*: stack, + patterns, structural boundaries, data-layer strategy. One file per decision. +- **`docs/architecture/`** — diagrams and models (C4, system context). Visual, + not normative; an ADR may embed or reference a diagram. +- **Открытые_вопросы registry** — *unresolved* product/business/legal questions + awaiting an explicit "закрываем". Not machine-enforced. +- A registry question resolving into a technical choice MAY graduate into an ADR. + +## Consequences +- No ADR for an item still open in the registry. +- ADR `## Enforcement` blocks target architecture-level constraints only — never + re-encode larastan / eslint / squawk rules (AK4). +``` + +- [ ] **Step 4: Write ADR-001 — frontend stack (with Enforcement)** + +Preferred: run `/adr-kit:adr "frontend stack Vue Vuetify"` and let the `adr-generator` agent emit the `## Enforcement` block in the exact v0.13 schema; paste the prose below. Verify key names (`forbid_import`/`forbid_pattern`/`require_pattern`) against `.claude/adr-kit-guide.md`. Create `docs/adr/ADR-001-frontend-stack-vue-vuetify.md`: + +```markdown +# ADR-001: Frontend stack — Vue 3 + Vuetify 3 + +- **Status:** Accepted +- **Date:** 2026-05-17 +- **Deciders:** Дмитрий + +## Context +Лидерра's UI is Vue 3 + Vuetify 3. Tailwind, Inertia, Livewire, Filament, Flux +UI, Nova, Folio, Volt, Wayfinder are excluded (CLAUDE.md §5 п.2). framer-motion +is a technical block — React-only peerDep, crashes in Vue. + +## Decision +All UI is Vue 3 SFC + Vuetify 3. No alternative UI framework or React-coupled +runtime library may be imported into `app/resources/js/`. + +## Consequences +- Laravel Boost (Roster auto-detect) serves only relevant guidelines. +- A dependency pulling React / Tailwind / Inertia is rejected at pre-commit. + +## Enforcement +```json +{ + "forbid_import": ["@inertiajs/vue3", "tailwindcss", "framer-motion", "react", "react-dom"], + "applies_to": ["app/resources/js/**"] +} +``` + +``` +(Adjust `applies_to` / key names to the schema in `.claude/adr-kit-guide.md`.) + +- [ ] **Step 5: Write ADR-002 — multi-tenancy via RLS (documentation-only)** + +Create `docs/adr/ADR-002-multitenancy-postgres-rls.md` — no Enforcement block: +```markdown +# ADR-002: Multi-tenancy via PostgreSQL Row-Level Security + +- **Status:** Accepted +- **Date:** 2026-05-17 +- **Deciders:** Дмитрий + +## Context +Лидерра is a multi-tenant SaaS CRM. Tenant isolation must be enforced at the +database layer, not only in application code. + +## Decision +Every tenant-scoped table carries RLS policies. Tenant id is set per transaction +via `SET LOCAL app.current_tenant_id` (`SetTenantContext` middleware). Five DB +roles; `crm_supplier_worker` is `BYPASSRLS` — queued jobs running as it MUST +filter `tenant_id` explicitly. + +## Consequences +- New tenant-scoped tables require an RLS policy + a `db/CHANGELOG_schema.md` + entry (CLAUDE.md §5 п.8). +- Verified by RLS smoke tests and the `rls-reviewer` agent — not by a regex gate. + +## Enforcement +None — verified by tests and code review. +``` + +- [ ] **Step 6: Lint and validate** + +```bash +npx markdownlint-cli2 "docs/adr/*.md" +npx cspell --no-progress --no-summary --no-gitignore "docs/adr/*.md" +``` + +Add valid project terms (`Vuetify`, `BYPASSRLS`, `Лидерра`, etc.) to `cspell-words.txt` if flagged. Then: + +``` +/adr-kit:lint docs/adr/ +``` + +Expected: all three ADRs pass adr-kit's structural checks. + +- [ ] **Step 7: Commit** + +```bash +git add docs/adr/ .claude/adr-kit-guide.md cspell-words.txt +git commit -m "feat(adr): bootstrap docs/adr — ADR-000/001/002 + adr-kit guide" +``` + +--- + +## Task 5: Wire `adr-judge` into lefthook (pre-commit job 9) + +**Files:** Create `tools/adr-judge.mjs`; Modify `lefthook.yml` + +> Skip this entire task for **knowledge-only** integration (see "Severable scope"). + +- [ ] **Step 1: Inspect `adr-judge` and choose the invocation** + +```bash +ls -la ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/bin/ +head -20 ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/bin/adr-judge +``` + +Decision: + +- **(a) self-contained** node/`.mjs` script, no plugin-local `require` → vendor: `cp /bin/adr-judge tools/adr-judge.mjs`. (Re-vendor after `/adr-kit:upgrade`.) +- **(b) has plugin-local deps** → write a 3-line `tools/adr-judge.mjs` wrapper that globs the newest `~/.claude/plugins/cache/rvdbreemen-adr-kit/*/bin/adr-judge` and `spawnSync`s it. + +Primary path = (a). Record the branch taken. + +- [ ] **Step 2: Add the lefthook job** + +Edit `lefthook.yml` — append after the `eslint-vue` job (job 8), inside `pre-commit:` → `jobs:`: + +```yaml + # 9. adr-judge — declarative ADR Enforcement-block checker (Прил. Н #36). + # Blocks the commit if a staged diff violates a forbid_*/require_* rule + # in an `## Enforcement` block of any docs/adr/ADR-*.md. + # Declarative regex only — no LLM calls, zero economy cost. + - name: adr-judge + glob: "*.{php,vue,ts,js,sql}" + run: node tools/adr-judge.mjs {staged_files} + fail_text: | + adr-judge: a staged change violates a documented Architecture Decision. + See the file:line citation above and the referenced docs/adr/ADR-*.md. + If the ADR is wrong, update it (and its Enforcement block) first. +``` + +- [ ] **Step 3: Verify the job runs clean** + +```bash +npx lefthook run pre-commit +``` + +Expected: 9 jobs now; `adr-judge` reports success. + +- [ ] **Step 4: Red test — confirm the gate blocks** + +```bash +echo "import { router } from '@inertiajs/vue3';" > app/resources/js/__adr_probe.ts +git add app/resources/js/__adr_probe.ts +npx lefthook run pre-commit +``` + +Expected: **FAIL** — `adr-judge` blocks on the `@inertiajs/vue3` import, citing `ADR-001` with file:line. + +- [ ] **Step 5: Green test — clean up** + +```bash +git restore --staged app/resources/js/__adr_probe.ts +rm app/resources/js/__adr_probe.ts +npx lefthook run pre-commit +``` + +Expected: PASS — all 9 jobs green, no probe file remaining. + +- [ ] **Step 6: Commit** + +```bash +git add lefthook.yml tools/adr-judge.mjs +git commit -m "feat(adr): wire adr-judge as lefthook pre-commit job 9 (AK1)" +``` + +--- + +## Task 6: Smoke #3 + #4, seed `docs/architecture/` + +**Files:** + +- Create: `docs/architecture/README.md`, `docs/architecture/c4-context.md` + +- [ ] **Step 1: Create the architecture-diagrams directory + index** + +```bash +mkdir -p "docs/architecture" +``` + +Create `docs/architecture/README.md`: + +```markdown +# docs/architecture — system diagrams & models + +C4 and architecture diagrams for Лидерра (Mermaid source). Generated with the +`mermaid` skill (`.claude/skills/mermaid/`). Decisions live in `docs/adr/`; +this directory holds the *visual* models. Map section: A6 «Архитектура систем». +``` + +- [ ] **Step 2: Smoke-test the mermaid skill — generate the seed C4 diagram** + +Invoke the `mermaid` skill to author a C4 Context diagram. Create `docs/architecture/c4-context.md`: + +````markdown +# C4 — System Context: Лидерра + +```mermaid +C4Context + title Лидерра — System Context + Person(manager, "Менеджер арендатора", "Работает со сделками и лидами") + Person(saasAdmin, "SaaS-админ", "Биллинг, инциденты, арендаторы") + System(liderra, "Лидерра CRM", "Multi-tenant CRM: лиды, сделки, биллинг") + System_Ext(supplier, "crm.bp-gr.ru", "Поставщик лидов (B1/B2/B3)") + System_Ext(unisender, "Unisender Go", "SMTP-relay для email") + System_Ext(yandex360, "Yandex 360", "SSO администраторов") + Rel(manager, liderra, "Использует", "HTTPS") + Rel(saasAdmin, liderra, "Администрирует", "HTTPS") + Rel(liderra, supplier, "Импорт лидов / webhook", "HTTPS") + Rel(liderra, unisender, "Отправка email", "SMTP") + Rel(saasAdmin, yandex360, "Аутентификация", "OAuth") +``` +```` + +Expected: the skill loads, the Mermaid `C4Context` block is syntactically valid (renders on GitHub natively — no `mmdc`/Chromium needed). + +- [ ] **Step 3: Smoke-test the architecture-patterns skill** + +Ask a sample architecture question (e.g. "what pattern fits the supplier-lead import pipeline?") and confirm the `architecture-patterns` skill activates and returns pattern guidance (layered / hexagonal / event-driven etc.). This is a functional smoke test — no file output required. + +- [ ] **Step 4: Lint the new docs** + +```bash +npx markdownlint-cli2 "docs/architecture/*.md" +npx cspell --no-progress --no-summary --no-gitignore "docs/architecture/*.md" +``` + +Add flagged valid terms to `cspell-words.txt`. + +- [ ] **Step 5: Commit** + +```bash +git add docs/architecture/ cspell-words.txt +git commit -m "feat(arch): seed docs/architecture — C4 Context diagram + index" +``` + +--- + +## Task 7: Unified normative registry sync (AK7 / AP2) + +**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** + +Read for exact insertion points and counters: `docs/Tooling_v8_3.md` Прил. Н §0 (counter "35") + §4.8/§4.9/§4.10; `docs/Plugin_stack_rules_v1.md` R10.1; `docs/Pravila_raboty_Claude_v1_1.md` §13.2. + +- [ ] **Step 2: Add Tooling Прил. Н §4.11–§4.13** + +Edit `docs/Tooling_v8_3.md`: add three subsections — `§4.11 #36 adr-kit`, `§4.12 #37 mermaid-skill`, `§4.13 #38 architecture-patterns` — all category **architecture-tooling** (off-phase). Note per tool: adr-kit (marketplace `rvdbreemen/adr-kit` v0.13.1 MIT; `adr-judge` via lefthook job 9, NOT adr-kit's git hook — AK1; `init`/`install-hooks` unused — AK1/AK2); mermaid-skill (`WH-2099/mermaid-skill` MIT, vendored standalone skill in `.claude/skills/mermaid/`); architecture-patterns (`secondsky/claude-skills` MIT, marketplace plugin). Add the bus-factor note (CC1). Bump §0 counter `35 → 38`; bump the Прил. Н version header. + +- [ ] **Step 3: Add 3 PSR_v1 R10.1 rows** + +Edit `docs/Plugin_stack_rules_v1.md`: add adr-kit, mermaid-skill, architecture-patterns rows to R10.1, category **architecture-tooling** (off-phase) — explicitly *outside* the UI-pool → no R6.0/R6.1 stack-filter, no R14 pipeline (same treatment as `claude-md-management`). 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 architecture-tooling note covering the three tools, alongside the existing infrastructure note. Re-read Pravila §0/§13 first to keep section 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 (`35` → `38`), §1 priority-chain row 2b count (`35` → `38`), three new §3.3 rows `#36 adr-kit` / `#37 mermaid-skill` / `#38 architecture-patterns` (architecture-tooling, off-phase). The plugin also writes the `docs/CHANGELOG_claude_md.md` entry and bumps §0 cross-ref versions (Tooling / PSR_v1 / Pravila). + +- [ ] **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(arch): register adr-kit/mermaid/architecture-patterns #36-38 (AK7/AP2)" +``` + +--- + +## Task 8: Reflect the 3 tools on the map (close A6) + +**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` — across `NODES`, `NODE_DETAILS`, `NODE_SECTION`, and the "Паспорт узла" date fields. Read an existing skill node for the mermaid-skill template. Note the current node count (~103-104) and the plugins-group size. + +- [ ] **Step 2: Add three nodes** + +Add to `NODES`, replicating the template shapes: + +- `adr_kit` — label `adr-kit`, plugins group. +- `arch_patterns` — label `architecture-patterns`, plugins group. +- `mermaid_skill` — label `mermaid (skill)`, skills group. + +Add matching `NODE_DETAILS` entries: adr_kit — "Плагин ADR. docs/adr/ + adr-judge в lefthook job 9."; arch_patterns — "Скил-плагин: справочник архитектурных паттернов."; mermaid_skill — "Vendored-скил: C4/architecture-диаграммы (Mermaid) → docs/architecture/." Паспорт: дата внедрения `2026-05-17` for all three. + +- [ ] **Step 3: Map all three to section A6** + +In `NODE_SECTION` add: + +```js +adr_kit: 'A6', arch_patterns: 'A6', mermaid_skill: 'A6', +``` + +A6 «Архитектура систем» goes from 0 → 3 nodes — the section is no longer empty. + +- [ ] **Step 4: Update header metrics** + +Bump the node count in the map header/legend by 3 (e.g. `103 → 106`). Update the plugins-group and skills-group count comments in `NODE_SECTION`. + +- [ ] **Step 5: Smoke-test the map** + +```bash +npx stylelint docs/automation-graph.html +``` + +Open `docs/automation-graph.html` in a browser (Playwright MCP or local `http.server`): 0 JS console errors; the 3 new nodes render; clicking section `A6` highlights all three. + +- [ ] **Step 6: Commit** + +```bash +git add docs/automation-graph.html +git commit -m "feat(map): add adr_kit/mermaid/arch_patterns nodes — closes section A6" +``` + +--- + +## Task 9: Final regression & branch finish + +**Files:** none modified + +- [ ] **Step 1: Full pre-commit chain** + +```bash +npx lefthook run pre-commit +``` + +Expected: all **9** jobs green (8 if knowledge-only). + +- [ ] **Step 2: Confirm app code untouched — run the suites** + +These tools change no `app/` code → suites must match the Task 1 baseline: + +```bash +cd app && php artisan test --parallel +npm run test:vue +``` + +Expected: Pest and Vitest counts unchanged vs Task 1 baseline (0 regressions). Record exact counts. + +- [ ] **Step 3: Confirm the economy/ruflo hook chain is intact** + +Economy marker still appears; Stop verifier still runs; no plugin leaked a `hooks` entry into either `settings.json`. + +- [ ] **Step 4: Pre-push checks** + +```bash +./bin/gitleaks.exe detect --source . --no-banner --config .gitleaks.toml --redact +./bin/lychee.exe --config .lychee.toml "docs/**/*.md" "db/**/*.md" "*.md" +``` + +Expected: gitleaks 0 leaks; lychee 0 broken (new `docs/adr/*.md` + `docs/architecture/*.md` are scanned — fix or `.lychee.toml`-exclude any link). + +- [ ] **Step 5: Finish the branch** + +Invoke `superpowers:finishing-a-development-branch` — present the standard options. Do **not** push without an explicit user choice. + +--- + +## Self-Review + +**1. Spec coverage** — adr-kit: install (Task 2), bootstrap (Task 4), enforcement (Task 5). mermaid-skill: install+lint-ignore (Task 3), smoke+seed (Task 6). architecture-patterns: install (Task 2), smoke (Task 6). Conflict audit: AK1→T5, AK2→T4+T7.5, AK3→T4.3 (ADR-000), AK4→T4.4, AK5/AP1→T2.5, AK6→no task, AK7/AP2→T7, AK8→no task, MK1→T3.3, MK2→T3.4, MK3→no task, CC1→T7.2. Map A6 closure→T8. No gaps. + +**2. Placeholder scan** — Task 5 Step 1 and Task 8 Step 1 are *decision/read-template* steps with concrete criteria, not "TBD" (the adr-judge dep shape and the live `claude_md_mgmt` node shape are not knowable without install / without reading the 2400-line map). All commands exact; ADR + C4 + README content shown in full. + +**3. Consistency** — `adr-judge` invoked uniformly (`node tools/adr-judge.mjs`); paths consistent (`docs/adr/`, `docs/architecture/`, `.claude/skills/mermaid/`); tool counter `35 → 38` consistent T7↔T8; node ids `adr_kit`/`mermaid_skill`/`arch_patterns` consistent T8 Steps 2-3; plugin ids `adr-kit@rvdbreemen-adr-kit` / `architecture-patterns@claude-skills` consistent. + +--- + +## Execution Handoff + +Plan complete. Two execution options: + +1. **Subagent-Driven** — fresh subagent per task, two-stage review. *Caveat:* Tasks 2, 3 (slash commands `/plugin …`, `/reload-plugins`), Task 4 Step 6 (`/adr-kit:lint`), Task 6 Steps 2-3 (skill invocations) and Task 7 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** — the integration is install/config/docs-heavy with many interactive main-session steps. + +Open question for the user: **full integration** (incl. Task 5 — adr-judge pre-commit enforcement) or **knowledge-only** (skip Task 5 — ADR store + diagrams + patterns skill, no commit gate)?