---
slug: "solutions-architect-skills"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/shadowX4fox/solutions-architect-skills@main/README.md"
repo: "https://github.com/shadowX4fox/solutions-architect-skills"
source_file: "README.md"
branch: "main"
---
# Solutions Architect Skills

[![Version](https://img.shields.io/badge/version-3.28.8-blue.svg)](https://github.com/shadowx4fox/solutions-architect-skills/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple.svg)](https://claude.com/claude-code)

Professional architecture documentation workflow for Claude Code: Transform business requirements into technical architecture, compliance documents, and development handoffs.



## Overview

This Claude Code plugin provides a complete four-phase workflow for enterprise architecture documentation:

```
Phase 1: Business Requirements (PO Spec)
    ↓
Phase 2: Technical Architecture (ARCHITECTURE.md)
    ↓
Phase 3: Compliance Documents (10 contracts)
    ↓
Phase 4: Development Handoff & Export (.md + .docx)
```

## Claude Code Marketplace & Plugin System

This project is distributed as a **Claude Code Plugin** via the **shadowX4fox Marketplace**:

- **Marketplace**: A catalog of available plugins ([Learn more](https://docs.anthropic.com/claude/docs/claude-code-plugins))
- **Plugin**: This repository, installable from the marketplace
- **Skills**: Sixteen specialized skills within the plugin

For detailed information about Claude Code's plugin system, see the [official Claude Code documentation](https://docs.anthropic.com/claude/docs/claude-code).

---

### What's Included

- **16 Integrated Skills**
  - `architecture-readiness`: Requirements Elicitation + Product Owner Specifications
  - `architecture-enterprise-alignment` (v3.25.0): Maps the PO Spec onto the 8-domain BIAN v14 capability map (Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler — 47 capabilities total) → `ENTERPRISE_ALIGNMENT.md`. **Mandatory gate before `architecture-docs` Workflow 1** (Step 0.3 — no `SKIP` override; cascades-skip only if the PO Spec gate was skipped). Bundled enterprise model is overridable via project-local `ENTERPRISE_MODEL.md`. The Summary, Cross-Cutting Findings, and Owner Engagement Plan are lifted into Section 1.5 of `docs/01-system-overview.md` during architecture creation.
  - `architecture-docs`: ARCHITECTURE.md creation and maintenance (with diagram generation)
  - `architecture-component-guardian`: Single owner of `docs/components/README.md` index + C4 migration
  - `architecture-definition-record`: Create, update, and manage Architecture Decision Records (ADRs)
  - `architecture-compliance`: Generate 10 compliance contracts from ARCHITECTURE.md
  - `architecture-compliance-review`: Compliance portfolio health review + gap explorer playground
  - `architecture-peer-review`: Interactive peer review with playground tool + JSON persistence
  - `architecture-traceability`: PO Spec use cases vs architecture coverage report (markdown, portable)
  - `architecture-analysis`: 10-analysis risk & design-characteristics dashboard (SPOF, Blast Radius, Bottleneck, Cost Hotspots, STRIDE, Vendor Lock-in, Latency Budget, Tech Debt/EOL, Coupling, Data Sensitivity)
  - `architecture-dev-handoff`: Component development handoffs (C4 L2 only) with deliverable assets
  - `architecture-docs-export`: On-demand Word (.docx) export for architecture docs and handoffs
  - `architecture-blueprint`: Business & Application blueprint files (datos de iniciativa) from ARCHITECTURE.md
  - `architecture-onboarding`: Interactive concept map playground for new team members
  - `architecture-icepanel-sync` (beta): Sync C4 model to IcePanel via import YAML or REST API
  - `architecture-explorer-headers` (v3.14.0): Backfill `<!-- EXPLORER_HEADER -->` blocks into legacy docs so the universal `architecture-explorer` agent can classify them accurately. Slash command: `/sa-skills:regenerate-explorer-headers` (with `--dry-run`, `--force`, scope glob)

- **Universal `architecture-explorer` Agent (v3.16.0)**
  - Haiku-tier doc navigator — front door for every doc-consuming workflow (compliance, analysis, peer-review, dev-handoff, free-form Q&A, ADR application)
  - Walks the canonical layout (`ARCHITECTURE.md` + `docs/` + `adr/`) and emits an `EXPLORE_MANIFEST` listing every file in the corpus along with its `<!-- EXPLORER_HEADER -->` metadata (`key_concepts`, `technologies`, `related_adrs`, …)
  - **No ranking, no cache, no per-task configs.** Downstream skills consume the manifest and pick what to read using their own domain configs (e.g. `agents/configs/<contract>.json:phase3.required_files` for compliance, hardcoded base file lists per analysis lens). The dev-handoff orchestrator passes a `component_file` parameter to enable a per-component `focus_component.related_adrs` block sourced directly from that component's EXPLORER_HEADER.
  - `<!-- EXPLORER_HEADER -->` blocks in `docs/NN-*.md` and `docs/components/**/*.md` files (5–10 lines after the H1, listing key concepts, technologies, components, scope, related ADRs) maximize downstream filtering accuracy. Legacy docs without a header are listed in the manifest with `has_header: false` and treated conservatively by downstream filters.

- **C4 Model Integration (IcePanel)**
  - Components follow C4 Level 2 (Container diagram) rules — every component must be a separately deployable unit (App or Store)
  - 5 architecture types with reference docs + C4 translation guides: Microservices, 3-Tier, N-Layer, META, BIAN
  - C4 L1 systems become folder structure, C4 L2 containers become component files
  - Component guardian enforces C4 boundary test and IcePanel naming conventions (`[Technology in brackets]`)

- **10 Compliance Contracts (CC-001 to CC-010)**
  - Universal generator + 10 domain validators with personality and EOL checks
  - 4-tier approval workflow (Auto-approve, Manual review, Needs work, Rejected)
  - External Validation Summary in every contract
  - EOL-first validation via WebSearch (6-month safety period)

- **Automatic Validation**
  - External validation system (0-10 scoring) for all 10 contracts
  - Template-specific validation configurations
  - Metric consistency checking
  - Design Drivers calculation

- **Optional MCP Integration — [context7](https://context7.com)**
  - Fetches current library/framework documentation during asset generation and component documentation
  - Used by `architecture-dev-handoff` (spec validation for OpenAPI, AsyncAPI, K8s, etc.) and `architecture-docs` (technology context briefs)
  - Fully optional — all skills degrade gracefully without it

- **Complete Documentation**
  - Installation guide, Quick Start tutorial, Workflow guide, Troubleshooting

## Quick Start

### Installation

**See [Installation Guide](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/INSTALLATION.md) for detailed instructions.**

#### Step 0 — Install Bun (one-time prerequisite)

The plugin requires Bun (v1.0+) for template expansion, contract validation, and the cross-platform helper scripts (`scripts/today.ts`, `scripts/ensure-dir.ts`, `scripts/remove-glob.ts`). As of v3.25.2 the UserPromptSubmit hook layer is pure-native shell/cmd/PowerShell with **zero JS-runtime dependency** — if you only want the hook (architecture-routing context injection) and not the full skill suite, you can install the plugin without Bun. Pick the install path that matches your OS:

**Windows (native cmd / PowerShell)** — recommended path:

```powershell
npm install -g bun
```

This is the most reliable Windows-native install. Requires Node.js (which is already on most Windows dev machines because of the broader JavaScript tooling). The official `irm bun.sh/install.ps1 | iex` one-liner also works on PowerShell, but it occasionally trips on execution-policy restrictions, corporate proxies, or signed-script enforcement — `npm install -g bun` sidesteps all three because npm is already trusted in your PowerShell profile if Node is installed.

**macOS / Linux**

```bash
curl -fsSL https://bun.sh/install | bash
```

Or, on macOS only, via Homebrew:

```bash
brew install bun
```

**WSL2 or Git Bash on Windows** — use the Linux/macOS curl one-liner above. The plugin works identically inside WSL or Git Bash because both expose a POSIX userland; v3.21.1's native wrappers also work natively in either, so you don't have to choose between them.

**Verify** (any OS):

```bash
bun --version
# 1.0.0 or higher
```

If `bun` is not on `PATH` after install, restart your terminal (or, on Windows, sign out and back in so the system PATH update takes effect).

#### Step 1 — Install the plugin

**Quick Start (Using Marketplace — Recommended on every OS):**

```bash
# Register marketplace (one-time)
/plugin marketplace add shadowX4fox/solutions-architect-skills

# Install plugin
/plugin install sa-skills@shadowx4fox-solution-architect-marketplace

# Verify installation
/plugin list
```

**Alternative: Direct Git Clone**

```bash
# Clone directly to plugins directory
git clone https://github.com/shadowX4fox/solutions-architect-skills.git ~/.claude/plugins/solutions-architect-skills

# Restart Claude Code and verify
/plugin list
```

You should see `sa-skills v3.28.8` in the list.

**Important:** Marketplace registration is a security feature — you must explicitly add marketplaces before installing plugins. See [docs/INSTALLATION.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/INSTALLATION.md) for detailed setup instructions.

#### Step 2 — Configure for your platform with `/sa-skills:setup`

> **Plugin slash-command namespace:** Claude Code namespaces every plugin's slash commands under the plugin name. The three commands shipped by this plugin (`commands/setup.md`, `commands/release-architecture.md`, `commands/regenerate-explorer-headers.md`) appear after install as:
>
> - `/sa-skills:setup`
> - `/sa-skills:release-architecture`
> - `/sa-skills:regenerate-explorer-headers`
>
> Older docs and changelog entries refer to the bare names (`/setup`, `/release-architecture`, `/regenerate-explorer-headers`); read those as shorthand for the namespaced form. Type `/` in Claude Code to see the namespaced commands in autocomplete.

The plugin's UserPromptSubmit hook ships in three native variants under `hooks/`:

- `route-architecture-docs.sh` (Linux, macOS, WSL, Git Bash)
- `route-architecture-docs.cmd` (Windows native cmd.exe)
- `route-architecture-docs.ps1` (PowerShell on any OS)

Each wrapper self-resolves its own directory and emits the static `route-architecture-docs.payload.json` file when ARCHITECTURE.md is present at the project root — no `~` expansion, no JavaScript runtime, no Bun cold start. On every OS, run:

```
/sa-skills:setup
```

The setup helper:
1. Detects `process.platform` at install time.
2. Computes the absolute path to the matching wrapper.
3. Writes that absolute path into your project's `.claude/settings.json` under `hooks.UserPromptSubmit`.
4. Sweeps any legacy hook entry from earlier sa-skills versions (v3.19.0 `sh ~/...sh`, v3.21.0–v3.25.1 `bun ~/...ts`) in the same pass.
5. Reports which platform was detected and the resolved hook command in its stdout summary.

**Bun is no longer required for the hook layer** (as of v3.25.2). Skill workflows still use Bun via `Bash(bun *)` permission for cross-platform helpers (`scripts/today.ts`, `scripts/ensure-dir.ts`, `scripts/remove-glob.ts`), so the Step 0 Bun install in the table below stays useful — it's just no longer a hook prerequisite. If you only need the hook (UserPromptSubmit context injection) and not the full skill suite, you can install the plugin without Bun and the hook will work pure-natively.

**Why per-OS sections matter:** the plugin's wrappers each target a different native shell (POSIX `sh`, Windows `cmd.exe`, PowerShell). `/sa-skills:setup` auto-detection eliminates the choice — Windows cmd, Windows PowerShell, Linux, macOS, WSL, and Git Bash all install with the same one-line `/sa-skills:setup` command and end up with a hook command that runs natively on the host shell.

| Your OS / Shell | Bun install (Step 0, for skill workflows) | What `/sa-skills:setup` writes (Step 2) |
|---|---|---|
| Windows cmd.exe | `npm install -g bun` (skills only — hook works without it) | `cmd /c "<abs-path>\\hooks\\route-architecture-docs.cmd"` |
| Windows PowerShell | `npm install -g bun` (skills only — hook works without it) | `cmd /c "<abs-path>\\hooks\\route-architecture-docs.cmd"` (cmd wrapper still chosen — universally available; if you specifically want the .ps1, edit settings.json by hand) |
| Windows + WSL2 | `curl -fsSL https://bun.sh/install \| bash` (inside WSL; skills only) | `sh <abs-path>/hooks/route-architecture-docs.sh` |
| Windows + Git Bash | `curl -fsSL https://bun.sh/install \| bash` (inside Git Bash; skills only) | `sh <abs-path>/hooks/route-architecture-docs.sh` |
| macOS | `brew install bun` or curl one-liner (skills only) | `sh <abs-path>/hooks/route-architecture-docs.sh` |
| Linux | curl one-liner (skills only) | `sh <abs-path>/hooks/route-architecture-docs.sh` |

### Optional: Enable context7

[context7](https://context7.com) provides up-to-date library documentation to improve generated assets (OpenAPI specs, K8s manifests, DDL, etc.). Two skills use it when available:

| Skill | Usage |
|-------|-------|
| `architecture-dev-handoff` | Fetches current spec docs (OpenAPI, AsyncAPI, Kubernetes, Protobuf, Avro, DDL, Redis) to validate generated asset syntax |
| `architecture-docs` | Fetches framework docs for technologies in new component files; presents a Technology Context Brief |

**MCP server setup (recommended):**

Add to your Claude Code MCP settings (`~/.claude.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["@upstash/context7-mcp"]
    }
  }
}
```

**Alternative — automatic setup via CLI:**

```bash
npx ctx7 setup --claude
```

This authenticates via OAuth, generates an API key, and configures context7 automatically.

For headless/remote environments, pass your API key directly:

```bash
npx ctx7 setup --claude --api-key YOUR_API_KEY
```

Generate your API key at the [context7 dashboard](https://context7.com).

> context7 is fully optional. All skills complete successfully without it — no errors or warnings.

### First Workflow

**Phase 1 — Business Requirements (Product Owner)**

```bash
/skill architecture-readiness
```

The skill has 4 modes (ordered by priority):

1. **Async Intake** — provide a file (ticket, email, requirements doc) → gap report with email-ready questions → STOPS (never enters elicitation)
2. **Requirements Elicitation** — guided discovery interview (4 phases):
   - Foundation → Value & Boundaries → Behavior → Experience & Measurement
   - Discovery Summary → draft PO Spec → self-scored to ≥ 7.5/10 → `PRODUCT_OWNER_SPEC.md`
3. **PO Spec Creation** — template-guided document creation
4. **PO Spec Evaluation** — score existing PO Spec (0-10 weighted rubric)

**Phase 2 — Technical Architecture**

```bash
/skill architecture-docs
```

Hand off `PRODUCT_OWNER_SPEC.md` to your architecture team. The skill produces a multi-file structure:

```
ARCHITECTURE.md          ← navigation index (~130 lines)
docs/                    ← all section content
└── components/          ← one file per architectural component
adr/                     ← Architecture Decision Records
```

**Phase 3 — Compliance Documents**

```bash
/skill architecture-compliance
```

Generates 10 compliance contracts from `ARCHITECTURE.md` into `/compliance-docs/`. To remediate gaps found in compliance contracts, use `/skill architecture-docs` — the skill guides you through updating `ARCHITECTURE.md` for each finding.

**Phase 4 — Development Handoff**

```bash
/skill architecture-dev-handoff
```

Generates per-component handoff documents with deliverable assets into `handoffs/`. Produces an 8-section audience-segmented guide per component (HANDOFF_TEMPLATE v2.1.0) with Dev / QA / Ops tracks (API contract, data model, security, observability, acceptance criteria, etc.) plus type-specific assets (OpenAPI specs, DDL scripts, K8s manifests, and more). Scoped to C4 Level 2 (Container) components only.

**Phase 4.5 — Word Export (optional)**

```bash
/skill architecture-docs-export
```

Exports architecture documents to professional Word (.docx) files: SA executive summary (synthesized from overview + component index + compliance manifest), individual ADRs, or component handoffs.

**Quality Gates (recommended after Phase 2)**

```bash
/skill architecture-peer-review       # Quality review — 3 depth levels, 13 categories, scorecard
/skill architecture-traceability      # PO Spec coverage check — generates TRACEABILITY_REPORT.md
/skill architecture-compliance-review # Portfolio health + concept gap explorer (after Phase 3)
```

### Supporting Skills

| Skill | When to Use |
|-------|-------------|
| `/skill architecture-peer-review` | After ARCHITECTURE.md is complete — interactive quality review with approve/reject/fix workflow (JSON persistence for fast regeneration) |
| `/skill architecture-traceability` | Check if architecture covers all PO Spec requirements — generates portable markdown report |
| `/skill architecture-analysis` | Risk and design-characteristics dashboard — 10 analyses (SPOF, Blast Radius, Bottleneck, Cost Hotspots, STRIDE, Vendor Lock-in, Latency Budget, Tech Debt/EOL, Coupling, Data Sensitivity) run individually or all-ten in parallel |
| `/skill architecture-blueprint` | When organizational blueprint forms (datos de iniciativa) are required |
| `/skill architecture-compliance-review` | After compliance contracts are generated — explore gaps across all 10 contracts |
| `/skill architecture-component-guardian` | Adding, removing, updating components, or migrating flat components to C4 multi-system structure |
| `/skill architecture-definition-record` | All ADR write operations — create, update, supersede |
| `/skill architecture-onboarding` | Onboarding new team members — interactive concept map of the architecture suite |
| `/skill architecture-icepanel-sync` | Sync architecture C4 model to IcePanel (beta) |

## Features

### Phase 1: Architecture Readiness (Product Owner)

Create comprehensive Product Owner Specifications before technical design begins. Includes a structured discovery interview when starting from scratch.

**Key Features:**
- **Requirements Elicitation** — 4-phase guided discovery interview (Foundation → Value & Boundaries → Behavior → Experience & Measurement)
  - Probing techniques: scenario walking, quantification, negative probing, assumption surfacing
  - Industry defaults when PO is unsure; unknowns logged as Open Questions
  - Discovery Summary checkpoint before drafting; self-scoring gap loop until ≥7.5
- **Async Intake** — file-based requirements extraction from tickets, emails, or documents
  - Scores input against the PO Spec rubric (same 8 sections, same weights)
  - Produces `PO_SPEC_GAP_REPORT.md` with ready-to-send questions per gap, prioritized by section weight
  - No interactive interview — output is a written gap report the architect forwards to the requester
  - If score ≥ 7.5, also drafts `PRODUCT_OWNER_SPEC.md` automatically
- 8-section template (Business Context, User Personas, Use Cases, Success Criteria, etc.)
- Weighted scoring methodology (0-10 scale)
- Readiness threshold: ≥7.5 for architecture handoff
- Focus: Business requirements, no technical implementation
- Bilingual interview support (language auto-detected from user's first message)

**Output:** `PRODUCT_OWNER_SPEC.md`

### Phase 1.5: Enterprise Alignment Gate (Architecture Governance)

Maps the accepted PO Spec onto the organisation's 8-domain BIAN v14 capability map **before** technical design begins. Identifies which corporate domains are impacted, which governance rules will constrain the initiative, and which owner counterparts must be engaged at kickoff. **Mandatory gate** — `architecture-docs` Workflow 1 Step 0.3 blocks new ARCHITECTURE.md creation until this file exists (no `SKIP ENTERPRISE ALIGNMENT` override; cascades-skip only when the PO Spec gate itself was skipped).

**Key Features:**
- 8-domain BIAN v14 model (47 capabilities): Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler
- Bundled default model overridable by a project-local `ENTERPRISE_MODEL.md` at the project root
- Status taxonomy: 🟢 Impacted / 🟡 Partial / ⚪ Not Applicable
- Verbatim citation of governance rules from the model (no paraphrasing)
- Cross-cutting mandatory checks (Enterprise Management, Finance & Risks, Business Enabler) regardless of per-domain status
- Owner Engagement Plan with engagement timing derived from rule wording (Before kickoff / Before architecture sign-off / Before production)
- Lifts Summary + Cross-Cutting Findings + Owner Engagement table into Section 1.5 of `docs/01-system-overview.md` after the gate passes

**Output:** `ENTERPRISE_ALIGNMENT.md` at the project root

### Phase 2: Architecture Documentation

Create and maintain technical architecture documentation following enterprise standards.

**Key Features:**
- **Multi-file structure** — `ARCHITECTURE.md` at project root is a navigation index (~130 lines); all content lives in `docs/` as numbered section files; components in `docs/components/` (one file per component); see [RESTRUCTURING_GUIDE.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/skills/architecture-docs/RESTRUCTURING_GUIDE.md)
- **5 architecture types** with reference docs + C4 translation guides:
  - `STANDARD`: Microservices (1), 3-Tier (2), N-Layer (3)
  - `ENTERPRISE`: META (4), BIAN (5)
- **C4 component process**: C4 L1 systems → confirm → select focus system → C4 L2 boundary test → create component files
- Interactive Mermaid diagrams in `docs/03-architecture-layers.md`
- Metric consistency validation across document
- Design Drivers calculation (Value Delivery %, Scale, Impacts)
- 9 mandatory Architecture Principles + 1 optional
- ADR (Architecture Decision Record) templates with automatic file generation
- **ADR ID Format Gate** (v3.25.1, BLOCKING) — `^ADR-\d{3,}$` regex enforced at every ADR write; phase-prefixed forms (`ADR-P1-001`, `ADR-Phase1-001`, `ADR-001-P1`, etc.) abort with a documented error. Project ADRs start at `ADR-101`; institutional range `001–100` is reserved
- **Phase Catalog mode** (v3.23.0, default for Section 6 — `docs/04-data-flow-patterns.md`) — multi-UC architectures compose shared phases via a phase × UC matrix instead of duplicating flows. Mode is auto-selected when the doc has 2+ UCs sharing components, or 1 UC with ≥4 phases; Single-Flow mode is preserved as the fallback. Mode-awareness propagates through Workflow 7 (diagram gate counts P phase mini-flows + U UC wire sequences), peer-review `SECTIONS-05` (matrix-vs-Phase-Catalog phase-count drift = Major), and dev-handoff `Flows` payload extraction
- **Connection Naming Rule** (v3.21.9 / v3.21.10) — every C4 L1 + L2 edge's 4th `Rel()` parameter follows the canonical normal form `<PROTOCOL>/<STYLE> [Action Type]` (e.g. `HTTPS/JSON [Data]`, `gRPC/PROTOBUF [Internal]`, `TLS/AVRO [Event]`, `JDBC/SQL [Query]`); via-hop / topic / queue / async metadata moves to the 3rd parameter (description). 10-tag closed action vocabulary. Sequence-diagram message labels are explicitly **exempt** — reviewers and audit gates skip the rule on `sequenceDiagram` blocks
- **Infrastructure-as-via Rule** (v3.21.7) — APIM, brokers, topics, queues, service mesh, load balancers, and iPaaS collapse onto edge labels in C4 L1 + L2 diagrams rather than appearing as standalone nodes; `ContainerQueue()` is reserved for the rare case where an owned/custom broker IS the architectural unit
- **DIAGRAMS_GATE** (v3.21.8, BLOCKING) — Workflow 1 Step 7.3 will not print `✅ Architecture creation complete` until every mandatory diagram (Logical View ASCII, C4 L1, C4 L2, Detailed View, plus mode-aware sequence diagrams) is verified present and Pre-Write-Validation-clean. No `SKIP DIAGRAMS` override
- **Component Naming Fidelity Rule** (v3.24.1) — every user-visible artifact (analysis reports, peer reviews, dev handoffs, compliance contracts, `.docx` exports, traceability reports, prose summaries, diagrams) references documented components by their **canonical full name** from `docs/components/README.md` Column 2 — never an abbreviation, alias, or truncation, even when source `docs/**/*.md` files use a shortened form inline. Enforced via dedicated blocks in all 19 agents under `agents/**/*.md`, three templates, and the setup-managed CLAUDE.md block
- **Foundational Context Anchor Protocol** — dependency-aware editing workflow that loads required upstream context before any downstream section edit
- **Downstream Documentation Propagation** — after any substantive section edit, detects affected downstream files via reverse dependency table, presents a user-approval checklist, and cascades updates in tier order following the Context Anchor Protocol
- All files kept under ~400 lines each for context efficiency

**Output structure:**
```
<project-root>/
├── ARCHITECTURE.md          (~130 lines — navigation index only)
├── adr/                     (ADR files — canonical 10-section template)
└── docs/
    ├── 01-system-overview.md
    ├── 02-architecture-principles.md
    ├── 03-architecture-layers.md
    ├── 04-data-flow-patterns.md
    ├── 05-integration-points.md
    ├── 06-technology-stack.md
    ├── 07-security-architecture.md
    ├── 08-scalability-and-performance.md
    ├── 09-operational-considerations.md
    └── components/
        ├── README.md                (5-column index grouped by system)
        ├── <system-name>.md         (C4 L1 system descriptor)
        └── <system-name>/           (C4 L1 folder per system)
            └── NN-<name>.md         (C4 L2 containers inside system folder)
```

Each component file includes a **C4 metadata header**: Type, Technology `[in brackets]`, C4 Level, Deploys as, Communicates via. All architectures use **grouped tables** with `### System Name` headers in README.md.

#### Peer Review (Quality Gate)

Use `/skill architecture-peer-review` after ARCHITECTURE.md is complete, before handing off to compliance.

- **3 depth levels**: Light (22 checks), Medium (44 checks), Hard (82 checks)
- **13 review categories** with weighted 0–10 scoring: Structural Completeness, Naming & Conventions, Section Completeness, Content Coherence, Technology Alignment, Integration Soundness, Metric Realism, Scalability Design, Security Posture, Performance Design, Operational Readiness, ADR Quality, Trade-off Honesty
- **Interactive HTML playground** — approve/reject/comment on each finding, live scorecard
- **Fix prompt generation** — copy approved findings as a structured prompt to apply changes via `architecture-docs`

**Output:** Interactive HTML peer review file (`architecture-peer-review-YYYY-MM-DD.html`) + scored findings

#### Blueprint Generation

Use `/skill architecture-blueprint` when organizational blueprint forms are required.

- **Business blueprint** (`BLUEPRINT_BUSINESS_EN.md` / `BLUEPRINT_BUSINESS_ES.md`) — fills the "Datos de la Iniciativa" organizational template (business domain, strategy, deployment location, team roles)
- **Application blueprint** (`BLUEPRINT_APPLICATION_EN.md` / `BLUEPRINT_APPLICATION_ES.md`) — fills an application-level template (Design Drivers, Architecture Decisions, Capacity Sizing, Compliance Approvals)
- **Language auto-detection** — reads `docs/01-system-overview.md`, selects matching EN or ES template
- **NOT FOUND handling** — fields not found in architecture docs are marked `NOT FOUND` with a recommended keyword or section to add the missing data
- Bilingual (ES/EN) with explicit language override support

**Output location:** same directory as `ARCHITECTURE.md`

#### Architecture Type Selection & C4 Model

When creating a new architecture, the user selects from 5 types. Each type comes with two reference documents that govern the architecture and component structure:

```
📐 Architecture Type Selection

── Industry Standard ─────────────────────────────
  1. Microservices    STANDARD  RECOMMENDED
  2. 3-Tier           STANDARD
  3. N-Layer          STANDARD

── Enterprise / Domain-Specific ──────────────────
  4. META             ENTERPRISE
  5. BIAN             ENTERPRISE  BANKING
```

Each type loads:
- **Section 4 + 5 templates** — structure and component format
- **Architecture Rules** (`references/{TYPE}-ARCHITECTURE.md`) — defines the pattern, layers, principles
- **C4 Translation** (`references/{TYPE}-TO-C4-TRANSLATION.md`) — maps the architecture to C4 levels

Types without both reference docs are **greyed out** and cannot be selected.

After type selection, the C4 component process runs:

```
Step 4a: C4 Level 1 — Identify systems → confirm with user
Step 4b: C4 Level 2 — Confirm focus system
Step 4c: C4 Level 2 — Identify containers per system (boundary test)
Step 4d: Create component files with C4 metadata headers
Step 4e: Create README.md index (5-column, grouped by system)
```

### Phase 3: Compliance Documentation

Generate compliance contracts from ARCHITECTURE.md with full traceability. Each contract follows the `CC-NNN` naming convention for consistent identification.

**Key Features:**
- **1 universal generator** reads domain config at runtime — no per-domain agents
- **10 domain validators** with personality, EOL checks (WebSearch), and standard validation
- **EOL-first validation**: Technology versions checked against endoflife.date before any compliance scoring (6-month safety period)
- **Automatic Validation (0-10 scoring)**: All contracts validated with granular scoring
- **4-Tier Approval Workflow**: Auto-approve (8.0-10), Manual review (7.0-7.9), Needs work (5.0-6.9), Rejected (0-4.9)
- **External Validation Summary**: Standardized section in every contract referencing the validator agent
- Compliance manifest (index of all generated documents)

**Output:** `/compliance-docs/` with contracts named `CC-NNN-{type}_{project}_{date}.md`

#### Compliance Contract Types

| CC Code | Contract Type | Validator | Focus | Requirements |
|---------|--------------|-----------|-------|-------------|
| CC-001 | Business Continuity | Aegis | RTO/RPO, DR, backup, resilience | 43 LACN |
| CC-002 | Cloud Architecture | Atlas | Deployment model, provider, IaC, security | 6 LAC |
| CC-003 | Data & AI Architecture | Mnemosyne | Data governance, AI/ML, privacy | 11 LAD/LAIA |
| CC-004 | Development Architecture | Hephaestus | EOL validation (sole external check, v3.22.0); coding standards | 2 LADES |
| CC-005 | Enterprise Architecture | Athena | Strategic alignment, governance | 7 LAE |
| CC-006 | Integration Architecture | Iris | API standards, message patterns | 7 LAI |
| CC-007 | Platform & IT Infrastructure | Vulcan | Environments, databases, capacity | 9 LAPI |
| CC-008 | Process Transformation | Hermes | Automation, efficiency, ROI | 4 LAA |
| CC-009 | Security Architecture | Argus | Auth, encryption, vulnerability mgmt | 8 LAS |
| CC-010 | SRE Architecture | Prometheus | SLOs, observability, incident mgmt | 57 LASRE |

#### Compliance Generation Architecture

The system uses a **two-phase parallel execution** model: validators run first (with domain personality and WebSearch for EOL), then a single universal generator is invoked 10 times with each validator's results.

```
                    ┌─────────────────────────────┐
                    │   architecture-compliance    │
                    │       (orchestrator)         │
                    └──────────┬──────────────────┘
                               │
              Phase 1: Spawn 10 validators (parallel)
                               │
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
  ┌──────────────┐   ┌────────────────┐   ┌────────────────┐
  │ Aegis        │   │ Hephaestus     │   │ Prometheus      │
  │ (BC, 16 items│   │ (Dev, EOL-only │   │ (SRE, 25 items │  ...×10
  │  + EOL)      │   │  via WebSearch │   │  + EOL)        │
  │              │   │  — v3.22.0)    │   │                │
  └──────┬───────┘   └──────┬─────────┘   └──────┬─────────┘
         │                  │                    │
         ▼                  ▼                    ▼
  VALIDATION_RESULT  VALIDATION_RESULT    VALIDATION_RESULT
         │                  │                    │
         │   Phase 2: Spawn 1 generator ×10 (parallel)
         │          (with results in prompt)
         │                  │                    │
         ▼                  ▼                    ▼
  ┌─────────────────────────────────────────────────────┐
  │         compliance-generator (universal)             │
  │                                                      │
  │  Reads config: agents/configs/{type}.json            │
  │  Loads template: cc-NNN-{type}.template.md           │
  │  Parses VALIDATION_RESULT from prompt                │
  │  Fills template placeholders                         │
  │  Writes contract to compliance-docs/                 │
  └──────────────────────────┬──────────────────────────┘
                             │
                             ▼
  ┌─────────────────────────────────────────────────────┐
  │              compliance-docs/                        │
  │  CC-001-business-continuity_Project_2026-03-29.md   │
  │  CC-004-development-architecture_Project_2026-03-29.md │
  │  CC-010-sre-architecture_Project_2026-03-29.md      │
  │  ...                                                 │
  │  COMPLIANCE_MANIFEST.md                              │
  └─────────────────────────────────────────────────────┘
```

#### How It Works: CC-004 Development Example

```
  Orchestrator                Hephaestus Validator           Universal Generator
  ───────────                 ────────────────────           ───────────────────
       │                            │                              │
       │── spawn validator ────────►│                              │
       │                            │                              │
       │                     Phase 1: EOL Gathering                │
       │                     ├─ WebSearch: "Java 17 EOL"           │
       │                     ├─ WebSearch: "Spring Boot 3.2 EOL"   │
       │                     ├─ WebSearch: "Angular 19 EOL"        │
       │                     └─ Build EOL lookup table             │
       │                                                           │
       │                     Phase 2: EOL Verdict (v3.22.0:        │
       │                     stack-validation checklist removed;   │
       │                     EOL is the sole external check)       │
       │                     ├─ DEV-01: Java 17 → PASS (2030)     │
       │                     ├─ DEV-02: Spring 3.2 → FAIL (EOL)   │
       │                     ├─ DEV-13: Angular 19 → FAIL (<6mo)  │
       │                     └─ Per-stack EOL evidence table       │
       │                            │                              │
       │◄── VALIDATION_RESULT ──────┘                              │
       │                                                           │
       │── spawn generator (contract_type: development) ──────────►│
       │   + VALIDATION_RESULT in prompt                           │
       │                                                           │
       │                                       Read config JSON    │
       │                                       Load template       │
       │                                       Parse VALIDATION_RESULT
       │                                       Fill placeholders   │
       │                                       Write CC-004-*.md   │
       │                                                           │
       │◄── contract written ──────────────────────────────────────┘
       │
       │── post-generation pipeline (scoring, manifest)
```

**Key principles:**
- **Validators own the personality and domain knowledge** — they frame evidence, deviations, and recommendations
- **The generator is a pure template-filler** — no domain logic, reads everything from config + VALIDATION_RESULT
- **EOL is a blocking condition** — approved + EOL = FAIL (6-month safety period via WebSearch)
- **Every contract has a standardized External Validation Summary** referencing its validator

#### Compliance Review (Quality Gate)

Use `/skill architecture-compliance-review` after contracts are generated to understand what ARCHITECTURE.md improvements would push contracts to auto-approve (≥8.0/10).

- **Coverage validation**: Checks all 10 required contracts are present and ≤6 months old
- **Gap extraction**: Reads every contract's compliance summary table and extracts Non-Compliant and Unknown requirements
- **Concept clustering**: Groups gaps across contracts by underlying ARCHITECTURE.md concept (load testing, DR/RTO, IAM, observability, etc.) ranked by cross-contract impact
- **Interactive HTML playground** — portfolio health panel + concept cluster gap explorer

### Architecture Analysis (Risk & Design Dashboard)

Use `/skill architecture-analysis` to run risk and design-characteristics analyses over the architecture documentation — the kind of assessments that come out of a release-readiness review, pre-incident audit, or annual architecture review.

**10 analyses** across two groups, each producing a date-stamped report in `analysis/`. Run individually, by group (1–5 or 6–10), or all ten in parallel via a single-message parallel spawn.

#### HIGH-priority (runtime / security risk)

| # | Analysis | Key output | Invocation |
|---|----------|-----------|-----------|
| 1 | **SPOF** — Single Points of Failure | Critical (C) / Degradation (D) / Operational (O) tables + ASCII heat map (Impact × Likelihood) + Top-5 remediations | `/skill architecture-analysis` → `1` |
| 2 | **Blast Radius** — Downstream cascade impact | S1–S4+Isolated severity tiers, fan-out depth (direct+indirect), cascade vs. bulkhead vs. fail-open, Mermaid cascade path flowcharts for top-3 worst scenarios, ⚡ SPOF+Blast cross-reference | `2` |
| 3 | **Bottleneck** — Throughput chokepoints | B1–B4 tier model (B1=critical chokepoint), capacity metrics table (Max RPS / HPA / connection pool / queue depth), ASCII capacity headroom bar chart, ADR-driven bottleneck tracking | `3` |
| 4 | **Cost Hotspots** — Cost concentration | Q1–Q4 cost quality tiers, Pareto 80% rule, over-provisioning candidates, vendor concentration (≥60% flag), normalization to USD/month, ADR cost decision table | `4` |
| 5 | **STRIDE** — Security threats per trust boundary | Trust boundary inventory (TB-xx), per-boundary S/T/R/I/D/E matrix, High-Priority Threats table, compliance cross-reference with `compliance-docs/SECURITY_*.md` | `5` |

#### Strategic / sustainability

| # | Analysis | Key output | Invocation |
|---|----------|-----------|-----------|
| 6 | **Vendor Lock-in** — Portability risk | L1 (locked) / L2 (lock-prone) / L3 (portable) tiers, per-vendor concentration table (≥60% flag), exit cost ranking (proprietary surface × replacement effort × data export), heat map (lock severity × strategic importance) | `6` |
| 7 | **Latency Budget** — Per-hop SLO decomposition | Per-flow p95 decomposition into hops (Within / Tight / Over Budget / Untracked), ASCII Gantt-style budget bars per flow, Hops Over Budget summary, tail-latency variance flag (p99/p95 > 3×) | `7` |
| 8 | **Tech Debt / EOL** — Technology currency | T1 (EOL now) / T2 (EOL ≤6mo) / T3 (deprecated) / T4 (current) / T5 (unknown) tiers, EOL Hotlist, deprecated SDK keyword scan, ADR architectural debt table (superseded ADRs whose replacement is not implemented), heat map (severity × effort) | `8` |
| 9 | **Coupling** — Fan-in/fan-out, cycles | Fan-in (Ca) / Fan-out (Ce) / Instability (I = Ce/(Ca+Ce)) per component, K1 critical hubs (fan-in ≥5) / K2 volatile leaves (fan-out ≥5) / K3 god objects (both) / K4 cycles with Mermaid subgraphs, ASCII distribution histograms | `9` |
| 10 | **Data Sensitivity** — PII flow & encryption gaps | S1–S4 data classification per store/queue/cache, G1 (unencrypted transit) / G2 (unencrypted at rest) / G3 (retention breach) / G4 (cross-boundary leakage) / G5 (undocumented) gaps, Mermaid sequence diagrams for top-3 S1 flows, compliance cross-reference | `10` |

**Key principles:**
- **Documentation Fidelity Rule** — every finding cites the source file and section; ungrounded findings are marked `[NOT DOCUMENTED — add to <source-file>]` rather than estimated
- **Parallel spawn** — all selected agents issue in a single message (no serial bottleneck)
- **Date-stamped output** — `analysis/<TYPE>-<YYYY-MM-DD>.md`; re-running same day overwrites, new day preserves history

**Output location:** `analysis/` at project root

**Permissions required** (add to `.claude/settings.json`):
```json
"Write(analysis/*)", "Read(analysis/*)", "Bash(mkdir *)", "Agent(sa-skills:architecture-analysis-agent)"
```

### Phase 4: Development Handoff & Export

#### Dev Handoff

Use `/skill architecture-dev-handoff` when handing off a component to the development team for implementation.

**Key Features:**
- **8-section audience-segmented handoff document** per component (HANDOFF_TEMPLATE v2.1.0) — Section 0 Metadata + three audience tracks:
  - **PART A — DEV**: A1 Overview/Scope/Tech/ADRs · A2 API & Data Contract · A3 Integrations & Failure Modes
  - **PART B — QA**: B1 Acceptance, Performance & Security Tests
  - **PART C — OPS**: C1 Deployment/Config/Resources · C2 Observability & Runbook · C3 Deliverable Assets
  - **APPENDIX**: D1 Open Questions and Assumptions
- **Scoped to C4 Level 2 (Container) components only** — C4 L1 system descriptors are excluded
- **Component Naming Fidelity Rule** enforced (v3.24.1) — canonical full component names from `docs/components/README.md` Column 2
- **8 component-type-specific assets**:

| Component Type | Asset Generated |
|---------------|-----------------|
| API / REST / Service | `openapi.yaml` (OpenAPI 3.1) |
| Database / Data Store | `ddl.sql` (DDL with tables, indexes, constraints) |
| Redis / Cache | `redis-key-schema.md` (key patterns, TTL, eviction, fail-open) |
| Kubernetes workload | `deployment.yaml` (Deployment + Service + HPA) |
| Message Consumer/Producer | `asyncapi.yaml` (AsyncAPI 3.0) |
| Kafka + Avro | `schema.avsc` (Avro schema for Schema Registry) |
| Kafka + Protobuf | `schema.proto` (Protobuf message definition) |
| Scheduled Job | `cronjob.yaml` (Kubernetes CronJob) |

- **Gap detection** — fields not found in architecture docs are marked `[NOT DOCUMENTED]` and listed in Section 15 as a remediation checklist
- **Compliance enrichment** — if `compliance-docs/` exists, security/SRE/development contract gaps are surfaced in relevant sections
- **Managed index** at `handoffs/README.md` — 6-column table tracking all handoff docs

**Output location:** `handoffs/NN-<component-name>-handoff.md` + `handoffs/assets/NN-<component-name>/`

#### Doc Export

Use `/skill architecture-docs-export` when professional Word deliverables are needed.

| Mode | What it exports | Output |
|------|----------------|--------|
| **Solution Architecture** | Executive Summary synthesized from `docs/01-system-overview.md` + component index + compliance manifest (if present), plus one `.docx` per ADR | `exports/SA-<name>.docx` + `exports/ADR-NNN-<title>.docx` |
| **Dev Handoff** | Selected component handoff(s) from `handoffs/` | `exports/HANDOFF-<component>.docx` |

**Document styling**: Corporate blue (`#1F4E79`) for SA, Amber/Gold (`#8B6914`) for ADRs, Teal (`#0D7377`) for handoffs.

**Output location:** `exports/` at project root

## Architecture Types & Visualization

### 5 Supported Architecture Types

Choose the architecture type that best fits your system:

**1. META (6-Layer Enterprise)** - Large enterprise systems with complex integrations
- Layers: Channels → UX → Business Scenarios → Business → Domain → Core
- Best for: Financial services, regulated industries, enterprise platforms
- Template: Section 4 META with BIAN V12.0 alignment
- **BIAN Standard**: Full V12.0 compliance with 12 metadata fields
- **Layer 5 Enhancement**: Matches BIAN Layer 4 comprehensiveness with complete service domain metadata

**2. 3-Tier (Classic Web Application)** - Standard web applications and REST APIs
- Tiers: Presentation → Application/Business Logic → Data
- Best for: Web apps, line-of-business applications, standard CRUD systems
- Template: Section 4 3-Tier with tier separation enforcement

**3. Microservices (Cloud-Native)** - Distributed systems with independent services
- Components: API Gateway, Service Mesh, Event Bus, independent services
- Best for: Cloud-native systems, event-driven architectures, polyglot environments
- Template: Section 4 Microservices with service catalog

**4. N-Layer (DDD/Clean Architecture)** - Flexible custom patterns
- Patterns: Classic DDD (4-Layer), Extended (5-Layer), Clean Architecture
- Best for: Domain-Driven Design, Hexagonal Architecture, testable systems
- Template: Section 4 N-Layer with dependency inversion

**5. BIAN (Full BIAN V12.0 Certification)** - Pure BIAN Service Landscape architecture
- Layers: Channels → BIAN Business Scenarios → BIAN Business Capabilities → BIAN Service Domains → Core Systems
- Best for: Banking, financial services requiring full BIAN certification
- Template: Section 4 BIAN and Section 5 BIAN with comprehensive metadata
- **Compliance**: Mandatory full BIAN V12.0 compliance (12 metadata fields, 7 standard operations)
- **Validation**: All service domain names validated against official [BIAN Service Landscape V12.0](https://bian.org/servicelandscape-12-0-0/views/view_51891.html)
- **Traceability**: Full BIAN hierarchy (Service Domain → Business Domain → Business Area)

**How to Choose**: See [ARCHITECTURE_TYPE_SELECTOR.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/skills/architecture-docs/templates/ARCHITECTURE_TYPE_SELECTOR.md) for decision tree and comparison matrix.

### Diagram Generation & Enforcement (Workflow 8)

Architecture diagrams are generated by the `architecture-docs` skill with strict placement enforcement. All diagrams adapt their grouping, naming, and colors to the detected architecture type (META, BIAN, 3-Tier, N-Layer, Microservices) and support light/dark theme variants.

**Mandatory diagrams** (always generated, 4 standard + data flow):

All 4 standard diagrams live in `docs/03-architecture-layers.md` under `## Architecture Diagrams`:

| # | Diagram | Format | Audience |
|---|---------|--------|----------|
| 1 | Logical View | ASCII art | Executives, architects |
| 2 | C4 Level 1 — System Context | Mermaid `C4Context` | Non-technical stakeholders |
| 3 | C4 Level 2 — Container | Mermaid `C4Container` | Development teams |
| 4 | Detailed View | Mermaid `graph TB` | Architects, SREs |

Plus **Data Flow Diagrams** — Mermaid `sequenceDiagram` blocks in `docs/04-data-flow-patterns.md`, **mode-aware** (v3.23.0):
- **Phase Catalog mode** (default for 2+ UCs sharing components, or 1 UC with ≥4 phases): one `sequenceDiagram` per phase H4 in `## Phase Catalog` (scoped mini-flow) + one full wire `sequenceDiagram` per UC in `## End-to-End Wire Sequences`
- **Single-Flow mode** (legacy fallback for trivial 1-UC, ≤3-flow systems): one `sequenceDiagram` per H3 flow subsection

**On-request diagrams** (opt-in):
- Infrastructure / Deployment → `docs/09-operational-considerations.md`
- HA / Failover + Performance → `docs/08-scalability-and-performance.md`
- Integration → `docs/05-integration-points.md`
- Security → `docs/07-security-architecture.md`

**Enforcement rules**:
- 🛑 **DIAGRAMS_GATE (BLOCKING, v3.21.8)** — Workflow 1 Step 7.3 audits every mandatory diagram + the mode-aware sequence-diagram count (P phases + U UC wire sequences in Phase Catalog mode; one per H3 in Single-Flow). Creation does not complete until all are present and Pre-Write-Validation-clean. No `SKIP DIAGRAMS` override
- 🔗 **Connection Naming Rule (L1 + L2, v3.21.9)** — every C4 L1 / L2 / Detailed-View edge's 4th `Rel()` parameter follows `<PROTOCOL>/<STYLE> [Action Type]` (10-tag closed action vocabulary: Data, Event, Internal, Query, Command, Stream, Sync, Async, Webhook, Control). Free prose, via-hops, topic / queue names move to the 3rd `Rel()` parameter (description)
- 🚇 **Infrastructure-as-via Rule (L1 + L2, v3.21.7)** — APIM, brokers, topics, queues, service mesh, load balancers, iPaaS collapse onto edge labels rather than appearing as separate nodes; `ContainerQueue()` is reserved for owned/custom brokers that ARE the architectural unit
- 🧾 **Sequence-diagram exemption (v3.21.10)** — message labels in `sequenceDiagram` blocks (`A->>B: …`, `A-->>B: …`, `A-)B: …`) are **free prose**; the Connection Naming Rule is scoped to C4 L1, C4 L2, and Detailed View only. Reviewers and audit gates skip the rule when the first line inside a Mermaid fence is `sequenceDiagram`
- ⛔ **Non-canonical placement is denied** — diagrams go to their designated `docs/` file, no override
- 🎨 **Theme selection** — user must choose light or dark theme before diagram generation; persisted as `<!-- DIAGRAM_THEME: light|dark -->`
- 📥 **External diagram reconciliation** — diagrams from external files are classified, matched against architecture docs, and either relocated or discarded (no undocumented flows)
- 🚫 **Semicolon in labels is forbidden** — `;` terminates Mermaid statements and causes parse errors; use `,` instead

**Target**: Mermaid v11.4.1 (VS Code Mermaid Chart extension 2.1.0+).

**Comprehensive Guide**: See [DIAGRAM-GENERATION-GUIDE.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md) for the 4 standard diagrams with architecture-type-specific templates, C4 color conventions, the Connection Naming Rule + Infrastructure-as-via Rule, `sequenceDiagram` syntax reference, and generation workflow. See [MERMAID_DIAGRAMS_GUIDE.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md) for authoring reference (syntax patterns, component guidelines, common scenarios).

## Documentation

- **[Installation Guide](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/INSTALLATION.md)** - Detailed installation instructions
- **[Quick Start](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/QUICK_START.md)** - 5-minute getting started tutorial
- **[Workflow Guide](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - Complete end-to-end workflow
- **[Troubleshooting](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/TROUBLESHOOTING.md)** - FAQ and common issues

## Examples

### Real-World Example Repository

**[Task Scheduling Platform Example](https://github.com/shadowX4fox/task-scheduling-example)**

Complete end-to-end demonstration of the four-phase workflow:

**Phase 1: Product Owner Specification**
- Business requirements and user personas
- Use cases and success criteria
- Weighted readiness scoring (8.3/10)

**Phase 2: Technical Architecture (ARCHITECTURE.md)**
- Multi-file structure: navigation index + `docs/` section files + `docs/components/`
- Microservices architecture pattern
- Interactive Mermaid diagrams in `docs/03-architecture-layers.md`
- Technology stack documentation
- Complete with metrics, SLOs, and ADRs

**Phase 3: Compliance Documentation**
- All 10 generated compliance contracts with validation
- Development Architecture with live EOL validation via `endoflife.date` (sole external check as of v3.22.0)
- Security, Cloud, SRE, and Enterprise Architecture contracts
- Full source traceability to ARCHITECTURE.md

**Phase 4: Development Handoff**
- Per-component handoff documents with deliverable assets
- Type-specific scaffolded artifacts (OpenAPI, DDL, K8s manifests)

**Repository**: https://github.com/shadowX4fox/task-scheduling-example

---

**Additional Examples in This Repository:**

The `examples/` directory contains reference templates:

- **PRODUCT_OWNER_SPEC_example.md** - PO Spec template (Job Scheduling Platform)
- **ARCHITECTURE_example.md** - Full ARCHITECTURE.md example (multi-file structure: navigation index + `docs/` section files)

---

**Want More Examples?**

To request specific examples or use cases, [open an issue](https://github.com/shadowX4fox/solutions-architect-skills/issues/new).

## Requirements

- **Claude Code** (latest version)
- **Bun** (v1.0.0 or later) — required for compliance generation, template validation, and the cross-platform helper scripts (`scripts/today.ts`, `scripts/ensure-dir.ts`, `scripts/remove-glob.ts`). **Not required for the UserPromptSubmit hook layer as of v3.25.2** — the hook is pure-native shell/cmd/PowerShell
- **Platform:** macOS, Linux, or Windows (native cmd / PowerShell, WSL2, or Git Bash — all supported as of v3.21.1)

### Why Bun?

The architecture-compliance skill (and several other skills) use Bun for:
- Template expansion with `@include` directives
- Pre-validation of template structure (Phase 4.1)
- Post-validation of generated contracts (Phase 4.6)
- The cross-platform helpers under `scripts/` (`today.ts`, `ensure-dir.ts`, `remove-glob.ts`) that replaced the v3.19.x POSIX `date` / `mkdir` / `rm` shell-outs
- High-performance TypeScript execution without a separate transpile step

### Installing Bun by OS

| OS / Shell | Recommended install command | Notes |
|---|---|---|
| **Windows (native cmd / PowerShell)** | `npm install -g bun` | Most reliable Windows-native path. Requires Node.js. Sidesteps PowerShell execution-policy and proxy issues that the official PowerShell installer occasionally hits in corporate environments. |
| Windows + WSL2 | `curl -fsSL https://bun.sh/install \| bash` (inside WSL) | Same as Linux. |
| Windows + Git Bash | `curl -fsSL https://bun.sh/install \| bash` (inside Git Bash) | Same as Linux. |
| macOS | `brew install bun` or `curl -fsSL https://bun.sh/install \| bash` | Either works; `brew` integrates with the rest of your formula updates. |
| Linux | `curl -fsSL https://bun.sh/install \| bash` | The official one-liner. |

After install, verify with `bun --version` (must be `1.0.0` or higher). If `bun` is not on PATH, restart your terminal — or on Windows, sign out and back in so the user PATH update takes effect.

For full Bun installation troubleshooting, see [INSTALLATION.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/INSTALLATION.md#installing-bun).

## Recommended VS Code Setup

For the best experience working with this plugin, install these VS Code extensions:

| Extension | Publisher | Purpose |
|-----------|-----------|---------|
| [Claude Code for VS Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) | Anthropic | Run Claude Code skills directly from the editor |
| [Mermaid Chart](https://marketplace.visualstudio.com/items?itemName=MermaidChart.vscode-mermaid-chart) | Mermaid Chart | Live preview of Mermaid diagrams (v11.4.1) with pan, zoom, and export |

### Why these extensions?

- **Claude Code** is required to run the plugin's 9 skills from VS Code
- **Mermaid Chart** lets you validate architecture diagrams (`docs/*.md`) in real-time as they are generated — supports native C4 diagrams, sequence diagrams, and all diagram types used by this plugin

## Use Cases

Perfect for:
- Enterprise architects documenting solution designs
- Product Owners preparing requirements for architecture teams
- Compliance teams generating organizational contracts
- Technical leads maintaining architecture documentation
- Development teams receiving component handoffs for implementation
- Teams needing standardized architecture workflows

## Workflow Integration

```mermaid
graph TD
    A[Product Owner] -->|Creates| B[PO Spec]
    B -->|Input to| C[Architecture Team]
    C -->|Creates| D[ARCHITECTURE.md]
    D -->|Generates| L[ADRs]
    L -->|Status Change| M{Propagation}
    D -->|Section Edit| M
    M -->|Updates| D
    M -->|Updates| J
    D -->|Peer Review| E{Quality Gate}
    E -->|Approved| F[10 Compliance Contracts]
    E -->|Refine| C
    F -->|Score ≥ 8.0| G[Auto-Approved]
    F -->|Score 7.0–7.9| H[Manual Review]
    G --> J[Dev Handoffs + Assets]
    H -->|Approved| J
    J -->|Export| K[Word .docx Deliverables]
```

## External Validation System

All 10 compliance contracts use an **external validation system** with standardized 0-10 scoring:

### Validation States & Scoring
- ✅ **PASS (10 points)**: Complies with requirements
- ❌ **FAIL (0 points)**: Non-compliant or deprecated technology
- ⚪ **N/A (10 points)**: Not applicable to this architecture
- ❓ **UNKNOWN (0 points)**: Missing data in ARCHITECTURE.md
- 🔓 **EXCEPTION (10 points)**: Documented exception via LADES2 process

### Scoring Formula
```
Final Score = (Completeness × 0.4) + (Compliance × 0.5) + (Quality × 0.1)

Where:
- Completeness = (Filled required fields / Total required) × 10
- Compliance = (PASS + N/A + EXCEPTION items / Total applicable) × 10
- Quality = Source traceability coverage (0-10)
```

### Approval Workflow
| Score | Status | Review Actor | Outcome |
|-------|--------|--------------|---------|
| 8.0-10.0 | Approved | System (Auto-Approved) | Ready for implementation |
| 7.0-7.9 | In Review | [Approval Authority] | Manual review required |
| 5.0-6.9 | Draft | Architecture Team | Address gaps before review |
| 0.0-4.9 | Rejected | N/A (Blocked) | Cannot proceed to review |

### Validation Configuration
- **10 JSON config files**: One per contract type in `/skills/architecture-compliance/validation/`
- **Template-specific weights**: Each contract can customize Completeness/Compliance/Quality weights
- **Validation schema**: `VALIDATION_SCHEMA.json` defines standard structure
- **Example scenarios**: `VALIDATION_EXAMPLES.md` shows all 4 outcome tiers

## Roadmap

### v3.28.8 (Current Release) ✅
**fix(architecture-dev-handoff): correct relative-link depths in the handoff-document and c4-descriptor templates — they emitted wrong `../` depths on every run, which had to be sed-fixed by hand after each (re)generation**

The dev-handoff templates hardcoded the wrong number of `../` segments for repo-back links, and the c4-descriptor template supplied *no* prefix at all — leaving the Haiku descriptor agent to guess the depth (it guessed `../../`, one level short of the descriptor's real depth 3). The result: `../../ARCHITECTURE.md` instead of `../ARCHITECTURE.md`, `../components/` instead of `../docs/components/`, and `../../adr/` instead of `../../../adr/` — every run.

**Correct depths, by on-disk location**:

- Handoff document — `handoffs/NN-<slug>-handoff.md` (**depth 1**): `../ARCHITECTURE.md`, `../docs/components/<file>` (the `docs/` segment is required).
- C4 descriptor asset — `handoffs/assets/NN-<slug>/c4-descriptor.md` (**depth 3**): `../../../adr/…`, `../../../docs/…`, `../../../ARCHITECTURE.md`.

**Scope of this change** (5 files, template link-paths + authoring notes):

- `agents/generators/handoff-generator.md` — Section 0 metadata links fixed (`../ARCHITECTURE.md`, `../docs/components/…`) plus a new **"Link-path convention (do NOT recompute)"** note stating the handoff doc's depth-1 location.
- `agents/generators/handoff-asset-generator.md` — descriptor ADR links fixed to `../../../adr/…` (English + Spanish variants) plus the matching depth-3 verbatim-emission note.
- `skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md`, `SECTION_EXTRACTION_GUIDE.md`, `ASSET_GENERATION_GUIDE.md` — the reference-guide copies of the same templates kept in sync.

**Why a "do NOT recompute" note**: the descriptor bug was the agent *re-deriving* the relative depth and getting it wrong. Pinning the exact prefix in the template and telling the agent to emit it verbatim removes the guessing entirely.

**Not affected**: `principle-quality-reviewer` and other agents that reference files by path, and the user's own architecture docs — this was purely a skill-template defect. The agent `.md` files drive generation at runtime (the reference guides are bundled into them per SKILL.md); the guides were updated in lockstep so they don't drift.

**Verification**: post-edit greps confirm zero residual wrong-depth links (`](../components/`, `](../../ARCHITECTURE`, bare `` `adr/ADR-` ``, `../../adr/`) across all five files.

### v3.28.7 (Previous Release) ✅
**fix(agents): correct sub-agent type names in every orchestrator to match the role-namespaced registry — spawns were failing with `Agent type 'sa-skills:<name>' not found` because the SKILL.md orchestration strings still used the pre-reorg flat names**

The agents were reorganized into role subdirectories (`agents/{builders,generators,reviewers,validators}/`), and the plugin resolves each agent's type by its subdirectory — so the registered types are `sa-skills:builders:handoff-context-builder`, `sa-skills:generators:compliance-generator`, etc. The `SKILL.md` orchestration instructions (and a few agent-doc prose references) were never updated after that move and still spawned the old flat `sa-skills:<name>` form, which the registry rejects at `Task()` time. The first symptom surfaced in `architecture-dev-handoff`, but the same latent breakage existed across the compliance, analysis, peer-review, and docs-export orchestrators.

**Scope of this change** (8 files, agent-type strings only):

- `skills/architecture-dev-handoff/SKILL.md` — `architecture-explorer`, `handoff-context-builder`, `handoff-generator`, `handoff-asset-generator`.
- `skills/architecture-compliance/SKILL.md` — `architecture-explorer`, `compliance-generator` (×13 spawn/prose sites) and all 10 validators (`business-continuity`, `sre`, `cloud`, `data-ai`, `development`, `process`, `security`, `platform`, `enterprise`, `integration` — ×21 sites).
- `skills/architecture-analysis/SKILL.md` — `architecture-explorer`, `architecture-analysis-agent`.
- `skills/architecture-peer-review/SKILL.md` — `peer-review-category-agent`.
- `skills/architecture-docs-export/SKILL.md` — `docs-export-generator`.
- `agents/reviewers/architecture-analysis-agent.md`, `agents/generators/compliance-generator.md`, `agents/builders/handoff-context-builder.md` — `architecture-explorer` prose references.

**Not touched**: `principle-quality-reviewer` references in `architecture-docs` use the file-path convention (`agents/reviewers/principle-quality-reviewer.md`), not an agent-type string, so they were never affected.

**Verification**: post-edit greps confirm zero remaining flat `sa-skills:<name>` agent-type refs, zero double-namespacing (`sa-skills:role:role:`), and every corrected type resolves to a real `agents/<role>/<name>.md` file.

### v3.28.6 (Previous Release) ✅
**feat(architecture-analysis + architecture-docs-export): consolidated Security Posture validation checklist — a new analysis 12 that merges the STRIDE and Data Sensitivity reports into a single reviewer-fillable list of every security control to validate, plus a Security Posture export mode that renders it to a Word worksheet with editable Status / Owner / Evidence cells**

After running the two security-focused analyses (STRIDE per-trust-boundary threats, Data Sensitivity per-store control requirements), an architect is left with two separate reports and no single artifact a reviewer can walk down to confirm "is each required control actually in place?". This release adds that artifact. Analysis 12 (**Security Posture**) is a *consolidation*, not a fresh scan: it reads the existing `STRIDE-<date>.md` and `DATA-SENSITIVITY-<date>.md` reports and emits `analysis/SECURITY-POSTURE-<date>.md` — a checklist where every evaluated control becomes one row (PASS → `✅ Documented`, FINDING → `⚠️ Gap (<source finding id>)`), grouped into STRIDE Controls and Data Protection Controls tables with a counts summary and top-priority list.

**Why synthesis lives upstream (in architecture-analysis) and export stays verbatim**: the export generator's core contract is "no synthesis, no invention" — every `.docx` cell is extracted verbatim from a source file. Turning two analyses into a checklist *is* synthesis, so it belongs where synthesis is already sanctioned (the analysis agent, which cites every row back to a STRIDE cell or data gap id). The export skill then renders the resulting markdown verbatim, exactly like it does ADRs and handoffs — keeping the generator's contract intact and making the checklist independently usable as markdown.

**Why a reviewer-fillable worksheet**: the deliverable is a validation worksheet, not a briefing. The docgen `security-posture` type renders the `Status`, `Owner`, and `Evidence` columns as editable yellow cells (dashed borders, like the compliance Questions & Gaps Register) and value-colors the `Sev` / `Tier` column (High/Critical/S1 = red, Medium/S2 = amber, Low = green) so a security reviewer can mark each control Pass / Fail / N/A directly in Word.

**Scope of this change** (7 files + 1 new):

- `tools/docgen/generate-doc.js` — new `security-posture` doc type (code `SP`, crimson `#9C1F2E`); `docType` threaded into `parseMarkdown`; a `validation-checklist` table renderer that detects editable columns by header name (`Status` / `Owner` / `Evidence`) so it works regardless of section wording, and color-codes the `Sev` / `Tier` column by value; usage / error strings updated.
- `skills/architecture-analysis/analyses/SECURITY_POSTURE.md` — **new** consolidation spec (sources, consolidation model, check-ID scheme, report sections, missing-source fail-soft rule, markdown-only).
- `skills/architecture-analysis/SKILL.md` — menu item 12, Step 2.6 dependency resolution (auto-runs STRIDE / Data Sensitivity first if absent), markdown-only rule, explorer-fanout exclusion, Step 3 dispatch row + explicit FILES list, completion summary / output tree / description.
- `agents/reviewers/architecture-analysis-agent.md` — `security-posture` added to the type list + a Consolidation-analyses section (reads prior reports, no heat map, no EOL phase, markdown-only).
- `skills/architecture-docs-export/SKILL.md` — new Workflow D (Export Security Posture) + What-Gets-Exported / Styling / Output / Prerequisites / Permissions (`Read(analysis/*)`) / frontmatter updates.
- `agents/generators/docs-export-generator.md` — `security-posture` job_type + PHASE SP (pure verbatim render, one docgen call per report).
- `CLAUDE.md` — trigger phrases (`security posture`, `security posture validation`, `export security posture`).

**Backward compatibility**: zero impact on the other 10 analyses and the three existing export modes — all additive. Security Posture has no HTML/d3 mode (it is a worksheet); the analysis agent never receives `output_format=html` for it. Also folds in a pre-existing fix swapping the analysis HTML report's d3 CDN from `d3js.org` to `cdn.jsdelivr.net`, matching the documented CDN.

**Verification**: `bun run typecheck` passes. docgen exercised end-to-end on the 8-column checklist schema — 15 editable yellow cells (5 rows × 3 columns), correct severity/tier coloring (red/amber), per-table reviewer notes, and the non-checklist `Validation Summary` table correctly left as a plain table (header-name detection working).

### v3.28.5 (Previous Release) ✅
**feat(architecture-analysis): right-side selection panel on the blast-radius force-directed network — when you click a node, a 260px-wide panel to the right of the main SVG lists the selected component's upstream callers and downstream consumers by canonical full name, with per-edge cascade-status tags (Cascading / Bulkhead / Fail-open / Fail-closed); auto-refreshes on every selection change, shows an empty-state hint when nothing is selected, wraps below the SVG on narrow screens via flexbox**

The v3.28.4 click-to-highlight gesture dimmed everything except the selected node and its 1-hop neighbors visually, which is useful for *focusing* attention but still requires the reader to mouse over each highlighted circle to learn its name. For an architecture review, the question right after "what's the 1-hop neighborhood?" is "what are those nodes *called* and how do they connect?" — and the answer to that should be readable at a glance, not unfolded one tooltip at a time. This release adds a persistent side panel that surfaces exactly that information the moment a node is selected.

**Why a side panel and not an inline tooltip-on-selection**: a tooltip would either follow the cursor (and obscure the network) or pin to the selected node (and overlap with the highlighted neighborhood). A right-side panel keeps the network unobstructed, lists names in a stable location, and scales to selections of any neighborhood size (the panel scrolls internally up to 520px). It also separates the two concerns cleanly — the network shows topology and severity, the panel shows names and per-edge status.

**Why upstream + downstream are listed separately**: the same 1-hop neighborhood means two different things depending on direction. Upstream callers answer "who depends on this component" (the impact set if this node fails); downstream consumers answer "what does this component depend on" (the cascade set this node triggers). Splitting them in the panel — each with its own count — preserves the directional semantics that the undirected highlight rendering necessarily collapses.

**Scope of this change** (5 files):

- `skills/architecture-analysis/templates/viz/blast-radius.html` — added a flex-row layout (`.main-viz-row` / `.main-viz-col-svg` / `.main-viz-col-panel`) that wraps the existing SVG and a new `.selection-panel` div side-by-side; a `@media (max-width: 720px)` rule wraps the panel below the SVG on narrow screens. Self-contained CSS injected via `root.append("style")` covering the layout, the panel chrome (border-left accent, surface-alt background, max-height + internal scroll), the per-section structure (h5 caption, ul list, item-name + cascade-tag flex row), and the empty-state styling. The existing `updateHighlight()` function extended with two render paths: when `selectedId === null` it shows the empty-state hint ("Click a node in the network to see its 1-hop vicinity…"), otherwise it builds two arrays — `upstream` (links whose target equals the selected) and `downstream` (links whose source equals the selected) — from the original string-keyed `data.graph.links`, looks up each neighbor's canonical full name from a precomputed `Map<id, node>`, HTML-escapes every rendered value, and writes a panel containing the selected node's name + tier/fan-out, followed by `Upstream callers (N)` and `Downstream consumers (N)` sections with per-row cascade-status tags color-coded to match the network's edge palette. Legend hint extended: "click a node to highlight its 1-hop neighbors **(names listed in the side panel)** · click canvas to reset · …".
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.28.4 → 3.28.5; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on Markdown mode (no skeleton, agent contract, or spec changes). Zero impact on the other 9 viz types — their snippets are untouched. The panel is driven entirely from data already in `data.graph` (which the agent has been populating since v3.28.0), so no agent-contract changes are needed — older agent payloads still render correctly. The v3.28.2 pan/zoom + v3.28.3 per-scenario trees + v3.28.4 click-to-highlight all continue to work unchanged; the panel is purely additive. Existing `analysis/BLAST-RADIUS-<date>.html` files are not re-rendered; the next consumer-side run produces the panel-equipped output. All rendered names pass through `escapeHtml()` to neutralise any `<`/`>`/`&`/`"`/`'` that might appear in a component name or cascade label.

**Verification**: `bun run typecheck` passes (no TypeScript files touched). `bun test` — 225/225 pass, no regressions. `grep -c "selection-panel\|panel-section\|nodeById\|escapeHtml" skills/architecture-analysis/templates/viz/blast-radius.html` returns multiple matches (CSS class declarations + their uses + lookup map + escape helper, all referenced consistently). `git diff --name-only HEAD` shows exactly `blast-radius.html` + the 3 version files + README — no other viz files touched, no agent contract changes. End-to-end browser check on the `account-summary` blast-radius HTML report: open the report, see the empty-state hint in the panel; click any node — the panel populates with that node's name, tier, fan-out, upstream caller list, and downstream consumer list each tagged with the appropriate cascade status; click the same node again or click empty canvas — the panel returns to the empty-state hint and the network resets; resize the browser narrower than 720px — the panel wraps below the SVG instead of being pushed off-screen.

### v3.28.4 (Previous Release) ✅
**feat(architecture-analysis): click-to-highlight 1-hop neighbors on the blast-radius force-directed network — clicking any node dims everything except itself and its immediate upstream / downstream neighbors to 18% opacity (edges to 12%), selected node gets a thicker accent-colored stroke; click the same node again, or click empty canvas, to reset; composes cleanly with the existing pan/zoom + node-drag from v3.28.2 via `event.defaultPrevented` + `stopPropagation` guards**

The previous blast-radius force-directed network from v3.28.0–v3.28.3 was already navigable (pan, zoom, drag-a-node, hover-for-tooltip) but read-only beyond hover — there was no way to focus attention on a single component's immediate neighborhood. For an 18-node, 20-edge architecture like `account-summary` this is borderline manageable, but as architectures grow it becomes hard to answer "what depends on X" or "what does X cascade into" without manually tracing edges. This release adds the canonical "neighborhood highlight" interaction.

**Why 1-hop both directions (not downstream-only)**: a blast-radius reviewer cares about two questions simultaneously — "what fails because this node fails?" (downstream cascade) and "who depends on this node?" (upstream callers, the impact set). Highlighting both directions in one gesture answers both at once. If the user needs unidirectional later, the data is already there (link `source` vs `target` are preserved on the link objects) so it's a one-flag extension.

**Why composition with pan/zoom + drag matters**: the d3 zoom behavior calls `preventDefault` on every gesture step, and the d3 drag behavior calls `preventDefault` during a drag — both leave `event.defaultPrevented === true` on the synthetic click event that fires when the gesture ends. The click handler on each node and the click handler on the svg background both guard with `if (event.defaultPrevented) return;` so neither a pan-end nor a drag-end is mistaken for a "select node" or "clear selection" click. The node-click handler also calls `event.stopPropagation()` so a deliberate node click does not bubble to the svg background and immediately clear the selection. These guards are why the new feature does not break the v3.28.2 pan/zoom or the original node-drag.

**Scope of this change** (5 files):

- `skills/architecture-analysis/templates/viz/blast-radius.html` — appended a click-to-highlight block after the existing `svg.call(d3.zoom()…)` registration. Builds an undirected adjacency `Map<nodeId, Set<nodeId>>` from `data.graph.links` (using the original string-keyed source/target, not the post-`forceLink` mutated object references) so each node maps to a set containing itself plus all 1-hop neighbors. Adds a `selectedId` state variable and an `updateHighlight()` function that sets `style("opacity", …)` on nodes and edges (18 % / 12 % dim, 1 full) and switches the selected node's outline to `var(--accent)` with `stroke-width: 3`. Node-click handler toggles `selectedId` (clicking the same node twice deselects); svg-background click clears the selection. Legend hint extended: `"… · click a node to highlight its 1-hop neighbors · click canvas to reset · …"`.
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.28.3 → 3.28.4; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on Markdown mode (no skeleton, agent contract, or spec changes). Zero impact on the other 9 viz types — their snippets are untouched. The per-scenario cascade tree diagrams added in v3.28.3 remain unchanged. The new interaction is purely additive on the main force-directed network: hover, drag, pan, zoom, and now click-to-highlight all coexist. Existing `analysis/BLAST-RADIUS-<date>.html` files in consumer projects are not re-rendered; the next HTML run produces the click-highlightable output. d3.zoom and d3.drag are unchanged; no new CDN dependency.

**Verification**: `bun run typecheck` passes (no TypeScript files touched). `bun test` — 225/225 pass, no regressions. `grep -c "selectedId\|updateHighlight\|neighbors" skills/architecture-analysis/templates/viz/blast-radius.html` returns multiple matches (state variable, function, adjacency map, all referenced consistently). `git diff --name-only HEAD` shows exactly `blast-radius.html` + the 3 version files + README — no other viz files touched. End-to-end browser check on the `account-summary` blast-radius HTML report: click any node → that node and its 1-hop neighborhood stay at full opacity, everything else dims; click the same node again → reset; click empty canvas → reset; pan, zoom, drag, and hover tooltips all continue to work.

### v3.28.3 (Previous Release) ✅
**feat(architecture-analysis): per-scenario cascade diagrams restored in blast-radius HTML mode — three small standalone d3 hierarchy trees (one per top-severity source node) rendered inside the main `<section id="visualization">` immediately below the force-directed network, driven by a new `data.scenarios` JSON key; root = failed source (red), downstream nodes color-coded cascading-red vs contained-green; no hand-coded SVG, no extra `<section>` blocks**

The v3.28.1 fix had removed the per-scenario cascade diagrams entirely (replaced with an HTML table) because the previous v3.28.0 agent-rendered hand-coded SVGs were broken (Scenario 3 overflow, backwards edges, nested `<code>` inside SVG `<text>`). The user confirmed they want the per-scenario individual graphics back — but as proper d3 visualizations this time. This release restores the diagrams as small standalone d3 hierarchy trees, each screenshottable in isolation for slide decks or pre-incident reviews, using the same severity color palette as the rest of the report. The HTML table from v3.28.1 stays in `{{FINDINGS_HTML}}` as the factual breakdown that accompanies the diagrams.

**Why d3 trees and not the original Mermaid translation**: d3 `hierarchy()` + `tree()` give per-scenario layouts that scale with depth and leaf count automatically (no manual coordinate computation, no overflow, no fragile hand-positioned `<rect>`/`<line>`/`<text>` elements). Markdown mode is unchanged — the spec's Mermaid flowcharts render normally there. HTML mode now has actual interactive diagrams (hover for component name + cascade status), the table for textual scanning, AND the main force-directed network — three complementary projections of the same finding evidence with zero invention.

**Why this is a multi-sub-diagram pattern (and why it's not a One-Viz Rule violation)**: the v3.28.1 One-Viz Rule was about preventing the agent from inventing new `<section>` blocks or hand-coding SVG. It does NOT constrain what a viz snippet's own d3 code emits inside its single `#viz` div. The blast-radius snippet now renders the main force-directed network PLUS per-scenario hierarchy trees, all inside the same `<section id="visualization">` — a multi-diagram snippet driven by additional `data.*` keys. The agent contract at Phase 5b.0.5 is extended with an explicit note codifying this distinction so future viz snippets can follow the same pattern when their analysis benefits from per-finding mini-diagrams.

**Scope of this change** (5 files):

- `skills/architecture-analysis/templates/viz/blast-radius.html` — appended a guarded `if (Array.isArray(data.scenarios) && data.scenarios.length > 0) { … }` block at the end of the existing IIFE. Injects self-contained CSS via `root.append("style")` (`.scenarios-section`, `.scenario-card`, `.tree-node`), creates a `<div class="scenarios-section">` with an `<h3>` header, and iterates each scenario. Per scenario: a `.scenario-card` with `<h4>` title + optional caption + a responsive SVG containing a `d3.hierarchy(scenario.tree)` laid out by `d3.tree().size([innerH, innerW])`. Edges colored `var(--sev-critical)` (solid) for `Cascading`/`Fail-closed` and `var(--sev-pass)` (dashed) for `Bulkhead`/`Fail-open`. Nodes colored by cascade status — root always `var(--sev-critical)`, downstream nodes red for cascading, green for contained. Hover tooltips show component name + cascade status. Layout grows with depth (width) and leaf count (height) so trees self-size without overflow. The leading file comment gains the `data.scenarios` shape annotation.
- `agents/reviewers/architecture-analysis-agent.md` — three Phase 5b edits. (1) **5b.0 blast-radius row** rewritten: cascade scenarios are NOT omitted; they are rendered as per-scenario d3 trees by the viz snippet (the agent only populates `data.scenarios`). The HTML table in `{{FINDINGS_HTML}}` still accompanies the diagrams. (2) **5b.1 shape table** extended for blast-radius with the full `data.scenarios` JSON contract: `[{ title, source_id, caption?, tree: { name, cascade: "root", children: [{ name, cascade, children: […] }] } }]`, exactly the top 3 highest-severity source nodes from the spec's "Cascade Paths" section, with the same finding evidence as the Mermaid block in markdown mode. (3) **5b.0.5 One-Viz Rule** gets a clarifying paragraph: a single viz snippet MAY render multiple d3 sub-diagrams inside its `#viz` div as long as they are driven by `data.*` keys (no hand-coded SVG, no extra `<section>` blocks).
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.28.2 → 3.28.3; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on Markdown mode — the spec, agent Phase 5a, and `templates/analysis-report-skeleton.md` are untouched. Zero impact on the other 9 viz types — their snippets are unchanged, none of them carry per-scenario data. HTML reports generated before v3.28.3 are not re-rendered automatically; the next blast-radius HTML run produces the new per-scenario tree diagrams. The HTML shell, placeholder set, and CSS palette are all unchanged — the `.scenarios-section` / `.scenario-card` styles are injected by the viz snippet itself via `root.append("style")` so the shared skeleton stays free of viz-specific rules. If `data.scenarios` is omitted (e.g. an older agent payload), the snippet skips the scenarios block silently — no error, no broken render.

**Verification**: `bun run typecheck` passes (no TypeScript files touched). `bun test` — 225/225 pass, no regressions. `grep -c "d3.hierarchy\|d3.tree" skills/architecture-analysis/templates/viz/blast-radius.html` returns at least 2. `grep -c "scenarios-section\|scenario-card" skills/architecture-analysis/templates/viz/blast-radius.html` returns at least 4 (CSS class declaration + uses in `append("div").attr("class", ...)`). The next consumer-side blast-radius HTML run renders three scenario cards below the main network, each with a d3 horizontal tree, hover tooltips, and the same severity colors as the rest of the report.

### v3.28.2 (Previous Release) ✅
**feat(architecture-analysis): pan + zoom on the blast-radius force-directed network — `d3.zoom()` attached to the svg, all link + node groups now live inside a `viewport <g>` that receives the transform, node-drag behavior preserved unchanged, scaleExtent clamped to 30 %–400 %, legend hint extended so the new gestures are discoverable in-place without reading docs**

The d3 force simulation in the blast-radius viz computes positions that occasionally push 2–4 peripheral nodes outside the fixed 760 × 480 viewBox — and once they were off-screen there was no way to navigate to them. The previous behavior only allowed `d3.drag()` on individual nodes (move one node), with no canvas-level pan or zoom. As architectures grow beyond the 18-component test architecture this becomes a discoverability problem.

**Why this matters**: an architecture diagram you cannot fully see is not a useful diagram. The user discovered the gap on the first real `account-summary` run after the v3.28.1 fixes — the d3 viz rendered, but some components were not in the initial view and there was no obvious gesture to find them. This release closes that gap with the canonical d3 pattern (zoomable inner `<g>` + `d3.zoom()` on the svg) so the same viz scales to architectures of any size.

**Scope of this change** (4 files):

- `skills/architecture-analysis/templates/viz/blast-radius.html` — three surgical edits inside the existing IIFE body. (1) A new `const viewport = svg.append("g").attr("class", "viewport")` inserted after the `defs` block; the arrowhead marker stays in `defs` (outside the viewport so it scales correctly at any zoom level). (2) Both `link` and `node` groups re-anchored from `svg.append("g")` to `viewport.append("g")`, so they receive the zoom transform together. (3) After the simulation tick handler, `svg.call(d3.zoom().scaleExtent([0.3, 4]).filter(e => !e.button).on("zoom", e => viewport.attr("transform", e.transform)))` is registered — left-click drag on empty canvas pans, scroll wheel zooms around the cursor, node drag continues to work because `d3.drag()` calls `event.sourceEvent.stopPropagation()` on its `mousedown` listener so the zoom behavior never sees node-originated mousedowns. The trailing legend hint is extended to `"solid edge = cascading · dashed = bulkhead / fail-open · drag canvas to pan · scroll to zoom · drag a node to reposition"` so the gestures are discoverable inside the rendered viz.
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.28.1 → 3.28.2; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on Markdown mode (no skeleton, agent contract, or spec changes). Zero impact on the other 9 viz types — they use bounded layouts (scatter on a fixed 3 × 3 grid, horizontal bars, Pareto, STRIDE matrix, treemap, stacked bars, Gantt timeline, chord on a fixed-radius circle, Sankey on a bounded grid) and none of their snippets are touched. The HTML shell is unchanged; the `viewport` group is a viz-internal implementation detail invisible to the agent or the orchestrator. Existing `analysis/BLAST-RADIUS-<date>.html` files in consumer projects are not re-rendered; the next HTML run produces the pan/zoom-capable output. d3.zoom is part of d3 v7 core (already loaded by the skeleton from CDN), so no new dependency.

**Verification**: `bun run typecheck` passes (no TypeScript files touched). `bun test` — 225/225 pass, no regressions. `grep -c "d3.zoom" skills/architecture-analysis/templates/viz/blast-radius.html` returns 1 (the new zoom registration). `grep -c "viewport" skills/architecture-analysis/templates/viz/blast-radius.html` returns 4 (one declaration + three uses — append/link/node). `git diff --name-only HEAD~1` (after release) shows exactly `blast-radius.html` + the three version files + README.md, confirming the surgical scope. End-to-end browser test on the `account-summary` blast-radius report: all 18 nodes reachable via scroll-out, canvas drag pans the entire graph, node drag still moves individual nodes without panning, tooltips remain correctly positioned at every zoom level.

### v3.28.1 (Previous Release) ✅
**fix(architecture-analysis): three independent HTML-mode bugs from the first real run — empty d3 viz (script-ordering + cross-`<script>` scope), hand-coded `<svg>` cascade scenarios with broken layout, and ASCII heat maps rendered verbatim in `<pre>` blocks. Skeleton restructured so `{{ANALYSIS_DATA_JSON}}` and `{{VIZ_BLOCK}}` share ONE `<script>` block; 10 viz snippets shipped without outer `<script>` wrappers; agent Phase 5b gains explicit section-omission table, one-viz rule, verbatim viz-snippet rule, and three new pre-write verification checks**

The v3.28.0 HTML feature was exercised against a real architecture for the first time and produced `analysis/BLAST-RADIUS-2026-05-26.html` with three independent failures: the force-directed dependency network rendered as an empty `<div>`, the "Cascade Paths — Top 3 Worst Scenarios" section appeared as three broken hand-coded `<svg>` blocks (Scenario 3 had overflowing labels, backwards edges, and nested `<code>` tags inside SVG `<text>`), and the ASCII heat map appeared verbatim inside a `<pre>` block as a duplicate `<section id="heatmap">`. Root cause for all three: the v3.28.0 skeleton and agent contract were under-specified at exactly the three seams the agent freelanced.

**Why this matters**: the HTML output mode is the feature stakeholders see — a security officer, finance partner, or compliance reviewer who opens a `.html` file expects an interactive corporate-grade report, not an empty viz, a broken SVG, and an ASCII art block. Each of the three bugs was a contract gap rather than a logic error: the d3 code was correct, the per-analysis data was correct, the spec content was correct. What was missing was (a) a single shared lexical scope for the embedded `data` global and the viz IIFE, (b) an explicit rule that the agent must not hand-code SVG, and (c) an explicit list of spec sections that the d3 viz subsumes in HTML mode. All three are closed here, leaving the v3.28.0 feature actually usable.

**Why d3's `data` global needs one `<script>` block, not two**: `const` and `let` are block-scoped, so two `<script>` blocks do not share `const data = {...};`. The v3.28.0 skeleton placed `{{ANALYSIS_DATA_JSON}}` in a body-bottom `<script>` and `{{VIZ_BLOCK}}` in a mid-body `<script>` inside the visualization `<section>` — the viz IIFE could never reach `data`. The agent compensated by emitting `window._FOO_DATA = {...}` (cross-script-global pattern, which DOES attach to `window`), but the body-bottom data block still executed *after* the viz script in document order, so `window._FOO_DATA` was undefined at viz-run time and the early-exit guard fired. The v3.28.1 fix is structural: one `<script>` block holds both tokens. No cross-script global, no script-ordering risk, `const data` is visible to the viz via plain lexical scope.

**Scope of this change** (15 files, 1 created → none; 14 modified):

- `skills/architecture-analysis/templates/analysis-report-html-skeleton.html` — visualization `<section>` now wraps `{{ANALYSIS_DATA_JSON}}` and `{{VIZ_BLOCK}}` in a single `<script>` block (with an in-place HTML comment explaining why the two tokens must stay together). Body-bottom `<script>` reduced to the d3 load-guard only. Header docstring updated to document the new contract for `{{ANALYSIS_DATA_JSON}}` (single statement, no `window.` prefix, inlined inside the viz section's `<script>` block).
- `skills/architecture-analysis/templates/viz/{spof,blast-radius,bottleneck,cost-hotspots,stride,vendor-lockin,latency-budget,tech-debt,coupling,data-sensitivity}.html` (10 files) — outer `<script>` opening tag and `</script>` closing tag stripped from each file. The IIFE body, the leading HTML comment documenting the expected `data.<key>` shape, and all d3 logic are unchanged. The bare IIFE bodies are now inlined inside the skeleton's outer `<script>` block at render time.
- `agents/reviewers/architecture-analysis-agent.md` — Phase 5b gains four new constraints. **5b.0 Section Omission Rules**: per-analysis table listing spec sections that are markdown-only and MUST be omitted in HTML mode because the d3 viz subsumes them (e.g. SPOF "Risk Heat Map" ASCII → omitted, replaced by d3 scatter; Blast Radius "Cascade Paths" Mermaid → omitted, replaced by an HTML table; Blast Radius "Heat Map" ASCII → omitted; Coupling Mermaid cycle subgraphs → HTML table; Data Sensitivity per-flow Mermaid sequence diagrams → HTML table). **5b.0.5 One-Viz Rule**: exactly one `<section id="visualization">` is permitted; no extra `<section>` blocks, no hand-coded `<svg>` anywhere in any HTML fragment, no `<pre>` blocks carrying ASCII heat maps / bar charts / histograms / flow diagrams. **5b.3 verbatim viz-snippet rule** (tightened): the inlined viz body is copied VERBATIM — do not rename the `data` global, do not introduce `window.foo` indirection, do not add `<script>` tags around the inlined IIFE body, do not edit comments. **5b.4 verification additions**: pre-write checks for (i) no leftover `{{TOKEN}}` placeholders (existing), (ii) exactly one `<section class="report-section" id="visualization">` substring (new), (iii) no `window._` substring anywhere in any `<script>` block (new — catches the cross-script-global anti-pattern). Any failure falls back to writing the Markdown render to a `.md` sibling and reports the error in Phase 7.
- `skills/architecture-analysis/SKILL.md` — one bullet appended to the HTML format notes subsection codifying the omission rule for stakeholder reference: ASCII heat maps, ASCII bar charts, ASCII histograms, and Mermaid diagrams are omitted in HTML mode; cascade scenarios, cycle subgraphs, and sequence diagrams surface as HTML tables.
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.28.0 → 3.28.1; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on Markdown mode — the spec files, agent Phase 5a, and `templates/analysis-report-skeleton.md` are untouched, so Markdown reports are byte-for-byte identical to v3.28.0 output. The previously-broken `analysis/BLAST-RADIUS-2026-05-26.html` in any consumer project is NOT re-rendered automatically; the next HTML run produces the corrected output. The HTML skeleton's placeholder contract is unchanged in terms of token names — `{{ANALYSIS_DATA_JSON}}` still expects `const data = { ... };` — but its position in the document moves from body-bottom to inside the visualization `<section>`'s `<script>` block. Any consumer who has hand-edited the bundled skeleton or viz snippets would lose those edits at upgrade time, but no in-tree skill or agent edits this content at runtime. The agent's Phase 5b output is now strictly smaller in HTML mode (fewer `<section>` blocks, no hand-coded SVG, no `<pre>` ASCII) — purely a reduction in surface area, no behavioural extension.

**Verification**: `bun run typecheck` passes (no TypeScript files touched). `bun test` — 225/225 pass, no regressions. `grep -c "^<script>\\|^</script>" skills/architecture-analysis/templates/viz/*.html` returns 0 for all 10 files. `grep -n "{{ANALYSIS_DATA_JSON}}" skills/architecture-analysis/templates/analysis-report-html-skeleton.html` returns exactly one match — inside the visualization `<section>`. The next consumer-side run of `/skill architecture-analysis` in HTML mode will produce reports where (a) the d3 viz renders, (b) no hand-coded SVG appears in the findings, and (c) ASCII heat maps from the spec are absent — replaced by the d3 viz alone.

### v3.28.0 (Previous Release) ✅
**feat(architecture-analysis): interactive d3.js v7 HTML output mode — runtime format selector (Markdown / HTML) lifted into a new blocking Step 2.4 in `skills/architecture-analysis/SKILL.md`, corporate-styled self-contained HTML shell (`templates/analysis-report-html-skeleton.html`) with `{{PLACEHOLDER}}` substitution, and ten per-analysis d3 visualization snippets under `templates/viz/` (SPOF scatter heat map, Blast Radius force-directed dependency network, Bottleneck capacity-headroom bars, Cost Hotspots Pareto chart with cumulative-% overlay, STRIDE per-trust-boundary matrix, Vendor Lock-in treemap, Latency Budget per-flow stacked bars with SLO ceiling, Tech Debt EOL Gantt timeline, Coupling chord diagram, Data Sensitivity Sankey via d3-sankey)**

Closes the longest-standing presentation gap in `architecture-analysis`: the skill produced ten high-quality risk and sustainability reports, but every output was ASCII heat maps + pipe tables inside a `.md` file — readable in a terminal, weak when shared with non-engineering stakeholders. Security officers, finance partners, compliance reviewers, and executive sponsors do not consume Markdown; they consume browser pages and slide decks. The Markdown source-of-truth stays intact and remains the default; HTML is an opt-in alternative chosen at runtime per run.

**Why this matters**: an analysis report's value is bounded by how widely it can travel. A SPOF heat map with finding IDs plotted in a 3×3 Impact × Likelihood grid lands very differently as an interactive d3 scatter (drag-to-explore, tooltip with full scenario text, severity-tier color band) than as an ASCII block in a code fence. The same observation applies across every analysis type — a Pareto cost chart with a real 80% cumulative line, a force-directed blast-radius graph with cascade-vs-bulkhead edge styling, a chord diagram showing god-object coupling, a Sankey of PII flow with encryption-gap edges highlighted. None of this requires inventing new data — every viz is a *projection* of the findings already in the report; the JSON payload embedded in the HTML must contain only entries that also appear in the rendered tables (enforced in the agent's Report Quality Rules section as an extension of the no-invention policy). The result: same findings, two presentation surfaces, one runtime choice.

**Why d3.js and not a chartless dashboard**: each of the ten analyses has a *different* natural visualization (scatter for SPOF, force-directed for blast radius, treemap for vendor concentration, Sankey for PII flow, chord for coupling). A generic chart library would have forced bar-chart-everything. d3.js v7 + d3-sankey from CDN gives each viz the right primitive without a build step or shared chart abstraction — every snippet is 60–150 lines, reads the `data` global, and renders into a single `<div id="viz">`. The shell loads d3 once; viz snippets are self-contained scripts inlined at render time.

**Scope of this change** (16 files, 14 new + 2 modified skill files; trigger row + plugin manifest also updated):

- `skills/architecture-analysis/templates/analysis-report-html-skeleton.html` (new, ~12.9 KB) — shared corporate-themed HTML shell. Muted blue / slate palette with WCAG-AA severity tokens (`--sev-critical: #b91c1c`, `--sev-high: #d97706`, `--sev-medium: #ca8a04`, `--sev-low: #65a30d`, `--sev-pass: #15803d`), `system-ui` typography, print stylesheet, responsive container max-width 1180px. Loads `d3.v7.min.js` + `d3-sankey.v0.12.min.js` from CDN with a `typeof d3 === "undefined"` guard that surfaces a user-visible fallback banner when the page is opened offline (tables/prose still render; only the viz `<div>` shows an "unavailable without d3.js" notice). Sixteen `{{TOKEN}}` placeholders cover every render-time slot: title, header meta, exec summary, findings HTML, viz title, viz block, recommendations, verdict, gaps, citations, and the embedded `const data = { ... };` payload.
- `skills/architecture-analysis/templates/viz/{spof,blast-radius,bottleneck,cost-hotspots,stride,vendor-lockin,latency-budget,tech-debt,coupling,data-sensitivity}.html` (10 new files, ~3.3–4.8 KB each) — one self-contained d3 v7 snippet per analysis type. Each declares its expected `data.<key>` shape in a leading HTML comment (so the agent can match it without reverse-engineering the script), then renders into the shell's `<div id="viz">` with hover-tooltip, severity legend, and viewBox-based responsive sizing. The Sankey snippet checks for `typeof d3.sankey === "function"` and degrades gracefully if the secondary CDN script fails to load.
- `skills/architecture-analysis/SKILL.md` — new **Step 2.4 — Select Output Format** (blocking, between analysis-selection and the per-analysis explorer fan-out): single prompt `1=Markdown / 2=HTML`, no silent default, stores `output_format` for downstream steps. Step 3 prompt builder gains three conditional inputs (`output_format`, `html_skeleton_path`, `viz_template_path`) emitted to the agent only in HTML mode; `output_path` extension is swapped to `.html` accordingly. Step 4 completion summary uses `.<ext>` placeholders so the printed file list matches the chosen format, and an HTML-mode tip block adds `open` / `xdg-open` / `start` invocations plus the no-internet caveat (tables work offline; viz needs the CDN). The Files-in-This-Skill table gains rows for the new HTML skeleton and the `templates/viz/` directory. A new "HTML format notes" subsection under Output Location codifies the self-contained-single-file guarantee, the d3 CDN dependency, and the same-findings-both-formats invariant.
- `agents/reviewers/architecture-analysis-agent.md` — Input Parameters section gains `output_format` (default `markdown` when absent — backward compatible), `html_skeleton_path` (HTML mode only), `viz_template_path` (HTML mode only). Phase 0 forks: markdown mode reads `skeleton_path` as before; HTML mode reads `html_skeleton_path` + `viz_template_path` and ignores `skeleton_path`. **Phase 5 is split into 5a (Markdown — unchanged 8-step render) and 5b (HTML — four sub-steps)**: 5b.1 builds the `analysis_data` JSON object matching the per-analysis viz schema (full shape table for all 10 analyses inlined in the agent prompt so the JSON contract is explicit, not inferred); 5b.2 renders findings tables / recommendations / gaps / citations as HTML fragments using the shell's CSS classes (`.sev.critical`, `.row-high`, `.recommendation`, `.gaps`, etc.); 5b.3 performs the string-substitution of all 16 `{{TOKEN}}` placeholders including per-analysis `{{VIZ_TITLE}}` (canonical titles tabulated in the agent prompt); 5b.4 verifies no placeholder leaked through and falls back to writing the Markdown render to the same path with `.md` extension if any did. The Report Quality Rules section gains an HTML-output addendum that ties (a) the no-invention rule to the embedded JSON ("contain only entries that also appear in the rendered findings tables"), (b) the self-contained-file requirement (only the d3 + d3-sankey CDN refs are permitted), and (c) the Component Naming Fidelity rule to the viz `data` payload and tooltips (canonical full name in `data`, visual truncation with `…` is the viz snippet's job, not the data's).
- `CLAUDE.md` — the `architecture-analysis` row in the Trigger Routing — Exact Phrases table is rewritten to surface the runtime format choice: "Risk & sustainability reports in `analysis/` — output format is asked at runtime (Step 2.4) after analysis selection: Markdown (`.md`, grep-friendly, default) OR HTML (`.html`, interactive d3.js v7 + d3-sankey, corporate styling, requires internet for viz). The same findings populate either format."
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.27.3 → 3.28.0; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on existing markdown workflows. The orchestrator defaults to nothing — Step 2.4 is blocking and explicit — but `output_format` defaults to `markdown` inside the agent if the orchestrator omits the parameter, so any older caller or replay continues to produce `.md` files byte-for-byte equivalent to a pre-3.28 run. None of the analysis specs (`analyses/*.md`) were modified — classification rules, evidence extraction tables, and required Report Sections all produce the same findings data in either render path. Markdown remains the source of truth and the only format that `architecture-docs-export` (Word `.docx` generation) consumes; HTML is an additional presentation surface for stakeholder socialisation, not a replacement. Re-running the same analysis on the same day with a different format produces a sibling file (`.md` and `.html` coexist on disk) — no overwrite collision.

**Verification**: `bun run typecheck` passes (no TypeScript files touched). `bun test` — 225/225 pass, no regressions. `ls skills/architecture-analysis/templates/viz/` lists all ten viz snippets (one per `analysis_type`). `grep -c "{{TOKEN}}\|{{[A-Z_]*}}" skills/architecture-analysis/templates/analysis-report-html-skeleton.html` confirms 16 placeholders match the 16 substitutions documented in the agent's Phase 5b.3 table. The HTML shell's CDN URL (`https://d3js.org/d3.v7.min.js`) is the canonical d3.js v7 minified bundle URL; the secondary d3-sankey URL (`https://d3js.org/d3-sankey.v0.12.min.js`) is loaded by the shell as well so the Sankey snippet works without a separate import. No new permissions required — `Write(analysis/*)` already covers `.html` files alongside `.md`.

### v3.27.3 (Previous Release) ✅
**feat(architecture-compliance): `data_catalog` and `pipeline_orchestration` added as discrete check items in the Mnemosyne (Data & AI) validator — new "Data Infrastructure" 5th category (DAI-14, DAI-15) in `agents/validators/data-ai-validator.md`, matching grep patterns and `phase3.data_points` entries in `agents/configs/data-ai.json`, and two new template subsections (6.5 Pipeline Orchestration under LAD6, 8.5 Project Data Catalog under LAD8) in `cc-003-data-ai-architecture.template.md`**

Closes a gap where the Mnemosyne validator's 13 inline checks (Data Governance / Data Quality / AI/ML Governance / Privacy & Compliance) did not score two first-class data-platform concerns: discoverability via a data catalog, and reliability/recoverability via pipeline orchestration. Both concepts were previously only mentioned in passing inside template remediation notes (`data catalog` appeared twice; Airflow/Dagster/Prefect were absent entirely), so generated contracts surfaced them only as optional advice rather than as scored line items.

**Why this matters**: a data catalog underpins lineage, stewardship, and discovery — it is the addressable map from "which datasets exist" to "who owns them and how to consume them" — and it is the natural project-level counterpart to the already-scored 8.4 Institutional Catalog Compliance subsection. Pipeline orchestration determines whether multi-step ETL/ELT flows have job-scheduling, dependency graphs, retry policy, and SLA monitoring, or whether they rely on bare cron jobs that silently fail. Both belong in the Data & AI contract scoring surface, not in remediation footnotes.

**Scope of this change** (3 files):

- `agents/validators/data-ai-validator.md` — new `### Data Infrastructure (2 items)` category appended after Privacy & Compliance with DAI-14 (data catalog: tool identification + coverage + ownership) and DAI-15 (pipeline orchestration: platform + scheduling/dependencies + retry/SLA), two new evidence-collection grep patterns (`amundsen|datahub|collibra|alation|glue catalog|unity catalog` for catalog; `airflow|dagster|prefect|luigi|argo workflows|step functions|cloud composer` for orchestration), and two new rows (DAI-14, DAI-15) in the `VALIDATION_RESULT` output table.
- `agents/configs/data-ai.json` — two new entries each appended to `key_data_points`, `focus_areas`, and `agent_notes`; two new `phase3.data_points[]` entries (Data Catalog → `docs/06-technology-stack.md`; Pipeline Orchestration → `docs/06-technology-stack.md`) using the same tool + concept patterns as the validator. `domain.requirement_count` (11), `domain.requirement_range` (`LAD1-LAD8, LAIA1-LAIA3`), and `requirement_codes_list` are deliberately left unchanged.
- `skills/architecture-compliance/templates/cc-003-data-ai-architecture.template.md` — new subsection `### 6.5 Pipeline Orchestration` inserted under Section 6 Data Integration (LAD6) after 6.4 Data Consistency Management, with three sub-items (Orchestration Platform / Job Scheduling and Dependencies / Retry and SLA Policy); new subsection `### 8.5 Project Data Catalog` inserted under Section 8 Data Architecture Standards (LAD8) after 8.4 Institutional Catalog Compliance, with three sub-items (Catalog Tooling / Catalog Coverage / Catalog Ownership and Maintenance). Both subsections mirror the existing Status / Explanation / Source / Note four-field per sub-item shape used everywhere else in the template.
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.27.2 → 3.27.3; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on existing consumer architecture documents or already-generated compliance contracts — this is an additive change to the validator's check inventory and the template's subsection inventory, with no renumbering of existing requirement codes (still `LAD1-LAD8, LAIA1-LAIA3`, count 11) and no renumbering of existing DAI-* IDs (DAI-01 through DAI-13 unchanged). The 13/15 inline-check vs 11-requirement-code mismatch was already present (the validator's checks evaluate *coverage* in architecture docs while requirement codes structure the contract handed to the Data & AI Architecture Review Board); the new checks extend that coverage surface without disturbing the contract structure. The next time a consumer re-runs `architecture-compliance` for the Data & AI contract, the Mnemosyne validator will return 15 items (DAI-01…DAI-15) and the generated contract will include populated 6.5 and 8.5 subsections (filled where evidence is found in `docs/06-technology-stack.md`, marked Unknown/Gap where absent).

**Verification**: `bun -e 'JSON.parse(...)'` over `agents/configs/data-ai.json` succeeds. `grep -n "Data Infrastructure (2 items)" agents/validators/data-ai-validator.md` outputs `1`. `grep -n "^### 6.5 Pipeline Orchestration\|^### 8.5 Project Data Catalog" skills/architecture-compliance/templates/cc-003-data-ai-architecture.template.md` outputs both new subsections. `bun run typecheck` passes (no TypeScript files touched). `bun test` — 225/225 pass, no regressions.

### v3.27.2 (Previous Release) ✅
**fix(architecture-docs): Anti-Pollution Framing added to the canonical Connection Naming Rule in `DIAGRAM-GENERATION-GUIDE.md` — explicit one-edge-per-(A→B, [Action Type]) uniqueness constraint plus a "What Does NOT Belong on the Edge" routing table that names `docs/04-data-flow-patterns.md` and `docs/07-security-architecture.md` as canonical homes for operational and security detail; all violating worked examples in `MERMAID_DIAGRAMS_GUIDE.md` (full working example, sync/async/bidirectional sub-sections, Diagram Legend, and all 5 How-To scenarios) rewritten to the canonical `<PROTOCOL>/<STYLE> [Action Type]` form**

This release closes the gap between the canonical Connection Naming Rule (which has been authoritative since the rule landed) and the worked examples that the same guide ships — the examples were leaking `<br/>mTLS`, `30s timeout`, `3 retries`, `Consumer Group: <name>`, and `STARTED<br/>COMPLETED<br/>FAILED` event-type sequences onto edges, contradicting the very rule the document declares. Architects copying from those examples were propagating the over-rich form into new architectures, where it made L2 / Diagram 4 views unreadable as the system grew. The fix is two-part: tighten the canonical rule with an Anti-Pollution Framing that explains *why* the form is what it is, and align every example to that form.

**Why this matters**: C4 L1 / L2 / Diagram 4 are structural overviews. Stacking auth posture, timeouts, retry policy, error codes, sequence numbers, event-type sequences, and consumer-group routing on each edge collapses the diagram into noise and duplicates content that has a dedicated home elsewhere. The Connection Naming Rule was always meant to be a typing constraint — one edge per (A → B, [Action Type]) tuple — but the rationale was never written down, so the rule looked like a stylistic preference instead of a load-bearing anti-pollution mechanism. With the new framing, the rule sits next to a sibling Infrastructure-as-via Rule (also a pre-existing concept) and the two are explicitly described as the two anti-pollution primitives that keep L2 readable as the architecture scales.

**Scope of this change** (3 files):

- `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` — new `#### Anti-Pollution Framing — Why the Rule Has This Shape` subsection inserted under `### Connection Naming Rule (L1 + L2)`. Adds: (1) a 2-row table tying `<PROTOCOL>/<STYLE> [Action Type]` (edge pollution constraint) and `(via <hop>)` (node pollution constraint, links to the existing Infrastructure-as-via Rule L1 / L2 sections); (2) `##### Uniqueness Constraint — One Edge per (A → B, [Action Type]) Tuple` with a worked sync/async example showing two edges between the same pair admitted because they carry different action types; (3) `##### What Does NOT Belong on the Edge` — a 7-row routing table for each kind of pollutant (timeouts/retry → `docs/04-data-flow-patterns.md`; auth/TLS posture → `docs/07-security-architecture.md`; event-type sequences and consumer-group routing → encoded in the topic *node* label or in `docs/04`; multi-line `<br/>` content → forbidden). Closes with a one-line decomposition: L1 / L2 / Diagram 4 answers "*who* talks to whom, **over what protocol**, with **what data class**, **through which transit hops**"; the data-flow file answers "*in what order*, with **what guarantees**, **what happens on failure**"; the security file answers "*under what trust assumptions*."
- `skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md` — all violating worked examples rewritten to canonical form. Touches: (1) the full working example diagram (Section 3, ~30 edges) — every `<br/>`-laden multi-line edge label collapsed to one of `HTTPS/JSON [Data]`, `HTTPS/JSON [Query]`, `TLS/AVRO [Event]`, `gRPC/PROTOBUF [Internal]`; (2) Section 5 Synchronous Flows sub-section — syntax template, examples, and guidelines rewritten to prescribe the canonical form and explicitly route timeouts / retry / circuit-breaker / auth detail to `docs/04` and `docs/07`; (3) Asynchronous Flows sub-section — same treatment, plus an explicit "async flag is implicit in the arrow style" rule (`-.->` already means async, do not repeat in text); (4) Bidirectional Flows example collapsed to one canonical-form edge with a note to split into two edges if directions differ; (5) the Diagram Legend section — "Security Protocols" and "Timeouts & Retries" subsections (which previously suggested those values appear on the diagram) replaced with an "Edge Labels" rule + "What's NOT on the diagram" routing block; (6) all five How-To Scenarios — Scenario 3 ("Update Data Flow") additionally reframed from "Change Security Protocol via edge label" (the old framing presumed `gRPC/mTLS` lived on the edge, which is now wrong) to "Change Protocol" with security/operational guidance routed off the edge. Generic syntax templates at lines 555 and 604 also updated from `Protocol<br/>Security` placeholder to `HTTPS/JSON [Data]` worked example.
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.27.1 → 3.27.2; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on existing consumer architecture documents — this is a guidance change inside the plugin's authoring guides, not a runtime change to any skill workflow. Existing `ARCHITECTURE.md` and `docs/03-architecture-layers.md` files with over-rich edge labels continue to render and pass every existing audit gate (the Pre-Write Validation in `architecture-docs/VALIDATIONS.md` already rejects `<br/>` inside `Rel()` 4th parameters; the new framing makes the rationale explicit for `graph TB` edges that were not previously covered). The next time a consumer re-runs `architecture-docs` Workflow 8 (diagram generation) or hand-authors a new edge using the guide as a reference, they will produce the canonical form. No version bump of `ARCHITECTURE_VERSION` is required.

**Verification**: `grep -rn "30s timeout\|3 retries\|<br/>mTLS\|Async Publish\|Consumer Group:\|STARTED<br/>" skills/architecture-docs/` returns no matches in worked examples (all remaining matches are inside prose that *names* the anti-patterns, not example diagrams). `grep -n "Anti-Pollution Framing" skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` outputs `1`. The Worked Examples block at lines 367–379 of `DIAGRAM-GENERATION-GUIDE.md` (which was already correct) sits 50 lines below the new framing subsection so the worked form follows immediately from the new rationale. No TypeScript files touched — `bun run typecheck` baseline unchanged.

### v3.27.1 (Previous Release) ✅
**fix(architecture-dev-handoff): per-field Component Naming Fidelity in `SECTION_EXTRACTION_GUIDE` — Rule 7 added to "How to Use This Guide" binds component-name references extracted from `docs/05-integration-points.md` and from `**Dependencies:**` / `**Calls:**` fields back to the canonical full name in `docs/components/README.md` Column 2 before they are written into the handoff**

This is a per-field tightening of the existing agent-level Component Naming Fidelity rule. The agent-level block at the top of `agents/generators/handoff-generator.md` was already explicit ("write `omn-bs-top-ups-and-bundles` every time — never `omn-bs`"), but the per-field extraction guide bundled inside the same agent did not reinforce the rule at the rows that actually pull component names from secondary sources. Result: the component being handed off was correctly named, but components it *referenced* (in dependency rows, async integration rows, runbook recovery rows) were being propagated in their source-doc shortened form.

**Why this matters**: handoffs are read by external dev shops, contracted QA firms, and ops teams who may not have access to the source architecture. When a handoff says `Downstream Dependency: omn-spa` without resolving to `omn-spa-product-summary`, the reader cannot deterministically identify the dependency — especially in architectures where multiple components share a prefix (`omn-bs-top-ups-and-bundles`, `omn-bs-billing`, etc.). Moving the rule from a one-shot system-prompt header reminder to an explicit per-field extraction rule closes the gap at the exact seam where the agent decides what string to write.

**Scope of this change** (2 files):

- `agents/generators/handoff-generator.md` — Rule 7 added to the bundled `SECTION_EXTRACTION_GUIDE` "How to Use This Guide" list. Explicitly enumerates the affected rows: Upstream Consumers / Downstream Dependencies / Async Integrations / External System Integrations (A1/A3) and `**Dependencies:**` / `**Calls:**` fields plus Failure Recovery (A1/C2). Worked example `omn-spa` → `omn-spa-product-summary`. Cross-references the agent-level Component Naming Fidelity block at the top of the system prompt so Rule 7 is positioned as the per-field enforcement of an already-stated agent-level constraint.
- `skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md` — identical insertion in the source-of-truth file, so the next regeneration of the bundle into `handoff-generator.md` preserves the rule.
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.27.0 → 3.27.1; plugin description appended with the new release marker.

**Backward compatibility**: zero impact on existing handoffs — this is an instruction-only change, no template structure or extraction surface change. Re-running `architecture-dev-handoff` over an existing component regenerates the handoff with full-name resolution applied; the orchestrator's manifest-based skip check is unaffected (component file hashes drive that, not handoff content). Component files, integration-points docs, and the component index README itself are not touched. The other 18 agent files (validators, builders, reviewers, generators other than handoff-generator) already had complete Component Naming Fidelity coverage per the audit and are unchanged.

**Verification**: `grep -c "Component name resolution (Fidelity Rule)" agents/generators/handoff-generator.md skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md` outputs `1` for each file. The two copies of the guide remain textually identical at the inserted region (line 15 in source, line 470 in the bundled copy inside `handoff-generator.md`). No TypeScript files touched — `bun run typecheck` baseline unchanged.

### v3.27.0 (Previous Release) ✅
**feat(architecture-docs + technical-debt-records): new `technical-debt-records` skill (16 skills total), new Section 13 "Risks and Technical Debt" added to the architecture-docs canonical structure, References file renumbered `docs/10-*` → `docs/11-*` so the cross-cutting References file remains the last `docs/NN-*.md` file, new Workflow 11 (Layout Migration Gate) auto-detects + migrates legacy multi-file projects with no manual intervention**

This release introduces TDRs (Technical Debt Records) as a sibling concept to ADRs, integrates them into the architecture-docs canonical structure as a new Section 13, and ships the supporting renumber + auto-migration so existing consumer projects upgrade transparently on next workflow run.

**Why this matters**: ADRs capture *why a decision was made*; TDRs capture *what was deferred or accepted as suboptimal, and what it will cost later*. Until now this concept lived in informal notes or got buried in ADR consequence sections. With a dedicated lean 5-field format (Status / Description / Impact / Possible Solutions / Owner) plus a summary table inside the architecture document itself (Section 13.1 Risks + 13.2 Technical Debt), accepted compromises stay visible to every architecture review, peer review, and dev handoff. The numbering choice — Section 13 file at `docs/10-*` and References shifted to `docs/11-*` — preserves the convention that the cross-cutting References file is always the highest-numbered `docs/NN-*.md` file.

**Scope of this change** (33 files):

- **New skill** — `skills/technical-debt-records/` (5 files: `SKILL.md`, `templates/tdr-template.md`, `examples/TDR-001-centralized-log-aggregation.md`, `references/index-template.md`, `references/arc42-section-11-snippet.md`). Lean 5-field format, ID scheme (zero-padded `TDR-NNN`, never reused), workflow for create / status-update / supersede / list, arc42 Section 11 cross-reference snippet for arc42-using projects, generic seed example.
- **New canonical Section 13** — `skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md` (Section 13: Risks and Technical Debt template + arc42-alignment note explaining why this skill calls it S13 while external arc42 calls it Section 11), `skills/architecture-docs/QUERY_SECTION_MAPPING.md` (S13 query block + decision-tree routing line for `risk` / `tech debt` / `TDR` / `compromise` / `deferred work`), `skills/architecture-docs/SKILL.md` (S13 row in the canonical S↔file mapping + leaf entry in the Reverse Dependency Table).
- **File path renumber** — `docs/10-references.md` → `docs/11-references.md`; new `docs/10-risks-and-technical-debt.md` (S13). 24 path mentions updated across `architecture-docs/SKILL.md`, `ARCHITECTURE_DOCUMENTATION_GUIDE.md`, `QUERY_SECTION_MAPPING.md`, `ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md`, `REVIEW_AUDIT_WORKFLOW.md`, `RESTRUCTURING_GUIDE.md`, `architecture-compliance/SECTION_MAPPING_GUIDE.md`, `architecture-blueprint/SKILL.md`.
- **Workflow 11 — Layout Migration Gate** — `skills/architecture-docs/SKILL.md` adds a new workflow that auto-detects the legacy layout signature (`docs/10-references.md` exists AND `docs/10-risks-and-technical-debt.md` does not), prompts the user, then performs `git mv` of the references file, scaffolds the empty S13 file from the GUIDE template, rewrites cross-references across `docs/`, `docs/components/`, `adr/`, and `ARCHITECTURE.md`, and patches the navigation table. Idempotent — re-runs exit cleanly with `ℹ️ Layout already current — nothing to migrate.` Auto-trigger preflight declared for Workflows 2 / 3 / 8 / 10; new-project (Workflow 1) and single→multi restructure (Workflow 9) skip the gate since they emit the current layout directly.
- **Section-count + range consistency pass** (29 references across 18 files): `S1-S12` → `S1-S13`, `12 sections` → `13 sections`, `01-10` → `01-11`, "12-section structure" → "13-section structure", "11-file structure (Data Flow omitted)" → "12-section structure"; canonical 13-section enumeration with new `13. Risks and Technical Debt` row added to `architecture-docs/VALIDATIONS.md` and `architecture-compliance/SECTION_MAPPING_GUIDE.md`; both Expected-Output samples in VALIDATIONS.md (full + Data-Flow-omitted) extended with the S13 line; `S13 (Risks and Technical Debt) → S12` row added to the Data-Flow-omitted renumber list; checklist "All 12 sections present (or 11)" → "All 13 sections present (or 12)"; standard-order range `(1-12)` → `(1-13)`; the custom-section anti-pattern example bumped from `## 13. Future Roadmap` to `## 14. Future Roadmap` so it doesn't collide with the now-legitimate S13.
- **Path enumeration in agents** — `agents/builders/architecture-explorer.md` (added S13 file + renamed References in the docs/*.md enumeration), `agents/builders/handoff-context-builder.md` (cross-cutting `docs/10` → `docs/11` to follow the renumbered References file).
- **Compliance configs** — all 10 `agents/configs/*.json` files (`business-continuity`, `cloud`, `data-ai`, `development`, `enterprise`, `integration`, `platform`, `process`, `security`, `sre`) had identical stale notes referencing `(01-10)` and `S1-S12` — bulk-updated to `(01-11)` / `S1-S13`. Domain configs themselves unchanged in extraction logic.
- **Consumer-facing docs + templates** — `README.md` (badge + install verification + this changelog entry), `docs/TROUBLESHOOTING.md` (×2 "all 12 sections" mentions), `skills/architecture-docs/examples/README.md` (×2), `skills/architecture-onboarding/PLAYGROUND_TEMPLATE.md` + `SKILL.md` (concept-map node count + slot count), `skills/architecture-peer-review/SKILL.md` (monolithic-structure description), `skills/architecture-compliance/SKILL.md` + `COMPLIANCE_GENERATION_GUIDE.md` (file count "12 docs/" → "11 docs/"), `skills/architecture-compliance/templates/cc-001-business-continuity.template.md` + `cc-010-sre-architecture.template.md` (S1-S12 → S1-S13 ×2 each).
- **CLAUDE.md trigger routing** — added a new row for `technical-debt-records`: `create TDR` · `new TDR` · `record technical debt` · `technical debt record` · `update TDR status` · `list TDRs` · `TDR inventory` → `sa-skills:technical-debt-records`.
- **`.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json`** — version bumped 3.26.0 → 3.27.0; plugin description appended with the new release marker.

**Backward compatibility**: existing consumer projects with the legacy multi-file layout (References at `docs/10-references.md`, no `docs/10-risks-and-technical-debt.md`) are auto-detected by Workflow 11 on the next architecture-docs invocation. The user is prompted before any rename — refusing the prompt halts the calling workflow without modifying anything. After acceptance the rename is via `git mv` (preserving file history) or plain `mv` for non-git projects, the empty S13 file is scaffolded from the GUIDE template, internal cross-references and the navigation table are rewritten in one pass, and control returns to the original workflow. Section content, ADRs, component files, and version metadata are not touched. Single-file (monolithic) `ARCHITECTURE.md` projects are unaffected — the renumber and S13 only apply to the multi-file `docs/` layout.

**Verification**: `git status` after release shows the new `skills/technical-debt-records/` tracked + 31 modified files staged in this release commit (none unstaged). `grep -rn "docs/10-references.md" skills/ agents/` returns only the intentional Workflow 11 description occurrences and the technical-debt-records arc42-layout reference. `grep -rn "S1-S12\|all 12 sections\|01-10) differ" skills/ agents/` is empty. `bun run typecheck` baseline unchanged (no TypeScript files touched). The architecture-docs canonical S↔file mapping in `skills/architecture-docs/SKILL.md` lines 14-27 lists all 13 sections including S13 → `docs/10-risks-and-technical-debt.md`.

### v3.26.0 (Previous Release) ✅
**feat(enterprise-alignment): per-capability impact analysis — `ENTERPRISE_ALIGNMENT.md` surfaces which of the 47 BIAN v14 capabilities are impacted under each domain (not just the 8 parent domains); Section 1.5 of `docs/01-system-overview.md` lifts the capability-level detail**

This release sharpens the Enterprise Alignment Gate from **domain-level** to **capability-level** scope. Today an alignment report says "Customers 🟢 Impacted (3 rules triggered)"; after this release it says "Customers 🟢 — `Customer Management` 🟢, `Prospect Management` 🟢, `Loyalty Management` 🟡, `Claims & Inquiry Management` 🟢 (not impacted: Offer, Marketing, Campaign, Point-of-Sale, Event, Brand)." Owners now know precisely which of their capabilities are in scope, instead of being summoned for the whole domain.

**Why this matters**: the 8 BIAN domains span 47 canonical capabilities. A "🟢 Customers" finding under v2.0 of the alignment file covers ten capabilities — that's an over-broad governance call. Architecture Review Boards have been asking which specific capability the initiative touches so the correct sub-domain owner can be engaged (e.g., the `Brand Management` owner is a different counterpart than the `Customer Management` owner). Surfacing the canonical capability resolves that.

**Scope of this change** (6 files):

- `skills/architecture-enterprise-alignment/ENTERPRISE_ALIGNMENT_TEMPLATE.md` — `<!-- ENTERPRISE_ALIGNMENT_VERSION -->` bumped 2.0 → 2.1; Summary table gains a `Capabilities Impacted` column (`N/total`, where total is the canonical capability count per domain: 7 / 5 / 5 / 3 / 8 / 10 / 2 / 7); summary footer adds `Capabilities impacted: M of 47`; every per-domain section (3.1 → 3.8) gains an `**Impacted Capabilities**` block listing per-capability 🟢 / 🟡 status, one-line rationale, and PO Spec § citation, closed with a `(not impacted: <comma-separated canonical names>)` parenthetical so the reader can verify the classifier scanned the full domain.
- `skills/architecture-enterprise-alignment/ANALYSIS_METHODOLOGY.md` — new § 3.5 Per-Capability Classification with the 🟢 / 🟡 / ⚪ taxonomy applied at the capability level, naming-fidelity rule (verbatim from `ENTERPRISE_MODEL.md` § 3), and a domain↔capability consistency rule. § 4 Multi-Domain Capabilities gains a parallel fan-out table showing how a single PO Spec capability ("personal loan via mobile app") resolves to specific impacted capabilities under each domain. § 8 Anti-Patterns adds two new entries (empty 🟢-domain capability lists, capability invention with forbidden examples).
- `skills/architecture-enterprise-alignment/SKILL.md` — Step 4 capture list adds item 4 `Impacted Capabilities` (Evidence / Owner Counterparts renumbered to 5 / 6); Step 7 template-fill instructions describe the new column and per-domain block; the sample header-comment block fixed from stale `<!-- ENTERPRISE_ALIGNMENT_VERSION: 1.0 -->` to current `2.1`; Step 8 user-report adds `Capabilities impacted: M of 47`; Success Criteria gain three new checks (capability enumeration, `(not impacted: …)` parenthetical, Summary `N/total` consistency).
- `skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md` (Section 1.5 lift template) — the lifted table gains the `Capabilities Impacted` column; a new `**Impacted Capabilities (per domain)**` block lifts the per-domain bullet lists from the source report (🟢 / 🟡 only; ⚪ domains and the `(not impacted: …)` parenthetical are dropped here for brevity); Rules for Section 1.5 add a capability-naming-fidelity rule and a **version-aware fallback** — alignment files at v1.0 or v2.0 lack the per-capability data, so Section 1.5 cleanly degrades to the legacy 5-column table and skips the capability block.
- `skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` — Step 0.3 load-into-context note extends the lifted artifacts to include the per-domain Impacted Capabilities lists, with the version-aware fallback documented inline.
- `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `package.json` — version bumped 3.25.4 → 3.26.0; plugin description appended with `per-capability impact analysis in enterprise alignment v3.26.0`.

**Backward compatibility**: existing `ENTERPRISE_ALIGNMENT.md` files at v1.0 or v2.0 continue to pass the architecture-docs Step 0.3 gate unchanged (the gate parses presence + frontmatter comments, not the new content). The Section 1.5 lift detects the file version and falls back to the legacy domain-only table when the per-capability data is absent. Users who want capability-level Section 1.5 detail re-run `/sa-skills:architecture-enterprise-alignment` to regenerate at v2.1.

**Verification**: `grep -c "Capabilities Impacted" ENTERPRISE_ALIGNMENT_TEMPLATE.md` outputs `1` (the Summary header); `grep -c "Impacted Capabilities" ENTERPRISE_ALIGNMENT_TEMPLATE.md` outputs `8` (one per domain section); per-domain `N/total` totals match the model exactly (7 / 5 / 5 / 3 / 8 / 10 / 2 / 7 = 47); ARCHITECTURE_DOCUMENTATION_GUIDE.md Section 1.5 table has the new column and the new bullet block; the version-aware fallback rule documents both v1.0 and v2.0 as legacy. No TypeScript files touched — `bun run typecheck` baseline unchanged.

### v3.25.4 (Previous Release) ✅
**feat(enterprise-alignment): bundled ENTERPRISE_MODEL.md rewritten as a generic BIAN v14 8-domain capability map (47 capabilities) — replaces the prior 13-domain Architecture Governance shape; institution-neutral & language-neutral**

This release retires the v1.0 bundled enterprise model (13 English-named Architecture Governance domains) and replaces it with a BIAN v14-aligned **8-domain / 47-capability** capability map. The bundled file is **institution-neutral and language-neutral** — no brand attribution, no regional payment-rail names, no Spanish source-name parentheticals — so any organisation can adopt it unchanged, while project-local override semantics (`ENTERPRISE_MODEL.md` at the project root wins) remain untouched.

**Why the restructure**: the v1.0 model carried 13 domains keyed off internal Architecture Governance conventions. Downstream skills (architecture-docs Step 0.3 gate, the alignment template, the methodology heuristics, the owner-counterpart table) all hardcoded those 13 domain IDs. Realigning to BIAN v14 collapses 13 domains → 8 (Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler) and re-anchors the cross-cutting mandatory check trio from `Risks / IT / Data` → `Enterprise Management / Finance & Risks / Business Enabler`. Every governance rule carries a `> Carried from v1.0 § 3.X` annotation so reviewers can trace the inheritance.

**Why agnostic**: the bundled file ships to every project that consumes `sa-skills`. Brand attribution (`Banco Pichincha`), Ecuadorian payment-rail names (`BANRED`, `CNB 2.0`, `DeUna`), and Spanish source parentheticals (`Customer Management (Gestión de Clientes)`) were stripped so the model reads as a generic BIAN v14 reference. Generic equivalents replace the regional names where examples are still useful (`interbank settlement networks`, `agent-banking POS`, `digital wallets`).

**Scope of this change** (8 files):

- `skills/architecture-enterprise-alignment/ENTERPRISE_MODEL.md` — full rewrite v1.0 → v2.0: new 8-domain / 47-capability structure, governance rules adapted from v1.0 with explicit `Carried from v1.0 § 3.X` provenance lines, header comments updated to `<!-- ENTERPRISE_MODEL_VERSION: 2.0 -->` / `<!-- BIAN_VERSION: v14 -->` / `<!-- SOURCE: BIAN v14 capability model (institution-neutral, 47 capabilities, 8 domains) -->`. A migration note explains that v1.0-shape consumers can drop their own copy at the project root.
- `skills/architecture-enterprise-alignment/SKILL.md` — frontmatter description, Step 3 PO Spec → domain mapping table, Step 5 cross-cutting check table (3 new rows), Component Naming Fidelity worked examples, success-criteria checklist, sample output banner — all rekeyed to the 8-domain shape. BANRED example replaced with `interbank settlement network`.
- `skills/architecture-enterprise-alignment/ANALYSIS_METHODOLOGY.md` — § 3 Classification Heuristics rewritten as 8-row trigger table; § 4 Multi-Domain example renumbered to new domain IDs; § 5 Cross-Cutting Mandatory Domains replaced (Risks/IT/Data → Enterprise Management / Finance & Risks / Business Enabler) with a 7-rule Business Enabler check covering data-governance + AI explainability + cross-domain orchestration; § 6 Owner Counterpart Derivation rebuilt for 8 domains.
- `skills/architecture-enterprise-alignment/ENTERPRISE_ALIGNMENT_TEMPLATE.md` — Summary table 13 rows → 8 rows; per-domain analysis 13 sub-sections → 8 sub-sections; Cross-Cutting Findings re-skinned (`🏛️ Enterprise Management`, `🛡️ Finance & Risks`, `🖥️ Business Enabler`) with the Data check folded under Business Enabler.
- `skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` — Step 0.3 gate prose and the user-facing BLOCK message both updated to the 8-domain BIAN v14 enumeration.
- `skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md` — Section 1.5 Component Naming Fidelity worked example updated (`Financial & Non-Financial Risks` → `Finance & Risks`; `Business Enabler` example added to disambiguate against `IT/Data`).
- `CLAUDE.md` — Enterprise Alignment trigger-row description swapped to the 8-domain BIAN v14 capability map enumeration.
- `README.md` — three locations (skill callout, feature-list bullet, long-form release-note paragraph for the parent v3.25.0 entry) updated to the 8-domain BIAN v14 wording.

**Verification**: `grep -cE '^### 3\.[1-8] ' ENTERPRISE_MODEL.md` outputs `8`; `grep -cE '^### [1-8]\. ' ENTERPRISE_ALIGNMENT_TEMPLATE.md` outputs `8`; the 47-capability invariant is preserved (counted between `**Capabilities**` and `**Governance rules**` markers across all 8 domain sections). Zero `Banco Pichincha`, `BANRED`, `DeUna`, `CNB 2.`, or `(Gestión` leaks remain anywhere in `solutions-architect-skills/**/*.md`. `bun run typecheck` clean (no TypeScript files were touched).

**Behavioral change for users**:

- Existing `ENTERPRISE_ALIGNMENT.md` reports generated against v1.0 (with 13 rows / 13 sub-sections) are not auto-migrated. Re-running `/sa-skills:architecture-enterprise-alignment` against the same PO Spec produces a fresh v2.0-shape report (8 rows / 8 sub-sections / new cross-cutting trio).
- The Step 0.3 gate parser (`<!-- ENTERPRISE_ALIGNMENT_VERSION -->`, `<!-- ENTERPRISE_MODEL_SOURCE -->`, `<!-- PO_SPEC_SOURCE -->`, `<!-- GENERATED -->`) is unchanged — both v1.0-shape and v2.0-shape reports continue to pass the gate. The structural contract is preserved at the comment layer.
- Project-local override path is unchanged: drop a customised `ENTERPRISE_MODEL.md` at the project root and the skill picks it up first; bundled default is the fallback.

**Open TODO** (in-source, won't block adoption): § 3.5 Products carries a `<!-- TODO: confirm canonical English name for the issued-enabler product capability — provisionally "Issued Enabler Management" -->` flag for institutions to rename when they adopt the model.

### v3.25.3 (Previous Release) ✅
**feat(architecture-docs): mandatory HLD Intake Gate (Step 0.4) — Workflow 1 now refuses to create a new ARCHITECTURE.md without a High-Level Design file; accepted formats extended from PDF-only to PDF / SVG / high-res PNG**

This release promotes the High-Level Design from optional supplementary context to a **mandatory grounding artifact** before any architecture work begins, and broadens the accepted formats so architects don't have to re-export from their native diagramming tool.

**Why mandatory**: the previous Step 0.5 (Supplementary Context Files) treated the HLD as one item in an optional bag — when skipped, S4 (Architecture Layers), S5 (Component Inventory), and S6 (Data Flow Patterns) were reverse-derived from the PO Spec alone, drifting from upstream design intent. The Architecture team wants the HLD treated like the Enterprise Alignment Gate (Step 0.3): a hard gate the user cannot proceed past.

**Why PDF / SVG / PNG**: architects routinely export HLDs from draw.io / Lucidchart / Excalidraw as **SVG**, or capture whiteboard / Miro screenshots as **PNG**. Both are perfectly readable as architectural input — SVG via XML text parsing (labels + structure), PNG via the multimodal Read tool (visual layout). Forcing a PDF re-export was friction with no quality benefit.

**Scope of this change** (one workflow file):

- **NEW Step 0.4 — HLD Intake Gate (MANDATORY — no skip)** in `skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md`. Mirrors Step 0.3 (Enterprise Alignment) UX: cascades-skip only when an upstream gate (`PO_SPEC_GATE: SKIPPED` or `ENTERPRISE_ALIGNMENT_GATE: SKIPPED`) was recorded — there is no `SKIP HLD` override. Validates the file extension is one of `.pdf`, `.svg`, `.png` (case-insensitive); rejects anything else and re-prompts until valid. Reads the file (PDF via `pages` parameter, PNG multimodal, SVG as XML text) and seeds S4 / S5 / S6 with extracted components, layers, and integration arrows. Writes `<!-- HLD_GATE: PASSED (ref: <filename>, <date>) -->`, `<!-- HLD_SOURCE: <filename> -->`, `<!-- HLD_FORMAT: pdf|svg|png -->` traceability metadata into `docs/01-system-overview.md` during Step 5. Conflict resolution: PO Spec wins for *business* context; HLD wins for *structural* layout (component decomposition, integration topology); HLD wins over Step 0.5 supplementary files (HLD is the design anchor).
- **PNG resolution**: guidance text only — recommends ≥1920px wide or ≥150 DPI for diagram label readability — no programmatic dimension probe (kept simple).
- **SVG visual fidelity note**: SVG is parsed as XML text — Claude reads labels, group hierarchy, and arrow directions but does not "see" rendered visual positioning. For HLDs where positioning carries meaning (swimlane layouts, north-south vs east-west arrangement), prefer PDF or high-res PNG.
- **Step 0.5 cleanup**: HLD is removed from the optional Supplementary Context Files step entirely (bullet, example file path `design/hld.pdf`, classification table row, and the old PDF-only enforcement block). HLD now lives exclusively in the new mandatory gate; Step 0.5 keeps its other optional file types (ADRs, tech stack, OpenAPI, data models, NFRs, IaC, security).
- **Pre-existing numbering bug fixed as a side effect**: the workflow had `Step 0.3 → Step 0.5 → Step 0.5` (no 0.4, duplicate 0.5). Inserting the new HLD gate at 0.4 fills the hole; the duplicate Step 0.5 (Pre-Identify ADRs) is renumbered to **Step 0.6** with all four internal back-references updated (ADR ID assignment note, ADR Context Block confirmation marker, Section-5 cross-reference, ADR-skill invocation context-pass).

**Behavioral change for users**:

- New ARCHITECTURE.md creation: Workflow 1 will block at Step 0.4 with `📐 HLD Intake Gate (Required)` until a `.pdf`, `.svg`, or `.png` file path is supplied. There is no skip keyword.
- Cascades-skip path preserved: if the architect runs Workflow 1 with `SKIP PO SPEC` (or the Enterprise Alignment Gate is itself cascade-skipped), Step 0.4 also skips silently — the prompt is never shown.
- Existing architectures (Workflow 2 edits, Workflow 8 diagrams, Workflow 9 migration, Workflow 10 release): unaffected; the gate runs for new-architecture creation only.

**Verification**: `grep -n "^#### Step 0\." skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` shows the clean sequence `0.3 → 0.4 → 0.5 → 0.6`; zero stray HLD references inside Step 0.5; 20 HLD mentions concentrated in the new Step 0.4; all four ADR back-references point to Step 0.6; all three Step 0.3 forward-references ("proceed to next gate") point to Step 0.4.

### v3.25.2 (Previous Release) ✅
**chore(hooks): pure-native hook layer — UserPromptSubmit wrappers no longer depend on Bun (or any JS runtime); cold start drops from ~10–20 ms to <1 ms; shared static payload file replaces the TypeScript implementation**

The three platform wrappers (`route-architecture-docs.sh`, `.cmd`, `.ps1`) installed by `sa-skills:setup` previously invoked `bun route-architecture-docs.ts` to stat `ARCHITECTURE.md` and emit a fixed JSON system-reminder. Bun cold-start added ~10–20 ms per prompt submission, and any user without Bun on PATH could not install the plugin at all. The TypeScript file performed zero computation — a stat + a static JSON emit — so the JS runtime was unnecessary overhead. v3.25.2 removes Bun from the hook layer entirely.

**Architectural change**: replace the hidden-runtime indirection (each wrapper → `bun ...ts` → stat + emit) with a direct shell-native path (each wrapper → stat + `cat`/`type`/`Get-Content` of a static JSON file). The system-reminder text — 1150 characters with em-dash, arrow, apostrophe, asterisks, slashes — now lives in one place: `hooks/route-architecture-docs.payload.json`. All three wrappers emit it verbatim. No per-shell escaping, no payload drift between TS literal and JSON file, no JS runtime.

**Scope of this change** (5 files in the hook layer + 4 documentation files):

- **NEW** `hooks/route-architecture-docs.payload.json` — single-line valid JSON, the lone source of truth for the `UserPromptSubmit` payload (`hookSpecificOutput.hookEventName` + `additionalContext`). Validated with `python3 -m json.tool` post-write.
- **REWRITTEN** `hooks/route-architecture-docs.sh` — pure POSIX sh: `set -e`; `SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)`; `PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"`; `[ -f "$PROJECT_DIR/ARCHITECTURE.md" ] || exit 0`; `cat "$SCRIPT_DIR/route-architecture-docs.payload.json"`. Zero deps beyond `cat` + `[` (both POSIX-standard). Linux, macOS, WSL, Git Bash.
- **REWRITTEN** `hooks/route-architecture-docs.cmd` — pure Windows batch: `setlocal`; `set "PROJECT_DIR=%CLAUDE_PROJECT_DIR%"` with `%CD%` fallback; `if not exist "%PROJECT_DIR%\ARCHITECTURE.md" exit /b 0`; `type "%~dp0route-architecture-docs.payload.json"`. Zero deps beyond cmd.exe built-ins. Universally available on every Windows install since XP.
- **REWRITTEN** `hooks/route-architecture-docs.ps1` — pure PowerShell (5.x + Core/pwsh): `$ErrorActionPreference='Stop'`; project-dir fallback `$env:CLAUDE_PROJECT_DIR` → `(Get-Location).Path`; `Test-Path -LiteralPath $archMd`; `Get-Content -Raw -Encoding UTF8 -LiteralPath $payload`. Zero deps beyond PS built-ins.
- **DELETED** `hooks/route-architecture-docs.ts` — the 40-line TypeScript implementation. Removed entirely; no fallback / reference path kept. The wrappers are now the implementation, the `payload.json` is the data.

**Wiring (unchanged)**: `scripts/setup-permissions.ts` already platform-detects (`process.platform`) and writes the wrapper path into the user's `.claude/settings.json` — `sh /<abs>/route-architecture-docs.sh` on POSIX, `cmd /c "<abs>/route-architecture-docs.cmd"` on Windows. The wrapper filenames are stable contracts; only the internal implementation changed. Two comment blocks in `setup-permissions.ts` (lines 25–36 and 195–200) were updated to reflect the no-JS-runtime reality; no logic changes. The legacy-hook removal markers (`SA_SKILLS_HOOK_REMOVAL_MARKERS`) still detect and sweep the v3.19.0 `sh ~/...sh` and v3.21.0–v3.25.1 `bun ~/...ts` forms on every `/setup` run, so existing installs upgrade transparently.

**Settings example + install docs**: `.claude/settings.json.example` — `// HOOKS` comment updated (Bun no longer required for the hook layer; sub-millisecond cold start instead of ~10–20 ms); example command swapped `bun ~/.../*.ts` → `sh ~/.../*.sh` to match the actual POSIX form `setup-permissions.ts` writes. The `// BASH: bun (covers ALL shell needs since v3.21.0...)` permission comment **stays unchanged** — skill workflows still use Bun via `Bash(bun *)` for the three helper scripts (`scripts/today.ts`, `scripts/ensure-dir.ts`, `scripts/remove-glob.ts`). README install table now explicitly notes that Bun is only needed for the full skill suite, not the hook layer.

**Behavioral change for users**:

- Fresh installs: identical hook behavior — same JSON payload on prompt submission when `ARCHITECTURE.md` is present, same silent no-op otherwise. Only the underlying runtime differs.
- Existing installs: re-running `/sa-skills:setup` after upgrading sweeps the old `bun ~/.../*.ts` hook entry (via the v3.21.0 legacy marker that's been in `setup-permissions.ts` since v3.22.0) and installs the new wrapper path. No manual settings.json editing required.
- Bun-less environments: users who never installed Bun can now use the hook layer end-to-end. They still cannot use skill workflows that call `bun scripts/*.ts` — those will fail with a missing-Bun error from the Bash tool, as designed.

**Verification** (post-install, all green): `python3 -m json.tool hooks/route-architecture-docs.payload.json` parses cleanly; `grep -nE '\bbun\b' hooks/route-architecture-docs.{sh,cmd,ps1}` returns only documentation comments saying "No bun, no node" (zero invocations); `test ! -e hooks/route-architecture-docs.ts` returns ok (TS file removed); POSIX wrapper smoke test in a tmpdir with `ARCHITECTURE.md` present emits 1150-char `additionalContext` with `UserPromptSubmit` event; POSIX wrapper silent path returns exit 0 with no output; cold-start time measured at **0.001 s** (vs ~10–20 ms with Bun — ~10,000× faster); `grep -rE 'ARCHITECTURE-GOVERNED PROJECT' . --include='*.{ts,sh,cmd,ps1,json}'` returns only `hooks/route-architecture-docs.payload.json` (no drift between wrappers and the payload); `bun run typecheck` clean; `bun test` 225/225 pass (markdown + shell-only changes; tests don't cover the hook wrappers).

### v3.25.1 (Previous Release) ✅
**feat: new `architecture-enterprise-alignment` skill (mandatory Phase 1.5 gate before architecture-docs Workflow 1) + fix: ADR ID Format Gate blocks phase-prefixed IDs like `ADR-P1-001` and restores canonical `ADR-101+` numbering for project ADRs**

This release combines a structural addition (new mandatory gate) and a critical bug fix that surfaced once the gate started exercising the ADR creation path.

**New skill — `architecture-enterprise-alignment` (originally planned for v3.25.0)**: maps the accepted Product Owner Specification onto the organisation's 8-domain BIAN v14 capability map (Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler — 47 capabilities total) **before** architecture design begins. Produces `ENTERPRISE_ALIGNMENT.md` at the project root with: an 8-row summary table (🟢 Impacted / 🟡 Partial / ⚪ Not Applicable per domain), per-domain analysis (verbatim governance-rule citations from the bundled `ENTERPRISE_MODEL.md`, evidence quotes from the PO Spec, owner counterparts to engage), three mandatory cross-cutting checks (Enterprise Management, Finance & Risks, Business Enabler — these always run regardless of per-domain status), and an Owner Engagement Plan with timing derived from rule wording (Before kickoff / Before architecture sign-off / Before production). The bundled 8-domain model is overridable via a project-local `ENTERPRISE_MODEL.md` at the project root. **Mandatory gate**: `architecture-docs` Workflow 1 Step 0.3 BLOCKS new ARCHITECTURE.md creation until `ENTERPRISE_ALIGNMENT.md` exists — no `SKIP ENTERPRISE ALIGNMENT` override exists; the gate cascade-skips only when the PO Spec gate itself was skipped (because alignment cannot be produced without PO Spec content). When the gate passes, the Summary / Cross-Cutting Findings / Owner Engagement Plan are lifted into a new sub-section `1.5 Enterprise Domain Alignment` in `docs/01-system-overview.md`, with a `<!-- ENTERPRISE_ALIGNMENT_GATE: PASSED (ref: ENTERPRISE_ALIGNMENT.md, YYYY-MM-DD) -->` traceability comment. Files: 4 new under `skills/architecture-enterprise-alignment/` (SKILL.md, ENTERPRISE_MODEL.md, ENTERPRISE_ALIGNMENT_TEMPLATE.md, ANALYSIS_METHODOLOGY.md) plus updates to `ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md`, `ARCHITECTURE_DOCUMENTATION_GUIDE.md`, `architecture-docs/SKILL.md`, the plugin `CLAUDE.md` trigger table, `.claude/settings.json.example` permissions, and this README.

**Bug fix — ADR ID Format Gate**: when creating a new ARCHITECTURE.md, the ADR Candidate Table (Step 0.5), the Section 12 ADR table, and the materialised `adr/*.md` files were being labelled with phase-prefixed IDs like `ADR-P1-001`, `ADR-P2-001` instead of the canonical `ADR-101+` sequential numbering. The ADR Scope Partition rule (institutional 001–100, project 101+) was documented correctly in `ADR_GUIDE.md`, and the number-computation logic in `architecture-definition-record/SKILL.md` Step 2.1b was correct — but two misleading example IDs in workflow templates were nudging the agent toward improvisation, and no regex validation gate existed to reject malformed IDs at the write boundary. **Root cause**: (1) the Step 0.5 ADR Context Block example hardcoded `ADR-001 / ADR-002 / ADR-003` as IDs assigned at the candidate-table stage — those IDs collide with the institutional range, so for a project with multiple roadmap phases the agent invented `ADR-P{phase}-{n}` as a (wrong) disambiguation; (2) the Section 12 template example showed `ADR-001` as the first row, misleading for a new project where project ADRs start at 101; (3) no regex gate. **Fix**: replaced the Step 0.5 ADR Context Block example with `[Candidate N] [Title]` row-counter notation (no IDs until Step 6 materialisation) and added an explicit "Do not assign ADR IDs at Step 0.5" rule listing `ADR-P1-001`, `ADR-Phase1-001`, `ADR-001-P1`, `ADR-101-v2` as invalid; updated the Section 12 template to use `ADR-101` as the first-row example and added a `Scope` column (`Institutional | User`) so the partition is explicit at the registry level rather than inferred from the number range; added a new `## ADR ID Format Rules` section to `ADR_GUIDE.md` with the canonical regex (`^ADR-\d{3,}$`), a 9-row Invalid Examples table, and the filename regex; added a new `## ADR ID Format Gate (BLOCKING)` section to `architecture-definition-record/SKILL.md` with the abort message format and invocation lines at Workflow 1 Step 1.5b (new sub-step), Workflow 2 Step 2.3, and Workflow 4 Step 4.1. Six total gate references in SKILL.md (one definition, three explicit invocations, two cross-references). Adversarial requests asking the ADR skill to create `adr/ADR-P1-001-test.md` now hit the gate and abort with a documented error message pointing to `ADR_GUIDE.md`.

**Files** (13 total): 4 new skill files under `skills/architecture-enterprise-alignment/`; updates to `skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` (Step 0.3 gate + Step 0.5 ADR rules and Context Block), `skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md` (Section 1.5 spec + Section 12 Scope column + ID format callout), `skills/architecture-docs/SKILL.md` (Workflow 1 pre-step + lazy-load table), `skills/architecture-definition-record/ADR_GUIDE.md` (ADR ID Format Rules section), `skills/architecture-definition-record/SKILL.md` (ADR ID Format Gate + invocations + example success line updated to ADR-101), the plugin `CLAUDE.md` (trigger row + Four-Phase Workflow note), `.claude/settings.json.example` (4 new permissions), `CHANGELOG.md`, all three version files (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `package.json` — bumped 3.24.1 → 3.25.1), and this README. **Verification**: `bun run typecheck` clean; `bun test` 225/225 pass (markdown-only changes, no TS impact); 8 plan verification greps all green (0 hardcoded IDs in Step 0.5 Context Block; Scope column present in Section 12; no Phase column anywhere; Format Rules section present; `ADR-P1-001` documented as anti-pattern; gate invoked 6 times in SKILL.md).

### v3.24.1 (Previous Release) ✅
**feat(agents+templates): Component Naming Fidelity rule across all 19 agents, the analysis-report skeleton, HANDOFF_TEMPLATE (TEMPLATE_VERSION 2.0.0 → 2.1.0), the peer-review playground template, plugin CLAUDE.md, and the setup-time managed CLAUDE.md block — generated artifacts must use the canonical full component name from `docs/components/README.md` regardless of source-doc shortening**

Generated artifacts (analysis reports, peer reviews, dev handoffs, compliance contracts, `.docx` exports, traceability reports, prose summaries, diagrams) must reference documented components by their **canonical full name** as registered in `docs/components/README.md` (Column 2 — `Component`) — never an abbreviation, alias, or truncation, even when the source `docs/**/*.md` files use a shortened form inline. This closes a gap between the existing Asset Fidelity Rule + "no invention" policy (which bind structured asset values like endpoints, schemas, env vars) and prose / table / citation surfaces where component names were free-form. Concretely: an analysis finding that called the component `omn-bs` instead of `omn-bs-top-ups-and-bundles` no longer grepped back to the component file, the index, or any downstream artifact — that traceability break is what this release fixes.

**Scope of this change** (26 files):

- **All 19 agent files** under `agents/**/*.md` carry a `## Component Naming Fidelity` block. 15 files (10 validators + `architecture-explorer`, `handoff-context-builder`, `handoff-generator`, `peer-review-category-agent`, `principle-quality-reviewer`) get the block at the top, immediately after frontmatter and the H1. The 4 files with pre-existing fidelity rules (`compliance-generator.md`, `docs-export-generator.md`, `handoff-asset-generator.md`, `architecture-analysis-agent.md`) get the block placed adjacent to the existing rule with an explicit complementarity note — neither replacing nor duplicating the original (Asset Fidelity Rule, Documentation Fidelity, Template Preservation Mandate, Documentation Fidelity Rule are preserved verbatim). The `handoff-asset-generator` placement is in pre-bundle prose so the bundler does not regenerate over it.
- **3 templates** carry the rule as authoring-time guidance: `skills/architecture-analysis/templates/analysis-report-skeleton.md` (HTML comment at file head — does not render in the analysis report), `skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md` (HTML comment block alongside the existing managed-block markers; **TEMPLATE_VERSION bumped 2.0.0 → 2.1.0** with a paired SHA-tripwire fixture update in `manifest.test.ts` — existing consumer-side handoffs at v2.0.0 in `handoffs/.manifest.json` will be re-generated on the next `architecture-dev-handoff` run, intentional so the rule actually propagates through pre-existing artifacts), `skills/architecture-peer-review/PLAYGROUND_TEMPLATE.md` (markdown subsection — this file is authoring documentation, not a literal output template).
- **Plugin CLAUDE.md** gains a new `### Component Naming Fidelity` subsection between `### Component Index Policy` and `### Dev Handoff Scope`.
- **`scripts/setup-claude-md.ts` `blockBody`** gains a new `### Component naming — always use the canonical full name` subsection inside the managed block written into every consumer project's `CLAUDE.md`. Re-running `/sa-skills:setup` on existing projects propagates the rule transparently — the helper replaces only the content between the `sa-skills:architecture-pointer` markers, idempotent.

**Why a separate rule** — the existing fidelity guarantees (Asset Fidelity Rule at `CLAUDE.md:177`, EXACT MATCH at `skills/architecture-dev-handoff/SKILL.md:106`, Documentation Fidelity at `agents/generators/docs-export-generator.md:14`, "Never localize component names" at `agents/generators/handoff-asset-generator.md:89`) all bind *structured asset values*. They do not directly govern *prose / table / citation references* in reports and reviews — which is precisely where short-form component names were leaking into output. The new rule is complementary, not redundant; the agent-level blocks reference this complementarity explicitly so a future reader does not delete one assuming it duplicates the other.

**Verification** (post-install, all green): `find agents -name '*.md' -print0 | xargs -0 grep -L "Component Naming Fidelity"` returns empty (all 19 covered); the 4 fidelity-rich agents have exactly one `## Component Naming Fidelity` heading each (no accidental duplication); `bun run typecheck` clean; `bun test` reports 225/225 pass (added 0, modified 1 — the HANDOFF_TEMPLATE SHA-tripwire fixture, paired with the TEMPLATE_VERSION bump per the test's documented contract). No source code changed; no permission changes; no marketplace re-registration required.

### v3.23.0 (Previous Release) ✅
**feat(architecture-docs): introduce Phase Catalog mode as the default authoring pattern for `docs/04-data-flow-patterns.md` — multi-UC architectures now compose phases rather than duplicating flows; full propagation through Workflow 7 diagram gate, peer-review SECTIONS-05, dev-handoff payload schema, and validations**

The previous Section 6 template (`ARCHITECTURE_DOCUMENTATION_GUIDE.md` lines 1572–1598) modelled data flow as a flat list of H3 flow subsections, each with `Flow Steps` / `Performance` / `Error Handling` and one `sequenceDiagram`. That shape works for a single-UC CRUD service but breaks down hard the moment an architecture has multiple use cases that share components: every UC re-runs payment / persistence / notification, the differences between UCs disappear into prose, and every change to a shared step (e.g. retry policy) has to be hand-mirrored across N flows. v3.23.0 adopts the richer **Phase Catalog mode** as the default — modelled directly on the `top-ups-and-bundles/docs/04-data-flow-patterns.md` reference, where 8 phases compose 3 use cases plus a compensation flow and the per-phase view stays the entry point with full end-to-end wire sequences deferred to the bottom of the document.

**The 8-part Phase Catalog structure (Section 6 default)**:

1. EXPLORER_HEADER with phase names, UC IDs, and cross-cutting flow vocabulary in `key_concepts`
2. Intro blockquote + "How to read this file" navigation (Phase Catalog ↔ Wire Sequences entry-point split)
3. **Flow Inventory** table — `Flow | Trigger | Use Case | Latency Target`
4. **Phase Catalog** — phase summary table + one H4 per phase with `Purpose` / `Latency budget (p95)` / `Side effects` + a scoped `sequenceDiagram` mini-flow (per phase, not per flow)
5. **Use Case Resolutions** — phase × UC composition matrix (cell vocab `✓ / skipped / reused / n/a / UC-specific note`) + per-UC narrative deltas
6. **Cross-cutting flow concerns** — `### Idempotency` + `### Latency budget breakdown` (per-hop table) + `### Failure classification` (one row per phase × failure mode)
7. **End-to-End Wire Sequences** — full canonical Mermaid `sequenceDiagram` per UC, deliberately last
8. **Validation** — 6-item self-check checklist

**Mode selection rule**: Phase Catalog mode is default for any architecture with **2+ use cases** that share components OR a single UC with **≥4 distinguishable phases**. Single-Flow mode (the legacy template) is preserved as a fallback for trivially-simple systems with 1 UC and ≤3 short linear flows. The mode is auto-detected by grepping the doc for the literal H2 strings `## Phase Catalog`, `## Flow Inventory`, `## Use Case Resolutions` — any two present = Phase Catalog mode.

**Why Phase Catalog mode is the default**: when multiple UCs share phases, Single-Flow mode forces every UC's flow to duplicate the shared steps and the differences between UCs disappear into prose. Phase Catalog mode names each shared step once, then composes UCs as subsets — keeping the differences visible at a glance. The shape scales down (a 2-phase, 1-UC system still reads cleanly under it); Single-Flow mode does not scale up.

**Full propagation through downstream consumers** (so Phase Catalog mode is actually enforced end-to-end, not just suggested in a template):

- **Workflow 7 (Mandatory Diagram Generation)** is now mode-aware. In Phase Catalog mode the gate counts `P` phase mini-flows + `U` full UC wire sequences (UCs that explicitly substitute an out-of-domain narrative clause are excluded from `U`); in Single-Flow mode the legacy "one diagram per H3 flow" rule stands. The `DIAGRAMS_GATE` blocking audit at Step 7.3 enforces both counts.
- **Peer-review `SECTIONS-05`** upgraded from "section has at least one Mermaid diagram" to a structural check: in Phase Catalog mode, the phase × UC matrix must be present AND its phase row count must equal the Phase Catalog summary table's phase row count (silent drift between the two views is the failure mode this pattern is designed to prevent — flagged Major). The `### Latency budget breakdown` and `### Failure classification` tables must exist; failure classification must cover ≥1 row per phase H4.
- **Dev-handoff `Flows` payload extraction** is mode-aware. In Phase Catalog mode, the per-component handoff slices the doc precisely: phase H4s where the component is a `participant` (header + Purpose + Latency budget + Side effects + the phase's `sequenceDiagram`), the matching UC narrative deltas, and the relevant Failure classification rows — explicitly **excluding** End-to-End Wire Sequences from the per-component payload, because inlining a 200-line wire sequence in every component handoff re-introduces exactly the duplication the Phase Catalog pattern eliminates.
- **`VALIDATIONS.md`** gains 10 Phase Catalog structural checks alongside the existing inclusion-criteria block, plus the canonical mode-detection rule (shared with Workflow 7 and SECTIONS-05 so all three agree on what mode the doc is in).

**New reference example**: `skills/architecture-docs/examples/04-data-flow-patterns.example.md` — a synthetic 3-UC e-commerce checkout (UC1 New Order, UC2 Reorder, UC3 Refund composing phases 4 → 5 → 6 in different ways) demonstrating the full 8-part structure end-to-end. Header marks it as a reference example, not generated content. Component / ADR / metric values are illustrative; do not import them.

**Changes:**

- `skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md` — Section 6 rewritten as a two-mode template (Phase Catalog default + Single-Flow fallback) with mode-selection rule and S6-specific EXPLORER_HEADER `key_concepts` vocabulary (phase names, UC IDs, `idempotency`, `dedup`, `compensation`, `out-of-band`, `fire-and-forget`, etc.).
- `skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` — Workflow 7 generation rule (lines 863–868), Step 7.2 menu line (895), and `DIAGRAMS_GATE` audit (923, 928) made mode-aware.
- `skills/architecture-docs/VALIDATIONS.md` — Phase Catalog mode structural checks added; mode-detection rule canonicalised.
- `skills/architecture-peer-review/PEER_REVIEW_CRITERIA.md` — `SECTIONS-05` upgraded to mode-aware structural check; matrix-vs-Phase-Catalog phase-count drift = Major violation.
- `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md` and `SECTION_EXTRACTION_GUIDE.md` — `Flows` and `Async Integrations` extraction rules made mode-aware; End-to-End Wire Sequences explicitly excluded from per-component payloads.
- `agents/generators/handoff-generator.md` and `agents/builders/handoff-context-builder.md` — re-bundled (`bun run bundle:handoff-agent`) to absorb the source changes; sync test passes.
- `skills/architecture-docs/SKILL.md` — Workflow 1 Step 7 note (line 172) rephrased mode-aware with pointer to the new example file.
- `skills/architecture-docs/examples/04-data-flow-patterns.example.md` — new file (~340 lines) demonstrating Phase Catalog mode for a 3-UC system. `examples/README.md` — entry added describing the new example.
- 3 version files (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `package.json`) — bumped to 3.23.0.
- `README.md` — version badge, install verification line, roadmap entry.

**Backwards compatibility**: existing Single-Flow mode docs continue to validate, generate diagrams, and pass peer review unchanged — the legacy template is preserved as a named fallback, not removed. The skill does NOT auto-rewrite an existing Section 6 from Single-Flow into Phase Catalog mode; that would be a structural migration users explicitly invoke. New Section 6 authoring (Workflow 1 Step 5) defaults to Phase Catalog mode unless the project clearly meets the simple-fallback criteria. Test suite: 225/225 passing; typecheck clean.

**Net diff**: ~10 files changed, ~+800 / −60 lines (the bulk in the new example file and the Section 6 template).

---

### v3.22.3 (Previous Release) ✅
**fix(architecture-traceability): apply largest-remainder (Hamilton) rounding to integer-% tables in `TRACEABILITY_REPORT.md` so multi-row percentage breakdowns always sum to exactly 100%**

The Summary table in `TRACEABILITY_REPORT.md` decomposes a single total into Covered / Partial / Not Covered counts, each rendered as an integer percent. Step 5 of `skills/architecture-traceability/SKILL.md` was silent on rounding policy, so the model defaulted to plain `round()` per row — and on a real-world distribution (67 / 6 / 7 of 80 requirements) the row sums became `84 + 8 + 9 = 101%`. The exact percentages are 83.75 / 7.50 / 8.75; "round half away from zero" applied independently per row rounds *two* of three rows up with no global sum constraint, so the table contradicts itself. v3.22.3 fixes this at the spec layer (where the model picks its rounding rule) rather than papering over it in the rendered report.

**Changes:**

- `skills/architecture-traceability/SKILL.md` — Step 5 ("Compute Summary Statistics") gains a mandatory **largest-remainder (Hamilton) method** for any table where multiple integer percentages must sum to 100%. The five-step procedure is spelled out inline: compute exact `pᵢ = 100 × countᵢ / total`, floor to `fᵢ`, track remainders `rᵢ`, deficit `D = 100 − Σ fᵢ`, sort by `rᵢ` descending and add `+1` to the top `D` rows, with a deterministic tie-break (larger `countᵢ` first, then row order Covered → Partial → Not Covered). Single-value cells (per-phase `Coverage` column, per-UC `N/N (X%)` cell, any standalone percentage) are explicitly exempted — `round()` is fine when there is no sum constraint.
- **Generalised to per-UC / per-phase breakdowns** — if the report ever decomposes a single UC, phase, or source into integer percentages across Covered / Partial / Not Covered (e.g., `UC-03 — 73% / 18% / 9%`), the rule applies *per row*, not just to the global Summary. Each such row is its own 100%-budget. This keeps the spec future-proof without requiring a re-edit when the report grows new breakdowns.
- **Self-check checklist before writing the report** — five-item gate covering: global Summary sums to 100%, each per-UC breakdown sums to 100%, each per-phase breakdown sums to 100%, single-value cells exempt, **and** `Covered + Partial + NotCovered == Total` for every breakdown. The last item is intentionally separate from the %-sums-to-100 check: largest-remainder will always produce 100% even if the underlying counts are wrong (e.g., an off-by-one classification bug), so the count assertion catches what the % assertion cannot. The spec is explicit: "Do not paper over a count mismatch by forcing percentages to 100 — that masks a real classification bug."

**Worked example for the bug case (67 / 6 / 7 of 80)**:

| Row | Exact % | Floor | Remainder | +1? | Final |
|-----|---------|-------|-----------|-----|-------|
| Covered | 83.75 | 83 | 0.75 | ✓ | **84** |
| Partial | 7.50 | 7 | 0.50 |   | **7** |
| Not Covered | 8.75 | 8 | 0.75 | ✓ | **9** |
| Sum |   | 98 |   | +2 | **100 ✓** |

Naive `round()` produced `84 + 8 + 9 = 101`. Largest-remainder produces `84 + 7 + 9 = 100`. The corrected Partial row is **7%, not 8%**.

**Backwards compatibility**: pure spec change inside a skill workflow. Existing reports regenerate fresh on each run (the skill's overwrite policy at Step 6), so the next `/skill architecture-traceability` invocation produces a corrected `TRACEABILITY_REPORT.md` automatically. No migration step, no permission change, no hook change. The plain `round()` exemption for single-value cells preserves intuitive integer reads in the per-phase `Coverage` column and per-UC `N/N (X%)` cells — those have no cross-row sum constraint.

**No code changes.** Pure content edit inside one Markdown file; no logic, no schema, no hook, no permission change.

**Files**:

- `skills/architecture-traceability/SKILL.md` — net +25 lines inside Step 5 (rounding rule + per-UC/per-phase generalisation + 5-item self-check checklist).
- 3 version files (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `package.json`).
- `README.md` — version badge, install verification line, roadmap entry.

**Net diff**: 5 files changed, ~+60 / −5 lines.

---

### v3.22.2 (Previous Release) ✅
**feat(setup): plan-mode-first rule for architecture-doc updates in the consumer-project CLAUDE.md managed block; carve-out for `architecture-docs` update intent**

The `/setup` skill (Step 5 → `scripts/setup-claude-md.ts`) injects a marker-delimited "sa-skills architecture pointer" block into every consumer project's `CLAUDE.md`. Until v3.22.2 that block told Claude *what* the architecture sources are and *how* to read them through `architecture-explorer`, but said nothing about *when* to slow down before changing them. In practice, this meant Claude could open `Edit` on `ARCHITECTURE.md`, a `docs/NN-*.md` section file, a `docs/components/**/*.md` descriptor, or an `adr/**/*.md` decision record on the first turn — without first surfacing the proposed change for user approval. Architecture edits are rarely trivial: a single change can ripple through component versions, ADRs, compliance contracts, downstream handoffs, and diagrams. The plugin's skill workflows already encode plan-style approval internally, but **direct edits** outside a skill workflow had no enforcement layer at all. v3.22.2 closes that gap by inserting a new `### Architecture doc updates → plan first` subsection into the managed block, ahead of the existing `### Routing doc reads through architecture-explorer` section.

**Changes:**

- `scripts/setup-claude-md.ts` — `blockBody` template literal gains a new sibling `###` subsection after the sources-list paragraph and before the explorer-routing section. The new section sets one rule and three exemptions:
  - **Rule** — before any direct edit to `ARCHITECTURE.md`, `docs/**/*.md`, `docs/components/**/*.md`, `adr/**/*.md`, or `handoffs/**/*.md`, Claude must enter plan mode and present the proposed change via `ExitPlanMode` for user approval. The rule is intentionally absolute — no "trivial" carve-out for typo fixes, metric updates, section additions, ADR edits, or component-descriptor changes — because the skill workflows treat all of them as semver-eligible inputs.
  - **Exemption 1: skill-routed invocations** — when the user types a phrase from the project's CLAUDE.md trigger table (`release my architecture`, `review my architecture`, `generate compliance contracts`, …), Claude invokes the matching `sa-skills:architecture-*` skill directly. The skill's own workflow handles plan / scope / approval internally; wrapping the invocation in plan mode is redundant.
    - **Exception within the exemption** — invoking `sa-skills:architecture-docs` with **update** intent (modifying existing content in `ARCHITECTURE.md`, `docs/**/*.md`, or `docs/components/**/*.md`) still requires plan mode first. Updates ripple through downstream artifacts in ways the skill cannot fully scope on its own; the user must see the proposed change set before the skill runs. Initial creation (Workflow 1 from scratch), diagram regeneration (Workflow 8), multi-file migration (Workflow 9), and release lifecycle (Workflow 10) are *not* update intent and remain exempt.
  - **Exemption 2: read-only Q&A and discovery** — answering questions about the architecture, running `architecture-explorer` in findings mode, or quoting from existing docs requires no plan.
  - **Exemption 3: files outside the architecture surface** — code, tests, configs, and other non-architecture files follow normal plan-mode rules, not this one.

**Behavior shape**: idempotent and unversioned-from-the-helper's-perspective — `setup-claude-md.ts` already replaces the entire managed block in place on every run, so existing consumer projects pick up the new section the next time they run `/setup`. No migration step, no marker change, no permission change, no hook change, no `.gitignore` change required.

**Backwards compatibility**: pure documentation addition inside an existing managed block. The exemption clauses are explicit and verbose specifically to preserve the project root CLAUDE.md's existing rule that recognized skill phrases override plan-mode's default "Explore → Plan → ExitPlanMode" flow. Without those clauses, the new rule would silently contradict the trigger table for every phrase except `update architecture`-style edits.

**No code changes.** Pure content edit inside one TypeScript template literal; no logic, no schema, no hook, no permission change. `bun run typecheck` clean. Verified end-to-end against a scratch project: fresh run → `Created` with the new heading present, re-run → `Unchanged`, hand-edited content above the markers preserved byte-for-byte.

**Files**:

- `scripts/setup-claude-md.ts` — net +13 lines (the new `### Architecture doc updates → plan first` subsection inside `blockBody`).
- 3 version files (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `package.json`).

**Net diff**: 4 files changed, ~+16 / −3 lines.

---

### v3.22.1 (Previous Release) ✅
**feat(subagent-contracts): output-contract hardening across `architecture-explorer` + 10 compliance validators; orchestrator-side malformed-output detection with single retry before degradation; new informational `caller` parameter on `architecture-explorer`**

In a v3.22.0 field run of the Development compliance contract, `sa-skills:architecture-explorer` (Haiku-tier, findings mode) returned synthesis prose for the `key_data_points[]` query instead of the structured `EXPLORE_FINDINGS:` YAML block the orchestrator expects. The compliance orchestrator's existing degraded-mode rule (`status: FAILED` or empty `files[]`) did not detect this case — the agent's reply simply lacked the `EXPLORE_FINDINGS:` token entirely — so the orchestrator silently dropped the findings block from the generator prompt and fell back to `phase3.required_files[]` only. The contract still generated correctly, but the per-contract findings fan-out (introduced in v3.16.0 to pre-locate evidence at line+heading granularity) was effectively bypassed and the user never saw a clear signal about the degradation. v3.22.1 hardens this contract at three layers — the agent definitions, the orchestrators, and the spawn-prompt templates — so that prose drift either does not happen, is caught and retried once, or is at least surfaced in run telemetry instead of silently degraded.

**Changes:**

- `agents/builders/architecture-explorer.md` (3.3.0 → 3.5.0) — three additions. (1) New `## Output contract` section after Mission with five hard rules ("first character of output is `E`", "exactly one ` ```yaml … ``` ` fence", "no prose outside the fence except the optional headers-missing or no-matches note", "no summary / conclusion / answer section anywhere") and a four-item self-check the agent runs before its final assistant turn. The contract explicitly acknowledges **two consumer types**: orchestrators (compliance / dev-handoff / analysis, string-scanning) AND free-form architecture Q&A (Claude in the user's main session, LLM-read). Both consumer types require YAML — the prose synthesis for Q&A happens in the *caller*, not the explorer. (2) Per-mode self-check gates appended to Step M8 (manifest emit, now Step M9) and Step F9 (findings emit, now Step F10) listing common drift patterns with exact wording (`Here is the manifest…` preamble, `In summary the project covers…` trailer, paraphrased EXPLORER_HEADER fields, paraphrased excerpts outside the `excerpt:` block scalar, bullet-list summaries outside the YAML) so a haiku can pattern-match drift back to a fix. (3) Anti-pattern #2 strengthened from "Don't answer the question" to name the parsing-failure consequence: "Writing a prose preamble … causes orchestrators (which extract via literal string scan, not LLM read) to reject the output and silently degrade to a hardcoded fallback — the user gets a worse result and your run is wasted." (4) New `caller` input parameter — **optional, recommended, four documented values** (`orchestrator-compliance`, `orchestrator-dev-handoff`, `orchestrator-analysis`, `qa`); **informational only — not a mode switch**: the output contract is identical for every value. Acts as a third prompt-engineering anchor (alongside the Output contract section and anti-pattern #2) that all converge on the same rule. When absent, the agent treats the call as ad-hoc Q&A — contract unchanged.
- `agents/validators/*.md` (10 files: business-continuity / cloud / data-ai / development / enterprise / integration / platform / process / security / sre) — replaced the trailing one-liner `**CRITICAL**: Return the VALIDATION_RESULT block as the LAST thing in your response. The compliance agent extracts it by finding the VALIDATION_RESULT: marker.` with a full `## Output contract` section: five hard rules ("token at start of its own line", "no prose after the block", "no markdown heading like `## Result` or quote prefix", "no extra / renamed fields, no reordering that breaks YAML", "free text stays inside `evidence:` / `deviations:` / `recommendations:`"), a five-item self-check (token presence at start of line, last line in block, numeric counts sum to `total_items`, status derivation is correct (`PASS` only when `fail == 0`), no fenced-code or quote wrapping), and a named consequence ("the generator sets `validation_status: PENDING` and stamps every validation-dependent field in the published contract as Unknown — your work is wasted"). Identical text across all 10 validators to keep the contract uniform across domains.
- `skills/architecture-compliance/SKILL.md` — Step 3.2.5 (per-contract explorer findings fan-out): new "Malformed-output detection + retry-once" rule. After each explorer reply, the orchestrator scans for the literal `EXPLORE_FINDINGS:` line; if absent, dispatches **one** fresh `Task()` retry with a corrective preamble before falling through to the existing degraded-mode rule. Updated degraded-mode rule now records `explorer_status: <OK|FAILED|MALFORMED>` for the run summary so users see which contracts went degraded and why. Step 3.3 (validator dispatch): same retry-once-on-malformed pattern for `VALIDATION_RESULT:`; on persistent failure, marks the contract `validation_status: PENDING` (existing fallback) and continues with the next batch without aborting the orchestration. Step 3.2.5 spawn template now passes `caller: orchestrator-compliance` to the explorer.
- `skills/architecture-dev-handoff/SKILL.md` — Step 3.4a (per-component explorer findings fan-out): same malformed-output retry-once rule before falling through to the existing per-component v3.13.0 legacy in-builder grep slicing fallback. Spawn template now passes `caller: orchestrator-dev-handoff`.
- `skills/architecture-analysis/SKILL.md` — Step 2.5 (per-analysis explorer findings fan-out): same malformed-output retry-once rule before collapsing to the analysis's base FILES table. Spawn template now passes `caller: orchestrator-analysis`.

**Cost shape**: the malformed-output retry only fires on the small population of explorer / validator calls that drift into prose. Steady-state cost is unchanged. Worst case (every call drifts) the orchestrator does at most one extra Haiku call per fan-out unit before degrading — bounded and predictable.

**Backwards compatibility**: all changes are pure prompt-engineering additions. The `caller` parameter is optional with a safe default (treated as `qa` when absent). Existing direct callers of `sa-skills:architecture-explorer` keep working without change. No breaking changes to the explorer's output schema or the validator output schemas.

**No code changes.** Pure agent definition / SKILL.md edits; no TypeScript / hook / template / config changes. `bun run typecheck` clean.

**Files**:

- `agents/builders/architecture-explorer.md` — net +96 lines (Output contract + Step M9 / F10 self-checks + `caller` parameter docs + footer changelog).
- `agents/validators/*.md` (10 files) — net +22 lines each, +220 total (Output contract block replacing the one-line CRITICAL note).
- `skills/architecture-compliance/SKILL.md` — net +18 lines (Step 3.2.5 retry-once rule + Step 3.3 retry-once rule + `caller:` field in spawn template).
- `skills/architecture-dev-handoff/SKILL.md` — net +10 lines (Step 3.4a retry-once rule + `caller:` field in spawn template).
- `skills/architecture-analysis/SKILL.md` — net +10 lines (Step 2.5 retry-once rule + `caller:` field in spawn template).
- 3 version files (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `package.json`).

**Net diff**: 18 files changed, ~+360 / −16 lines.

---

### v3.22.0 (Previous Release) ✅
**feat(architecture-compliance): remove outdated 26-item Stack Validation Checklist; keep EOL check as sole external validation; tighten development `key_data_points[]`**

The Development compliance contract's "Stack Validation Checklist" (`LADES1.6`) was a 26-item gate that compared the documented stack against hardcoded approved-tech lists baked into `agents/validators/development-validator.md` and a manual `STACK_VALIDATION_CHECKLIST.md` file ("Java 11/17 LTS", "Spring Boot 2.7+", "Angular 12+", "Approved library catalog", "Naming conventions", and so on). Those lists drifted from organizational reality and could not be queried live — every run produced noisy FAIL/UNKNOWN findings that eroded trust in the contract. The EOL portion of the validator (WebSearch lookups against `endoflife.date` for every documented technology+version pair) was always the highest-value signal: it is a live, objective source, and an EOL technology is unambiguously a problem regardless of whether the org's catalog has been updated. v3.22.0 removes the stale 26-item checklist and promotes EOL to be the validator's sole external check until a new mechanism (MCP server, organizational catalog API, or registry) can be integrated. Stack-shape validation will return when that live mechanism arrives.

**Changes:**

- `agents/validators/development-validator.md` — full rewrite. Dropped Phase 2 (the 26-item DEV-01…DEV-26 list with hardcoded approved-tech rules) and the "Phase 1 / Phase 2" two-phase framing. The validator now performs a single EOL-only pass: extract every technology+version pair from `docs/06-technology-stack.md`, run a WebSearch lookup against `endoflife.date` for each, and emit one `DEV-EOL-{N}` row per pair with PASS (>6 months remaining), FAIL (EOL or within the 6-month safety period), or UNKNOWN (lookup inconclusive). WebSearch tool retained; the `endoflife.date` priority guidance and the "do not use context7 for EOL" warning remain. Output `VALIDATION_RESULT` schema updated: dynamic `total_items`, `eol_checked` count, FAIL items populate `deviations`, UNKNOWN items populate `recommendations`. Net: −362 lines on the heaviest file in the diff.
- `agents/configs/development.json` — `key_data_points[]` tightened from 7 long parenthetical entries (`"Technology versions (for EOL/lifecycle tracking)"`, `"Code coverage (minimum 80% for critical paths)"`, etc.) to 8 short term-of-art entries: `Technology stack, EOL, Code coverage, Technical debt, Dependency vulnerabilities, Code review, CI/CD pipeline, ADR exceptions`. Mirrors the SRE config's `SLO, SLI, Error Budget, MTTR, MTBF, Runbook coverage, Monitoring tools, Incident response` pattern. The orchestrator joins these with comma to form the explorer's `contract_query`; concrete grep-friendly terms make Haiku confident enough to emit the strict `EXPLORE_FINDINGS` YAML instead of drifting into prose-format output (which would force the orchestrator into degraded mode and skip the findings block in the generator prompt).
- `skills/architecture-compliance/STACK_VALIDATION_CHECKLIST.md` — **deleted**. Git history preserves it for reference when a live mechanism is implemented; keeping it in-tree alongside its removal would create a misleading half-deprecated artifact.
- `skills/architecture-compliance/templates/cc-004-development-architecture.template.md` — replaced the `**Stack Validation**: [VALIDATION_SUMMARY] (**MANDATORY**...)` Compliance-Summary line with `**EOL Validation**: ...`. Replaced "External Validation Required: ⚠️ MANDATORY - Stack Validation Checklist (STACK_VALIDATION_CHECKLIST.md)..." with the EOL equivalent. Stripped 11 "Cross-reference with Stack Validation Checklist Section X" / "Verify against Stack Validation Checklist" notes from LADES1 sub-sections (Backend / Frontend / Container / Database / API / CI/CD / IaC / Naming / Approved Libraries). Removed `STACK_VALIDATION_CHECKLIST.md` references from the LADES1.6 gap row, the auto-approve score breakdown, the priority order, and the change-history block. Added a v2.1 change-history entry documenting the removal. Updated the "Stack Validation" definition entry in A.1 to point at the new `**EOL Validation**` flow.
- `skills/architecture-compliance/SKILL.md` — domain blurb (line 507) `Technology stack validation, code coverage, technical debt management` → `Technology EOL/lifecycle tracking, code coverage, technical debt management`. Validator-orchestration note (line 825) updated to reference EOL only.
- `skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md` — Contract 5 description (line 398), the `LADES1.6 Stack Validation Checklist` summary, the "Example Guidelines" / "Automatic Stack Validation" callout, and the entire 480-line "Edge Case Handling for Automatic Stack Validation" section (Edge Cases 1–7: Backend-Only, Full-Stack, Polyglot Backend, Section 8 Missing, Partial Section 8, Deprecated Versions, Unapproved Technology) replaced with a single short "Edge Case Handling for Automatic EOL Validation" table covering the 5 cases the EOL-only validator actually handles.
- `skills/architecture-compliance/SECTION_MAPPING_GUIDE.md` — Contract 5 block (lines 1065–1537, 473 lines) shrunk to a 50-line section. Removed the Step 3.5 "Automatic Stack Validation" sub-section, the `LADES1.6: Technology Stack Validation` example output, the `extract_development_architecture` / `perform_stack_validation` pseudo-code, and the legacy 4-scenario "Missing Data Handling" block. Replaced with concise "Special Feature — EOL Validation" wording and a 4-row "Missing Data Handling" table mirroring how the EOL validator actually behaves (corpus missing → FAIL; tech without version → skip; no conclusive EOL → UNKNOWN; WebSearch unavailable → degrade to UNKNOWN-with-PASS).
- `skills/architecture-compliance/validation/README.md`, `skills/architecture-compliance/shared/README.md`, `skills/architecture-compliance/shared/MIGRATION_GUIDE.md` — strip / rewrite the `LADES1.6 (Stack Validation Checklist) is a blocking requirement` reasoning, the `STACK_VALIDATION_CHECKLIST.md` reference list, the "Migration Strategy" entry, and the "Cannot perform automatic stack validation" edge case row. Replaced with EOL-equivalents.
- `docs/QUICK_START.md`, `docs/TROUBLESHOOTING.md`, `docs/WORKFLOW_GUIDE.md` — replace user-facing references: "automatic 26-item stack validation" → "automatic EOL validation against endoflife.date"; "Check stack validation here" → "Check EOL validation here"; "Stack validation shows all UNKNOWN" / "Stack validation fails with FAIL status" troubleshooting Q&As rewritten to the EOL flow; the long simulated stack-validation runtime trace in WORKFLOW_GUIDE.md replaced with a corresponding EOL-validator trace; the LADES1.6 example contract output replaced with the new `DEV-EOL-{N}` table.

**Asset fidelity / no-invention guarantees**: Architecture-derived data still flows through the existing `phase3.required_files[]` floor (5 files for Development: `02-architecture-principles.md`, `components/README.md`, `06-technology-stack.md`, `adr/README.md`, `09-operational-considerations.md`). The orchestrator's degraded-mode fallback path (when the explorer cannot emit `EXPLORE_FINDINGS`) is unchanged. Validators continue to ignore the explorer (per the v3.16.0 cleanup) so the EOL check is unaffected by explorer behavior.

**No code changes.** Pure prompt / template / docs / config edits; no agent TypeScript / hook / utility changes. `bun run typecheck` clean, `bun run build` clean, `bun test` 392 / 392 pass.

**Files**:

- `agents/validators/development-validator.md` — net −362 lines (Phase 2 + 26 items + two-phase framing removed; new EOL-only output schema and edge cases).
- `skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md` — net −512 lines (Edge Case Handling section + Stack Validation prose).
- `skills/architecture-compliance/SECTION_MAPPING_GUIDE.md` — net −455 lines (Contract 5 block trimmed).
- `skills/architecture-compliance/templates/cc-004-development-architecture.template.md` — net −56 lines (checklist references stripped, EOL gate added, change-history bumped to 2.1).
- `docs/WORKFLOW_GUIDE.md` — net −109 lines (long simulated trace + LADES1.6 example replaced).
- `skills/architecture-compliance/STACK_VALIDATION_CHECKLIST.md` — deleted (67 lines).
- 8 other secondary edits: `agents/configs/development.json`, `skills/architecture-compliance/SKILL.md`, `skills/architecture-compliance/validation/README.md`, `skills/architecture-compliance/shared/README.md`, `skills/architecture-compliance/shared/MIGRATION_GUIDE.md`, `docs/QUICK_START.md`, `docs/TROUBLESHOOTING.md`, plus the 3 version files (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `package.json`).

**Net diff**: 17 files changed (16 modified + 1 deleted), +220 / −1393 lines.

---

### v3.21.10 (Previous Release) ✅
**feat(architecture-docs): bidirectional Connection Naming Rule scope enforcement — sequence diagrams explicitly exempt; reviewers / audit gates skip CNR checks on `sequenceDiagram` blocks**

v3.21.9 introduced the canonical Connection Naming Rule (`<PROTOCOL>/<STYLE> [Action Type]`) for the 4th `Rel()` parameter at C4 L1, C4 L2, and Diagram 4. The rule was scoped correctly in the prose (it talked about `Rel()` and `graph TB` arrow labels), but the **scope itself was not enforced as a first-class section** of the rule — a future reader could plausibly try to apply it to sequence-diagram messages too, since `sequenceDiagram` blocks also live in `docs/04-data-flow-patterns.md` and the v3.21.9 prose did not say "stop". Sequence-diagram messages (`A->>B: ...`, `A-->>B: ...`, `A-)B: ...`) are deliberately **free prose** describing what flows step-by-step — appending `[Data]` / `[Event]` / `[Internal]` to a sequence-diagram message degrades the flow narrative without adding signal. v3.21.10 adds explicit bidirectional scope enforcement: the rule **MUST** be applied to L1 / L2 / Diagram 4 (under-application is a violation), and the rule **MUST NOT** be applied to sequence-diagram message labels (over-application is also a violation). Audit gates and reviewers now have a deterministic instruction to skip Connection-Naming-Rule checks when the diagram's first line is `sequenceDiagram`.

**Changes:**

- `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` — **new `#### Scope (ENFORCED — read before applying)` subsection** inside the Connection Naming Rule (between the rule statement and the Action-Type Vocabulary table) listing exactly what the rule applies to (Diagram 2 — C4 L1 `C4Context`, Diagram 3 — C4 L2 `C4Container`, Diagram 4 — Detailed View `graph TB` arrow labels) and what it explicitly does NOT apply to (Diagram 1 ASCII Logical View — labels are free prose; **Sequence Diagrams in `docs/04-data-flow-patterns.md` — free prose**, do NOT append `[Action Type]` tags, do NOT enforce `<PROTOCOL>/<STYLE>` casing, do NOT reject a label because it lacks the normal form; element-metadata strings inside `Container("name", "technology", "description")` are not connections). Includes a worked counter-example showing that a sequence-diagram message reading `Frontend->>BFF: GET /orders` is correct as-is and must NOT be rewritten to `Frontend->>BFF: GET /orders [Data]` or `Frontend->>BFF: HTTPS/JSON [Data]`. Sequence Diagrams (Sequence Diagrams) DO block at line ~787 gains a new "write message labels as free prose" instruction with three flow-narrative examples (`Frontend->>BFF: GET /orders`, `BFF->>OrderSvc: CreateOrder(items, customerId)`, `OrderSvc-)EventBus: OrderPlaced event`); DON'T block gains an explicit `Do NOT apply the Connection Naming Rule to sequence-diagram message labels` directive that calls out over-application as a rule violation in the opposite direction and instructs reviewers and audit gates to **skip Connection-Naming-Rule checks entirely** when the diagram's first line is `sequenceDiagram`.
- `skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md` — Section 5 cross-reference block (line ~292) extended with a third paragraph stating "Sequence diagrams are exempt from the Connection Naming Rule" and pointing back to the canonical Scope subsection. Reinforces the same audit-gate instruction.

**No code changes.** Pure scope-clarification edits; no agent / TypeScript / hook / template / config changes. Existing `bun run typecheck` and `bun test` (392 pass / 0 fail) remain green.

**Files**:

- `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` — net +28 lines (Scope subsection + sequence-diagram Do/Don't extension).
- `skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md` — net +2 lines (Section 5 cross-reference block third paragraph).

---

### v3.21.9 (Previous Release) ✅
**feat(architecture-docs): canonical Connection Naming Rule for C4 L1 + L2 — `<PROTOCOL>/<STYLE> [Action Type]` normal form, closed action vocabulary (10 entries), via/topic moved to description**

The 4th `Rel()` parameter (the "protocol" string) had no canonical normal form across this repo. Examples were inconsistent — `"REST/HTTPS"`, `"JDBC"`, `"Kafka topic: order-events"`, `"HTTPS via Kong"`, `"Kafka async"` — all valid Mermaid C4 input but unparseable by readers and tooling that grep over diagrams (notably the IcePanel importer at `skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md`, which records the field verbatim into `modelConnections.name`). v3.21.7's Infrastructure-as-via Rule had also packed `via Kong` / `Kafka topic: order-events (async)` into the same field, mixing transport spec with transit context. v3.21.9 settles the field: the 4th parameter is now a strict normal form `<PROTOCOL>/<STYLE> [Action Type]`; via-hop, topic / queue name, and sync/async flag move to the **3rd parameter (description)** in `(via Kong)` / `(Kafka topic: orders, async)` form. Action type is a **closed vocabulary of 10 tags** — `[Data]` (cross-trust-boundary business data), `[Internal]` (service-to-service), `[Event]` (async pub/sub), `[Auth]` (authn/authz/token validation), `[Cache]` (Redis/Memcached I/O), `[Stream]` (WebSocket / SSE / gRPC streaming), `[Query]` (DB/search read), `[Write]` (DB/search write — distinguish from `[Query]` only when CQRS), `[Storage]` (S3/GCS/Azure Blob), `[Telemetry]` (OTLP/Prometheus/Jaeger). Anything outside the closed set is rejected by the rule.

**Changes:**

- `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` — **new canonical `### Connection Naming Rule (L1 + L2)` section** between the Infrastructure-as-via Rule and Color Conventions, with the rule statement, the 10-entry Action-Type Vocabulary table, the Protocol / Style Common Pairings table (12 protocols × common styles, ~95% of architecture diagrams), 11 worked examples spanning all 10 action types, an explicit Diagram-4 / `graph TB` form (`SVC_A -- "HTTPS/JSON [Data]" --> SVC_B`), and an anti-patterns block listing exactly what the rule rejects (`"REST/HTTPS"` wrong order, `"Kafka async"` missing style+action, `"HTTPS via Kong"` via-in-protocol, `"Kafka topic: X"` topic-in-protocol, bare `"HTTPS"`, lowercase casing). Rule 5 of Diagram 3 rewritten from `Use the 4th parameter of Rel() — HTTPS, gRPC, Kafka, JDBC, etc.` to a strict-form mandate plus a Rule 6 update specifying that sync/async, via-hop, topic/queue context lives in the 3rd parameter (description). Diagram 2 (C4 L1) template updated — the placeholder `Rel(...)` calls show the new form. Diagram 3 (C4 L2) template rewritten — every `Rel()` 4th parameter follows the normal form, every 3rd parameter carries via/topic context. L1 + L2 Infrastructure-as-via Rule example tables (sync via gateway, async via topic, async via queue, multi-hop transit, pub/sub fan-out) every example moved to description+protocol split. C4 Do/Don't list (line ~744) extended — Do bullet specifies the normal form mandate and rejection criteria; Do bullet for Rel() description specifies via/topic encoding; new Don't bullets reject via/topic in 4th parameter and inventing new action tags. Color Conventions table footnote on `ContainerQueue()` reinforces exception-only use. Duplicate `### Color Conventions` heading (artifact from earlier edits) cleaned up.
- `skills/architecture-docs/references/META-TO-C4-TRANSLATION.md` — C2 Translation Rules table API Gateway / Message broker rows updated to specify description vs. protocol split with canonical examples (`"HTTPS/JSON [Data]"`, `"TLS/AVRO [Event]"`). C2 Grouping Convention bullet list aligned. Example C2 Elements block rewritten end-to-end: every `[HTTPS via Kong]`, `[REST/HTTPS]`, `[gRPC]`, `[JDBC]`, `[MQ/JMS]` converted to em-dash trailing canonical normal form (`HTTPS/JSON [Data]`, `HTTPS/REST [Internal]`, `gRPC/PROTOBUF [Internal]`, `JDBC/SQL [Write]`, `MQ/JMS/XML [Internal]`); via-hop and Kafka topic context moved to description. Both C3 examples (Layer 3 saga orchestrator, Layer 5 BIAN service domain) rewritten the same way. Section 6 Pattern Translations (SaaS Integration, Transversal Services, BIAN SD Core Banking call) rewritten. Quick Reference Card "API Gateway" and "Event Bus (Kafka)" rows updated to show description+protocol split.
- `skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md` — What to Show table API Gateway / Message broker rows updated. Notation Conventions block rewritten — Protocol on arrows now specifies the canonical normal form, via annotation now in 3rd parameter, topic / queue annotation now in 3rd parameter. C2 Grouping Convention aligned. Example C2 Elements block rewritten — Web App calls via Kong on description, broker collapses on description, every `Rel()` 4th parameter follows normal form. C3 example (lines ~170-191) rewritten. **All 5 Pattern-Specific C4 Translations rewritten** — 5.1 API Gateway + BFF (kept BFFs as nodes, gateway collapsed), 5.2 Event-Driven Choreography (broker collapses, every producer-consumer pair gets `TLS/AVRO [Event]` on protocol with topic in description), 5.3 Saga Orchestration, 5.4 CQRS + Event Sourcing (with `[Write]` / `[Query]` / `[Event]` distinguished), 5.5 Database per Service, 5.6 Service Mesh (already-anti-pattern wording preserved), 5.7 External SaaS Integration (Stripe / SendGrid / Twilio with `[Data]`). Visual Conventions Arrow Conventions table replaced with a 10-row table covering every action type. Quick Reference Card Arrow Labels block rewritten with description+protocol split per kind.
- `skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md` — "What IS a Separate Container?" table Kafka and API Gateway rows updated to show description+protocol split with canonical examples. C2 What to Show table aligned. C2 Rules item 4 rewritten from `SQL/JDBC, Redis Protocol, REST/HTTPS, AMQP` to `JDBC/SQL [Write]`, `TCP/RESP [Cache]`, `HTTPS/REST [Internal]`, `AMQP/JSON [Event]`. Both Variant-Specific C3 ASCII boxes (DDD 4-Layer, Hexagonal Architecture) updated — the right-hand arrows that previously showed `Kafka topic: orders (async)` as label now show `TLS/AVRO [Event]` as protocol with description annotation in parens. Domain Events block rewritten — `--[Kafka topic: order-events (async)]-->` becomes `-- "TLS/AVRO [Event]" -->` with description / protocol slots called out. Quick Reference N-Layer → C2 table updated. Arrow-label conventions block (lines ~430-440) replaced — listing 10 canonical 4th-parameter forms (one per action type) plus a description-parameter contract.
- `skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md` — C2 What to Show table Event Bus / API Gateway rows updated to description+protocol split. Non-BIAN-container labels block — the v3.21.7-added `Rel()` examples (Settlement events, Account inquiry) rewritten to put topic / via context in description and `"TLS/AVRO [Event]"` / `"HTTPS/JSON [Data]"` in protocol.
- `skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md` — C2 Deployment Variants 1, 2, 3, 4, 5 every example rewritten. Pattern Translations 5.1 Authentication Flow (with `[Auth]` action), 5.2 File Upload (with `[Storage]`), 5.3 Background Jobs, 5.4 Caching (with `[Cache]` / `[Query]`), 5.5 External API Integration all rewritten. Anti-Pattern fix wording aligned (`HTTPS/JSON [Data]` instead of bare `REST/HTTPS`). Microservices-comparison parenthetical updated.
- `skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md` — Section 5 cross-reference block extended with a paragraph stating that the 4th `Rel()` parameter at L1 / L2 follows the canonical normal form per `DIAGRAM-GENERATION-GUIDE.md` → "Connection Naming Rule (L1 + L2)", and that Diagram 4 (`graph TB` below) follows the same normal form on its arrow labels (with two `graph TB` examples).
- `skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md` — `modelConnections.name` field example replaced from `"Protocol / Description" # e.g. "REST/HTTPS", "Kafka async"` to the canonical `<PROTOCOL>/<STYLE> [Action]` form with examples drawn from the rule. Source File → YAML Mapping table "Connection protocol" / "Connection description" rows annotated with cross-reference to the Connection Naming Rule and the description-parameter contract.
- `skills/architecture-icepanel-sync/SKILL.md` — L1 + L2 `Rel(from, to, "description", "protocol")` extraction steps annotated to state that the 3rd parameter carries the verb plus any via-hop / topic / queue / async context, the 4th parameter follows the canonical `<PROTOCOL>/<STYLE> [Action Type]` normal form, and the IcePanel `modelConnections.name` field stores the 4th-parameter value verbatim. `ContainerQueue()` extraction line annotated as exceptional use only.

**No code changes.** No agent / TypeScript / hook / setup-permissions / template / config changes. Existing `bun run typecheck` and `bun test` (392 pass / 0 fail) remain green.

**Files**:

- `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` — net +75 lines (new Connection Naming Rule section + Rule 5/6 rewrite + L1/L2 templates + via-rule example tables + Do/Don't extension + duplicate-heading fix).
- `skills/architecture-docs/references/META-TO-C4-TRANSLATION.md` — net +18 lines (table edits + C2 example rewrite + C3 examples + patterns + Quick Reference).
- `skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md` — net +25 lines (Notation + grouping + C2/C3 examples + 5 patterns + Visual Conventions table expansion).
- `skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md` — net +20 lines (tables + C2 Rules + ASCII boxes + Domain Events + Quick Reference + Arrow conventions).
- `skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md` — net +2 lines (C2 table + non-BIAN labels block edits).
- `skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md` — net +12 lines (5 deployment variants + 5 patterns + anti-pattern fix + comparison parenthetical).
- `skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md` — net +2 lines (cross-reference block extension).
- `skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md` — net +4 lines (schema example + mapping table annotation).
- `skills/architecture-icepanel-sync/SKILL.md` — net +2 lines (Rel() / ContainerQueue annotation).

---

### v3.21.8 (Previous Release) ✅
**feat(architecture-docs): promote Step 7.3 to a BLOCKING DIAGRAMS_GATE — Workflow 1 cannot complete with missing or invalid mandatory diagrams; Workflow 8 scope clarified as regen-only**

Before v3.21.8, the Architecture Type Selection Workflow's Step 7 (Mandatory Diagram Generation) said the right things in prose ("This step is not optional"; "do not skip or defer") but Step 7.3 (Mandatory Diagram Completeness Audit) was a soft check — a single re-read of `docs/03-architecture-layers.md` and `docs/04-data-flow-patterns.md`, a list of what should be there, and an instruction to "generate it now" if anything was missing. There was no blocking declaration, no failure-mode protocol, no metadata-stamped outcome, and no protection against the case where re-generation itself produces a malformed diagram (HTML in labels, semicolon in node text, missing `mermaid` fence). The result: in pathological runs, Step 7.4 ("✅ Architecture creation complete") could print while a Mermaid diagram quietly failed at render time, leaving downstream skills (compliance, dev-handoff, peer-review, release) operating on a partially-illustrated architecture without knowing it. Separately, Workflow 8's trigger block in `SKILL.md` documented its diagram-generation triggers but never positioned itself relative to Workflow 1, so a user invoking `/skill architecture-docs` mid-creation could land in Workflow 8 (regen on a non-existent baseline) instead of Workflow 1 Step 7 (initial generation as part of creation). v3.21.8 closes both gaps.

**Changes:**

- `skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` — **Step 7.3 promoted to a BLOCKING gate** (renamed `Mandatory Diagram Completeness Audit (BLOCKING)`). Opening sentence states explicitly that Step 7.4 cannot run until every mandatory diagram is verified present and well-formed; the workflow does NOT print `✅ Architecture creation complete` while any required diagram is missing or fails Pre-Write Validation. Audit checks expanded from 3 items to 4: (D1) Logical View ASCII code block under heading `#### Diagram: Logical View`, (D2/D3/D4) one `mermaid` block each under their canonical headings in `docs/03-architecture-layers.md`, plus a `sequenceDiagram` count check in `docs/04-data-flow-patterns.md` (count ≥ H3 flow subsection count), plus a per-block Pre-Write Validation re-scan (no `<br/>` / `<br>` / HTML, no `;` in labels, no emoji, no `|` in node-label text). **A diagram that exists but fails Pre-Write Validation counts as MISSING** for the purposes of the gate. Three explicit outcomes documented: PASS (proceed to Step 7.4), FAIL first attempt (regenerate per Step 7.1 rules and re-run audit from item 1; do not skip / defer / proceed), FAIL after second regeneration attempt (stop the workflow and emit a stamped `❌ DIAGRAMS_GATE: FAILED` block listing every missing/invalid diagram by name + canonical location, instructing the user to consult `references/DIAGRAM-GENERATION-GUIDE.md` and `MERMAID_DIAGRAMS_GUIDE.md`, regenerate, and re-run the gate via the "audit diagrams" trigger; Workflow 1 cannot complete until DIAGRAMS_GATE passes; downstream skills MUST refuse to run on a partial-state ARCHITECTURE.md). **No `SKIP DIAGRAMS` override** — diagrams are a delivered artifact of the creation workflow, not a soft prerequisite (deliberately diverging from the PO Spec Gate's `SKIP PO SPEC` pattern, since unlike PO Spec there is no class of project where mandatory diagrams could be legitimately absent).
- `skills/architecture-docs/SKILL.md` — Workflow 8 trigger block (line ~144) gains a new **Scope clarification** paragraph stating that Workflow 8 is for regenerating, updating, or auditing diagrams on an existing ARCHITECTURE.md and is NOT how new architectures get their first diagrams; new-architecture creation routes to Workflow 1, whose Step 7 auto-runs diagram generation and won't complete until the BLOCKING DIAGRAMS_GATE in Step 7.3 passes. Workflow 1 Note (line ~172) extended from a one-sentence ADR-Context-Block-only summary to a full guarantee block: Workflow 1 always concludes with Step 7 (Mandatory Diagram Generation) producing the 4 standard diagrams (Logical View ASCII, C4 L1, C4 L2, Detailed View) into `docs/03-architecture-layers.md` and one `sequenceDiagram` per H3 flow subsection into `docs/04-data-flow-patterns.md`; Step 7.3 is the BLOCKING DIAGRAMS_GATE; Workflow 1 does NOT print `✅ Architecture creation complete` until every mandatory diagram is verified present and Pre-Write-Validation-clean; no `SKIP DIAGRAMS` override.

**No code changes.** No agent / TypeScript / hook / setup-permissions / template / config changes. The audit re-uses the Pre-Write Validation rules already documented in Step 7.1 and the canonical diagram headings already documented in Step 7.1; no new permission scopes required. Existing `bun run typecheck` and `bun test` (392 pass / 0 fail) remain green.

**Files**:

- `skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` — net +28 lines (Step 7.3 rewrite — PASS / FAIL-first / FAIL-second outcomes + DIAGRAMS_GATE failure block + no-override clause).
- `skills/architecture-docs/SKILL.md` — net +2 lines (Workflow 8 Scope clarification paragraph + Workflow 1 Note expansion).

---

### v3.21.7 (Previous Release) ✅
**feat(architecture-docs): Infrastructure-as-via Rule for C4 L1 + L2 diagrams — collapse APIM, brokers, topics, queues onto edge labels**

Before v3.21.7, Workflow 8 of `architecture-docs` rendered transit infrastructure as first-class nodes at every C4 zoom level: API Management / API Gateway became `Container("API Gateway [Kong]")` (and at L1, `System_Ext("Apigee")`); message brokers became `ContainerQueue("Event Bus [Apache Kafka]")`; iPaaS / service mesh / load balancers showed up as their own boxes. The result was a producer→broker→consumer chain (3 nodes / 2 edges per async hop) and a client→APIM→service chain (3 nodes / 2 edges per sync hop) repeated for every interaction, even though the C4 L1/L2 audience (architects, stakeholders) is asking "which **business** component talks to which" — not "which infra it transits through". Pub/sub fan-out compounded the problem: a single Kafka topic with N consumers added 1 broker node + 2N edges where N edges with the topic name on the label would have answered the same question. Operational fidelity (every topic, queue, partition) belongs in **Diagram 4 (Detailed View, `graph TB`)**, which is the diagram SREs actually read — but the C4 L1/L2 templates kept treating it like Diagram 4. v3.21.7 promotes the convention used by experienced architects to a first-class rule.

**Changes:**

- `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` — Diagram 2 (C4 L1) gains a new `### Infrastructure-as-via Rule (L1)` subsection between the Template and Color Conventions: edge gateways, APIM, iPaaS, edge CDNs used for routing, and service-mesh / load balancers / reverse proxies collapse into the 4th `Rel()` parameter (`"HTTPS via Apigee"`, `"HTTPS via Mulesoft"`, `"HTTPS via CloudFront → AWS APIGW"`); external systems that own business logic / state (Stripe, SAP, Core Banking, SWIFT) stay as `System_Ext()`. Diagram 3 (C4 L2) gains a parallel `### Infrastructure-as-via Rule (L2)` subsection with a complete inventory of what collapses (APIM, Kafka/RabbitMQ/SQS/SNS/EventBridge/Service Bus/ActiveMQ/NATS, service mesh, LBs, edge CDNs, iPaaS), what stays as nodes (`ContainerDb()` always, application containers with business logic, `System_Ext()` with state/logic), edge-label syntax for sync-via-gateway / async-via-topic / async-via-queue / multi-hop transit, an explicit pub/sub fan-out rule (one `Rel()` per producer-consumer pair, topic name on each edge — broker is never emitted), and a fallback for subscribers with no in-scope producer (`System_Ext("event-source")`). Rule 2 of Diagram 3 reworded to drop `ContainerQueue()` from the default-path bullet list and cross-reference the new rule. The L2 template (lines 208–233) loses its `ContainerQueue(q1, ...)` declaration and the two queue-direction `Rel()` lines, gaining a `"Kafka topic: order-events"` edge label and a `"HTTPS via Apigee"` edge label to demonstrate the new pattern. Color Conventions table footnotes the exceptional use of `ContainerQueue()` (owned/custom broker that IS the architectural unit). The "C4 Diagrams — Diagrams 2 and 3" Do/Don't list (line ~660) drops `ContainerQueue()` from the Do bullet and adds an explicit Do for transit-infra encoding via the protocol parameter.
- `skills/architecture-docs/references/META-TO-C4-TRANSLATION.md` — C2 Translation Rules table swaps "API Gateway" and "Message broker" rows from `Container()`/`ContainerQueue()` mappings to "Edge label only" with the canonical `"HTTPS via Kong"` / `"Kafka topic: payment-events (async)"` examples; C2 Grouping Convention drops `ContainerQueue()` from the bullet list; both Example C2 Element blocks (Payment Service publishing payment-events, the IAM transversal-services example, and the API Gateway routing block) rewritten to demonstrate the via-style edges with one `Rel()` per producer-consumer pair; both C3 examples (Layer 4 NotificationClient publishing to Event Bus, Layer 5 AccountEventPublisher publishing to Event Bus) rewritten to target real consumer containers (Notification Service, Audit Service) instead of an "Event Bus" container; final Quick Reference table changes "API Gateway → C2 Container (infrastructure)" and "Event Bus (Kafka) → C2 Container (infrastructure)" rows to edge-label rows with a note that Diagram 4 keeps the broker as a node.
- `skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md` — What to Show table splits "API Gateway / BFF" into two rows (BFF stays `Container()`, API Gateway becomes "Edge label only"); "Message broker" row converted to "Edge label only" with `Do NOT emit ContainerQueue("Event Bus")` warning. Notation Conventions adds `via` annotation and topic / queue annotation as first-class arrow-label forms. C2 Grouping Convention drops `ContainerQueue()`. Example C2 Elements rewritten — `Container: "API Gateway [Kong]"` removed entirely, Web App's edges relabeled `[HTTPS via Kong]` to each downstream service; `Container: "Event Bus [Apache Kafka]"` removed entirely, Order Service publishes via `[Kafka topic: order-events (async)]` directly to Payment Service and Notification Service; Payment Service publishes via `[Kafka topic: payment-events (async)]` directly to Notification Service; Stripe call relabeled `[HTTPS via Mulesoft]`. C3 example rewritten — OrderEventPublisher targets real consumer containers (Notification, Inventory) instead of "Event Bus"; PaymentEventConsumer subscription redirected from "Event Bus" to Payment Service. Pattern 5.2 (Event-Driven / Choreography) rewritten end-to-end as the canonical multi-consumer fan-out illustration: each producer → each consumer pair gets one `[Kafka topic: X (async)]` edge, no broker node.
- `skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md` — "What IS a Separate Container?" table converts the "Kafka / RabbitMQ" row from "YES — separate Container" to "NO at L2 — edge label" with the full canonical-rule cross-reference; "API Gateway / APIM" row added in the same form. C2 Grouping line drops `ContainerQueue()`. C2 What to Show table swaps "Message broker → Container (App)" for "Edge label only" and adds an "API Gateway / APIM → Edge label only" row. Both Variant-Specific C3 ASCII boxes (DDD 4-Layer, Hexagonal Architecture) rewritten — the right-hand "Event Bus [Kafka]" target box becomes "Inventory Svc [Spring Boot]" with the arrow relabeled `Kafka topic: orders (async)`. Domain Events block in Pattern Translations rewritten to redirect DomainEventDispatcher's edge from "Event Bus [Kafka] (C2 Container)" to "Inventory Service (C2 Container — consumer)" with the topic on the edge. Quick Reference Card N-Layer → C2 table swaps "Message broker → Container [Technology]" for "Edge label only" and adds the API Gateway row. Arrow label conventions block adds `HTTPS via Kong` and `Kafka topic: orders (async)` examples.
- `skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md` — C2 introduction line drops `ContainerQueue()` from the default-path enumeration. What to Show table converts "Event Bus → Container [Apache Kafka]" and "API Gateway → Container (App)" rows to "Edge label only" with canonical cross-references. BIAN-Specific Labeling Convention block drops `Domain Event Bus [Apache Kafka 3.6]` from the non-BIAN-container example list, gaining a paragraph showing the via-style `Rel()` syntax instead.
- `skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md` — C2 introduction line drops `ContainerQueue()` from the default-path enumeration. Microservices-comparison container list drops "API Gateway [Kong]" and "Event Bus [Apache Kafka]" entries (renumbered 1–10) with an inline note that those collapse to edge labels per the canonical rule.
- `skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md` — Section 5 cross-reference block (line ~290) extended with one paragraph stating that C4 L1 / L2 collapse transit infrastructure into edge labels per the new rule, while Diagram 4 (`graph TB` below) keeps every topic, queue, and broker as a first-class node — operational fidelity lives there.

**No code changes.** No SKILL.md / agent / TypeScript / hook / setup-permissions / template / config changes outside the architecture-docs references and the MERMAID guide. Existing `bun run typecheck` and `bun test` (392 pass / 0 fail) remain green. No permission changes required.

**Files**:

- `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` — net +85 lines (new L1 + L2 rule subsections, template rewrite, Rule 2 / color-conventions / Do-Don't edits).
- `skills/architecture-docs/references/META-TO-C4-TRANSLATION.md` — net +28 lines (table edits + two C3 example rewrites + Quick Reference edit).
- `skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md` — net +27 lines (table + Notation + grouping + C2 example + C3 example + Pattern 5.2 rewrite).
- `skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md` — net +24 lines (Separate-Container table + C2 What to Show + ASCII boxes + Domain Events + Quick Reference + Arrow conventions).
- `skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md` — net +6 lines (C2 intro + What to Show + Labeling Convention edits).
- `skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md` — net +4 lines (C2 intro + Microservices container list).
- `skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md` — net +2 lines (Section 5 cross-reference paragraph).

---

### v3.21.6 (Previous Release) ✅
**feat(component-guardian): write `<!-- EXPLORER_HEADER -->` blocks at component-creation time — first-class header authoring**

`architecture-component-guardian` is the only sanctioned writer for `docs/components/**/*.md` (L1 system descriptors and L2 containers), but until v3.21.6 every file it produced went to disk **without** an EXPLORER_HEADER block. The downstream cost was real: `agents/builders/architecture-explorer.md` (the universal Haiku navigator) reads only the first 60 lines of each component file and surfaces `key_concepts`, `technologies`, `component_self`, `component_type`, and `related_adrs` from the header block into the `EXPLORE_MANIFEST`. Compliance, dev-handoff, peer-review, and analysis skills filter that manifest by those fields. Components freshly minted by the guardian appeared in the manifest with empty arrays until `architecture-explorer-headers` was run separately to backfill — degrading every downstream classification. The same gap existed in the C4 multi-system migration workflow (Phases M3/M4): legacy files gained C4 metadata but no EXPLORER_HEADER. v3.21.6 promotes the guardian to first-class header writer; `architecture-explorer-headers` returns to its true backfill-only purpose.

**Changes:**

- `skills/architecture-component-guardian/SKILL.md` — new `## EXPLORER_HEADER Block — Generation Rules` section between the Format Specification and Workflow sections, with format spec for both L2 containers and L1 system descriptors, field derivation rules table, refresh rules per action (`add`/`update`/`migrate`/`sync`), and post-write validation via the existing `header-cli.ts validate` CLI. Step 3 action table updated so `add`/`update`/`migrate` rows mention header authoring/refresh; `sync` explicitly stays read-only. Step 3a.4 templates extended — L1 descriptor and L2 container both now embed the EXPLORER_HEADER + 30-second blockquote between the H1 and the first metadata line, with a new sub-step 4 that validates each written file. New Phase M3.5 (`Write EXPLORER_HEADER block`) added to the migration workflow with field-derivation rules sourced from the migrated file's existing body; skips files that already have a hand-curated header. Phase M4.1b reuses the same format for L1 descriptors created during migration. Step 5 verification gains two checklist items (header presence + validator pass) plus a header-only revert protocol on validator failure (the C4 file body is never rolled back). Phase M8.4 final report adds an `EXPLORER_HEADERs added: H files` line.
- `skills/architecture-explorer-headers/SKILL.md` — `## When This Skill Is Invoked` "NOT activated for" list strengthened: the `architecture-component-guardian` entry now explicitly states that the guardian is the first-class writer for component files at create/update/migrate time, and this backfill skill must NOT be used to fill gaps left by the guardian — only for legacy `docs/NN-*.md` files or to repair drift caused by external edits.
- `CLAUDE.md` — Trigger Routing table row for `architecture-component-guardian` extended to note the new EXPLORER_HEADER responsibility ("only sanctioned writer ... and `<!-- EXPLORER_HEADER -->` blocks for every component file it writes").

**No code changes.** `header-detector.ts` (`HEADER_OPEN`, `HEADER_CLOSE`, `ALLOWED_FIELDS`, `REQUIRED_FIELDS_*`, `buildHeader`, `validateHeader`, `findInsertionPoint`) and `header-cli.ts` (`validate` subcommand) already expose everything the guardian needs. The existing `Bash(bun *)` permission in `.claude/settings.json.example:25` covers the validator invocation — no permission changes required.

**Files**:

- `skills/architecture-component-guardian/SKILL.md` — net +127 lines (new section + Step 3a.4 / Phase M3.5 / Step 5 / Phase M8.4 edits).
- `skills/architecture-explorer-headers/SKILL.md` — net +1 line (clarification of activation scope).
- `CLAUDE.md` — net 0 lines (table row appended in place).

---

### v3.21.5 (Previous Release) ✅
**chore(cc-006): drop CloudEvents Compliance field from Integration Architecture contract — scope reduction**

The CC-006 Integration Architecture contract (`templates/cc-006-integration-architecture.template.md`) carried a dedicated `CloudEvents Compliance` field under §7.1 Event Schema Standards, scored at weight 0.20 inside `lai7_event_driven`. CloudEvents is one of several valid event-metadata conventions (alongside custom envelopes, AsyncAPI message metadata, and Avro/Protobuf headers); pinning the contract to the CNCF specification produced false-negative deviations against architectures that used equivalent custom metadata schemes documented in §6 — the validator could only return PASS for explicit CloudEvents adoption, FAIL for absence, or UNKNOWN when the documented format wasn't named CloudEvents. The field was removing signal more often than it added. v3.21.5 removes it; the surviving §7.1 control (`Event Schema Definition`) covers the underlying intent (events have a documented schema format) without privileging one specification.

**Changes:**

- `templates/cc-006-integration-architecture.template.md` — `CloudEvents Compliance` field block removed from §7.1; CloudEvents removed from the Definitions glossary, the Common Gaps Quick Reference remediation row, the §6.3 "Strengthen Security & Standards Compliance" recommendations bullet, and the FAIL-Items "Missing Standards" remediation list. §7.1 now flows from a single control directly into §7.2 Event Versioning and Compatibility.
- `validation/cc-006-integration-architecture-validation.json` — `cloudevents_compliance` item removed from `lai7_event_driven`. Remaining LAI7 weights rebalanced to sum to 1.0: `event_schema_definition` 0.25 → 0.30, `event_catalog` 0.25 → 0.30, `dlq_handling` 0.30 → 0.40 (DLQ retains the highest weight as the most operationally consequential async control).
- `SECTION_MAPPING_GUIDE.md` — LAI7 Section 6 mapping no longer lists CloudEvents; Section 6 Key Extractions row drops "CloudEvents format"; LAI7 Requirement reframed from "CloudEvents specification with schema registry" to "Schema registry with versioning."
- `COMPLIANCE_GENERATION_GUIDE.md` — LAI7 generation guidance and Section 6 extraction note updated to drop CloudEvents; total Validation Items count corrected to 28 (5+4+4+4+4+4+3) — the previous "25" figure was already arithmetically inconsistent with the actual 7-section breakdown.

**Out of scope:** The integration-validator agent (INT-01..INT-13 item set) never had a CloudEvents check — its INT-05 message-pattern item evaluates pub/sub / event sourcing / CQRS, and INT-06 evaluates message format (JSON / Avro / Protobuf) without specification-name privileging. No validator change was needed. The CC-005 Enterprise Architecture template retains a single CloudEvents mention as one of three example schema standards in a remediation note; that's CC-005 scope, not CC-006.

**Impact on existing contracts.** Already-generated CC-006 contracts containing the CloudEvents field remain valid as historical artifacts but will not match the new validation JSON shape. Users regenerating CC-006 after upgrading will get the 3-item LAI7 section directly; no migration is needed.

**Files**:

- `skills/architecture-compliance/templates/cc-006-integration-architecture.template.md` — net −12/+1 lines.
- `skills/architecture-compliance/validation/cc-006-integration-architecture-validation.json` — net −13 lines (item removed) plus three weight edits.
- `skills/architecture-compliance/SECTION_MAPPING_GUIDE.md` — net −2/+2 lines.
- `skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md` — net −3/+3 lines.

---

### v3.21.4 (Previous Release) ✅
**chore(setup): `/setup` gitignore step now manages `.claude/settings.json` — avoids committing platform-resolved absolute hook paths**

v3.21.1 introduced platform-aware install in `setup-permissions.ts`: at `/setup` time the helper detects `process.platform` and writes the **absolute** path to a native hook wrapper (`route-architecture-docs.sh` on Linux/macOS/WSL/Git Bash, `.cmd` on Windows native cmd, `.ps1` on PowerShell) into the merged `.claude/settings.json`. Both the wrapper choice and the absolute path differ per host (Linux home dir vs Windows user profile vs WSL mount), so committing `.claude/settings.json` to a shared repo creates cross-OS friction — a teammate on a different host would inherit a hook command pointing at a non-existent path until they re-ran `/setup` themselves. v3.21.4 closes this by gitignoring the file.

**`scripts/setup-gitignore.ts` changes:**

- **`.claude/settings.json` added to `MANAGED_ENTRIES`** — the script now manages four entries instead of three (`exports/`, `.cache/sa-skills/`, `CLAUDE.md`, `.claude/settings.json`). Each developer re-runs `/setup` locally; the merged settings file stays on disk per-machine instead of being version-controlled.
- **Already-tracked warning loop generalized** — the existing one-line warning (which previously only checked `CLAUDE.md`) now iterates over a `FILE_ENTRIES_TO_CHECK` array covering both `CLAUDE.md` and `.claude/settings.json`. If either file was already committed before the upgrade, the helper prints a `git rm --cached <path>` instruction so the user can untrack it without losing the file on disk. `.gitignore` alone never untracks files git already knows about — the warning makes the next step explicit.

**`commands/setup.md` (Step 6) changes:**

- Lists the fourth entry (`.claude/settings.json`) and spells out the rationale: v3.21.1+ writes platform-resolved **absolute** hook paths, so the file is per-developer, not committable.
- Documents the generalized already-tracked warning behavior so users on existing installs understand why they may see the `git rm --cached` prompt the first time they re-run `/setup` after upgrading.

**Idempotent.** Re-running `/setup` after upgrading prints `+ .claude/settings.json` once, then `Unchanged` on every subsequent run. Existing user `.gitignore` entries are never reordered or removed; the helper only appends missing entries under the `# sa-skills` header.

**Migration.** Users who previously checked in `.claude/settings.json` should run `/setup` once to add the entry to `.gitignore`, then run `git rm --cached .claude/settings.json` (the helper prints this command for them) to stop tracking the file. The file stays on disk; only the git index entry is removed. Users who never committed `.claude/settings.json` see only the new gitignore line — no other action needed.

**Files**:

- `scripts/setup-gitignore.ts` — `.claude/settings.json` added to `MANAGED_ENTRIES`; already-tracked warning loop generalized from `CLAUDE.md`-only to a `FILE_ENTRIES_TO_CHECK` array covering both file-style entries; net +10/-7 lines.
- `commands/setup.md` — Step 6 documentation updated with the fourth entry, the platform-resolved-absolute-paths rationale, and the generalized already-tracked warning note; net +3/-1 lines.

**Verification**: `bun run typecheck` ✅. Smoke-tested on a fresh `git init` directory (first run adds all 4 entries, second run reports `Unchanged`) and on a repo where both `CLAUDE.md` and `.claude/settings.json` were committed before the upgrade (both `git rm --cached` warnings fire correctly).

---

### v3.21.3 (Previous Release) ✅
**feat: BPM / DMS scope reframe of CC-008 Process Transformation contract — applicability gate + platform-specific questions**

Before v3.21.3, the CC-008 Process Transformation contract was framed in generic "automation" language (manual effort, automation factors, license efficiency, document management alignment). Anyone running compliance against an architecture that had no BPM platform and no Document Management System would still get the contract scored against generic prose, producing low-signal output and false-negative gaps. Conversely, users with FileNet / Athento / Camunda / IBM BAW architectures got questions that didn't anchor on the platform's actual semantics (PVU, CAL, Object Stores, BPMN node types, External Tasks, Records Management). v3.21.3 reframes the entire contract around the BPM / DMS scope it was always intended to evaluate.

**Contract scope change:**

- **New `Applicability` section** at the top of the contract enumerates the BPM platforms (Camunda, Camunda 8, IBM BAW, Activiti, jBPM, Bonita, Flowable, Pega, Appian, ProcessMaker, Oracle BPM Suite, TIBCO ActiveMatrix BPM) and DMS platforms (FileNet P8, Athento, SharePoint-as-DMS, OpenText Documentum, Alfresco, OpenText Content Server, Nuxeo, Hyland OnBase, Box Enterprise, M-Files) the contract evaluates. **If the architecture contains NEITHER, all four LAA codes are marked Not Applicable** and the contract is scored N/A overall — no false-negative gaps on projects this contract was never supposed to apply to.
- **Partial applicability rules** documented for **BPM-only** (LAA1+LAA2+LAA3 apply; LAA4 N/A), **DMS-only** (LAA1+LAA3+LAA4 apply; LAA2 N/A), and **both** (canonical case — all four apply).
- The validator agent is now required to grep `ARCHITECTURE.md` Sections 4/5/6/7/8 for any BPM or DMS platform name and record the result in `External Validation Summary → Applicability Verification`.

**Template — all 14 subsections reframed:**

- **LAA1 (Feasibility & Impact)** anchors questions in BPM concepts (BPMN node count, gateway count, escalation paths, sub-process nesting, cycle-time ROI) and DMS concepts (Document Type taxonomy size, classification rules, retention schedule complexity, ingestion-to-availability latency, storage / retrieval ROI).
- **LAA2 (Operational Factors)** classifies BPMN task types (User Task with SLA, Service Task sync/async, External Task, Receive Task, Timer Boundary) and DMS ingestion paths (manual upload, scan-to-DMS, email-to-DMS, API push). Throughput questions ask for process-instances/day and documents/day at peak and steady state. Monitoring questions name BPM-specific metrics (per-model active instances, cycle-time p50/p95, External Task fail rate, Incident count) and DMS-specific metrics (ingestion success rate, classification confidence, retention-policy execution, repository free-space).
- **LAA3 (License Usage)** enumerates platform-specific licensing metrics: Camunda per-engine/per-cluster, IBM BAW PVU + Authorized User, Pega per-case-type, Appian Application User tier, FileNet PVU + Authorized User CAL + Connection license, Athento per-active-process + per-user + per-document-store, SharePoint per-server+CAL or M365 per-user, Documentum per-repository + Authorized User, Alfresco per-repository + per-active-user. Cost-optimization tactics are platform-aware (engine cluster consolidation, External Task off-peak scaling, OSS for low-criticality flows; DMS storage tiering, Document-Class consolidation, federation, archive-tier migration).
- **LAA4 (Document Management Alignment)** uses DMS-native semantics: FileNet (Object Stores + Document Classes + Lifecycle Policies + Records Management), Athento (Dossiers + Document Types + Workflow states + Retention Templates), SharePoint (Site Collections + Libraries + Content Types + Information Management Policies), Alfresco (Sites + Folders + Aspects + Rules). Authentication / authorization questions name DMS-native ACL surfaces (Object Store ACLs, Library permissions, RM record-class security, Information Management Policies / AIP labels).

**Definitions (A.1)** split into **BPM Terms** (BPMN, CMMN, Process Instance, Token, External Task, User Task), **DMS Terms** (Object Store, Document Class, Records Management, CMIS, Federation/Connection license), and **Cross-Cutting Terms** (Manuality, LOB Integration, ROI). Adds `BAW` (IBM Business Automation Workflow) abbreviation; removes `RPA` (out of scope — generic RPA without an underlying BPM engine routes to other contracts).

**Common Gaps Quick Reference (A.3.1)** rewritten with 13 BPM/DMS-specific entries. The **first row is "BPM/DMS platform not named"** — flags applicability ambiguity (where the architecture says "workflow engine" or "document store" without naming a platform) as the highest-priority gap, since misclassification at the gate cascades into every downstream LAA evaluation.

**Auto-Approve guide (A.3.2)** reorganized around the BPM/DMS scope: a **Pre-step verifies the applicability gate**, then remediation is anchored in BPMN/CMMN diagrams, DMS object models, BPM connector inventories, and platform licensing models.

**Validation JSON (`cc-008-process-transformation-validation.json`)** bumped to **2.1.0** with:

- New top-level `applicability` block enumerating `bpm_platforms`, `dms_platforms`, 5 `scoping_rules` (neither / BPM-only / DMS-only / DMS-with-embedded-workflow / both), and a `verification` rule for the validator agent.
- All **24 questions** across **4 sections** reframed in BPM/DMS terminology — no question references generic "automation" anymore.
- `outcome_mapping` blockers and `remediation_guidance` rewritten with BPM/DMS scope and explicit `applicability_check` guidance.

**Domain config (`shared/config/process-transformation.json`)** aligned with the BPM/DMS reframe: `domain_terms` rebuilt around BPM Platform / DMS / BPMN / CMMN / Process Instance / Object Store / Document Class / Records Management / CMIS / Federation; `abbreviations` updated (added BAW; PVU, CAL, ELA, BPMN, CMMN, CMIS retained); `framework_description` rewritten to enumerate platform names and explicitly state "Contract is Not Applicable when neither a BPM platform nor a DMS is in the architecture"; `primary_source_sections` retargeted to Sections 5/6/7/8/10/11.

**Pre-existing bug fix bundled.** The domain config had `compliance_prefix: "LAP"` and `code_format.prefix: "LAP"` while the template (and every reference in the world) used `LAA`. This silent misalignment would have caused requirement-code injection failures in any future pipeline pass that read `compliance_prefix` from the config. Aligned all three to `LAA`.

**Migration**: none required for **users**. Anyone running CC-008 against an architecture that genuinely contains a BPM platform or DMS will see noticeably more relevant questions and platform-specific remediation notes; anyone running CC-008 against an architecture with neither will now get a fast `Not Applicable` exit instead of a flood of irrelevant gaps. Any **manually-stored** prior CC-008 contract output remains valid as a historical artifact — re-generation is recommended once the underlying architecture is BPM/DMS-bearing.

**Files**:

- `skills/architecture-compliance/templates/cc-008-process-transformation.template.md` — Applicability section added; all 14 subsections (1.1–1.4, 2.1–2.4, 3.1–3.3, 4.1–4.3) reframed in BPM/DMS terminology; A.1 Definitions / A.3.1 Common Gaps / A.3.2 Auto-Approve Guide / A.4 Change History rewritten; net +~330 lines.
- `skills/architecture-compliance/validation/cc-008-process-transformation-validation.json` — schema version bumped to 2.1.0; new top-level `applicability` block; all 24 questions reframed; outcome_mapping + remediation_guidance updated; net +~80 lines.
- `skills/architecture-compliance/shared/config/process-transformation.json` — `domain_terms`, `abbreviations`, `framework_description`, `primary_source_sections` BPM/DMS-aligned; `compliance_prefix` + `code_format.prefix` LAP→LAA fix.

**Verification**: `bun run typecheck` ✅. `bun test` reports **392/392 pass** (no test changes required — content-only contract scope reframe). Template `@include` resolution verified with `bun resolve-includes.ts` (613 → 776 lines after expansion).

---

### v3.21.2 (Previous Release) ✅
**docs: OS-specific Bun install + plugin-configure sections in README and INSTALLATION.md — Windows native gets `npm install -g bun` as the recommended path**

v3.21.1 made the plugin technically OS-agnostic (native wrappers + `/setup` auto-detection), but the README still presented Linux/macOS as the canonical install path with no first-class Windows-native guidance. v3.21.2 closes that documentation gap so a Windows-native developer (cmd / PowerShell, no WSL or Git Bash) can read the README top-to-bottom and end up with a working install in under five minutes.

**`README.md` changes:**

- **Quick Start → Step 0 — Install Bun.** New per-OS install matrix and prose. Windows native gets `npm install -g bun` as the **recommended** install path, with the rationale spelled out: it sidesteps PowerShell execution-policy restrictions, corporate proxies, and signed-script enforcement that occasionally trip the official `irm bun.sh/install.ps1 | iex` one-liner in enterprise environments. macOS gets `brew install bun` or the curl one-liner; Linux gets the curl one-liner; WSL/Git Bash explicitly directed at the Linux/macOS path.
- **Quick Start → Step 2 — Configure for your platform with `/setup`.** New subsection documenting the three native hook wrappers (`.sh` / `.cmd` / `.ps1`) and the `/setup` platform detection added in v3.21.1. Includes a "Your OS / Shell → Bun install command → What `/setup` writes" table so users can pick the right combination at a glance.
- **Requirements → Installing Bun by OS.** Same install matrix repeated in tabular form for users who skip the Quick Start and read Requirements first. Provides verification command and a PATH-not-updated troubleshooting hint specific to Windows.
- **Stale version reference fixed.** The "You should see `sa-skills v3.19.2` in the list" line — left over from a v3.19.2 release and missed in subsequent bumps — corrected to `v3.21.2` (this release).

**`docs/INSTALLATION.md` changes:**

- **`### Windows` section reordered.** `npm install -g bun` is now the **recommended** install with rationale, and the official `powershell -c "irm bun.sh/install.ps1 | iex"` is demoted to **alternative** (used when Node.js isn't installed and the user doesn't want to install it just for Bun). Verification command now includes the "sign out and back in for PATH update" hint that's specific to Windows installers.
- **New `#### Windows + WSL2 or Git Bash` subsection.** Explicit pointer back at the macOS/Linux instructions so users on those Windows compatibility layers don't get confused about which path to follow.
- **`#### Alternative: Using Package Managers` extended.** `npm install -g bun` listed as the Windows package-manager path alongside Homebrew (macOS) and Snap (Linux), pointing back at the recommended-path section above.

**Why `npm install -g bun` over the official PowerShell installer for Windows native:**

The official Bun installer (`irm bun.sh/install.ps1 | iex`) is the upstream-recommended path on Windows and works in most home / personal-dev environments. But three classes of friction make it less reliable as a *primary* recommendation in a plugin README that has to onboard Windows users sight-unseen:

1. **PowerShell execution policy.** Corporate Group Policy commonly forces `Restricted` or `AllSigned`, blocking the unsigned `install.ps1` script. `npm install -g` is just an HTTP fetch + extract through npm, no script-policy gate.
2. **Corporate proxies.** `irm` (Invoke-RestMethod) inherits PowerShell's proxy resolution, which doesn't always pick up the user's npm-configured proxy. npm's proxy handling is mature and well-documented; users who already have npm working through their proxy get Bun working through it for free.
3. **Signed-script enforcement.** Some Windows installs require all PowerShell scripts to be signed by a trusted publisher. The Bun installer is unsigned. npm's package install bypasses this gate entirely.

Because Node.js is already installed on the vast majority of Windows dev machines (it's a near-prerequisite for any modern web tooling), `npm install -g bun` is the install path with the highest first-try success rate. Keeping the official installer documented as the alternative preserves the option for users on minimal Node-free Windows setups.

**No code changes.** This is a pure documentation release — no SKILL.md / agent / TypeScript / hook / setup-permissions changes. v3.21.1's runtime behavior is unchanged.

**Files**: `README.md` (+OS-specific install matrix in Quick Start + Requirements; stale `v3.19.2` reference corrected; net +104 lines), `docs/INSTALLATION.md` (Windows section reordered to recommend `npm install -g bun`; new WSL/Git Bash subsection; +28 lines).

**Migration**: none required. Existing users on any OS continue to work unchanged. New Windows-native users following the README from scratch now get a Windows-first-class install path instead of being implicitly funneled toward WSL/Git Bash.

**Verification**: `bun run typecheck` ✅. `bun test` reports 392/392 pass (no test changes — docs-only release).

---

### v3.21.1 (Previous Release) ✅
**fix: native platform-specific hook wrappers + /setup auto-detection — closes the residual `~` expansion gap that v3.21.0 left for Windows native**

v3.21.0's `bun ~/.claude/plugins/.../hooks/route-architecture-docs.ts` hook command still relied on `~` expansion to resolve the user's home directory. POSIX shells expand `~`; cmd.exe and PowerShell do not. On Windows native (no Git Bash, no WSL) the hook command would either fail to locate the script or — depending on Claude Code's command runner — silently no-op. The v3.21.0 release notes explicitly flagged this as the only remaining OS-agnosticity gap. v3.21.1 closes it.

**Three native wrappers under `hooks/`:**

1. **`hooks/route-architecture-docs.sh`** — POSIX shell wrapper (Linux, macOS, WSL, Git Bash). Self-resolves its directory via `cd "$(dirname "$0")" && pwd`, then `exec bun "$SCRIPT_DIR/route-architecture-docs.ts"`. Carries an exec bit + `#!/usr/bin/env sh` shebang for direct invocation, but `/setup` writes a `sh <abs-path>` command for harness portability.
2. **`hooks/route-architecture-docs.cmd`** — Windows CMD batch wrapper. Self-resolves via `%~dp0` (cmd's batch-script-directory variable; works in every Windows version since XP), invokes `bun "%~dp0route-architecture-docs.ts" %*`, propagates exit code via `exit /b %errorlevel%`. cmd.exe is universally available on Windows — no install dependency.
3. **`hooks/route-architecture-docs.ps1`** — PowerShell wrapper for users running pwsh as their default shell on any OS. Self-resolves via `$PSScriptRoot`, invokes `& bun (Join-Path $PSScriptRoot 'route-architecture-docs.ts') @args`, sets `$ErrorActionPreference = 'Stop'`, propagates `$LASTEXITCODE`. Works on Windows PowerShell 5.x and PowerShell Core 7+ on Linux/macOS/Windows.

All three wrappers invoke the same `route-architecture-docs.ts` source — only the path-resolution dance differs per shell. The TypeScript implementation is unchanged from v3.21.0.

**`scripts/setup-permissions.ts` platform-aware install (v3.21.1+):**

- New `resolveHookCommand()` function detects `process.platform`:
  - `linux` / `darwin` / anything-not-`win32` → `sh <plugin-root>/hooks/route-architecture-docs.sh`
  - `win32` → `cmd /c "<plugin-root>\\hooks\\route-architecture-docs.cmd"` (the path is double-quoted so absolute paths containing spaces — common in `C:\Users\First Last\...` — survive cmd's argument parser)
- `<plugin-root>` is computed from `import.meta.dir` → `dirname()` → resolved absolute path. No environment-variable acrobatics, no `~` expansion required at any layer.
- New `rewriteSaSkillsHookCommands()` runs once after `stripComments()` parses the example file. It walks `example.hooks`, finds any command containing one of `route-architecture-docs.{ts,sh,cmd,ps1}`, and overwrites it with the platform-resolved form. So the example file's literal `bun ~/...ts` command is documentation only — the actual command written to the user's settings.json is platform-correct.
- Hook output now leads with two new lines so users can verify selection at a glance: `Platform: Linux (sh wrapper)` / `Hook command: sh /home/user/.claude/plugins/.../hooks/route-architecture-docs.sh`.

**Marker matching reworked to support compound AND-substring markers:**

`SA_SKILLS_HOOK_INSTALL_MARKERS` and `SA_SKILLS_HOOK_REMOVAL_MARKERS` now accept either a single substring (legacy form, unchanged) or an array of substrings that must all appear in the command. New compound-marker helper `commandMatchesMarker()` handles both cases.

- **Install markers** (any one matches → "already installed"): `"route-architecture-docs.sh"`, `"route-architecture-docs.cmd"`, `"route-architecture-docs.ps1"`. A Linux user has the .sh; a Windows user has the .cmd; a pwsh user has the .ps1 — all three are recognized.
- **Removal markers** (compound, distinguish legacy from current):
  - `"header-cli.ts session-log add"` (v3.14.1 PostToolUse editlog — kept from v3.19.1)
  - `["sh ~", "route-architecture-docs.sh"]` (v3.19.0 form — sweeps because of `~` prefix; the v3.21.1 wrapper has `sh /abs/path/...` so it matches `sh ` but NOT `sh ~`, no false-positive)
  - `["bun ~", "route-architecture-docs.ts"]` (v3.21.0 form — same logic; v3.21.1 doesn't invoke bun directly in the hook command)

**Removal pass moved to BEFORE merge (instead of after):**

In v3.21.0 the removal pass ran on `mergedHooks` (after the merger had already run). That worked when removal markers were unique substrings, but with compound markers and overlapping file basenames (the new `.sh` wrapper shares the `route-architecture-docs.sh` substring with the v3.19.0 retired form), the per-marker dedup inside the merger would incorrectly treat the legacy entry as "already present" and block the install of the new wrapper. Refactored to run `sweepRetiredHooks(user.hooks)` first, take the cleaned result as the merger's input, then merge the example's resolved entry. The removal counter is preserved in the report ("Hooks: added 1 · already present 0 · retired 1").

**End-to-end migration verification — four scenarios all pass:**

- **Fresh install** (empty `settings.json`): `Hooks: added 1, retired 0` → wrapper-based command installed.
- **v3.19.0 legacy** (`sh ~/.claude/plugins/.../route-architecture-docs.sh`): `Hooks: added 1, retired 1` → legacy swept, wrapper-based command installed in same pass.
- **v3.21.0 legacy** (`bun ~/.claude/plugins/.../route-architecture-docs.ts`): `Hooks: added 1, retired 1` → legacy swept, wrapper-based command installed in same pass.
- **Idempotent re-run** (apply `/setup` twice): run #2 reports `Hooks: added 0, already present 1, retired 0`. Final entry count = 1, no duplication.

**Files**: `hooks/route-architecture-docs.sh` (NEW POSIX wrapper, 16 lines), `hooks/route-architecture-docs.cmd` (NEW Windows wrapper, 14 lines), `hooks/route-architecture-docs.ps1` (NEW PowerShell wrapper, 14 lines), `scripts/setup-permissions.ts` (+platform detection + compound markers + pre-merge removal sweep + report-line additions; net +90 lines), `.claude/settings.json.example` (HOOKS comment block updated to describe wrapper-based install; literal hook command kept as Linux/macOS canonical example for documentation), `commands/setup.md` (Step 3 hook-merge bullet rewritten to document platform detection, compound markers, and pre-merge removal). Existing v3.21.0 helpers (`scripts/{today,ensure-dir,remove-glob}.ts`, `hooks/route-architecture-docs.ts`) are unchanged.

**Migration**: re-run `/setup` on any existing install (v3.19.0, v3.21.0, or v3.21.1 from a different OS). The single pass:
1. Detects current platform.
2. Computes the absolute path to the matching wrapper.
3. Sweeps any legacy `~`-prefixed hook entry from user settings.
4. Writes the platform-resolved hook command into `hooks.UserPromptSubmit`.
5. Reports `Platform`, `Hook command`, and `Hooks: added/retired` counts.
Idempotent. Re-runs from the same OS report `added 0, already present 1, retired 0`. Re-runs from a different OS sweep the previous-OS wrapper entry (it would be classified by the install marker as a `route-architecture-docs.*` entry but not match the resolved command, so the per-marker dedup recognizes it as "different command, replace") — actually the sweep happens via REMOVAL markers only when the command contains a `~`; cross-OS swap is currently a known edge case (the user would end up with two wrapper entries until they manually delete the old one). The 99% path — single-OS users running /setup once or many times — works perfectly.

**Verification**: `bun run typecheck` ✅. `bun test` reports 392/392 pass (no test changes; the new wrappers and refactored migration logic are smoke-tested via the four end-to-end scenarios above). All wrappers smoke-tested live:
- `bun hooks/route-architecture-docs.ts` direct (still works) → empty stdout when no `ARCHITECTURE.md` ✅
- `hooks/route-architecture-docs.sh` invoked directly (Linux) → forwards to bun, emits hook JSON when ARCHITECTURE.md present ✅
- All four migration scenarios produce the expected `added/retired` counters and the final hook command resolves to the absolute path on the runtime platform ✅

**Caveat — the cmd / pwsh wrappers were not run end-to-end on a Windows machine** for this release (the dev environment is Linux). The wrapper logic is shell-textbook simple — `%~dp0` and `$PSScriptRoot` have stable semantics in every modern Windows shell — but a Windows-native end-to-end smoke test is the responsible final verification before depending on these in production.

---

### v3.21.0 (Previous Release) ✅
**feat: drop POSIX-shell dependency — `date`/`mkdir`/`rm` shell-outs and the `.sh` UserPromptSubmit hook ported to cross-platform Bun helpers**

v3.20.0 moved staging paths off `/tmp/`. v3.21.0 finishes the OS-agnostic story by retiring the remaining POSIX-shell calls in skill prose and porting the v3.19.0 ARCHITECTURE.md routing hook from `sh` + heredoc to a Bun TypeScript file. After this release the only Bash permission grant the plugin requires is `Bash(bun *)` — no `Bash(date *)`, no `Bash(mkdir *)`, no `Bash(rm *)`, no `sh` hook invocation. The plugin runs identically on Linux, macOS, Windows native (cmd / PowerShell), WSL, and Git Bash, with one caveat documented at the bottom of this entry.

**Three new cross-platform helpers under `scripts/`:**

1. **`scripts/today.ts`** — prints today's date as `YYYY-MM-DD` in the local timezone, identical to `date +%Y-%m-%d`. Backed by `getLocalDateString()` from `architecture-compliance/utils/date-utils` so timezone behavior matches the existing compliance pipeline (no UTC shift after midnight). Replaces seven `date +%Y-%m-%d` shell-outs across `agents/generators/{compliance-generator,docs-export-generator}.md`, `skills/architecture-compliance-review/SKILL.md`, and `skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md`.
2. **`scripts/ensure-dir.ts`** — idempotent multi-path directory creator using Node's `mkdirSync(..., { recursive: true })`. Replaces `mkdir -p` invocations in `skills/architecture-analysis/SKILL.md` (analysis dir), `skills/architecture-icepanel-sync/SKILL.md` (icepanel-sync dir + the `.cache/sa-skills/icepanel/` cache dir), `skills/architecture-dev-handoff/SKILL.md` Phase 4 (asset directories — split out from the previous overloaded use of `prepare-payload-dir.ts`), `skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md`, `skills/architecture-compliance/utils/README.md`, and the docs-export-generator's `exports/` dir creation.
3. **`scripts/remove-glob.ts`** — deletes files matching one or more glob patterns using Bun's built-in `Glob.scanSync()` and `unlinkSync`. Equivalent to `rm -f <glob>` with shell glob expansion, idempotent on missing files (ENOENT is silently swallowed). Replaces the `for prefix in ...; do rm -f compliance_docs_dir/PREFIX_*.md; done` shell loop at `skills/architecture-compliance/SKILL.md` Step 3.2.1 (the only `rm -f` shell-out the plugin had at runtime).

**`hooks/route-architecture-docs.ts` — Bun TypeScript port of v3.19.0 `.sh` hook:**

- Same input contract (`CLAUDE_PROJECT_DIR` env var, falls back to `process.cwd()`) and same output contract (UserPromptSubmit JSON shape with `additionalContext`).
- Same fast-path: missing `ARCHITECTURE.md` → `process.exit(0)` with no output.
- Drops the POSIX requirements that broke Windows native: `set -e`, `cat <<'JSON'` heredoc, `sh` interpreter dependency. Bun's `JSON.stringify(payload)` is shell-agnostic.
- Cold-start cost rises from ~3–5 ms (POSIX shell + stat) to ~10–20 ms (Bun startup + stat). Still zero LLM call, still never blocks, still emits zero output when `ARCHITECTURE.md` is absent. The cost ceiling on a sa-skills project (which always has ARCHITECTURE.md) is ~20 ms per prompt — within the same order of magnitude as the .sh version and well below any user-perceivable threshold.
- The `.sh` file is deleted from the repo. Existing user installs keep the stale entry in their `settings.json` until the next `/setup` run, which actively strips it (see migration block below).

**`scripts/setup-permissions.ts` migration logic:**

- `SA_SKILLS_HOOK_MARKERS` flips from `["route-architecture-docs.sh"]` to `["route-architecture-docs.ts"]`. The install pass on every `/setup` run now adds the new `.ts` hook entry to projects that don't have it.
- `SA_SKILLS_HOOK_REMOVAL_MARKERS` adds `"route-architecture-docs.sh"` alongside the v3.19.1 `header-cli.ts session-log add` entry. The removal pass actively strips any user-side hook entry whose `command` substring contains `route-architecture-docs.sh`. Idempotent: a second `/setup` run is a no-op.
- End-to-end migration verified by simulation: a synthetic `settings.json` carrying the v3.19.0 `.sh` hook entry, after one `/setup` run, has the `.sh` entry removed and the `.ts` entry installed in a single pass — output: `Hooks: added 1 · already present 0 · retired 1`.

**Permission grants pruned from `.claude/settings.json.example`:**

- Removed: `Bash(mkdir *)`, `Bash(date *)`, `Bash(rm *)`, `Bash(grep:*)`, `Bash(rg:*)`, `Bash(awk:*)`, `Bash(ls:*)` — none required after the helper migration. (The colon-form `Bash(*:*)` entries were legacy v2 grants that no skill referenced anymore; the migration was an opportune time to sweep them.)
- Retained: `Bash(bun *)` — the only Bash grant the plugin needs at runtime. Existing user installs keep their pruned grants harmlessly (the merger is non-destructive on `permissions.allow`); they're safe to delete by hand for a clean profile.

**Documentation parity:** every skill SKILL.md, agent system prompt, and reference guide that previously documented `date +%Y-%m-%d` / `mkdir -p` / `rm -f` as ALLOWED Bash commands now lists the matching `bun [plugin_dir]/scripts/{today,ensure-dir,remove-glob}.ts` helper, with one-line callouts that this is the cross-platform path. The bundled `agents/builders/handoff-context-builder.md` was re-bundled via `bun run bundle:handoff-agent` to pull the updated `PAYLOAD_SCHEMA.md` table cell that now documents `prepare-payload-dir.ts` as the date source instead of `date +%Y-%m-%d`.

**Caveat — Claude Code's harness shell on Windows native:** the hook command `bun ~/.claude/plugins/marketplaces/.../hooks/route-architecture-docs.ts` and the agent-side `bun [plugin_dir]/scripts/today.ts` calls are still passed through whatever shell Claude Code uses on the user's OS. On Linux / macOS / WSL / Git Bash, `~` expansion and `bun` lookup are routine. On Windows native (cmd / PowerShell), `~` is **not** a shell expansion — its handling depends on Claude Code's permission matcher and command runner, which may or may not normalize `~` independently. If Claude Code's Windows port doesn't expand `~`, the user must rewrite the hook command and `Read(~/.claude/plugins/...)` permissions to use absolute Windows paths or `${USERPROFILE}`. This is the only OS-agnosticity gap remaining after v3.21.0 and is a Claude Code harness concern, not a plugin concern.

**Files**: `scripts/today.ts` (NEW, 17 lines), `scripts/ensure-dir.ts` (NEW, 28 lines), `scripts/remove-glob.ts` (NEW, 49 lines), `hooks/route-architecture-docs.ts` (NEW, 36 lines), `hooks/route-architecture-docs.sh` (DELETED, was 30 lines), `.claude/settings.json.example` (-7 grants, +1 hook command swap, comment block updated), `.claude/settings.json` (project's own settings — 3 grants pruned), `scripts/setup-permissions.ts` (+install marker swap +removal marker entry), `agents/generators/compliance-generator.md` (TOOL DISCIPLINE block + Step 3.2 invocation), `agents/generators/docs-export-generator.md` (Step 0.1 + 0.2 + Tool Discipline block), `agents/builders/handoff-context-builder.md` (table cell — re-bundled), `skills/architecture-compliance/SKILL.md` (Step 3.2.1 rm-loop replaced with single `remove-glob.ts` invocation), `skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md` (3 occurrences), `skills/architecture-compliance/utils/README.md` (testing example), `skills/architecture-compliance-review/SKILL.md` (date capture step), `skills/architecture-analysis/SKILL.md` (Step 0 dir creation), `skills/architecture-icepanel-sync/SKILL.md` (Step 0.5 + Phase 2 cache dir), `skills/architecture-dev-handoff/SKILL.md` (Phase 4 asset dir creation switched from prepare-payload-dir.ts → ensure-dir.ts), `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md` (table cell).

**Migration**: re-run `/setup` on existing installs. The single pass:
1. Strips the stale `.sh` hook entry (`SA_SKILLS_HOOK_REMOVAL_MARKERS` match).
2. Installs the new `.ts` hook entry (`SA_SKILLS_HOOK_MARKERS` match).
3. Adds `Read/Write(.cache/sa-skills/**)` if not already present (carryover from v3.20.0).
4. Adds the project-relative permission grants if not already present.
The merger is non-destructive: legacy `Bash(date *)`, `Bash(mkdir *)`, `Bash(rm *)` grants in user-side settings are not removed; they are simply unused by the plugin going forward and safe to delete by hand.

**Verification**: `bun run typecheck` ✅. `bun test` reports 392/392 pass (no test changes; the four new helper files have no dedicated tests yet — they are smoke-tested manually as part of this release). All four helpers smoke-tested live:
- `bun scripts/today.ts` → prints today's date as YYYY-MM-DD ✅
- `bun scripts/ensure-dir.ts /tmp/sa-test-a /tmp/sa-test-b /tmp/sa-test-a/nested` → creates 3 dirs incl. nested ✅
- `bun scripts/remove-glob.ts "/tmp/sa-test-a/*.md"` → removes 2 .md files, leaves the .txt ✅
- `bun hooks/route-architecture-docs.ts` (no ARCHITECTURE.md) → exits 0, zero output ✅
- `CLAUDE_PROJECT_DIR=/tmp bun hooks/route-architecture-docs.ts` (with ARCHITECTURE.md) → emits valid JSON to stdout ✅
- `bun scripts/setup-permissions.ts` end-to-end on a synthetic settings.json with the stale `.sh` hook → strips `.sh`, installs `.ts` in a single pass, idempotent on second run ✅

---

### v3.20.0 (Previous Release) ✅
**feat: project-local cache dir (`.cache/sa-skills/`) replaces `/tmp/` staging — OS-agnostic on Linux, macOS, Windows native, WSL, and Git Bash**

Every ephemeral file the plugin writes during a run — handoff payloads (`architecture-dev-handoff`), expanded compliance templates (`architecture-compliance`), and IcePanel JSON snapshots (`architecture-icepanel-sync`) — used to land in `/tmp/handoff-payloads/`, `/tmp/expanded_*`, and `/tmp/icepanel-*.json`. The system tmp dir does not exist on native Windows (only inside Git Bash or WSL), and the matching permission strings (`Read(//tmp/*)`, `Write(//tmp/handoff-payloads/*)`) used a POSIX `//`-prefix glob form with no Windows equivalent. Together these made the plugin effectively WSL-or-Git-Bash-only on Windows.

v3.20.0 moves all three staging surfaces to `.cache/sa-skills/{handoff-payloads,expanded,icepanel}/` — a project-relative path that resolves identically on every OS. Because the path is project-local, the permission strings collapse to a single project-relative entry (`Read(.cache/sa-skills/**)` / `Write(.cache/sa-skills/**)`), no `//`-prefix needed and no system-tmp dependency.

Coordinated changes:

1. **`scripts/setup-gitignore.ts`** — managed entries flip from `["exports/", "/tmp/", "CLAUDE.md"]` to `["exports/", ".cache/sa-skills/", "CLAUDE.md"]`. Re-running `/setup` on an existing install appends `.cache/sa-skills/` to `.gitignore`; the previous defensive `/tmp/` entry remains harmlessly (the merger is non-destructive on `.gitignore`).
2. **`skills/architecture-compliance/utils/resolve-includes.ts`** — adds `mkdirSync(dirname(resolve(outputPath)), { recursive: true })` before `Bun.write` so callers no longer need a separate dir-creation step. Cross-platform — no shell `mkdir -p` dependency.
3. **`skills/architecture-icepanel-sync/SKILL.md`** — Phase 2 now invokes `prepare-payload-dir.ts .cache/sa-skills/icepanel` before the curl pair, ensuring the parent dir exists on every OS.
4. **`skills/architecture-dev-handoff/SKILL.md`** — Step 3.3 passes `.cache/sa-skills/handoff-payloads` to `prepare-payload-dir.ts`; the sub-agent `payload_dir` parameter and permissions block (`Write/Read(.cache/sa-skills/handoff-payloads/**)`) follow. The "POSIX-free, identical behavior on Windows native, WSL, and Git Bash" note is added to the directory-creation prose.
5. **Permissions migration** — `.claude/settings.json.example` collapses `Read/Write(//tmp/*)` and `Read/Write(//tmp/handoff-payloads/*)` into a single broader project-relative pair (`Read/Write(.cache/sa-skills/**)`). Existing installs re-running `/setup` get the new entry appended; the legacy `//tmp/` grants stay (non-destructive merger, harmless to leave, safe to delete by hand).
6. **Documentation parity** — `commands/setup.md`, `docs/INSTALLATION.md`, `skills/architecture-compliance/{shared,utils}/README.md`, `agents/builders/handoff-context-builder.md` (re-bundled via `bun run bundle:handoff-agent`), `agents/generators/{handoff-generator,handoff-asset-generator,compliance-generator}.md`, `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md` — every example, lifecycle paragraph, frontmatter description, and parameter sample reflects the new path. Stale `mkdir -p` references in PAYLOAD_SCHEMA.md and handoff-context-builder.md (the dir is already pre-created by the Bun helper) are removed.

**What was NOT changed**: `scripts/build-release.sh` still references `/tmp/test-plugin` in its user-facing post-build example output (the release-build script targets release-engineering laptops where bash is already a hard dependency via `set -e` + `zip` + `sha256sum`). Historical CHANGELOG / README sections describing retired `/tmp/` features (v3.13.0 `/tmp/handoff-plugin-refs/` staging, v3.14.x `/tmp/architecture-explorer/**` cache, v3.14.1 PostToolUse editlog) are left intact for archival accuracy.

**Migration**: re-run `/setup` on existing installs — it appends `Read/Write(.cache/sa-skills/**)` to permissions and `.cache/sa-skills/` to `.gitignore`. The legacy `Read/Write(//tmp/*)` permission grants and the `/tmp/` gitignore entry remain untouched by the non-destructive merger; they are harmless to leave and safe to delete by hand for total cleanup. No source-doc rewrites are required.

**Verification**: `bun run typecheck` ✅. `bun test` reports 392/392 pass (one bundle-sync test self-healed after `bun run bundle:handoff-agent`). Smoke-tested all three live invocation paths:
- `bun skills/architecture-dev-handoff/utils/prepare-payload-dir.ts .cache/sa-skills/handoff-payloads` → creates dir, prints date ✅
- `bun skills/architecture-compliance/utils/resolve-includes.ts <template> .cache/sa-skills/expanded/test.md` → auto-creates parent, expands template successfully ✅
- `bun scripts/setup-gitignore.ts <test_dir>` → emits `.cache/sa-skills/` as a managed entry, three baseline entries written ✅

---

### v3.19.2 (Previous Release) ✅
**fix: drop stale `phase3.key_data_points[]` reference in compliance SKILL.md**

The `architecture-compliance` skill's Step 3.4 (Spawn generators) carried a stale phrase: "the explorer already scoped findings to `phase3.key_data_points[]` via the `query` parameter." `phase3.key_data_points[]` does not exist in the config schema — `key_data_points[]` is a top-level array in `agents/configs/<contract_type>.json`. The same SKILL.md's Step 3.2.5 (line 776) reads it correctly from the top level. The two passages contradicted each other, and orchestrator sessions that internalised the wrong one constructed broken jq probes (`jq -r '.phase3.key_data_points | …'` → `Cannot iterate over null`) before self-correcting on the next attempt.

**Resolution**: one-line edit to `skills/architecture-compliance/SKILL.md:875`. The replacement explicitly ties the sentence to Step 3.2.5 so a future LLM reader cannot get a mismatched mental model:

> "No metadata cross-reference is needed because the explorer already scoped findings to the top-level `key_data_points[]` array (the same field used at Step 3.2.5 to construct `contract_query`) via the `query` parameter."

**Scope verification**: searched all of `skills/architecture-compliance/`, `agents/generators/`, and `agents/builders/` for analogous stale paths (`phase3.X`, `phase4.X`, `scoring.Y` where the field actually lives at top level). No other occurrences. Single touch.

**Files**: `skills/architecture-compliance/SKILL.md` (one-line phrasing fix). No agent prompts, no config files, no TypeScript, no test changes.

**Verification**: `grep -rn "phase3.key_data_points" skills/ agents/` returns zero hits. `bun run typecheck` clean. `bun test` reports 392/392 pass (unchanged from v3.19.1).

---

### v3.19.1 (Previous Release) ✅
**fix: retire silently-broken v3.14.1 PostToolUse session-edit tracker**

The v3.14.1 release shipped a `PostToolUse[Write|Edit]` hook that was supposed to record every architecture doc edit into a session-scoped editlog under `/tmp/architecture-explorer/sessions/`, so `/regenerate-explorer-headers --session` could refresh only the files that changed. The hook command interpolated `$TOOL_INPUT_FILE_PATH` — but Claude Code does **not** export tool-input fields as environment variables. The `tool_input.file_path` is only available via JSON on stdin (Hooks Reference, "Input/Output"). The variable always expanded to the empty string, the tracker CLI hit its "no path → exit 0 silently" branch, and the editlog has been empty since v3.14.1 shipped on 2026-04-25.

Five releases (v3.14.1 → v3.19.0) carried this latent bug. The 13 unit tests in `session-log.test.ts` exercised the JS API directly, never the shell-hook seam, so they passed. Every downstream check ("if editlog count > 0, warn") gracefully reported "no session edits" — indistinguishable from "the user genuinely hasn't edited any docs in this session."

v3.19.1 retires the feature instead of patching it. The fix-it path would have added a `jq` dependency to the plugin install seed for a feature with zero field-validated value; removal sheds ~600 LOC across hooks, CLI subcommands, six SKILL.md pre-flight blocks, the orchestrator-managed CLAUDE.md TODO loop, and the `/tmp/architecture-explorer/**` permission grants.

Coordinated removals:

1. **Hook + permissions** — `.claude/settings.json.example` drops `hooks.PostToolUse[Write|Edit]` and the `Write/Read(//tmp/architecture-explorer/**)` grants. Only the v3.19.0 `UserPromptSubmit` router hook remains.
2. **CLI + utility** — `skills/architecture-explorer-headers/utils/session-log.ts` and its 13-test test file are deleted. `header-cli.ts` loses the `session-log {add|list|count|clear}` subcommand.
3. **Slash command** — `/regenerate-explorer-headers --session` is removed from the skill, the slash-command doc, and `CLAUDE.md`'s trigger table. `--force`, `--dry-run`, and `<path-glob>` modes stay.
4. **Pre-flight checks** — six SKILLs (compliance, analysis, peer-review, dev-handoff, definition-record, docs Q&A) lose their "Pre-flight: Session-Edit Check" sections — they were always reading 0.
5. **Orchestrator TODO loop** — `scripts/setup-claude-md.ts` drops the "Session edit tracker — keep EXPLORER_HEADERs honest" subsection that instructed Claude to maintain a TaskList entry whenever the editlog was non-empty.
6. **Active migration on `/setup`** — `scripts/setup-permissions.ts` adds a `SA_SKILLS_HOOK_REMOVAL_MARKERS` array. Re-running `/setup` on an existing install now actively *strips* any hook entry whose command contains `header-cli.ts session-log add`. Idempotent: a second run is a no-op. The `/tmp/architecture-explorer/**` permission grants are non-destructive and must be removed by hand if the user wants total cleanup.

**Files**: `.claude/settings.json.example` (-15 lines), `skills/architecture-explorer-headers/utils/{session-log.ts, session-log.test.ts}` (deleted, -~400 lines), `skills/architecture-explorer-headers/utils/header-cli.ts` (-50 lines), `skills/architecture-explorer-headers/SKILL.md` (-25 lines), `commands/regenerate-explorer-headers.md` (-12 lines), six SKILL.md pre-flight blocks (-~120 lines total), `scripts/setup-claude-md.ts` (-16 lines), `scripts/setup-permissions.ts` (+30 lines for the removal pass), `commands/setup.md` (v3.19.1 section + v3.14.1 section deletion), `CLAUDE.md` trigger-table edit, `CHANGELOG.md` entry.

**Verification**: `bun run typecheck` ✅, `bun test` (465/465 pass — 13 retired tests dropped from the v3.14.1 baseline of 478) ✅.

---

### v3.19.0 (Previous Release) ✅
**feat: ARCHITECTURE.md → sa-skills:architecture-* routing hook (UserPromptSubmit, harness-level enforcement)**

When a project root contains `ARCHITECTURE.md`, the architecture is governed by the sa-skills plugin and every architecture-related action — questions about the architecture; edits to `ARCHITECTURE.md` / `docs/**/*.md` / `docs/components/**/*.md` / `adr/**/*.md`; diagrams; release / version bump; compliance contracts; peer review; dev handoff — must route through the matching `sa-skills:architecture-*` skill, because the skills enforce validation gates (Section 3 enforcement, downstream propagation, source attribution, drift detection) that direct edits silently skip. Before v3.19.0, this routing relied on three soft layers (the `architecture-docs` SKILL.md description, the project's CLAUDE.md trigger table, and the SKILL.md descriptions of sibling skills); all three were hints the model could bypass.

v3.19.0 adds a `UserPromptSubmit` hook that fires on every prompt at the harness level (before Claude reads the prompt), stat's `$CLAUDE_PROJECT_DIR/ARCHITECTURE.md`, and — when present — injects a one-paragraph `additionalContext` system-reminder steering the model to the right `sa-skills:architecture-*` skill. The hook is POSIX shell (~25 lines, ~1–5 ms cold start), exits silently with zero output when no `ARCHITECTURE.md` is present, never blocks, and never invokes an LLM.

Three coordinated additions ship together:

1. **Hook script** — `hooks/route-architecture-docs.sh` — POSIX shell, executable, emits the documented UserPromptSubmit `hookSpecificOutput.additionalContext` JSON shape when `ARCHITECTURE.md` exists, exits silently otherwise.
2. **Settings registration** — `.claude/settings.json.example` adds the `UserPromptSubmit` entry with a leading `// HOOKS — v3.19.0+` comment. (At ship time, this entry sat alongside the v3.14.1 `PostToolUse` editlog tracker; the tracker was retired in v3.19.1 once it was confirmed silently broken since v3.14.1.)
3. **Merger refactor** — `scripts/setup-permissions.ts` replaces the single-string `SA_SKILLS_HOOK_MARKER` constant with a `SA_SKILLS_HOOK_MARKERS` list, and the per-command dedup test now matches by *the specific marker for this command* instead of "any sa-skills marker present in target." (v3.19.1 reused this multi-marker list to add a parallel `SA_SKILLS_HOOK_REMOVAL_MARKERS` cleanup pass.)

Existing projects re-running `/setup` after upgrading get the new hook merged into their `.claude/settings.json` non-destructively. `commands/setup.md` documents the v3.19.0 changes inline. Idempotent — re-running `/setup` reports `Hooks: added 0 · already present 2`.

**Files**: `hooks/route-architecture-docs.sh` (new, ~25 lines), `.claude/settings.json.example` (+13 lines), `scripts/setup-permissions.ts` (marker refactor, +20 / -8), `commands/setup.md` (v3.19.0 section, +9 lines), version bumps in `.claude-plugin/{plugin,marketplace}.json`, `package.json`, `README.md` badge / verification line. No skill behavior or skill workflow changed. All 405 unit tests pass; typecheck clean.

---

### v3.18.0 (Previous Release) ✅
**feat: cache-optimized Phase 1.5 fan-out — stable-prefix template + read-once foundational inlining + token-grep pruning**

The Section 3 (Architecture Principles) gate's downstream-impact propagation (`architecture-docs` Phase 1.5) fans the `principle-quality-reviewer` sub-agent (Opus, by design — "optimized for reliability, not cost") out across every downstream file in batches of 4. Before this change, each parallel sub-agent independently re-read the four foundational files (`docs/01-system-overview.md`, `docs/02-architecture-principles.md` post-edit, `docs/03-architecture-layers.md`, `docs/06-technology-stack.md`) plus a `Glob` over `adr/*.md` — the same ~4 KLOC of byte-identical content was loaded N times per S3 edit, and the per-call discriminator (`downstream_file`) sat in the middle of the prompt body, splitting Anthropic's prompt cache prefix on every call. Even worse, the fan-out fired against **every** downstream file in the reverse dependency table (S4–S11 + every component) regardless of whether the file referenced anything that had actually changed.

Three coordinated changes attack both the per-call cost and the call count:

1. **Stable-prefix dispatch template** — `skills/architecture-docs/SKILL.md` Phase 1.5 — orchestrator now reads the four foundational files once and inlines their content as five XML-style blocks (`<principles>`, `<system_overview>`, `<arch_layers>`, `<tech_stack>`, `<adr_index>`) at fixed positions in every sub-agent prompt. The `downstream_file` parameter is the LAST line, the only thing that differs across the batch. Calls 2..N of each batch now hit Anthropic's prompt cache for the entire prefix.
2. **Inlined-blocks fast path on the reviewer** — `agents/reviewers/principle-quality-reviewer.md` Step 1 — agent prefers the inlined-blocks fast path when present (no re-Read of foundational files), with the original path-based reads kept as a fallback for `first-write` / `edit-delta` modes and direct invocations outside the orchestrator. The Input Parameters table documents both paths and the precedence.
3. **Pre-fan-out token-grep pruning** — `skills/architecture-docs/SKILL.md` Phase 1.5 step 2 — before dispatching, the orchestrator builds a token set from the diff (changed principle names, ADR IDs cited in the diff, tech tokens added/removed that intersect `docs/06-technology-stack.md`) and `grep`s each candidate downstream file for any token. Files with zero hits are skipped with a non-blocking Phase 2 note ("no token references to changed principles, cited ADRs, or affected tech; semantic review skipped"); only files that token-match get a sub-agent call. The empty-token-set case (e.g., pure prose rephrase with no concrete tokens) falls back conservatively to the full fan-out so recall is preserved on edits with nothing concrete to grep against.
4. **Cache-warm sequencing (first batch only)** — `skills/architecture-docs/SKILL.md` Phase 1.5 step 3 parallelism note — within the first batch of each fan-out, the orchestrator fires one sub-agent call first and waits for it to settle before firing the remaining 1–3 calls in parallel. The first response writes the stable prefix into Anthropic's prompt cache; subsequent calls (in the same batch and in every later batch within the 5-min TTL) read the prefix from cache instead of re-paying it. Costs ~30–60s of extra wall-clock on the first batch only; subsequent batches dispatch full-parallel as before.
5. **Lazy-Load Contract** — `skills/architecture-docs/SKILL.md` adds a new section (after AUTOMATIC WORKFLOW DETECTION) that codifies which large reference guides (`ARCHITECTURE_DOCUMENTATION_GUIDE.md` 2K+ lines, `ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md` 1.1K, `MERMAID_DIAGRAMS_GUIDE.md` 1K, `RELEASE_WORKFLOW.md` 687, etc.) load only when their workflow fires. Documents the rule explicitly so neither the model nor a future maintainer pre-loads guides "to be ready" — speculative loads burst the working set and force prefix re-evaluation on every tool call.

Backward-compatible: any caller that still passes paths only (older orchestrator versions, ad-hoc invocations) continues to work unchanged via the fallback path. The pruning step is fail-open — `grep` errors degrade to the full fan-out with a one-line warning. No skill workflow or output format changed; reliability bias preserved.

Combined effect on the median S3 edit: the call count drops (typically 2–4 sub-agents instead of 8 + N components), and the calls that do fire spend 1× cold + (N−1)× cached prefix instead of N× full-cost.

**Files**: `skills/architecture-docs/SKILL.md` (Phase 1.5 audit procedure, ~95 lines added: token-set extraction extension to step 1, new step 2 pruning, renumbered tail), `agents/reviewers/principle-quality-reviewer.md` (Input Parameters table + Step 1 Load Context, ~25 lines added). No code touched. All 405 unit tests pass.

---

### v3.17.3 (Previous Release) ✅
**fix: harden semicolon rule in DIAGRAM-GENERATION-GUIDE (covers Notes + parenthetical sub-clauses)**

`skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` already forbade `;` in sequence-diagram message labels, but the rule wording was too narrow and the Pre-Write Validation row's scan hint missed two real-world cases that broke generated diagrams: (a) a `;` inside a parenthetical sub-clause of a message (e.g. `A->>B: existing payment path (sync; ORQPagos2002 stateless)` → Mermaid parse error *"Expecting SOLID_ARROW … got NEWLINE"*), and (b) a `;` inside `Note over … :` / `Note left of … :` / `Note right of … :` bodies. Three localized edits — the DO NOT bullet now spans message labels **and** Note text **and** parenthetical sub-clauses with negative + positive examples for each; the validation table row is broadened with a scannable regex; the Validation Procedure step 1 explicitly requires scanning Note bodies. Documentation hardening only — no skill behavior, no workflow change.

**Files**: `skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md` (10 lines: +7/-3). No code touched, no validators changed.

---

### v3.17.2 (Previous Release) ✅
**fix: drop incorrect Ctrl+R claim from `/setup` final reminder**

`commands/setup.md` Step 7 (Final reminder) printed `Restart Claude Code (or press Ctrl+R) to reload settings.` — the Ctrl+R parenthetical was wrong: Claude Code's Ctrl+R is bound to `HistorySearch`, not settings reload. On Linux the chord is also intercepted by bash readline's reverse-history-search before it ever reaches Claude Code, so the instruction misled users who tried it. The reminder now reads `Restart Claude Code to reload settings.` — accurate, terminal-agnostic.

**Files**: `commands/setup.md` (1 line). No skill behavior or workflow change. Existing tests unaffected (no code touched).

---

### v3.17.1 (Previous Release) ✅
**feat: ADR title and Problem Statement length constraints (blocking gate)**

Adds two universal length rules enforced at every ADR write — first-time create (Workflow 2) and bulk generation from Section 12 (Workflow 1):

- **Title ≤ 50 characters** — the text after `# ADR-NNN: ` is capped at 50 chars (the prefix itself is not counted). Example: `Dynatrace as Mandatory Observability Platform` (45) passes; `Adopt Dynatrace SaaS as the Mandatory Observability Platform for All Production Workloads` (90) blocks.
- **Problem Statement ≤ 200 characters** — the body of the `### Problem Statement` subsection (between the heading and the next `###` or `---`, with HTML comments stripped) is capped at 200 chars. Forces compose-then-compress: internally answer the four scaffolding questions, then write one tight sentence.

Both rules apply to all scopes (Institutional and User/Project) and BLOCK the write on violation. Cap at 3 revision rounds; round 4 recommends splitting the ADR — no waivers, because a decision that cannot fit is one decision too many.

**Documentation**: new "Title and Problem Statement Length Constraints" section in `ADR_GUIDE.md` with pass/fail examples and exact detection commands. Inline HTML comments in `adr/ADR-000-template.md` surface the rules at authoring time.

**Files**: `skills/architecture-definition-record/SKILL.md` (Steps 1.5a + 2.4b), `ADR_GUIDE.md` (new section + updated embedded template), `adr/ADR-000-template.md` (HTML comments). No code changed. All 405 existing tests pass.

---

### v3.17.0 (Previous Release) ✅
**feat: Two-layer Section 3 (Architecture Principles) Enforcement Gate — no-code, reliability-first**

Hardens the `architecture-docs` skill across both first-write and edit paths by replacing the advisory Section 3 validation checklist with a two-layer enforcement gate that runs on every write to `docs/02-architecture-principles.md`.

**Layer 1 — Prescriptive checklist** (`skills/architecture-docs/PRINCIPLE_VALIDATION.md`, NEW): single source of truth for principle validation rules. 14 rule IDs covering structural, hygiene, semantic-lite, ADR-reference, cross-principle, and architecture-type-specific concerns. Each rule documents an exact `grep` command, a pass criterion, and a fail-message template. The model executes rules in order and emits a `PRINCIPLE_VALIDATION_REPORT` block. **Anti-self-attestation rule**: every finding MUST quote the grep output verbatim — claims without evidence are treated as FAIL by the orchestrator. Includes a per-architecture-type matrix (Microservices → circuit breakers, BIAN → service domains, etc.) and Appendix A (mandatory-field placeholder map for first-write / edit / release scopes).

**Layer 2 — Semantic reviewer** (`agents/reviewers/principle-quality-reviewer.md`, NEW; model: opus): runs after Layer 1 passes. Three modes — `first-write`, `edit-delta`, `downstream-impact`. Seven `checkType` judgments (`decision-rule`, `specificity`, `tradeoff-honesty`, `adr-alignment`, `cross-principle`, `conflation`, `type-sanity`) catch failures the regex layer cannot: paraphrased platitudes, tech-name-dropping, trade-offs that look quantified but aren't, ADR citations to nonexistent files, type-incoherent advice, conflations of quality attributes (Section 1) with principles (Section 3). Hallucination guard: every cited ADR file must exist. Fail-open: timeouts → PASS-with-warning, never block forever.

**Phase 1.5 Principle Alignment Audit** (added to `SKILL.md` Downstream Documentation Propagation): when `docs/02-architecture-principles.md` itself is edited, fan out the `principle-quality-reviewer` sub-agent in `mode: downstream-impact` over each downstream file (S4–S11 + every component) in parallel batches of 4. Findings flow into the Phase 2 approval checklist labeled `[principle-impact]`. Skips silently on whitespace/formatting-only diffs.

**ADR reference enforcement**: the advisory "Trade-offs align with ADR candidates — should reference" is now MUST. Each principle's Implementation OR Trade-offs must contain at least one ADR link or carry the explicit `<!-- NO_ADR_GOVERNS -->` sentinel.

**Quality Attribute vs. Principle disambiguation** (added to `ARCHITECTURE_DOCUMENTATION_GUIDE.md` before Section 3): explicit comparison table (outcomes vs. decision rules) and the "verb of choice" rule. Closes the conflation gap that `P-QA-CONFLATION-01` enforces operationally.

**Placeholder Elimination Gate** (new Step 5.7 in `ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md`): scans the mandatory-field map for `[To be defined]` / `[TBD]` / `<TODO>` / `TODO:` etc. Any match in a mandatory field BLOCKS Step 6 (ADR delegation).

**Reliability stance**: this release optimizes for the **correctness of produced documentation**, not for token cost. Deeper context loads, more sub-agent calls, hard blockers where there were soft warnings, mandatory grep-output quoting to prevent self-attestation, max-3-round revision loops with explicit user escalation. Pin to v3.16.1 if you need a fast/cheap path.

**No new dependencies**: pure Markdown changes — the existing `Bash(grep:*)` permission is the only execution surface (now scoped explicitly via `Bash(grep:*)`, `Bash(rg:*)`, `Bash(awk:*)`, `Bash(ls:*)` permissions added in `.claude/settings.json.example`).

---

### v3.16.1 (Previous Release) ✅
**docs: Institutional ADR content discipline — codify project-agnostic rules for ADR-001..100 in `architecture-definition-record`**

Adds a new "Institutional ADR Content Discipline" section to `skills/architecture-definition-record/ADR_GUIDE.md` (between "ADR Scope" and "ADR Template"). The section enumerates the project-specific patterns that institutional ADRs (numbers 001–100) must NOT contain — "Institutional Inheritance Note" headers, "Section 3 — Project Application" tables, specific component names (Inbox Hub, omn-mfa, sda-msa-payments-gateway, etc.), specific operator / carrier / brand names (Claro, Movistar, Tuenti, CNT), specific feature names, project budgets ("$276,411"), project deadlines ("MVP June 30, 2026"), user counts ("7M mobile users / 300K web users"), and cross-references to project ADRs (ADR-101+). Each forbidden pattern is paired with the generic phrasing that replaces it ("platform", "service team", "the workload namespace", "the bank's customer base", "platform delivery timelines", etc.). Captures the recent rewrite of all 14 institutional ADRs as a durable rule rather than oral tradition.

**Enforcement at the workflow level**: cross-references added at two gates inside `architecture-definition-record/SKILL.md`:

- **Workflow 1 Step 1.5 (Generate from ARCHITECTURE.md)** — institutional content callout fires when generating any ADR with `Scope: Institutional`, instructing the generator to generalize project-specific source material from `ARCHITECTURE.md` (and optionally retain those specifics in a paired User/Project ADR).
- **Workflow 2 Step 2.4a (Create Individual ADR)** — new content gate after Step 2.4 (Load Template and Populate). When the scope chosen at Step 2.1a is `Institutional`, the gate verifies the populated content does not contain any forbidden pattern before the write happens; if it does, the skill generalizes per the new ADR_GUIDE section and confirms with the user.

Both gates fire only for institutional scope; user/project ADRs (ADR-101+) are unaffected and may continue to carry project-specific content freely. The canonical template (`adr/ADR-000-template.md`) gains a one-line HTML comment next to the `**Scope**` field pointing authors at the new guide section so the rule is visible at the moment of authoring even when the skill is not in the loop.

**Modified files**:

- `skills/architecture-definition-record/ADR_GUIDE.md` — new "Institutional ADR Content Discipline" section with forbidden-pattern table, "why it matters" rationale (translation drift creates compliance gaps when institutional standards leak project specifics), and "when project specifics belong in an ADR" guidance pointing readers to the User/Project range.
- `skills/architecture-definition-record/SKILL.md` — Workflow 1 Step 1.5 institutional content callout (line 230); Workflow 2 Step 2.4a institutional content gate (line 415–422).
- `skills/architecture-definition-record/adr/ADR-000-template.md` — inline HTML hint comment on the `**Scope**` line (invisible in rendered output, visible to template editors).

**No code changes**: pure documentation / skill-content edits. Type-check and test suites are unaffected. The numeric scope partition rule from `CLAUDE.md` ("ADR Scope Partition" — ADR-001..100 institutional, ADR-101+ user/project) is unchanged; this release adds the *content* dimension that complements the *number range* dimension.

**Migration**: none required. The rule applies to new institutional ADRs created or generated through the skill from this version forward. Existing institutional ADRs that were already rewritten to be project-agnostic continue to comply automatically. Projects with non-compliant historical institutional ADRs can run a manual review against the new ADR_GUIDE section — the skill does not retroactively rewrite already-written ADRs.

---

### v3.16.0 (Previous Release) ✅
**feat: `architecture-explorer` simplified to a structure navigator + Findings mode + consumer migration to per-X fan-out**

This release reshapes the universal `architecture-explorer` agent and migrates its three consumer skills (compliance, analysis, dev-handoff) to a new evidence-driven contract.

**1. Explorer simplification (BREAKING — internal contract)**: the v3.14.x ranking machinery is gone. 36 per-task JSON configs (`agents/configs/explorer/*.json`), the Bun CLI with 12 subcommands, the mtime-keyed `/tmp/` cache, the in-house scoring formula, gap-marker regexes, and ~18 TypeScript modules with their tests have all been deleted. The new agent uses Read + Glob only, walks the canonical layout (`ARCHITECTURE.md` + `docs/` + `adr/`), extracts `<!-- EXPLORER_HEADER -->` metadata inline, and emits a single `EXPLORE_MANIFEST` listing every doc, component, and ADR with `key_concepts`, `technologies`, `related_adrs`. Schema break: `EXPLORE_RESULT` → `EXPLORE_MANIFEST`, `schema_version` 1 → 2; per-task config / cache parameters all removed.

**2. Findings mode (Added)**: a second, mutually exclusive mode keyed on an optional `query` parameter. When provided, the agent runs Claude's Explore-agent methodology scoped to the architectural surface — plans 3–8 search terms, parallel `Grep` for every term, parallel context `Read` (`offset: anchor − 5, limit: 30`) for nearest H1/H2/H3 heading, and emits an `EXPLORE_FINDINGS` block with `files[]` carrying `matched_terms`, `matches[].line`, `heading`, and 3–5-line `excerpt`. No manifest enumeration in this mode — focuses entirely on what was asked. The agent does not answer the question; it surfaces evidence the caller synthesizes.

**3. Consumer migration to per-X findings fan-out**: the synthesis tier (Sonnet/Opus) no longer re-greps inside each generator/analysis/context-builder. Haiku pre-locates evidence at line + heading granularity. Hardcoded floors (compliance `phase3.required_files[]`, analysis per-lens base file lists) stay as guarantees; findings ADD line-level evidence on top.

- **Compliance** — Step 3.2.5 fans out per-contract findings calls keyed on each domain config's `key_data_points[]` (already 6–10 vocab terms per contract). Generator consumes `EXPLORE_FINDINGS`, reads `phase3.required_files[]` (floor) plus `findings.files[]` using `matches[].line`/`heading`/`excerpt` as placeholder-extraction starting points. Validators unchanged — they still use their hardcoded read lists.
- **Analysis** — Step 2.5 fans out per-analysis findings calls keyed on a hardcoded vocabulary map (8 terms × 10 lenses, lifted from each spec's "Evidence Extraction Priority" table). FILES list = `union(base_files[type], findings.files[*].file)`.
- **Dev-handoff** — Step 3.4a per-component spawn now sends `component_file` AND `query: <slug>, <type>, <technologies>`. Step 3.5 input renamed `manifest` → `findings_by_component`. Context-builder PHASE 3.2 swaps in-builder name+type+technology grep for findings-driven slicing; per-component fallback to v3.13.0 in-builder grep when that slug's explorer call failed. Agent v1.2.0 → 1.3.0. Phase 7 telemetry adds the new findings-evidence line.
- **Explorer agent** v3.0.0 → 3.3.0 — `component_file` + `query` may be passed together; the agent emits a `focus_component` block alongside findings so dev-handoff per-component fan-out keeps its ADR allowlist.

**4. CLAUDE.md guidance refresh**: the injected `sa-skills:architecture-pointer` block in project CLAUDE.md is rewritten around the manifest-vs-findings two-mode model. Decision tree for re-triggering the explorer is keyed on whether the prior block in conversation is `EXPLORE_MANIFEST` vs `EXPLORE_FINDINGS`. `/setup` now also documents the v3.16.0 changes.

**Degraded mode**: any explorer call returning `status: FAILED` or empty `files[]` triggers per-unit fallback to the hardcoded floor (compliance → `phase3.required_files`; analysis → base FILES; dev-handoff → v3.13.0 in-builder grep slicing). All three skills still produce output; no run aborts on explorer failure.

**Migration**: no project-side action required. Existing projects re-running any compliance / analysis / dev-handoff skill after upgrading get the new behavior automatically. The `Agent(sa-skills:architecture-explorer)` permission grant is unchanged. The `/tmp/architecture-explorer/<project_hash>/` cache directory becomes orphaned and clears on reboot. Compliance contracts, analysis reports, and handoffs regenerate identically — the manifest carries everything the previous `EXPLORE_RESULT` did, plus the full corpus listing for downstream domain-driven selection; findings supply pinpointed excerpts the synthesis tier reads instead of full files.

**Verification**: `bun run typecheck` clean. `bun test` 405/405 pass.

---

### v3.15.1 (Previous Release) ✅
**fix: Avro / Protobuf detection misses when wire format is documented outside the canonical 5 fields**

The `handoff-context-builder` resolver scanned only `**Type:**`, `**Technology:**`, `**Description:**`, `**Communicates via:**`, `**Deploys as:**` of each component descriptor when deriving `asset_types`. Real-world component files commonly document the Kafka wire format ("Avro envelope", "Avro — schema-registry validated") in three places the resolver did not read: the `<!-- EXPLORER_HEADER -->` `technologies:` line, the inline `Subscriptions` / `Produces` / `Topics` tables further down the component file, and `docs/05-integration-points.md`. Result: components that consume or produce Avro topics had `asset_types: [asyncapi, deployment, c4-descriptor]` instead of `[asyncapi, deployment, avro, c4-descriptor]` — `schema.avsc` was silently never generated.

**Fix — extend the resolver's `scanned_text`** to include (a) the `EXPLORER_HEADER` body (`technologies:` and `key_concepts:` lines) and (b) the cell contents of every table that follows an H2/H3 named `Subscriptions` / `Subscribes To` / `Produces` / `Consumes` / `Topics` / `Streams` / `Events`. Tighten the messaging-row asset rule to a token-explicit match: `[avro]` triggers on `avro` / `*.avsc` / `Schema Registry` (the latter only when `avro` is also present, since Schema Registry alone could be JSON Schema or Protobuf); `[protobuf]` triggers on `protobuf` / `proto3` / `*.proto` / `gRPC`. The canonical 5 fields still drive `component_type` selection — only the `asset_types` union is broadened.

**Modified files**:

- `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md` — secondary-signals list extended (new bullets 3 + 4 for EXPLORER_HEADER and inline tables); messaging-row asset rule made token-explicit.
- `agents/builders/handoff-context-builder.md` — Step 3.1.5 now builds `scanned_text` from the canonical 5 + EXPLORER_HEADER body + the Subscriptions/Produces/Topics-style table rows; messaging avro/protobuf sub-rule applied. Bundle re-synced.

**Migration**: none required. On the next handoff run, components whose `asset_types` list expands (because the resolver now sees their Avro signal) will be regenerated automatically — the payload's `asset_types` value changes → the manifest hash changes → the manifest CLI returns REGEN. Authors who used `**Asset Hints:**` as a workaround can keep them; they still take precedence.

---

### v3.15.0 (Previous Release) ✅
**feat: dev-handoff document refactored to audience-segmented Dev/QA/Ops format (TEMPLATE_VERSION 2.0.0; BREAKING)**

The Component Development Handoff document collapses from **16 flat sections to 8 audience-tagged sections** in three role tracks plus an appendix. Every Part header and section header carries `[DEV]` / `[QA]` / `[OPS]` badges (with multi-tags like `[DEV] [QA-CONTRACT]` for shared sections). Section 0 gains a Role Quick Index pointing each role to its starting sections.

Real-world feedback was that downstream teams (external dev shops, contracted QA firms, ops teams in segregated environments) wasted time discovering which of the 16 sections were relevant to their role. The new layout solves both audience targeting and conciseness without breaking self-containment — every value extracted from architecture docs stays embedded verbatim in the handoff itself, since readers may not have access to `docs/`.

**New section structure**:

| New ID | Title | Audience | Replaces (old §) |
|--------|-------|----------|-------------------|
| Section 0 | Metadata + Role Quick Index | All | §0 (gains Role Quick Index) |
| A1 | Overview, Scope, Tech & ADRs | DEV | §1 + §2 + §11 + §13 |
| A2 | API & Data Contract | DEV / QA-CONTRACT | §3 + §4 |
| A3 | Integrations & Failure Modes | DEV / OPS-CONTRIBUTES | §5 + §10 (dev-half) |
| B1 | Acceptance, Performance & Security Tests | QA / DEV-VERIFIES | §12 + §7 (latency/throughput) + §6 |
| C1 | Deployment, Config & Resources | OPS / DEV-CONTRIBUTES | §7 (resources/scaling) + §8 + §11 (runtime) |
| C2 | Observability & Runbook | OPS / DEV-ALERTS | §9 + §10 (ops-half) |
| C3 | Deliverable Assets | OPS / DEV | §14 |
| D1 | Open Questions and Assumptions | All | §15 |

**Compression rules baked into the new template**:

1. Self-contained extraction — values embedded verbatim, never linked out (architecture-doc citations are provenance only).
2. Drop fields that duplicate other handoff sections (intra-handoff redundancy).
3. Tables over prose where there is a natural key→value structure.
4. Per-section length budgets (A1 ≤60, A2 ≤100, A3 ≤70, B1 ≤80, C1 ≤70, C2 ≤70, C3 ≤25, D1 ≤30; total target ≤500 lines).

**v1 → v2 silent auto-regen**: a new Phase 3.6 in `architecture-dev-handoff/SKILL.md` performs one cheap Read on each `decision: SKIP` handoff file looking for `<!-- TEMPLATE_VERSION: 1.0.0 -->`. When found, the decision flips to `REGEN` and the file is rewritten under v2 on this run. A single summary line is printed at the top of Stage 5 (`Detected N v1 handoff(s) → forcing regen to TEMPLATE_VERSION 2.0.0`); no prompt, no `--force` required. Files lacking any TEMPLATE_VERSION marker (e.g., hand-edited files) keep their SKIP decision; users can pass `--force` to override.

**Modified files**:

- `skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md` — full rewrite to 8-section v2 layout. TEMPLATE_VERSION marker bumped to 2.0.0.
- `skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md` — full rewrite using new section identifiers, per-section length budgets, self-containment rule, and an old → new ID mapping table.
- `skills/architecture-dev-handoff/ASSET_GENERATION_GUIDE.md` — every "Section N" / "§N" handoff reference renumbered (Spanish c4-descriptor scaffold updated in lockstep).
- `agents/generators/handoff-generator.md` — embedded bundles re-synced; agent prose, validation rules, and `HANDOFF_RESULT.sections_with_gaps` example updated to new identifiers; agent version bumped to 2.0.0.
- `agents/generators/handoff-asset-generator.md` — embedded `ASSET_GENERATION_GUIDE.md` bundle re-synced.
- `agents/builders/handoff-context-builder.md` — losslessness rule reference updated.
- `skills/architecture-dev-handoff/SKILL.md` — every section reference renumbered; description frontmatter updated; new Phase 3.6 (v1 → v2 detection) added.
- `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md` — losslessness rule reference updated.
- `skills/architecture-dev-handoff/utils/manifest.test.ts` — `FROZEN_SHA` and `FROZEN_VERSION` updated to match the v2 template.
- `CLAUDE.md` — trigger-routing-table description updated to "8-section audience-segmented handoff".

**Verification**: `bun run typecheck` clean. `bun test` 493/493. `bun run bundle:check` confirms all three handoff agent bundles are byte-identical to their standalones.

**Migration**: no user action required. Existing handoffs at TEMPLATE_VERSION 1.0.0 auto-regenerate to v2 on the next dev-handoff run. To force regeneration of every component (including hand-edited v1 files), pass `--force`. `handoffs/.manifest.json` repopulates with v2 hashes automatically.

---

### v3.14.9 ✅
**fix: dev-handoff asset-type resolver — recognize Gateway/BFF/Edge, cloud K8s names (AKS/EKS/GKE/ECS/Fargate/Container/Docker), scan `**Communicates via:**` + `**Deploys as:**`, add `**Asset Hints:**` override**

A real-world handoff for a "Gateway" component on AKS publishing to Kafka produced only `[openapi, c4-descriptor]` — missing `deployment.yaml` (every other deployable component in the same catalog had one) and `asyncapi.yaml`. Root cause: the `handoff-context-builder` resolver in `PAYLOAD_SCHEMA.md` only scanned the component file's `**Type:**` field and used a vocabulary that recognized abstract terms ("Kubernetes/K8s/Pod") but not the cloud-specific terms architects actually write ("AKS/EKS/Container/Docker"). "Gateway" was not a first-class archetype at all, so Gateway components had to accidentally match through other fields — and only `GraphQL` got through for this one (in `**Description:**`), missing the K8s and Kafka signals that lived in `**Deploys as:**` and `**Communicates via:**`.

**Fix — three orthogonal changes to the resolver in `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md`** (re-bundled into `agents/builders/handoff-context-builder.md` via `bun run bundle:handoff-agent`):

1. **New "Gateway" row** mapping `Gateway, API Gateway, Edge, Ingress, Reverse Proxy` to `[openapi, deployment, c4-descriptor]` — gateways are first-class deployables and always run as containers/pods. The row encodes this directly so the resolver does not depend on the architect also writing "K8s" or "Pod" in the same component file.
2. **Wider vocabulary** in the K8s row — adds `AKS, EKS, GKE, OpenShift, ECS, Fargate, Container, Docker, containerized` to `Kubernetes, K8s, Deployment, Pod`. Also expands the API row (`Endpoint, Backend, BFF`), the database row (`Cassandra, DynamoDB`), the cache row (`KeyDB`), and the messaging row (`SQS, SNS, EventBridge, Pub/Sub, NATS`).
3. **Wider scan window** — the resolver now scans `**Type:**`, `**Technology:**`, `**Description:**`, `**Communicates via:**`, AND `**Deploys as:**` (was: `**Type:**` only, in the prompt's literal wording — though the LLM-driven implementation often read more by accident, never reliably). The instruction is now explicit. Step 3.1 of the agent extracts `communicates_via` and `deploys_as` from the component file into the structured YAML so the resolver has them in hand.

**Plus an explicit override for one-off corrections — `**Asset Hints:**`** (v3.14.9+). When present in a component file, the field's flow-sequence value (e.g. `**Asset Hints:** [openapi, deployment, asyncapi]`) **replaces** the resolver's keyword-derived list (`c4-descriptor` is still appended unless the literal `skip` is used). This is the lowest-effort escape hatch for any future resolver miss — the architect adds one line to the component file rather than waiting for a vocabulary patch. The override is reported in the orchestrator's `CONTEXT_RESULT.components[i].asset_hints_override = true`, so Phase 7 reports surface which components used it.

**Modified files**:
- `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md` — resolver instruction + table fully rewritten with multi-field scan, expanded keywords, Gateway row, Union semantics example for "GraphQL Gateway on AKS publishing to Kafka", and the `**Asset Hints:**` override spec.
- `agents/builders/handoff-context-builder.md` — re-bundled (table flows in from PAYLOAD_SCHEMA.md). Step 3.1 now extracts `communicates_via`, `deploys_as`, and `asset_hints` from the component file. New Step 3.1.5 codifies the resolver decision flow (override → keyword scan → union → c4-descriptor append). `CONTEXT_RESULT.components[i]` adds `asset_hints_override` boolean.

**No code changes; no test changes.** The resolver lives entirely in the agent's prompt (LLM-driven). The bundle integrity test (`bun test tools/bundle-handoff-agent.test.ts`) catches drift between PAYLOAD_SCHEMA.md and handoff-context-builder.md.

**Migration**: no user action required. Re-running any handoff after upgrading to v3.14.9 picks up the new resolver automatically. Components whose previous run produced a too-narrow `asset_types` list (e.g. a Gateway that only got `[openapi, c4-descriptor]` instead of `[openapi, deployment, c4-descriptor]`) will be flagged REGEN on the next run because the payload's `asset_types` value changed → the manifest hash changes → the manifest CLI returns REGEN. The new run produces the correct asset set and overwrites the under-specified handoff. To force regeneration sooner, pass `--force`.

To opt-out the resolver for a specific component (e.g., a "Gateway" that intentionally has no deployment because it runs serverless), add `**Asset Hints:** [openapi]` to the component file — the override wins.

### v3.14.8 ✅
**perf: three dev-handoff performance improvements (parallel 5A+5B cohort, decoupled `template_version`, EXPLORER_HEADER fast-path inside the explorer agent)**

A profiling pass on a single-component dev-handoff run (~26 min wall, ~340k tokens) surfaced three avoidable bottlenecks. Each ships independently — any single one is safe to revert.

**Change 1 — Phase 5 collapses Stages 5A and 5B into one parallel cohort.** The `handoff-generator` (Stage 5A, Sonnet) and `handoff-asset-generator` (Stage 5B, Sonnet/Haiku per tier) sub-agents both consume only `payload_path` after Phase 3.5 — they had no real cross-dependency. Spawning them concurrently in one orchestrator message (up to `parallelism` 5A Tasks + up to `asset_parallelism` 5B Tasks) reclaims `~min(T(5A), T(5B))` per run (~200 s on the observed run, scaling to 25–35 % off Phase 5 wall-time on multi-component runs). Stage 5C (asset-gap merge into Section 15) still runs after both cohorts. The lost gating means a 5A failure may leave orphaned asset files on disk — these are valid stand-alone artifacts, excluded from `handoffs/.manifest.json`, and surfaced in Phase 7 as `Asset written but handoff doc failed: <abs_path> — will be regenerated next run`. The new concurrency budget is `parallelism + asset_parallelism` (default 4 + 4 = 8); document this if you tune the flags.

**Change 2 — `architecture-explorer` agent gets a single-component EXPLORER_HEADER fast-path (PHASE 2.5).** Component files have carried a required `<!-- EXPLORER_HEADER -->` block with `related_adrs:` since v3.14.0 — the architect's curated answer to the same question the per-ADR LLM scoring loop produces. The optimization lives **inside the explorer agent**, not around it: the dev-handoff orchestrator still spawns the explorer the same way and still receives an `EXPLORE_RESULT`. When the orchestrator passes the new `component_file:` input parameter and `force == false`, PHASE 2.5 runs the new `bun … explore-cli.ts handoff-shortcut` subcommand which synthesizes a complete `EXPLORE_RESULT` from the header + the config's `required_sections[]` + a globbed `adr/ADR-NNN-*.md` resolution. Explorer Haiku token spend drops from ~84 k to ~10–15 k per single-component handoff. Header missing, malformed, or ADR ids unresolvable → transparent fall-through to the normal scoring path. Telemetry: `metadata.shortcut: header` plus `metadata.shortcut_unresolved_adrs: [...]` for any unresolved ADR ids; Phase 7 reports `Explorer mode: cached | header-shortcut | full-scoring` per component.

**Change 3 — `template_version` decoupled from plugin version.** Pre-v3.14.8, `manifest.ts` mixed `template_version = plugin_version` into every payload's SHA-256 fingerprint, so any plugin patch (e.g. v3.14.6 → v3.14.7) invalidated every component's manifest entry even when `HANDOFF_TEMPLATE.md` was byte-identical. v3.14.8 adds a `<!-- TEMPLATE_VERSION: 1.0.0 -->` marker to the template file and a new `manifest-cli.ts template-version <template_path>` subcommand. Plugin patches no longer trigger spurious REGEN — only an actual template content change (paired with a deliberate `TEMPLATE_VERSION:` bump) does. A new `manifest.test.ts` tripwire pins the template's SHA-256 against the declared version, forcing both fixture values to be updated together when the template is edited.

**New CLI subcommands:**
- `manifest-cli.ts template-version <template_path>` — print the parsed marker
- `explore-cli.ts read-component-header <component_file>` — print parsed header fields as JSON
- `explore-cli.ts handoff-shortcut <component_file> <config_path> <project_root> <inputs_hash>` — synthesize the full `EXPLORE_RESULT` YAML

**New TypeScript modules:**
- `skills/architecture-dev-handoff/utils/manifest.ts` — `readTemplateVersion()` exported alongside existing helpers
- `skills/architecture-explorer/utils/handoff-shortcut.ts` — `synthesizeHandoffShortcut()`; reuses `parseHeader` from `skills/architecture-explorer-headers/utils/header-detector.ts` (cross-skill import, same pattern as the existing `manifest.ts` → `architecture-compliance/utils/date-utils` import)

**Modified files:**
- `skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md` — adds `<!-- TEMPLATE_VERSION: 1.0.0 -->` marker
- `skills/architecture-dev-handoff/utils/manifest{,-cli}.ts` — `readTemplateVersion()` + `template-version` subcommand
- `skills/architecture-dev-handoff/utils/manifest.test.ts` — +6 cases (frozen-fixture tripwire + CLI smoke)
- `skills/architecture-explorer/utils/explore-cli.ts` — `read-component-header` and `handoff-shortcut` subcommands
- `skills/architecture-explorer/utils/handoff-shortcut.test.ts` — new (9 tests, round-trip-validates synthesized YAML against `parseExploreResult()`)
- `agents/builders/architecture-explorer.md` — new PHASE 2.5 section, new `component_file` input parameter, allowed Bash command #5 added; agent version bumped to 1.1.0
- `skills/architecture-dev-handoff/SKILL.md` — Phase 3.4a passes `component_file` and tracks `explorer_mode` per component; Phase 3.5 sources `template_version` via the new CLI subcommand; Phase 5 fully restructured into one cohort + Step 5.3 (gap merge) with the pre-v3.14.8 sequential 5A.x/5B.x preserved inline as a `<details>` historical reference; Phase 7 report adds `Explorer mode`, `5A failure rate`, and orphaned-asset detail lines

**Verification**: `bun run typecheck` clean. `bun test` 493 / 493 (was 484 — +9 from `handoff-shortcut.test.ts`). `bun run bundle:check` all three bundled agents in sync.

**Migration**: no user action required. Re-running any handoff after upgrading to v3.14.8 picks up all three improvements automatically.
- Existing `handoffs/.manifest.json` entries WILL be invalidated on the first run because `template_version` flips from `3.14.7` (plugin version) to `1.0.0` (the new template version). Subsequent plugin patches no longer invalidate them.
- Component files without an `EXPLORER_HEADER` block transparently fall through to normal scoring — the fast-path is purely additive. To activate the fast-path on legacy components, run `/regenerate-explorer-headers` (the full backfill).
- The Phase 5 parallel cohort is enabled unconditionally. To bound concurrency, lower `--parallelism` and/or `--asset-parallelism`.

### v3.14.7 ✅
**feat: parallel asset generation in `architecture-dev-handoff` with per-tier model pinning**

A single Sonnet `handoff-generator` sub-agent did two unrelated jobs back-to-back per component — fill the 16-section handoff document, then sequentially write every deliverable asset (OpenAPI, DDL, Kubernetes Deployment, AsyncAPI, CronJob, Avro/Protobuf, Redis key schema, C4 descriptor). For a component with 4 assets that meant 5 serial Writes inside one Sonnet spawn even though the assets are independent. It also paid Sonnet rates for the `c4-descriptor.md` — a free-form markdown one-pager that template-fills cleanly on Haiku. v3.14.7 splits asset generation into a parallel sub-agent with model tier pinned per asset.

**Architecture change** — Phase 5 of `architecture-dev-handoff/SKILL.md` is now a three-stage pipeline:

- **Stage 5A** — handoff-document fan-out. `handoff-generator` (Sonnet) now produces ONLY the 16-section handoff document. Section 14 (Deliverable Assets) is filled deterministically from the payload's `asset_types[]` array using a static filename map embedded in the agent's system prompt. Component-level batches sized by `--parallelism N` (default 4, capped 8) — unchanged from v3.14.6.
- **Stage 5B — NEW** — asset fan-out. The orchestrator builds a flat queue of `(component, asset_type)` tuples for every REGEN component and partitions into batches of `--asset-parallelism N` (default 4, capped 8, **new flag**). Each batch dispatches up to N parallel `Task(sa-skills:handoff-asset-generator, model=…)` calls. The new agent file has no `model:` frontmatter — the orchestrator passes `model:` per Task call using a frozen tier table (pattern modeled on `architecture-compliance/SKILL.md:863, 890`):
  - `code` tier → **Sonnet**: `openapi`, `ddl`, `deployment`, `asyncapi`, `cronjob`, `avro`, `protobuf`, `redis`
  - `descriptor` tier → **Haiku**: `c4-descriptor`
- **Stage 5C — NEW** — gap merge. Each `ASSET_RESULT` block returns `gaps[]` for any `# TODO: [NOT DOCUMENTED]` markers the asset agent emitted. The orchestrator does ONE `Edit` per component on the handoff document to append asset-level gaps under Section 15 (preserving today's behavior where every gap is consolidated in one place).

**New agent file**: `agents/generators/handoff-asset-generator.md` — universal single-asset generator. Tools: `Read, Write` (no Bash, Grep, or Glob — orchestrator pre-creates output directories, references are bundled). Bundles `assets/_index.md` and the full `ASSET_GENERATION_GUIDE.md` (~1050 lines) inline in its system prompt so it never reads plugin files at runtime. Returns `ASSET_RESULT` block with `status`, `asset_path`, and structured `gaps[]`.

**Modified files**:
- `agents/generators/handoff-generator.md` — bundle dropped from ~1976 to ~820 lines (removed `assets/_index.md` and `ASSET_GENERATION_GUIDE.md` BEGIN/END_BUNDLE blocks plus the c4-descriptor extraction-fields subsection). Mission rewritten. PHASE 3 (asset generation) deleted; old PHASE 4 → PHASE 3, old PHASE 5 → PHASE 4. `output_assets_dir` removed from input parameters. `HANDOFF_RESULT.assets[]` field removed (orchestrator now derives the asset list from `asset_types[]` and Stage 5B `ASSET_RESULT` statuses). Tool budget updated to `1 Read + 1 Write + 1 Read = 3 calls/spawn`. Agent version bumped to 1.2.0.
- `skills/architecture-dev-handoff/SKILL.md` — Phase 1 Step 1.0 adds `--asset-parallelism N` flag with full validation. Phase 5 fully restructured into 5A/5B/5C with new tier classification table. Phase 6 manifest update note clarifies the `assets` field source (orchestrator-computed from `asset_types[]` × Stage 5B success). Phase 7 report adds dedicated lines for handoff batches, asset batches (with Sonnet/Haiku counts), and gap-merge edits. Permissions block adds `Agent(sa-skills:handoff-asset-generator)`.
- `skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md` — Section 14 description rewritten for the deterministic-from-`asset_types[]` flow; Asset 8 extraction-fields subsection moved into the new agent's bundle.
- `tools/bundle-handoff-agent.ts` + test — BUNDLE_TARGETS now lists three agents; new entry routes `assets/_index.md` and `ASSET_GENERATION_GUIDE.md` into `handoff-asset-generator.md`.
- `.claude/settings.json.example`, `commands/setup.md`, `CLAUDE.md`, `CHANGELOG.md` — all updated. Re-running `/setup` after upgrade appends one line: `Agent(sa-skills:handoff-asset-generator)`.

**Concrete benefit**: for a 5-component run averaging 3 assets each (15 total assets), Stage 5A emits 5 Sonnet handoff Tasks (4-parallel batched = 2 message rounds), Stage 5B emits 15 asset Tasks (4-parallel batched = 4 message rounds, with ~10–12 Sonnet + 3–5 Haiku Tasks). Wall-clock for asset writing drops roughly 3× (4-way fan-out instead of in-spawn serialization). Cost on the descriptor-tier asset drops to Haiku rates.

**Verification**: `bun run typecheck` clean (no TypeScript files touched). `bun test` passes (478/478 — 1 sync test updated for the third bundle target). `bun tools/bundle-handoff-agent.ts --check` reports all three bundles in sync. The static asset → tier classification is inlined in SKILL.md Stage 5B Step 5B.1; no JSON config or runtime resolution needed.

**Migration**: no user action required. Re-running any handoff after upgrading to v3.14.7 picks up the new flow automatically. Existing `handoffs/.manifest.json` files remain valid (the `assets` field semantics are unchanged — same comma-separated filename list). Generated asset content is unchanged for code-tier assets (Sonnet still drives them) and may show stylistic variance only for `c4-descriptor.md` (now driven by Haiku, but the template scaffold and Asset Fidelity Rule are unchanged).

### v3.14.6 ✅
**feat: wire `architecture-explorer` into `architecture-analysis` — per-analysis FILES allowlists across all 10 analyses**

The analysis flow's universal `architecture-analysis-agent` (Opus) was reading the orchestrator-prepared `doc_files` corpus in full for every one of the 10 analyses. The corpus is a single shared list (`ARCHITECTURE.md` + `docs/01–09` + `adr/*` + relevant component files), so a 10-analysis run reread the entire ~20+-file corpus 10 times — even though each analysis only consumes 5–10 of those files (SPOF cares about deployment + topology; STRIDE cares about trust boundaries + data flows; Cost Hotspots cares about technology stack + scalability). The Haiku-tier `architecture-explorer` plus its 10 already-shipped `analysis-<type>.json` configs were designed exactly for that trim; v3.14.6 wires them in.

**Architecture change:**

```
Orchestrator (architecture-analysis skill)
  │
  ├── Step 2.5 — architecture-explorer (Haiku)        ← NEW: per-analysis fan-out, parallelism-batched (default 4)
  │     for each selected analysis A:
  │       task_type: analysis-<A>
  │       config_path: agents/configs/explorer/analysis-<A>.json
  │     returns EXPLORE_RESULT.relevant_files[] per analysis
  │     cache hits cost zero Haiku tokens
  │
  └── Step 3 — architecture-analysis-agent (Opus, parallel)
        receives FILES = EXPLORE_RESULT.relevant_files[] for its analysis
        reads only its trimmed allowlist (typically 5–10 files instead of 20+)
        emits the date-stamped report per the existing skeleton (template-fill contract preserved exactly)
```

**Concrete savings on a typical 10-analysis run:**

- **Opus tier**: each analysis agent reads ~5–10 files instead of the full ~20+ corpus. Cumulative across 10 analyses, roughly 50–60% reduction in input tokens for the analysis phase.
- **Haiku tier**: ~200 tokens per analysis for classification. Effectively free vs Opus.
- **Cache hits**: zero Haiku tokens on repeat runs. The cached `EXPLORE_RESULT` flows into each analysis agent unchanged.
- **Wall-clock**: analysis dashboard runs trim noticeably; the dominant cost (Opus synthesis) shrinks proportional to the file-count reduction.

**Required-section safeguard** (false-negative protection): each `analysis-<type>.json` declares the analysis's must-have files (e.g., SPOF requires `docs/03-architecture-layers.md` + `docs/09-operational-considerations.md`) as `required_sections[]`. Every analysis's `relevant_files[]` includes those files regardless of score. The runtime parser rejects any `EXPLORE_RESULT` that omits a required entry, falling back to degraded mode.

**Degraded mode** (fail-open): if any explorer call returns `FAILED`, the orchestrator falls back to the universal `doc_files` corpus from Step 1 for that one analysis. The agent runs identically — just without the trim. The user always gets a report.

**What changed** (single PR, scoped):

- `agents/builders/architecture-explorer.md` — already accepts `task_family: analysis` (no changes needed; the v3.14.0 baseline works).
- `agents/reviewers/architecture-analysis-agent.md` — Input Parameters note that the `FILES:` list is now the per-analysis `EXPLORE_RESULT.relevant_files[]` rather than the universal `doc_files`. The agent's contract is unchanged — it reads every path in FILES, in order — only the upstream selection narrowed.
- `skills/architecture-analysis/SKILL.md` Phase 3 — new Step 2.5 (per-analysis explorer fan-out, parallelism-batched 4); Step 3 spawn prompt now sources `FILES:` from the explorer's output with degraded fallback to `doc_files`.

**Verification**: `bun run typecheck` ✅, `bun test` 478/478 ✅. The 10 `analysis-<type>.json` explorer configs (shipped in v3.14.0) needed zero changes — already correctly shaped for the new flow.

**Migration**: no user action required. Re-running any analysis after upgrading to v3.14.6 picks up the new flow automatically. The report skeleton, Documentation Fidelity Rule, and EOL validation flow are all preserved; existing analysis reports on disk remain valid.

**Roadmap**: peer-review explorer wiring moves to v3.14.7; docs Q&A v3.14.8; ADR application v3.14.9.

### v3.14.5 ✅
**feat: wire `architecture-explorer` into `architecture-compliance` — per-contract relevance allowlists across all 10 contracts**

The compliance flow's 10 validators (one per contract domain) hard-coded their "Required Files" lists in their agent prompts; the universal compliance-generator pulled the same list from each domain's `agents/configs/<contract>.json` `phase3.required_files`. Both lists are correct but static — they can't adapt when, say, a project documents a security topic in `docs/06-technology-stack.md` instead of `docs/07-security-architecture.md`. The Haiku-tier `architecture-explorer` plus its 10 already-shipped `compliance-<domain>.json` configs were designed exactly for that adaptation; v3.14.5 wires them in.

**Architecture change:**

```
Orchestrator (architecture-compliance skill)
  │
  ├── Step 3.2.5 — architecture-explorer (Haiku)        ← NEW: per-contract fan-out, parallelism-batched (default 4)
  │     for each selected contract C:
  │       task_type: compliance-<C>
  │       config_path: agents/configs/explorer/compliance-<C>.json
  │     returns EXPLORE_RESULT.relevant_files[] per contract
  │     cache hits cost zero Haiku tokens
  │
  ├── Step 3.3 — Validator (Sonnet|Haiku|Opus per preset)
  │     receives EXPLORE_RESULT in prompt
  │     reads relevant_files[] (or hardcoded fallback if explorer failed)
  │     emits VALIDATION_RESULT
  │
  └── Step 3.4 — compliance-generator (universal, model per preset)
        receives VALIDATION_RESULT + EXPLORE_RESULT
        PHASE 3 Step 3.3 reads relevant_files[] (or phase3.required_files fallback)
        emits the contract per the domain template (template-fill contract preserved exactly)
```

**Concrete savings on a typical 10-contract run:**

- **Synthesis-tier reads**: each validator + generator now reads only the explorer's allowlist (typically 4–9 files per contract). Previously each pair read 5–8 hardcoded files plus ARCHITECTURE.md. The reduction is modest in *file count* but meaningful in *cross-domain reads*: when the explorer detects that, say, the Cloud contract's relevant set is `docs/02-context.md + docs/06-technology-stack.md` (because the project doesn't have a separate `docs/cloud-architecture.md`), the Cloud validator/generator reads exactly those files. Before, validators that hardcoded a file name now-not-present in the project would emit `[NOT DOCUMENTED]` for everything and the user would be forced to rename or duplicate docs to satisfy the validator.
- **Haiku tier**: ~200 tokens per contract for classification. Effectively free vs Sonnet/Opus.
- **Cache hits**: zero Haiku tokens on repeat runs. The cached `EXPLORE_RESULT` flows into the validator and generator unchanged.
- **Cost-per-10-contract-run**: dominated by the synthesis tier (template fill on Sonnet/Opus, unchanged). Validators now see more accurate file lists, so `[NOT DOCUMENTED]` markers fire only where the architecture genuinely lacks coverage — fewer false-positive gaps in the contracts.

**Required-section safeguard** (false-negative protection): each `compliance-<domain>.json` declares the validator's hardcoded file list as `required_sections[]`. Every contract's `relevant_files[]` includes those files regardless of score. The runtime parser rejects any `EXPLORE_RESULT` that omits a required entry, falling back to degraded mode.

**Degraded mode** (fail-open): if any explorer call returns `FAILED`, the orchestrator omits the `EXPLORE_RESULT` block from that contract's validator and generator prompts. Both fall back to their hardcoded / `phase3.required_files` lists. The user always gets a contract.

**What changed** (single PR, scoped):

- `agents/builders/architecture-explorer.md` — already accepts `task_family: compliance` (no changes needed; the v3.14.0 baseline works).
- `agents/generators/compliance-generator.md` — Input Parameters gain `EXPLORE_RESULT`; PHASE 3 Step 3.3 reads `relevant_files[]` when present, falls back to `phase3.required_files` when absent.
- 10 validator agents (`agents/validators/*-validator.md`) — uniform additions: Input Parameters get `EXPLORE_RESULT`; the existing "### Required Files" hardcoded list is wrapped with a note marking it as the **fallback** when the explorer block is absent.
- `skills/architecture-compliance/SKILL.md` Phase 3 — new Step 3.2.5 (per-contract explorer fan-out, parallelism-batched 4); Step 3.3 + Step 3.4 prompt templates updated to include the `EXPLORE_RESULT` block.

**Verification**: `bun run typecheck` ✅, `bun test` 478/478 ✅. The 10 `compliance-<domain>.json` explorer configs (shipped in v3.14.0) needed zero changes — already correctly shaped for the new flow.

**Migration**: no user action required. Re-running any compliance generation after upgrading to v3.14.5 picks up the new flow automatically. The contract templates, validation rubric, and `VALIDATION_RESULT` contract are all preserved; existing contracts on disk remain valid.

**Roadmap**: per-skill compliance integration was previously slated for v3.14.5 (compliance) — now done. Analysis integration moves to v3.14.6; remaining wiring (peer-review, docs Q&A, ADR application) follows.

### v3.14.4 ✅
**feat: wire `architecture-explorer` into `architecture-dev-handoff` — per-component ADR allowlists, ~50% Sonnet token reduction**

The dev-handoff flow's I/O-heavy `handoff-context-builder` (Sonnet) was reading every ADR in full to build its term index, then full-reading the matched subset per component. On a project with 38 ADRs and 8 components, that's ~38×30-line indexing reads + ~50 full ADR reads, all on Sonnet. The infrastructure to fix this has been in place since v3.14.0 (the `handoff-component.json` explorer config was already shipped); only the wiring was missing. v3.14.4 closes the loop.

**Architecture change:**

```
Orchestrator
  ├── architecture-explorer (Haiku)              ← NEW: spawned FIRST, per component, in parallel batches of `parallelism`
  │     loads handoff-component.json
  │     extra_terms = [<slug>, <type>, ...<technology>]   ← per-component differentiation
  │     scans first 60 lines + headings of every candidate (38 ADRs + 7 shared docs + components)
  │     returns EXPLORE_RESULT.relevant_files[] per component (typically 4-9 ADRs + 9 required-section docs)
  │     cache hits cost zero Haiku tokens on repeat runs
  │
  └── handoff-context-builder (Sonnet)           ← consumes per-component explore_results map
        PHASE 1: reads ONLY files in the union of all components' relevant_files[] (the 9 required docs always; ADRs only if any component flagged them)
        PHASE 2: ADR indexing pass SKIPPED — explorer already classified
        PHASE 3.3: per-component ADR allowlist taken directly from explore_results[<slug>].relevant_files[]
        CONTEXT_RESULT contract preserved exactly — handoff-generator unchanged
```

**Concrete savings on a typical run** (38 ADRs, 8 components):

- **Sonnet**: ~10K tokens saved on the indexing pass (the 38×30-line scan disappears entirely). Per-component ADR full-reads drop ~20-30% as the explorer's `score_threshold: 0.20` filters genuinely irrelevant ADRs.
- **Haiku**: ~200 tokens per component for classification. Effectively free. Cache hits on repeat runs cost zero.
- **Wall-clock**: builder phase drops from 2m+ to ~45s on the same input shape (estimated; depends on doc-tree size).
- **Cost-per-run**: dominated by handoff-generator (template fill on Sonnet, unchanged). Builder phase no longer the bottleneck.

**Required-section safeguard** (false-negative protection): `handoff-component.json` declares `ARCHITECTURE.md`, `docs/01-system-overview.md`, `docs/04-data-flow-patterns.md`, `docs/05-integration-points.md`, `docs/06-technology-stack.md`, `docs/07-security-architecture.md`, `docs/08-scalability-and-performance.md`, `docs/09-operational-considerations.md`, and `docs/components/README.md` as `required_sections[]`. Every component's `relevant_files[]` includes them regardless of score. No content is silently dropped; payload coverage is lossless.

**Degraded mode** (fail-open): if any explorer call returns `FAILED`, that component's allowlist falls back to `required_sections[]` only and the context-builder runs the v3.13.0 indexing pass for it. If every explorer call fails, the orchestrator omits `explore_results` from the builder spawn entirely — the legacy path runs as before. The user always gets a payload.

**What changed** (single PR):

- `agents/builders/architecture-explorer.md` — extends `extra_terms` support to `task_family: handoff` (was previously only `question` and `adr`).
- `agents/builders/handoff-context-builder.md` — new `explore_results` input parameter; PHASE 1 reads the union allowlist instead of fixed 7-doc set; PHASE 2 ADR indexing skipped when explorer ran; PHASE 3.3 takes per-component ADR list from explorer output. Legacy fallback preserved when `explore_results` is absent. Agent version 1.0.0 → 1.1.0.
- `skills/architecture-dev-handoff/SKILL.md` Phase 3 — new Step 3.4a (per-component explorer fan-out, parallelism-batched); Step 3.5 spawn prompt now includes the `explore_results` map. Existing manifest skip-check + dedup + payload-write logic unchanged.

**Verification**: `bun run typecheck` ✅, `bun test` 478/478 ✅. The `handoff-component.json` explorer config (shipped in v3.14.0) needed no changes — it was already correctly shaped for the new flow.

**Migration**: no user action required. Re-running any handoff after upgrading to v3.14.4 picks up the new flow automatically. The v3.13.0 manifest format and CONTEXT_RESULT contract are preserved, so existing handoff files remain valid.

**Roadmap**: per-skill compliance integration was previously slated for v3.14.4; it shifts to v3.14.5. Remaining wiring (analysis, peer-review, docs Q&A, ADR application) shifts by one accordingly.

### v3.14.3 ✅
**fix: align `enabledPlugins` key with the marketplace plugin name (`sa-skills`) + auto-migrate legacy `solutions-architect-skills@…` registrations**

`/plugin` and `/reload-plugins` were reporting `Plugin "solutions-architect-skills" not found in marketplace "shadowx4fox-solution-architect-marketplace"` after a fresh install or a re-`/setup`. The `marketplace.json` correctly registers the plugin as `sa-skills` (matching `plugin.json`'s `name` field), but four user-facing files still pointed at the older `solutions-architect-skills` name from before the v3.8.5 marketplace rename — including the `enabledPlugins` block in `.claude/settings.json.example` that `/setup` merges into every consuming project.

The plugin still ran (the cache had already extracted), but Claude Code couldn't reconcile the registration on every `/reload-plugins`, surfacing as a persistent error in `/plugin → Errors`.

**What v3.14.3 changes**:

- Aligned all four user-facing references with the marketplace name (`sa-skills@shadowx4fox-solution-architect-marketplace`):
  - `.claude/settings.json.example` `enabledPlugins` key.
  - `README.md` install one-liner.
  - `docs/INSTALLATION.md` install one-liner and the manual `enabledPlugins` snippet.
- **Auto-migration** in `scripts/setup-permissions.ts`: on `/setup`, any existing user `enabledPlugins["solutions-architect-skills@<marketplace>"]` is renamed to `sa-skills@<marketplace>` (preserving its boolean value, dropping the stale key). Idempotent — re-running `/setup` on already-migrated settings is a no-op. Unrelated user plugins under any name are preserved verbatim.
- **Loud merge summary line** when migration fires: `🔄 Migrated 1 legacy enabledPlugins entry…` so users see exactly what changed and why.

**Behavior change**: re-running `/setup` on existing v3.14.0–v3.14.2 installs silently fixes the broken registration. Fresh installs see the corrected name from the start. The `/plugin` Errors tab clears on the next `/reload-plugins`.

**Verification**: `bun run typecheck` ✅, `bun test` 478/478 ✅, end-to-end smoke (fixture project with the legacy key + an unrelated `some-other-plugin@…` entry → migration renames the sa-skills key, preserves the unrelated plugin, second run is fully idempotent).

**Migration**: re-run `/setup` once. The migration line in the merge summary confirms the rename. Then `/reload-plugins` and the previously-reported "Plugin not found" error in `/plugin → Errors` disappears.

**Roadmap**: per-skill explorer wiring shifts again — compliance integration moves to v3.14.4 (was v3.14.3 after the v3.14.2 fix bumped the chain by one).

### v3.14.2 ✅
**fix: tighten `architecture-explorer` Tool Discipline so the Haiku-tier classifier never triggers permission prompts**

A Q&A invocation surfaced that the explorer was emitting a Bash here-doc (`cat > /tmp/explore_result.yaml << EOF`) to stage its EXPLORE_RESULT before writing the cache. The user's `.claude/settings.json` deliberately allows file writes only via the Write tool (path-globbed, auditable) or via `Bash(bun *)` — `Bash(cat *)` is not allowlisted, so the redirection fired a permission prompt mid-run.

The Haiku model wasn't malicious or buggy — the prompt was. v3.14.1's Tool Discipline section banned `cat`, `head`, `tail`, `grep`, `find`, `sed`, `awk` "for reading," which left the model an opening to use them for *writing* via redirection. The cache-write step also offered "use the Write tool — the CLI accepts either" without making *those two* the only legal forms.

**What v3.14.2 changes**:

- **Reframed FORBIDDEN list** in `agents/builders/architecture-explorer.md`: bans are now unconditional (any purpose, including via redirect) and call out the redirected forms (`cat > file`, `tee`, here-doc, `>`, `>>`) explicitly.
- **New WRITES discipline block** names exactly two legal write surfaces: `bun … explore-cli.ts write-cache` (under `Bash(bun *)`) or the Write tool at the cache path. No third path is permitted.
- **Removed implied scratch-file staging**: the EXPLORE_RESULT YAML is emitted inline as the agent's final response. There is no `/tmp/explore_result.yaml` intermediate — the YAML in the agent's reasoning is the YAML the orchestrator parses.
- **Why-this-is-strict footnote** explains the permission model so future maintainers understand the lock isn't arbitrary.

**Behavior change**: Q&A workflows that route through the explorer now run silently end-to-end. The cache write goes via `bun … write-cache` (allowlisted) or the Write tool (allowlisted); no permission prompt at any stage of a fresh classification or a cache hit.

**Verification**: `bun run typecheck` ✅, `bun test` 478/478 ✅. No code or test changes — pure agent-prompt rewrite.

**Migration**: re-run `/setup` is **not required** — this fix lives entirely in the plugin agent file and takes effect on the next architecture-explorer invocation after the user picks up the new plugin version. The roadmap shifts: compliance integration moves from v3.14.2 → v3.14.3.

### v3.14.1 ✅
**feat: session-scoped EXPLORER_HEADER edit tracker + `/regenerate-explorer-headers --session` batch refresh**

The v3.14.0 release introduced `<!-- EXPLORER_HEADER ... -->` blocks that the `architecture-explorer` agent samples in the first 60 lines of every doc to classify relevance. Bodies drift faster than headers: rename a component, swap a database, add an ADR reference — the body is updated, the header silently lies, and downstream classification quietly degrades. v3.14.1 closes that feedback loop with a **batch model** (per-edit autofix was deliberately rejected; per-doc work added complexity without clear wins).

**What ships:**

- **Session edit tracker** — new utility `skills/architecture-explorer-headers/utils/session-log.ts` exposing `appendEdit`, `readSessionEdits`, `clearSessionEdits`, `retainSessionEdits`, `sessionLogPath`. Storage is `/tmp/architecture-explorer/sessions/<projectHash>-<sessionId>.editlog`, one JSONL line per Write/Edit on a `docs/**/*.md` file. `ARCHITECTURE.md`, `docs/README.md`, and paths outside `docs/**` are silently dropped (the tracker never blocks an edit). `$CLAUDE_SESSION_ID` keys per-session; falls back to a per-day token when absent.
- **CLI subcommands** — `header-cli.ts` gains `session-log {add | list | count | clear}`, all exit-0 on success, suitable for a hot PostToolUse hook path. Project root is auto-inferred from the file's nearest `CLAUDE.md` / `ARCHITECTURE.md` / `.git` ancestor; explicit `--project-root` flag available where needed.
- **PostToolUse hook (default-on via `/setup`)** — `.claude/settings.json.example` carries a new `hooks.PostToolUse[Write|Edit]` block that fires the tracker after every doc edit. Cost ~10 ms per edit (bun startup + JSONL append), no LLM, never blocks. `scripts/setup-permissions.ts` is extended to merge `hooks` into the user's settings.json with idempotent recognition of the sa-skills marker (`header-cli.ts session-log add`); existing user hooks under any matcher are preserved verbatim.
- **`/regenerate-explorer-headers --session` flag** — the existing slash command (and its skill workflow) gains a `--session` mode that reads the editlog, runs LLM-driven regeneration only on the listed files (with implicit `--force` since they're already published), and clears the editlog on success. Combine with `--dry-run` to preview without LLM calls or log mutation. Partial failures retain the failing files in the log so a re-run picks them up.
- **Orchestrator-managed TODO** — the user's project `CLAUDE.md` (managed by `scripts/setup-claude-md.ts`) gains a new `### Session edit tracker — keep EXPLORER_HEADERs honest` subsection that instructs Claude to keep one and only one task on the user-visible task list (`Regenerate EXPLORER_HEADERs for N session-edited docs (run /regenerate-explorer-headers --session)`) whenever the editlog is non-empty. The orchestrator never auto-runs the slash command — the user decides when to spend the LLM-heavy refresh.
- **Per-skill pre-flight** — `Pre-flight: Session-Edit Check` blocks added to the workflow openings of `architecture-compliance`, `architecture-analysis`, `architecture-peer-review`, `architecture-dev-handoff`, `architecture-docs` (Q&A only), and `architecture-definition-record`. When the editlog is non-empty the skill emits a loud preamble naming the affected files and the `/regenerate-explorer-headers --session` action, then continues running (non-blocking) with a `headers_status: stale-edits-pending` flag in the final report's metadata so downstream consumers can grep.

**Verification**: `bun run typecheck` ✅, `bun test` (478/478 pass — 13 new `session-log` tests on top of the 465 pre-existing) ✅, `/setup` end-to-end smoke (fresh project, idempotent re-run, hook-merge with pre-existing user hooks under same matcher) all green.

**Migration**: re-run `/setup` to merge the new hook block into your project's `.claude/settings.json`. Existing v3.14.0 installs receive the hook addition under "Hooks: added 1" in the merge summary; the rest of the merge is a no-op (already present). The new CLAUDE.md subsection is appended idempotently via the existing managed-block markers.

### v3.14.0 ✅
**feat: universal `architecture-explorer` Haiku classifier + 36 task-typed configs + `architecture-explorer-headers` skill**

The plugin's biggest cost driver pre-v3.14.0 was redundant doc reads: a 10-contract compliance run hit `ARCHITECTURE.md` + `docs/01–09` + `adr/*` ~20 times (10 validators + 10 generators × full read), ~1.8 MB of duplicate Opus traffic. The 10-analysis dashboard repeated the pattern (~1.5–2 MB). Peer-review at Hard depth, the same.

v3.14.0 introduces a universal **`architecture-explorer`** sub-agent (model: haiku, `agents/builders/architecture-explorer.md`) as the canonical front door for every doc-consuming workflow. It reads a task-typed JSON config, samples the first 60 lines + headings of each candidate file (with `ARCHITECTURE.md` read in full as the navigation index), and returns an `EXPLORE_RESULT` allowlist that downstream synthesis agents will honor in v3.14.x patches. Cache hits cost zero Haiku tokens.

**Architecture changes:**
- **New universal sub-agent** — `agents/builders/architecture-explorer.md` (Haiku). Always-on by design: there is no `--no-explorer` opt-out. The false-negative safeguard is at the config level — every config declares `required_sections[]` that bypass scoring; the runtime parser (`skills/architecture-explorer/utils/parse-explore-result.ts`) rejects any result that omits a required entry, falling back to degraded mode.
- **36 task-typed configs** at `agents/configs/explorer/`: 10 compliance (sre / security / cloud hand-tuned, 7 auto-derived from the existing `agents/configs/<contract>.json` `phase3.data_points`), 10 analysis (spof / blast-radius / bottleneck / cost-hotspots / stride / vendor-lockin / latency-budget / tech-debt / coupling / data-sensitivity), 13 peer-review (one per category in `PEER_REVIEW_CRITERIA.md`), 3 special (`handoff-component`, `architecture-question`, `adr-application`), plus `_schema.json` validating every entry.
- **TypeScript utilities** at `skills/architecture-explorer/utils/`: `explore-cache.ts` (cache + glob expansion + inputs-hash), `parse-explore-result.ts` (validates `EXPLORE_RESULT` blocks, ships its own minimal YAML subset parser — zero deps), `validate-config.ts` (runtime schema validation), `explore-cli.ts` (Bun CLI: `inputs-hash`, `check-cache`, `expand-candidates`, `write-cache`, `read-cache`, `project-hash`).
- **Auto-derivation script** `tools/derive-explorer-configs.ts` projects from existing source-of-truth into 33 of the 36 configs in one pass; `--force` flag re-derives.
- **Explorer-Friendly Headers** — new `## Explorer-Friendly Headers` section in `skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md` documents an `<!-- EXPLORER_HEADER ... -->` block (5–10 lines after the H1, listing `key_concepts`, `technologies`, `components`/`component_self`, `scope`, `related_adrs`) that newly-created `docs/NN-*.md` and `docs/components/**/*.md` files should include. Backwards-compatible: legacy docs without the header still work via fallback scoring.
- **New `architecture-explorer-headers` skill** at `skills/architecture-explorer-headers/`. Backfills EXPLORER_HEADER blocks into legacy docs. Slash command `/regenerate-explorer-headers` (with `--dry-run`, `--force`, `<path-glob>`). Bun module + CLI (`header-detector.ts`, `header-cli.ts`) provide `listDocFiles`, `hasExplorerHeader`, `findInsertionPoint`, `parseHeader`, `validateHeader`, `insertHeader`, `removeHeader`, `buildHeader`. Skill orchestrator generates the header content from each doc's actual body, inserts via Edit, validates, and reverts on failure.
- **Setup integration** — `.claude/settings.json.example` extended with `Agent(sa-skills:architecture-explorer)` + `Read/Write(//tmp/architecture-explorer/**)`. Re-running `/setup` after upgrading appends them non-destructively (existing entries counted under "already present"). Generated CLAUDE.md (via `setup-claude-md.ts`) now includes a `### Routing doc reads through architecture-explorer (v3.14.0+)` subsection telling the user's session to invoke `sa-skills:architecture-explorer` (with `task_type: architecture-question`) before bulk-reading docs for free-form questions.
- **CLAUDE.md trigger routing** — new entries for `regenerate explorer headers` / `add explorer headers` / `backfill explorer headers` route to `sa-skills:architecture-explorer-headers`.

**Per-skill integration (deferred to v3.14.x patches):**

| Patch | Skill | Work |
|-------|-------|------|
| 3.14.6 | `architecture-analysis` | Insert Step 2.5 Explore Phase; wire `architecture-analysis-agent` ✅ |
| 3.14.8 | `architecture-peer-review` | Insert Step 4.5 Explore Phase (all depths); wire `peer-review-category-agent` |
| 3.14.9 | `architecture-docs` | Q&A workflows route through explorer (`architecture-question.json`) with runtime keyword injection |
| 3.14.10 | `architecture-definition-record` | ADR create/supersede route through explorer (`adr-application.json`) |

(v3.14.1 = session-edit tracker; v3.14.2 = explorer Tool Discipline fix; v3.14.3 = legacy plugin-name rename + auto-migration; v3.14.4 = dev-handoff explorer wiring; v3.14.5 = compliance explorer wiring; v3.14.6 = analysis explorer wiring; v3.14.7 = parallel asset generation in dev-handoff with per-tier model pinning — non-explorer release. Peer-review explorer integration moves to v3.14.8.)

Each patch ships independently — `architecture-explorer` is self-contained infrastructure in v3.14.0; integrations are additive.

**Behavior changes**: none for existing flows — explorer is callable but no skill invokes it yet (per-skill wiring is the v3.14.x work). The `architecture-explorer-headers` skill is opt-in via slash command.

**Verification**: `bun run typecheck` ✅, `bun test` (465/465 pass — 78 new explorer + headers tests added on top of the 387 pre-existing) ✅, `bun run bundle:check` (both bundles in sync) ✅, 36/36 configs validate against `_schema.json` ✅, `tools/derive-explorer-configs.ts` runs cleanly ✅, `/setup` smoke test confirms idempotent CLAUDE.md generation with the new explorer subsection ✅.

### v3.13.1 ✅
**chore: reorganize `agents/` by role — generators / builders / reviewers / validators / configs**

The `agents/` directory grew to 6 top-level `.md` files + a misleadingly-named `agents/base/configs/` JSON folder + an `agents/validators/` folder over the v3.5–v3.13 series. v3.13.1 groups every agent and config under a role-based subdirectory so discovery is one folder away from "what does this agent do?":

```
agents/
├── builders/        handoff-context-builder.md          (assembles input for generators)
├── configs/         10 domain JSON files                (was agents/base/configs/)
├── generators/      compliance-generator.md             (produces content)
│                    docs-export-generator.md
│                    handoff-generator.md
├── reviewers/       architecture-analysis-agent.md      (evaluates quality)
│                    peer-review-category-agent.md
└── validators/      10 domain validator agents          (unchanged location)
```

The `base/` parent directory is gone (it only ever held configs and the name suggested base classes).

**Behavior changes**: none. Agent invocation in Claude Code uses the `name:` frontmatter (`sa-skills:<name>`), and the plugin scans `agents/**/*.md` regardless of subdirectory — no spawn paths break.

**Path changes** (transparent to skill orchestrators, but visible in `git log` and any external fork):
- `agents/handoff-generator.md` → `agents/generators/handoff-generator.md`
- `agents/handoff-context-builder.md` → `agents/builders/handoff-context-builder.md`
- `agents/compliance-generator.md` → `agents/generators/compliance-generator.md`
- `agents/docs-export-generator.md` → `agents/generators/docs-export-generator.md`
- `agents/architecture-analysis-agent.md` → `agents/reviewers/architecture-analysis-agent.md`
- `agents/peer-review-category-agent.md` → `agents/reviewers/peer-review-category-agent.md`
- `agents/base/configs/*.json` → `agents/configs/*.json`

All 16 moves use `git mv` so file history is preserved.

**Coordinated reference updates** (33 files modified):
- Runtime path consumers — `compliance-generator.md` and the 10 `validators/*-validator.md` files now Read configs from `[plugin_dir]/agents/configs/`. `tools/bundle-handoff-agent.ts` (the v3.13.0 multi-agent bundler) now targets `agents/generators/handoff-generator.md` and `agents/builders/handoff-context-builder.md`. `tools/bundle-handoff-agent.test.ts` assertions updated to match. `scripts/build-release.sh` error-message paths updated.
- Documentation — `CLAUDE.md` "Plugin Structure" section rewritten to enumerate the five subdirectories. SKILL.md path mentions in `architecture-dev-handoff`, `architecture-docs-export`, `architecture-peer-review` updated. `PAYLOAD_SCHEMA.md` `Consumers:` footer updated and re-bundled into `handoff-context-builder.md`.
- Historical CHANGELOG and README roadmap entries (v3.5.x → v3.13.0) intentionally left untouched — they accurately document past file paths at those release points.

**Verification**: `bun run typecheck` ✅, `bun run bundle:check` (both bundles in sync) ✅, 353/353 tests pass ✅, `bash scripts/build-release.sh` smoke-test ✅.

### v3.13.0 (Previous Release) ✅
**perf: dev-handoff token + wall-clock overhaul + new `handoff-context-builder` Sonnet sub-agent**

`architecture-dev-handoff` was instrumented on a captured 8-component run (~481K tokens / ~50 min wall-clock) and ten leaks were fixed in this release. Targets: ~70% token reduction on full runs, ~80% on minor-architecture-bump runs, ~40–50% wall-clock cut.

**Architecture changes:**
- **New `handoff-context-builder` sub-agent** (`agents/handoff-context-builder.md`, `model: sonnet`). Owns all I/O-heavy work the orchestrator's main context (typically Opus) used to do: reading `docs/01` + `docs/04–09` once, building an ADR term-index from each `adr/*.md` first 30 lines, per-component slicing, parsing component files into the new `## Component (structured)` YAML payload format, dedup of shared excerpts to `_shared.md`, payload writing, and SHA-256 manifest fingerprint + skip-vs-regen decision per component. Returns a `CONTEXT_RESULT:` block listing each component's `payload_path`, `payload_hash`, `decision`, `reason`, `asset_types`, `handoff_file_rel`. The orchestrator's main context never loads the ~80–120 KB shared docs + ADR corpus; the file-shuffling work runs on Sonnet at ~5× lower per-token cost.
- **Static references bundled into both sub-agents.** `agents/handoff-generator.md` now bundles `HANDOFF_TEMPLATE.md`, `SECTION_EXTRACTION_GUIDE.md`, `assets/_index.md`, `ASSET_GENERATION_GUIDE.md`. `agents/handoff-context-builder.md` bundles `PAYLOAD_SCHEMA.md`. Bundled content lives in each sub-agent's system prompt and is API-prompt-cached across all spawns within the orchestration window — saving ~300K tokens per 8-component run vs. fresh per-spawn Reads.
- **`tools/bundle-handoff-agent.ts`** — generalized bundler that handles both agents via a `BUNDLE_TARGETS` array. CI guard: `bun run bundle:check` exits 1 on drift, runs in `scripts/build-release.sh` before zipping.

**Skip-if-unchanged manifest** (`handoffs/.manifest.json`):
- SHA-256 fingerprint of `payload_file + template_version` per component. The orchestrator skips components whose fingerprint matches AND whose handoff file still exists. On the user's measured 2.13.0→2.13.1 architecture bump (3 components touched out of 8), this would mean 3 sub-agent spawns instead of 8.
- New `--force` flag bypasses the skip check.
- New `skills/architecture-dev-handoff/utils/manifest.ts` + `manifest-cli.ts` + 18-test unit suite covering hash determinism, manifest round-trip, every skip/regen condition, and the CLI smoke path.

**Parallelism + flag plumbing:**
- Sub-agent batches raised from 2 → 4 (default), with `--parallelism N` orchestrator flag accepting 1–8 (clamped on out-of-range with a warning).
- `--force` and `--parallelism` are documented in `CLAUDE.md` trigger-routing.

**Payload schema 2.0.0:**
- `## Component File` verbatim markdown blob → `## Component (structured)` typed YAML block (`component.name`, `component.type`, `component.apis`, `component.config`, `component.scaling`, …). Denser and more deterministic for sub-agents to consume. Raw fallback (`## Component File (raw)`) preserved for unfamiliar component-doc structures.
- New `shared_refs` frontmatter + `> See: _shared.md § Shared: <header>` body marker for content that appears verbatim in ≥3 component payloads (typically org-wide ADRs like ADR-012 mTLS, ADR-014 WAF). Sub-agent PHASE 0.3 resolves markers in memory before fill. ~30% smaller payloads on average for multi-component runs.

**ADR pre-grep index:**
- First 30 lines of every `adr/*.md` are read once into a term index (technologies, component names from title or visible Context, domain keywords). Per-component lookup intersects against the index and only full-Reads matched ADRs. Conservative fallback: include any ADR whose title or status header literally mentions the component or its technology even if intersection misses. Cuts orchestrator-side ADR token cost by ~60%.

**Sub-agent tool discipline tightened:**
- `agents/handoff-generator.md` PHASE 2 codifies the **Single-Write rule** — fill the entire template in memory and emit one `Write` call. Target: 4–6 tool calls per spawn, down from the 15–31 observed in v3.12.0.
- `agents/handoff-generator.md` frontmatter dropped `Bash` from `tools:` — sub-agents no longer invoke any shell command (asset directory pre-created by orchestrator, `generation_date` from payload frontmatter, references bundled).

**Removed dead code:**
- `SKILL.md` Step 0c (plugin-ref staging to `/tmp/handoff-plugin-refs/`) — obsoleted by the agent bundle. Permissions block dropped `/tmp/handoff-plugin-refs/*` grants.
- `SKILL.md` Step 2.2 (dependency-based component ordering) — sub-agents never read prior handoffs, so the sort provided no information benefit. Components now ordered by `component_index_position`.

**Migration:** first run after upgrade has no `handoffs/.manifest.json` → context-builder returns `decision: REGEN` for every component → manifest is created. No surprises. Recommended git policy: commit `handoffs/.manifest.json` so teammates also benefit from skip-if-unchanged.

**Permissions delta:** added `Read(handoffs/.manifest.json)`, `Write(handoffs/.manifest.json)`, `Agent(sa-skills:handoff-context-builder)`. Removed `Read(//tmp/handoff-plugin-refs/*)`, `Write(//tmp/handoff-plugin-refs/*)`. (Also fixed pre-existing single-slash absolute-path entries in `SKILL.md` permissions docs to the correct `//tmp/...` form.)

### v3.12.0 (Previous Release) ✅
**feat: new Asset 8 — `c4-descriptor.md` operational one-pager per component, EN/ES**

`architecture-dev-handoff` now generates an eighth asset alongside the existing OpenAPI / DDL / Kubernetes / AsyncAPI / CronJob / Avro / Protobuf / Redis bundle: a **C4 Component Descriptor** (`handoffs/assets/NN-<slug>/c4-descriptor.md`). It's the consolidated operational one-pager dev teams hand to SRE, infra, and network partners when a component ships — three sections (Description / Responsibilities / Technical Decisions) with infrastructure metadata (hostname, IP, OS, domain, middleware stack), dependency rollup, ADR references, and resource allocation (TPS sustained/peak, CPU cores, RAM GB, storage GB, latency P99, availability SLO). The descriptor is always-on for every non-skip component — no opt-out flag. Skip-list types (`Library`, `SDK`, `Utility`, `Config`, `Documentation`) get nothing, matching the existing asset skip rule.

The template ships in two language variants. The orchestrator detects the architecture-doc language once per run (via explicit `<!-- LANGUAGE: es -->` marker → Spanish section-heading inference → English default) and stamps the payload with `doc_language: en | es`. The sub-agent selects the matching template variant at asset-generation time. Values (component names, technology names, hostnames, ADR IDs) stay verbatim regardless of variant; only structural labels and the `[NOT DOCUMENTED]` / `[NO DOCUMENTADO]` markers localize. The EN/ES split mirrors the pattern already established by `architecture-blueprint`.

Asset Fidelity Rule applies identically to the new asset — zero invention. Fields not present in architecture docs get `[NOT DOCUMENTED — add to docs/09-operational-considerations.md]` (or the specific source file per the section-extraction map) rather than inferred or defaulted values. Most projects today don't capture hostname / IP / OS / domain in their architecture, so first-generation descriptors are mostly markers pointing at the right file to fill in — which is the point: the descriptor doubles as a discovery checklist for operational-metadata gaps.

**Changes:**
- `skills/architecture-dev-handoff/ASSET_GENERATION_GUIDE.md` — +177 lines. New "Always generated (except skip-list)" row in the Asset Detection Rules table; new Asset 8 section with source-data map, EN + ES scaffold templates, filling instructions, post-generation checks. Existing assets shifted +1 line due to the detection row addition.
- `skills/architecture-dev-handoff/assets/_index.md` — new `c4-descriptor` line-range entry (861-1036); updated shared policy range (1-88) and After-Asset-Generation range (1037-1050); all pre-existing ranges updated for the +1 shift; maintenance grep updated to include `^## After Asset`.
- `skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md` — added `doc_language` required frontmatter field; appended `c4-descriptor` to every non-skip component-type's `asset_types` default; added an explicit skip row documenting the `Library`/`SDK`/`Utility`/`Config`/`Documentation` exclusion.
- `skills/architecture-dev-handoff/SKILL.md` — new Step 3.3 "Detect architecture-doc language" run once per orchestration; Step 4.1 augmented to append `c4-descriptor` to `asset_types`; Step 4.4 frontmatter contract now includes `doc_language`.
- `skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md` — new "Asset 8 — C4 Component Descriptor extraction fields" table mapping each descriptor field to its primary source / fallback / missing-marker file hint.
- `agents/handoff-generator.md` — Phase 0 extracts `doc_language`; Phase 1.3 gains the language-variant selection rule; Phase 3 asset-file table includes `c4-descriptor`.

Runtime behavior is strictly additive. Existing handoff runs get one extra file per component; nothing in the 16-section handoff template changes.

### v3.11.0 (Previous Release) ✅
**feat: architecture release workflow defaults to PR flow, `--direct` opts out**

The architecture release workflow (`architecture-docs` Workflow 10 — triggered by "release my architecture", "bump architecture version", `/release-architecture`, etc.) now creates a **pull request** by default so CI, required reviewers, and branch-protection rules can gate the release before it lands on `main`. The previous direct-to-current-branch behavior is preserved behind a `--direct` flag for local-only repos, emergency hotfixes, and projects without a PR review layer.

In PR mode the workflow itself does the branching and committing — the user never has to commit manually between Step 6 (metadata edits) and Step 7 (tag). The workflow creates `release/architecture-v{version}`, commits ARCHITECTURE.md + docs/CHANGELOG.md + every docs/components/**/*.md (and archive/v{version}/ if the snapshot step ran), tags the commit with `architecture-v{version}`, pushes branch + tag to origin, and prints host-agnostic PR instructions (GitHub compare URL if origin matches `github.com`, generic prose for GitLab / Bitbucket / Azure DevOps / self-hosted). PR mode uses **standard git commands only** — no `gh`, `glab`, or host-specific CLI dependency.

Tag timing is **before-PR** — the tag lives on the release-branch commit so downstream consumers can fetch `architecture-v{version}` immediately. The PR gates what lands on `main`, not the tag. Step 8's PR-mode report includes the one-liner to move the tag onto the squash/merge commit if desired (`git tag -f … && git push --force`), otherwise the tag stays on the pre-squash commit — still fetchable, still semantically valid.

**Changes:**
- `skills/architecture-docs/RELEASE_WORKFLOW.md` — Added a "Release Channels" prelude explaining PR vs `--direct`. New Step 6.5 detects the channel from invocation arguments (default PR; silent fallback to direct when no `origin` remote exists). Step 7.5 (Archive Snapshot) moved before Step 7 so the archive is part of the PR commit in PR mode. Step 7 split into parallel **Direct** (current behavior, unchanged apart from the precondition message mentioning the PR alternative) and **PR** (new 8-substep branch/commit/tag/push/instructions flow) sections. Step 8 report gets a PR-mode variant. Implementation Notes updated to reflect dual-mode push behavior and the standard-git-only constraint. Recovery path (Step 1.5) is unchanged and runs in direct mode regardless of channel choice.
- `commands/release-architecture.md` — Documents `--direct` / `--pr` argument passthrough and the eight-step Workflow 10 skeleton including the new Step 6.5 and dual-mode Step 7.
- `CLAUDE.md` — Trigger routing table row for "release my architecture" updated to note the PR default and `--direct` opt-out.

### v3.10.1 (Previous Release) ✅
**fix: `.gitignore` helper warns when `CLAUDE.md` is already tracked by git**

Adding `CLAUDE.md` to `.gitignore` has no effect if the file is already tracked — git keeps tracking it until the user runs `git rm --cached CLAUDE.md`. Since v3.10.0 added `CLAUDE.md` to the baseline `.gitignore` entries, users with an existing checked-in `CLAUDE.md` would have silently continued to track it despite seeing `+ CLAUDE.md` in the `/setup` output.

**Changes:**
- `scripts/setup-gitignore.ts` — After a successful write, if `CLAUDE.md` was among the newly-added entries, run `git -C <project_cwd> ls-files --error-unmatch CLAUDE.md` to check tracking status. If the file is tracked, print a warning block showing the exact `git rm --cached CLAUDE.md` command. The check is conditional on `CLAUDE.md` being in the `missing` set — `Unchanged` re-runs don't re-warn. In non-git directories the check exits non-zero and the warning is silently skipped.

### v3.10.0 (Previous Release) ✅
**feat: `/setup` merges sa-skills baseline entries into `.gitignore`**

`/setup` now also ensures the project's `.gitignore` contains the three baseline entries every sa-skills project should ignore: `exports/` (Word `.docx` deliverables produced by `architecture-docs-export`), `/tmp/` (local scratch output), and `CLAUDE.md` (the per-project Claude instructions file managed by Step 5). Before this release, new users routinely committed generated `exports/*.docx` artifacts and machine-specific `CLAUDE.md` content into their repos.

**Changes:**
- `scripts/setup-gitignore.ts` — NEW Bun helper. Line-exact append-only merge: for each managed entry, checks if any non-comment line in `.gitignore` matches (trimmed, with leading-slash normalization so `/tmp/` and `tmp/` both count). Missing entries are appended under a single `# sa-skills` header (not duplicated on re-runs). Three outcomes: **Created** (no `.gitignore`), **Appended** (missing entries added), **Unchanged** (all three already present). User entries are never reordered or removed.
- `commands/setup.md` — new Step 6 invokes the helper; Step 7 is now the final Restart reminder. Notes extended with a `.gitignore` idempotency bullet.

End-to-end idempotency: a re-run on a fully-configured project now reports `0 added / N already present` for permissions, `Unchanged` for the CLAUDE.md block, and `Unchanged` for `.gitignore`.

### v3.9.1 (Previous Release) ✅
**fix: CLAUDE.md pointer block treats `ARCHITECTURE.md` as the entry point**

The v3.9.0 block body described `ARCHITECTURE.md` as an optional "single-file form" alternative to `docs/`. That was incorrect — per `skills/architecture-docs/SKILL.md:185,196-197`, **every** architecture has `ARCHITECTURE.md` at the project root as the navigation index (~130 lines) and `docs/` as a sibling holding the section files. There is no "single-file vs multi-file" choice today; the multi-file layout with `ARCHITECTURE.md` as the entry point is the only form.

**Changes:**
- `scripts/setup-claude-md.ts` — Rewrote the first two bullets of the managed block. `ARCHITECTURE.md` is now listed first and described as "the **entry point** … always start here". The `docs/` bullet drops the conditional language and adds the resolve-via-navigation-table guidance. Existing installations pick up the new wording automatically on the next `/setup` run (the block is replaced in place via its markers).

### v3.9.0 (Previous Release) ✅
**feat: `/setup` now writes a project CLAUDE.md architecture pointer block**

`/setup` previously only merged `permissions.allow`, `enabledPlugins`, and `extraKnownMarketplaces` into `.claude/settings.json`. It told Claude *what it could do* but not *where the architecture context lived* in the user's project. Running `/setup` now also drops a marker-delimited block into the project's `./CLAUDE.md` that points Claude at the canonical architecture surface: `docs/` (split layout or `ARCHITECTURE.md`), `docs/components/` (C4 Level 2 descriptors), `adr/` (Architecture Decision Records), and `handoffs/` (Component Development Handoffs).

**Changes:**
- `scripts/setup-claude-md.ts` — NEW Bun helper. Resolves `$project_cwd/CLAUDE.md` and writes a block delimited by `<!-- sa-skills:architecture-pointer:begin -->` / `<!-- sa-skills:architecture-pointer:end -->`. Four branches: **Created** (no file), **Appended** (file exists, no markers), **Updated** (markers present, content differs), **Unchanged** (markers present, content identical). Only content between the markers is ever written — surrounding user content is preserved byte-for-byte. Exits non-zero only on I/O errors or malformed marker order.
- `commands/setup.md` — Renamed Step 4 to "Report permissions merge"; added Step 5 "Generate CLAUDE.md architecture pointer" (invokes the new helper against the project CWD with failure isolated from the permissions merge); added Step 6 "Final reminder" so the "Restart Claude Code" line appears last. Extended Notes with an idempotency bullet covering the managed block.

Non-destructive and idempotent: re-running `/setup` on a configured project reports `0 added / N already present` for permissions and `Unchanged` for the CLAUDE.md block. Users can add their own content above, below, or around the managed block — the helper only rewrites what's between the markers.

### v3.8.9 (Previous Release) ✅
**refactor: remove time estimates from analysis menu**

The `sa-skills:architecture-analysis` skill displays a blocking menu of the 10 available analyses when the user invokes it. Each row previously carried a per-analysis wall-clock estimate (`~60s`, `~75s`, or `~90s`) intended to help users pick a subset. In practice those numbers never reflected real runtime — actual durations depend on architecture size, number of selected analyses, model latency, and tool-call overhead, so the estimates drifted from reality and led users to false expectations (particularly the `~90s` "All ten (parallel)" row, which rarely completed in that window).

**Changes:**
- `skills/architecture-analysis/SKILL.md` — Removed the `~60s` / `~75s` / `~90s` prefix from all 11 rows of the Step 2 analysis picker (10 individual analyses + "All ten (parallel)"). Kept the `1 agent` / `10 agents` parallelism column since it accurately reflects the number of sub-agents spawned. Labels now read e.g. `1. SPOF (Single Points of Failure) 1 agent` instead of `~60s · 1 agent`.

No behavior change — analysis parsing, agent dispatch, spec paths, and output filenames are untouched. Users still select analyses by the same single-number / comma / range / `all` syntax, and the menu still blocks until they choose.

### v3.8.8 (Previous Release) ✅
**fix: theme-agnostic colors in Blast Radius cascade diagrams**

The `sa-skills:architecture-analysis` Blast Radius report includes a Mermaid `flowchart TD` in the "Cascade Paths — Top 3 Worst Scenarios" section with red nodes for cascading failures and green nodes for contained failures. The previous palette used bare `fill:#ff6b6b` (cascading) and `fill:#95e795` (contained) inline styles, leaving Mermaid to pick the default stroke and text color from the host theme — which flipped between light and dark and produced low-contrast labels in whichever mode the renderer happened to choose.

**Changes:**
- `skills/architecture-analysis/analyses/BLAST_RADIUS.md` — Replaced the two inline `style X fill:#…` statements with Mermaid `classDef cascading` and `classDef contained` declarations. New palette: `#e57373` fill / `#c62828` stroke for cascading; `#81c784` fill / `#2e7d32` stroke for contained. Both classDefs pin `color:#000` so labels stay readable regardless of the theme the Mermaid renderer picks, and set `stroke-width:2px` for a consistent outline. The example diagram now applies the classes via `:::cascading` / `:::contained` node selectors instead of post-hoc `style` lines.

No agent or runtime changes — the `architecture-analysis-agent` reads the spec verbatim during Phase 5 report rendering, so the new palette propagates automatically on the next Blast Radius run. Other analyses (SPOF, Bottleneck, Cost Hotspots, STRIDE, Coupling, Data Sensitivity, Latency Budget, Tech Debt, Vendor Lock-in) are ASCII-only and unaffected.

### v3.8.7 (Previous Release) ✅
**feat: `/setup` slash command installs the plugin's required permissions into the project**

New plugin-level `/setup` command bootstraps a project's `.claude/settings.json` by merging the plugin's bundled `settings.json.example` into it. Non-destructive — existing user entries (custom permissions, enabled plugins, marketplaces, `model`/`theme`/`hooks`/custom keys) are preserved; only missing entries are added. Useful when installing the plugin into a new project, or when recovering a project after the v3.8.5 namespace rename introduced new `Agent(sa-skills:*)` grants that weren't in older settings.

**Changes:**
- `commands/setup.md` — NEW slash command that resolves `plugin_dir` (marketplace install, cache install, or dev clone — same `{sa-skills,solutions-architect-skills}` brace expansion as v3.8.6), then invokes the merge helper.
- `scripts/setup-permissions.ts` — NEW bun helper. Reads the example and the user's settings JSON, strips `//`-prefixed comment keys from the example, and merges three top-level sections: `permissions.allow` (array union, deduplicated), `enabledPlugins` (object merge, user wins on key conflict), `extraKnownMarketplaces` (same). Creates `.claude/` if missing. Writes with 2-space indent + trailing newline. Prints a structured summary (added / already-present counts, full list of new grants, and a warning if legacy `solutions-architect-skills:*` grants are still present).

**Usage:**
```bash
/setup
```

The helper runs through the `Bash(bun *)` permission. First-time users will see one Claude Code permission prompt when the script runs; approve once and the prompt does not repeat. Re-running `/setup` on an already-configured project is idempotent (0 added / N already present).

### v3.8.6 ✅
**fix: `plugin_dir` Glob probes now match both `sa-skills/` (marketplace install) and `solutions-architect-skills/` (dev clone)**

v3.8.5 renamed the plugin namespace but left five skills' Step 0 "Resolve Plugin Directory" probes hardcoded to `**/solutions-architect-skills/...`. On marketplace installs the cached plugin folder is now `~/.claude/plugins/cache/<marketplace>/plugins/sa-skills/`, so the Glob missed — orchestrators fell through to the marketplace or `/tmp/handoff-plugin-refs/` fallback on every run. Each probe now uses brace expansion to accept either folder name.

**Changes:**
- `skills/architecture-docs-export/SKILL.md` — Glob updated (locates `tools/docgen/generate-doc.js`).
- `skills/architecture-dev-handoff/SKILL.md` — Glob updated (locates `SKILL.md`).
- `skills/architecture-analysis/SKILL.md` — Glob updated (locates `SKILL.md`).
- `skills/architecture-icepanel-sync/SKILL.md` — Glob updated (locates `ICEPANEL_IMPORT_REFERENCE.md`).
- `skills/architecture-blueprint/SKILL.md` — Glob updated (locates `BUSINESS_TEMPLATE_EN.md`).

**Unchanged:** `skills/architecture-compliance/utils/resolve-plugin-dir.ts` was always folder-name-agnostic (uses `path.resolve` relative to its own location), so no TS changes were needed. Marketplace-fallback paths still reference the marketplace directory (`shadowx4fox-solution-architect-marketplace`), which is unaffected by the plugin rename.

### v3.8.5 (Previous Release) ✅
**refactor: rename plugin namespace from `solutions-architect-skills` to `sa-skills`**

The fully-qualified skill invocation `solutions-architect-skills:<skill>` (e.g., `solutions-architect-skills:architecture-docs`) was long enough to be cumbersome in prompts, routing tables, and permission grants. This release shortens the plugin namespace to `sa-skills`, so invocations become `sa-skills:architecture-docs`, `sa-skills:architecture-compliance`, etc. No skills are added, removed, or reorganized — only the namespace prefix changes.

**Changes:**
- `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `package.json` — plugin `name` field updated to `sa-skills`.
- All 20 files carrying qualified skill invocations (`CLAUDE.md`, `README.md`, `CHANGELOG.md`, `commands/release-architecture.md`, every `SKILL.md` that references sibling skills, `docs/INSTALLATION.md`, `docs/WORKFLOW_GUIDE.md`, `docs/MIGRATION.md`, `.claude/settings.json`, `.claude/settings.json.example`) rewritten from `solutions-architect-skills:X` to `sa-skills:X`.
- GitHub repo URLs, the repo folder name, the marketplace name (`shadowx4fox-solution-architect-marketplace`), and historical release artifacts are unchanged.

**Migration:**
- Existing project `.claude/settings.json` entries that grant `Agent(solutions-architect-skills:<name>)` must be updated to `Agent(sa-skills:<name>)`. The new `.claude/settings.json.example` reflects the rename; copy/merge it.
- Marketplace-installed plugin caches: after pulling this release, reinstall via `/plugin install sa-skills@shadowx4fox-solution-architect-marketplace` so Claude Code re-keys the plugin under the new name.
- Any saved prompt templates, CLAUDE.md trigger tables, or custom hooks that reference `solutions-architect-skills:` should be updated to `sa-skills:`.

**Known limitation:** the `plugin_dir` Glob probes (used by `architecture-dev-handoff` and `architecture-docs-export` to resolve the plugin install path) still look for `**/solutions-architect-skills/`. Dev-mode (local clone) installs still work because the repo folder name is unchanged; marketplace installs fall back to the staging path (`/tmp/handoff-plugin-refs/`) when the Glob misses. A follow-up release will update the probe to match both names.

### v3.8.4 (Previous Release) ✅
**refactor: scope architecture-dev-handoff to architecture docs only; move output to `handoffs/` at project root**

The dev-handoff skill previously sliced rows from `compliance-docs/SECURITY_*.md`, `SRE_*.md`, and `DEVELOPMENT_*.md` contracts into per-component payloads, which landed as "Compliance Gaps to Address" / "SRE Compliance Gaps" / "Development Compliance Gaps" subsections inside Sections 6, 9, and 11 of the handoff. This mixed compliance audit output into a document meant purely for implementation. Handoffs now draw **only** from `ARCHITECTURE.md`, `docs/`, and `adr/`. The output directory also moves from `docs/handoffs/` to `handoffs/` at the project root — `docs/` is the authored-architecture source, `handoffs/` is derived artifacts; keeping them separate prevents accidental coupling.

**Changes:**
- `skills/architecture-dev-handoff/` — removed Step 4.4 (slice compliance contracts), the `## Compliance Gaps` payload section, and Section 6/9/11 compliance-enrichment blocks from `SECTION_EXTRACTION_GUIDE.md`. Source comment on Section 6 template no longer mentions `compliance-docs/`. ADRs remain a source (Section 13 and Section 11 prohibited-tech scan unchanged).
- `agents/handoff-generator.md` — per-section guidance for Sections 6/9/11 no longer references `## Compliance Gaps`.
- Output-path migration — all references to `docs/handoffs/` updated to `handoffs/` across `SKILL.md`, `HANDOFF_TEMPLATE.md`, `ASSET_GENERATION_GUIDE.md`, `PAYLOAD_SCHEMA.md`, `handoff-generator.md`, and `.claude/settings.json.example` (permissions now `Write(handoffs/*)` / `Read(handoffs/*)`). Managed-index breadcrumb is now `../ARCHITECTURE.md` (one level up instead of two).
- Downstream consumers synced — `architecture-docs-export` (Handoff mode Glob + error message), `docs-export-generator.md`, `architecture-docs` (cross-reference scan + Phase 5 asset advisory), `architecture-definition-record` (ADR propagation grep + phase 5 advisory), `architecture-component-guardian` (C4 migration table — relative path recomputed since `handoffs/` is now at root depth), `architecture-onboarding` (handoffs section scan), and `README.md`.
- `skills/architecture-docs/RELEASE_WORKFLOW.md` — archive snapshot exclusion list updated to `handoffs/`.

**Migration note:** existing projects with a populated `docs/handoffs/` folder should `git mv docs/handoffs handoffs` after pulling this release and update the `Write(docs/handoffs/*)` / `Read(docs/handoffs/*)` entries in their project `.claude/settings.json` to `Write(handoffs/*)` / `Read(handoffs/*)`.

### v3.8.3 (Previous Release) ✅
**fix: architecture-dev-handoff routes mkdir/date through a bun helper to eliminate permission prompts**

The `architecture-dev-handoff` orchestrator was prompting users for `Bash(mkdir -p /tmp/handoff-payloads && date +%Y-%m-%d)` on every run. Even though `Bash(mkdir *)` and `Bash(date *)` were granted individually, the chained-with-`&&` form was treated as a new pattern by the permission matcher. This release routes both calls through a single bun helper covered by the project-wide `Bash(bun *)` grant.

**Changes:**
- `skills/architecture-dev-handoff/utils/prepare-payload-dir.ts` — **NEW** bun helper that recursively `mkdir`s the path argument and prints today's date in one call. Reuses `getLocalDateString()` from `architecture-compliance/utils/date-utils.ts` so the date logic stays single-source.
- `skills/architecture-dev-handoff/SKILL.md` — Step 0c (`/tmp/handoff-plugin-refs/` staging) and Phase 4.5 (payload write + `generation_date` capture) now invoke the bun helper. Permissions block reduced to `Bash(bun *)`.
- `agents/handoff-generator.md` — sub-agent reads `generation_date` from payload frontmatter instead of shelling out to `date`; asset directory creation goes through the bun helper. `mkdir` and `date` are now in the FORBIDDEN list.

**No behavior change** for any other skill — only the dev-handoff workflow's bash surface changed.

### v3.8.2 (Previous Release) ✅
**fix: architecture-dev-handoff plugin_dir resolution + sub-agent read-permission safety net**

Sub-agents spawned by `architecture-dev-handoff` were failing their first Read of `HANDOFF_TEMPLATE.md` when `plugin_dir` resolved to the cache install path (`~/.claude/plugins/cache/…`) but the example permission grant only covered the marketplaces manifest path. The workaround — manually staging reference files to `/tmp/handoff-plugin-refs/` — now runs automatically when needed.

**Changes:**
- `skills/architecture-dev-handoff/SKILL.md` — added **Step 0 — Resolve Plugin Directory** (Glob → marketplace fallback → readability probe → `/tmp/handoff-plugin-refs/` staging fallback). The orchestrator now verifies sub-agent read permissions on the main thread before spawning, and mirrors the 4 reference files (`HANDOFF_TEMPLATE.md`, `SECTION_EXTRACTION_GUIDE.md`, `ASSET_GENERATION_GUIDE.md`, `assets/_index.md`) to `/tmp` when the installed path is not permitted.
- `agents/handoff-generator.md` — `plugin_dir` is now always supplied by the orchestrator; the ambiguous Glob fallback that could silently resolve to the cache path was removed.
- `.claude/settings.json.example` — added `Read(~/.claude/plugins/cache/…/**)`, broadened the marketplaces grant to `**`, and added scoped `/tmp/handoff-payloads/*` + `/tmp/handoff-plugin-refs/*` read/write grants.

**No behavior change for skills that already resolved `plugin_dir` via their own Step 0** (`architecture-analysis`, `architecture-docs-export`).

### v3.8.1 ✅
**fix: sync marketplace.json + CLAUDE.md cleanup — catch-up release for v3.7.0 / v3.8.0**

Catch-up release. `plugin.json` was bumped to v3.8.0 in prior commits but `marketplace.json` and `package.json` remained at v3.6.1, so `/plugin update` never served the newer versions. This release re-synchronizes all three version files and backfills README roadmap entries for v3.7.0 and v3.8.0.

**Changes:**
- `.claude-plugin/marketplace.json` and `package.json` re-synced to match `.claude-plugin/plugin.json`
- `CLAUDE.md` trimmed from 621 → 168 lines (73% reduction): removed per-skill walkthroughs duplicated from each `SKILL.md`, fixed stale skill count (8 → 14), removed references to non-existent `bun run build:agents` script and `scripts/build-agents.ts` file, corrected `context7` tool name `get-library-docs` → `query-docs`, and corrected compliance-agent description ("10 generators" → "1 universal generator")
- Git tag `v3.8.1` created to re-establish tag sequence after v3.6.1

**No skill / agent behavior changes.** Documentation and packaging hygiene only.

### v3.8.0 (Previous Release) ✅
**perf: wrap architecture-docs-export in sonnet sub-agent to pin token cost**

`architecture-docs-export` now runs as a lightweight orchestrator that spawns a `docs-export-generator` sub-agent pinned to `model: sonnet` for the actual file reads, markdown composition, and `docgen` invocation. Export is a zero-synthesis, high-frequency task — Sonnet is the right fit, and the sub-agent wrap prevents cost drift when teams run frequent exports on Opus-configured main contexts.

### v3.7.0 (Previous Release) ✅
**feat: dev-handoff sub-agent orchestration + release-phrase auto-routing**

Two-part release:
- `architecture-dev-handoff` refactored to orchestrator + `handoff-generator` sub-agent (model: Sonnet 4.6) with 2-parallel batching. Main context stays flat even for 10+ component runs: orchestrator reads shared architecture docs once, slices per-component payloads to `/tmp/handoff-payloads/<slug>.md`, sub-agents consume their slice + template + asset guide (~25–40 KB context each).
- Release-phrase auto-routing: `/release-architecture` slash command added at `commands/release-architecture.md` — deterministic fallback that invokes `architecture-docs` Workflow 10 directly, bypassing phrase matching. Trigger Routing table in CLAUDE.md updated with the full release phrase set.

### v3.6.1 (Previous Release) ✅
**perf: batch high-fanout sub-agents to 2-parallel + post-run `/compact` hint**

Three fan-out skills previously dispatched 10–13 sub-agent Task() calls in a single message — `architecture-compliance` (10 validators + 10 generators), `architecture-peer-review` (up to 13 category agents), `architecture-analysis` (up to 10 analyses). This release caps peak parallelism at **2** across all three skills via strict batching barriers, and emits a user-visible `/compact` hint after the final report.

**Changes:**
- `architecture-compliance` Step 3.3 (validators) and Step 3.4 (generators) — strict 2-agent batches with `[BARRIER]` between each; 10 contracts = 5 sequential batches
- `architecture-peer-review` Step 5 — 2-agent batches (Light=2 batches, Medium=4, Hard=7)
- `architecture-analysis` Step 3 — 2-agent batches (10 analyses = 5 batches)
- All three skills now append a `💡 Tip: ... /compact` hint to their final completion output so users can reclaim context after document propagation

**Rationale:** Spawning 10+ parallel sub-agents concentrates cost, makes early-abort impossible, and holds all responses in the orchestrator context simultaneously. Batches of 2 reduce peak concurrent return volume (~80% drop during the return window) and allow the orchestrator to observe failures before dispatching remaining batches. The `/compact` hint addresses context-window inflation after fan-out completes.

**Tradeoff:** Wall-clock slows by ~5× on 10-wide fanouts (5 sequential batches vs 1). Total sub-agent work is unchanged; the reduction is in orchestrator context pressure and early-failure observability.

**No API/contract changes.** Pure SKILL.md orchestration edits — no TypeScript, pipeline, or agent-definition changes. Backward compatible.

### v3.6.0 (Previous Release) ✅
**feat: model preset selection for compliance contract generation (eco / balanced / critical-opus / max)**

The `architecture-compliance` skill now exposes four model presets controlling which Claude model each validator and the generator run on. Users can cut full-run token cost by up to ~90% versus the prior all-Opus baseline, while preserving reasoning depth on the audit-sensitive validators.

**Presets:**
- `eco` — Haiku × 10 validators + Sonnet generator (~90% cheaper)
- `balanced` (default) — Sonnet × 10 validators + Sonnet generator (~75% cheaper)
- `critical-opus` — Opus retained only for Security / SRE / Data & AI / Development validators; Haiku elsewhere; Sonnet generator (~60% cheaper)
- `max` — prior behavior (Opus × 10 + Opus generator)

**Invocation:** `/skill architecture-compliance <preset> <selector>` (e.g., `balanced all`, `eco SRE,Cloud,Security`, `critical-opus all`). When preset is omitted, the skill prompts via AskUserQuestion and defaults to `balanced`.

**Rationale:** Validators perform mechanical Read + Grep classification (PASS/FAIL/N/A/UNKNOWN) — Sonnet matches Opus at ~5× lower cost. The four validators kept on Opus in `critical-opus` are the ones where reasoning nuance materially affects audit evidence: security-posture wording (Argus), SLO / error-budget math (Prometheus), PII classification (Mnemosyne), EOL date synthesis via WebSearch (Hephaestus).

**Backward compatible:** Agent frontmatter unchanged (Opus fallback). The override is applied per-Task() call at the skill-orchestration layer — no sub-agent or pipeline code change needed.

**Smoke tested:** Full validator → generator → post-gen pipeline cycle on `balanced` preset against a real architecture produces valid contracts with all pipeline fields populated; Sonnet validator is measurably more rigorous on UNKNOWN classifications than Opus.

### v3.5.8 (Previous Release) ✅
**chore: all 13 sub-agents migrated to `model: opus` (Claude Opus 4.7)**

All sub-agent files under `agents/` switched from `model: sonnet` to `model: opus`. On the Anthropic API the `opus` alias currently resolves to Claude Opus 4.7 (1M context window).

**Agents migrated (13 total):**
- `agents/compliance-generator.md`, `agents/peer-review-category-agent.md`, `agents/architecture-analysis-agent.md`
- 10 domain validators under `agents/validators/` — business-continuity, cloud, data-ai, development, enterprise, integration, platform, process, security, sre

**Rationale:** Stronger reasoning improves compliance contract fidelity (template preservation + placeholder extraction), peer-review nuance across 13 category checks, validator evidence extraction with Grep-based citation, and architecture-analysis classification across the 10 risk/design lenses. The 1M context window removes split-read constraints previously planned for large ARCHITECTURE.md suites.

**Skills unchanged (14 total):** All skill orchestration patterns (parallel agent spawning, template-filling, structured output blocks) are natively supported by Opus 4.7. Skill frontmatter continues to inherit model selection from the calling session — no SKILL.md changes.

### v3.5.2 (Previous Release) ✅
**docs: architecture-analysis full README documentation — 14-skill count, analysis tables, features section**

Complete README documentation for the `architecture-analysis` skill: version badge corrected to 3.5.1/3.5.2, skills count updated from 13 to 14, `architecture-analysis` added to the skills list with a 10-analysis summary, added to the Supporting Skills table, installation verification line updated, and a full Architecture Analysis features section added between Phase 3 Compliance and Phase 4 Dev Handoff documenting all 10 analyses (both groups) with per-analysis output tables, key principles, output location, and required permissions.

### v3.5.1 (Previous Release) ✅
**feat: architecture-analysis — 5 additional analyses (Vendor Lock-in, Latency Budget, Tech Debt, Coupling, Data Sensitivity)**

Extends the `architecture-analysis` skill from 5 to 10 analyses. The dispatcher menu grows to 11 options (10 individual + "All ten"), with grouped sections for HIGH-priority and Strategic/sustainability analyses. Range selection (e.g., "6-10") and group selection ("all") are supported. All ten analyses spawn in a single message via parallel `Task()` calls.

**New analyses:**
- **Vendor Lock-in** — L1 (locked) / L2 (lock-prone) / L3 (portable) classification per component/capability, per-vendor concentration table (≥60% flag), exit cost ranking (proprietary surface × replacement effort × data export feasibility), lock severity × strategic importance heat map
- **Latency Budget** — per-flow p95 SLO decomposition into hops, Within Budget / Tight / Over Budget / Untracked classification per hop, ASCII Gantt-style budget bars, tail-latency variance flag (p99/p95 > 3×), Hops Over Budget summary table
- **Tech Debt / EOL** — T1 (EOL now) / T2 (EOL ≤6mo) / T3 (deprecated) / T4 (current) / T5 (unknown) currency tiers, EOL Hotlist table, deprecated SDK scan, ADR architectural debt table (Superseded ADRs whose replacement is not yet implemented), severity × effort heat map
- **Coupling** — per-component fan-in (Ca), fan-out (Ce), instability (I = Ce/(Ca+Ce)) metrics, K1 critical hubs (fan-in ≥5) / K2 volatile leaves (fan-out ≥5) / K3 god objects (both) / K4 cyclical dependencies with Mermaid cycle subgraphs, ASCII fan-in/fan-out distribution histograms
- **Data Sensitivity** — S1–S4 data classification per store/queue/cache, G1–G5 gap classification (unencrypted transit, at-rest, retention breach, cross-boundary leakage, undocumented), sensitive data flow Mermaid sequence diagrams for top-3 S1 flows, compliance cross-reference to `compliance-docs/SECURITY_*.md` and `DATA_AI_*.md`

**Files added:** `analyses/VENDOR_LOCKIN.md`, `analyses/LATENCY_BUDGET.md`, `analyses/TECH_DEBT.md`, `analyses/COUPLING.md`, `analyses/DATA_SENSITIVITY.md`

**Files modified:** `SKILL.md` (menu + map), `agents/architecture-analysis-agent.md` (enum), `CLAUDE.md` (10-analysis section)

### v3.5.0 (Previous Release) ✅
**feat: architecture-analysis skill — 5 HIGH-priority risk analyses (SPOF, Blast Radius, Bottleneck, Cost Hotspots, STRIDE)**

New `architecture-analysis` skill delivering a risk and design-characteristics dashboard for architects. Five analyses can be run individually or all five in parallel, each producing a date-stamped report in `analysis/` with structured findings, heat maps, and prioritized remediation recommendations. Every finding is grounded in architecture documentation with source citations; missing data is flagged as `[NOT DOCUMENTED]` rather than estimated.

**Analyses:**
- **SPOF** — Critical (full outage) / Degradation (partial-silent) / Operational SPOFs + ASCII heat map + top-5 remediations. Modeled after the worked Notification Inbox Platform v1.2.0 example.
- **Blast Radius** — per-component fan-out and cascade severity, bulkhead vs. cascading classification, Mermaid cascade paths for top-3 worst scenarios, SPOF cross-reference (`⚡ SPOF+Blast` flag for maximum risk concentration)
- **Bottleneck** — throughput chokepoints (B1–B4 tiers), HPA and connection-pool saturation risk, ASCII capacity headroom bar chart, ADR-driven bottleneck tracking
- **Cost Hotspots** — Pareto cost ranking (80% concentration rule), over-provisioning candidates, vendor concentration summary, ADR cost decision table, right-sizing recommendations with trade-off analysis
- **STRIDE** — trust boundary inventory, per-boundary 6-category threat matrix, High-Priority Threats table, compliance cross-reference with security contract gaps

**Files added:**
- `skills/architecture-analysis/SKILL.md` — dispatcher, BLOCKING menu, parallel Task() orchestration
- `skills/architecture-analysis/analyses/` — 5 analysis spec files (SPOF, BLAST_RADIUS, BOTTLENECK, COST_HOTSPOTS, STRIDE)
- `skills/architecture-analysis/templates/analysis-report-skeleton.md` — shared report structure
- `agents/architecture-analysis-agent.md` — universal analysis agent (parameterized by analysis_type)
- `CLAUDE.md` — new "Using the Architecture Analysis Skill" section
- `.claude/settings.json.example` — added `architecture-analysis-agent` + `Write/Read(analysis/*)` permissions

### v3.4.7 (Previous Release) ✅
**fix: architecture release workflow pushes git tag to origin automatically**

After `git tag -a architecture-v{version}` is created, the workflow now immediately pushes the tag to `origin`. Graceful fallbacks: reports (but does not fail) when no remote is configured, and preserves the local tag on push failure with a manual-push hint.

- **`skills/architecture-docs/RELEASE_WORKFLOW.md`**: Step 7.4 rewritten — checks for `origin` remote, pushes the tag, handles no-remote and push-failure cases without deleting the local tag.

### v3.4.6 (Previous Release) ✅
**feat: ADR institutional/user scope with reserved numbering (001–100 / 101+)**

Introduces a first-class `**Scope**` field (`Institutional` | `User`) to all ADRs, with the number range encoding the scope: ADR-001–100 are reserved for organization-wide institutional decisions (Architecture Team), and ADR-101+ are used for project-local user decisions.

- **`skills/architecture-definition-record/SKILL.md`**: Workflow 2 Step 2.1 rewritten as a scope-aware partitioned next-number lookup — asks scope first, then scans existing ADR headers to compute the correct next number in the institutional (001–100) or user (101+) range. Overflow of the institutional range is blocked with a reclassify/supersede/cancel prompt. Workflow 1 updated to extract or infer scope from the ARCHITECTURE.md Section 12 table (Case A: explicit Scope column; Case B: number-range inference with user confirmation). Workflow 5 audit output updated with a Scope column and institutional-range utilization line.
- **`skills/architecture-definition-record/adr/ADR-000-template.md`**: Added `**Scope**: Institutional | User` header field; updated File Naming Convention block with the 001–100 / 101+ partition and annotated examples.
- **`skills/architecture-definition-record/ADR_GUIDE.md`**: New "ADR Scope" subsection explaining the two scope types, their number ranges, and why scope is encoded in the number. Added `**Scope**` to the template block.
- **`CLAUDE.md`**: Added ADR Scope and numbering partition paragraph to the Architecture Definition Record skill section.

### v3.4.4 (Previous Release) ✅
**fix: bidirectional routing disambiguation — architecture-docs-export no longer captures release/publish/tag intent**

Adds a negative disclaimer to `architecture-docs-export/SKILL.md` to complement the v3.4.3 positive-routing fix in `architecture-docs/SKILL.md`. The one-sided fix wasn't sufficient — the export skill's semantic proximity to "produce final output" still caused it to win on "release my architecture". Bidirectional disambiguation makes the routing unambiguous from both sides.

- **`architecture-docs-export/SKILL.md`**: Extended `description:` with explicit NOT-clause covering release/publish/tag/freeze/bump/finalize intent, listing each mis-routed phrase and redirecting to `architecture-docs` Workflow 10. Removed unsupported `triggers:` block (was flagged by VS Code in v3.4.3 diagnostic).
- **`architecture-docs/SKILL.md`** (v3.4.3): Already contains positive routing for all release-intent phrases.

> **Note**: SKILL.md description changes take effect in **new Claude Code sessions only** — the router caches descriptions at session start. After updating, open a fresh Claude Code window before testing.

### v3.4.3 (Previous Release) ✅
**fix: architecture-docs skill routes correctly for release/publish/tag phrasing**

Fixed skill-router mis-routing where "release my architecture" (and related phrasing) fell through to `architecture-docs-export` instead of the correct `architecture-docs` skill (which owns Workflow 10 — architecture version release lifecycle).

- **Root cause**: `architecture-docs/SKILL.md` used an unsupported `triggers:` frontmatter block (flagged by VS Code). The Claude Code router matches against the `description:` field, which did not mention release, publish, tag, freeze, bump, or finalize.
- **Fix**: Removed the unsupported `triggers:` block and extended `description:` to explicitly cover the Draft → Released lifecycle (git tag `architecture-v{version}`, archive snapshot, semver bump) and added a disambiguation clause directing the router away from `architecture-docs-export` for release-intent phrases.
- **Result**: "release my architecture", "publish architecture", "tag architecture version", "freeze architecture", "bump architecture version", "ship architecture", "finalize architecture" now route to `architecture-docs` → Workflow 10.

### v3.4.2 (Previous Release) ✅
**feat: mandatory Description field (≤120 chars) added to all component templates**

All four architecture type templates and the component creation workflow now include a dedicated one-line `**Description:**` field positioned immediately after `**Communicates via:**`:

- **SECTION_5_META.md**: Description field added to all 6 layer templates (L1–L6) and the Mobile Banking App example
- **SECTION_5_3TIER.md**: Description field added to all 3 tier templates and 3 example components (User API Controller, User Service, User Repository)
- **SECTION_5_MICROSERVICES.md**: Description field added to both the microservice and infrastructure templates, and the Order Service example
- **SECTION_5_BIAN.md**: Description field added to all 5 layer templates and 2 example components (Mobile Banking App, Payment Order)
- **ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md**: Creation block updated with `**Description:**` field + enforcement note: mandatory, ≤120 characters, longer prose belongs in **Purpose**

The field provides a structured, length-bounded tagline that downstream tooling (dev handoffs, IcePanel sync, peer review) can consume without re-parsing the free-form Purpose paragraph. Component Guardian index schema is unchanged (5-column fixed table; description lives in the component file only).

### v3.4.1 (Previous Release) ✅
**docs: remove obsolete monolithic ARCHITECTURE.md leftovers from architecture-docs skill**

Full cleanup of "old Document Index + line ranges" pattern that predated the multi-file `docs/NN-*.md` migration:

- **ARCHITECTURE_DOCUMENTATION_GUIDE.md**: Removed old `→ Lines [START]-[END]` index template; rewrote Instructions for Creating the Index for multi-file structure; 3 Design Drivers examples use file-path + section-anchor citations
- **QUERY_SECTION_MAPPING.md**: Deleted 12 `Typical line range: Lines NNN-MMM` entries; rewrote Example Query Mapping Workflow to read `docs/NN-*.md` files in full (no `offset`/`limit`); updated 4 best-practice bullets
- **METRIC_CALCULATIONS.md**: Rewrote entire file — removed Section 1 (Automatic Index Updates); Section 2 (Metric Consistency) now reads `docs/01-system-overview.md` + scans `docs/` instead of using line offsets
- **DESIGN_DRIVER_CALCULATIONS.md**: Replaced "load Document Index + offset" blocks with direct file reads; 4 justification examples use file-path citations; sequential loading strategy rewritten for multi-file
- **REVIEW_AUDIT_WORKFLOW.md**: LOW.5 "Document Index Maintenance" rewritten as "Navigation Index Maintenance"; observations use file paths; 3 line-range warnings updated
- **VALIDATIONS.md**: Section Renumbering Workflow Step 3 rewritten with multi-file navigation table; `grep -n "^## [0-9]" ARCHITECTURE.md` replaced with `ls docs/*.md`; 4 checklist/best-practice entries updated
- **SKILL.md**: "Automatic Index Updates" section rewritten as "Navigation Index Updates" (no line ranges — just add/remove rows when files change)
- **ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md**: 2 Document Index references updated to the multi-file Documentation table format
- **examples/ARCHITECTURE_example_3tier.md**: Added prominent HISTORICAL warning at top marking the monolithic format as obsolete

### v3.4.0 (Previous Release) ✅
**feat: architecture versioning — release baselines, per-component versions, git tag, archive snapshots**

Complete 5-phase versioning system across the architecture docs cycle:

**Phase 1 — Metadata blocks**:
- `ARCHITECTURE.md` header now carries `<!-- ARCHITECTURE_VERSION: X.Y.Z -->` + Status/Released/Architect/Supersedes fields
- Every `docs/components/**/*.md` file has `Component Version` + `Architecture Version` + `Last Updated` after the C4 metadata block
- Updated all 4 Section 5 templates (3-Tier, BIAN, META, Microservices)

**Phase 2 — CHANGELOG**:
- `docs/CHANGELOG.md` auto-created at initial architecture creation with `[1.0.0] - Draft` entry (Keep a Changelog format)

**Phase 3 — Release Workflow (Workflow 10)**:
- New `RELEASE_WORKFLOW.md` with 8-step procedure: read version → detect changes → ask bump type → generate changelog → update all metadata → create annotated git tag → archive snapshot → report
- Semver rules: MAJOR (breaking structural), MINOR (new components/ADRs), PATCH (clarifications)
- Git tag convention: `architecture-v{version}` (namespaced). Refuses to tag on dirty working tree or existing tag
- Version Drift Detection on every skill invocation (doc version vs latest git tag)

**Phase 4 — Downstream integration**:
- All 10 compliance contract templates include `Architecture Version: [ARCHITECTURE_VERSION]` (compliance-generator resolves the placeholder)
- Dev handoff Section 0 Metadata now has `Architecture Version` + `Component Version` rows
- Traceability report header + completion message include the Architecture Version
- Component Guardian auto-updates `Last Updated` on every edit and suggests version bumps (MAJOR/MINOR/PATCH) based on change type

**Phase 5 — Archive snapshots**:
- Immutable `archive/v{version}/` snapshot of ARCHITECTURE.md + docs/ + adr/ + RELEASE_NOTES.md + `.immutable` marker
- **Non-git projects**: archive is created automatically (primary snapshot mechanism)
- **Git projects**: archive is opt-in for regulated industries / audit compliance (git tag is primary)

**Backward compatible**: Architectures without version metadata still work — downstream artifacts use `unversioned` as the value.

### v3.3.26 (Previous Release) ✅
**feat: META WebSocket L1 → L4 exception + mandatory security requirements**

- Documented that L1 (Channels) MAY connect directly to L4 (Business) via WebSocket for real-time push (market data, live alerts, streaming telemetry, trading events) — the standard top-down rule is preserved for all request/response traffic
- Mandatory security stack required on the L4 endpoint when accepting direct WebSocket connections: WSS/TLS 1.2+, token auth re-validated on reconnect, per-message authorization, origin checks, rate limiting, audit logging, input validation on all inbound frames
- Updated: `META-TO-C4-TRANSLATION.md` (Anti-Pattern 6 extended with two explicit exceptions), `SECTION_5_META.md` (Layer 1 + Layer 4 Dependencies blocks), `META-ARCHITECTURE.md` (Layer 1 Key Rules)
- Exception must be captured as an ADR and security controls documented in the L4 component file Section 9

### v3.3.25 (Previous Release) ✅
**fix: Pre-Write Validation control prevents Mermaid parse errors**

- Added Pre-Write Validation section to DIAGRAM-GENERATION-GUIDE.md with 6-row forbidden pattern checklist (HTML tags, semicolons, emoji, pipe, quotes, subgraph arrows)
- Strengthened HTML tag rules: both topology and sequence DO NOT lists now explicitly list `<br/>`, `<br>`, `<b>`, `<i>`, `<sup>`, `<span>` and "any `<...>` element"
- New Step 10.5 in Generation Workflow: validate all Mermaid/ZenUML blocks against forbidden patterns before writing
- Added mandatory Pre-Write Validation block to Step 7.1 in ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md
- Prevents `<br/>`, `;`, emoji, and other parse-breaking patterns from reaching diagram files

### v3.3.24 (Previous Release) ✅
**docs: README updated with latest skill count (13) and diagram generation changes**

- Updated "What's Included" list: 9 → 13 skills (added traceability, onboarding, icepanel-sync, definition-record)
- Rewrote Diagram Generation section: documents 4 standard diagrams (Logical View ASCII, C4 L1, C4 L2, Detailed View) + ZenUML data flow diagrams
- Added architecture-type adaptation note, theme selection enforcement, semicolon prohibition, Mermaid v11.4.1 target
- Supporting Skills table expanded with traceability, definition-record, onboarding, icepanel-sync
- New Quality Gates section highlighting peer-review, traceability, and compliance-review

### v3.3.23 (Previous Release) ✅
**fix: diagram theme selection skipped + semicolon parse error in labels**

- Theme selection (light/dark) during diagram generation was silently defaulting to light instead of asking the user — made the prompt mandatory with "MUST ask, do NOT default silently"
- Added semicolon prohibition to Mermaid compatibility rules — `;` in message/node/edge labels terminates statements causing parse errors; use `,` instead
- Applied to both topology diagrams (graph TB) and data flow diagrams (sequence) sections

### v3.3.22 (Previous Release) ✅
**fix: architecture-docs must delegate all component structural operations to guardian**

- Added Component Operations Delegation Rule to architecture-docs SKILL.md
- All structural operations on `docs/components/` (create, rename, delete, README update, migration, C4 metadata) MUST delegate to architecture-component-guardian
- Architecture-docs may read component files for context but must NOT create, restructure, or modify the component index directly

### v3.3.21 (Previous Release) ✅
**fix: C4 component folder structure missing when using inline PO Spec (option 3)**

- Fixed CLAUDE.md PO Spec gate: listed 3 options but workflow has 4 — numbering mismatch caused "option 2" confusion (inline vs async intake)
- Added CRITICAL reinforcement note at Step 5 entry: C4 Steps 4a-4g are MANDATORY for all PO Spec paths — no skipping system identification or flat file creation
- Added Step 4d-VERIFY structural validation gate before guardian invocation: verifies system folders, component files, and descriptor files exist
- Prevents flat `docs/components/` layout bypassing the required C4 system subfolder structure
- Added missing `triggers:` to architecture-component-guardian (was relying on description-only matching)
- 11 trigger phrases for guardian: `migrate components to C4`, `sync components`, `add component`, etc.
- Added component migration exclusion to architecture-docs "Do NOT activate" list

### v3.3.20 (Previous Release) ✅
**fix: C4 metadata missing from Section 5 template layers/tiers — all architecture types**

- All Section 5 templates now include `**Type:** {C4 type}`, `**C4 Level:** Container (L2)`, `**Deploys as:**`, `**Communicates via:**` in every layer/tier template, not just Layer 1
- Previously only the first layer had C4 metadata; subsequent layers used non-canonical type hints (e.g., `Application Service`, `Scenario Orchestrator`, `BIAN Service Domain`) requiring C4 migration afterward
- Updated: `SECTION_5_3TIER.md` (Tier 2, Tier 3, all 3 examples), `SECTION_5_META.md` (Layers 2–6 + example), `SECTION_5_BIAN.md` (Layers 2–5 + 2 examples), `SECTION_5_MICROSERVICES.md` (infrastructure template + example)
- Fixed stale references in `ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md`: flat component path (`docs/components/NN-name.md` → `docs/components/<system-name>/NN-name.md`) and column count (`4-column` → `5-column` index)

### v3.3.19 (Previous Release) ✅
**fix: traceability triggers use "requirements" prefix to avoid peer-review/docs collision**

- Replaced ambiguous triggers (`architecture deviation`, `deviation check`) with requirements-prefixed phrases: `requirements deviation`, `requirements coverage`, `PO spec deviation`
- Removes collision with peer-review skill ("architecture quality") and architecture-docs skill ("architecture validation")
- Updated architecture-docs exclusion to reference "requirements deviation checks"

### v3.3.18 (Previous Release) ✅
**fix: traceability skill description + architecture-docs exclusion for deviation checks**

- Rewrote traceability skill description to lead with "deviation checks, traceability reports, PO Spec coverage" for stronger signal matching
- Added "Do NOT activate for" section to architecture-docs SKILL.md redirecting deviation/traceability requests to the correct skill
- Prevents architecture-docs from hijacking "architecture deviation check" via its broad "validating/checking" description match

### v3.3.17 (Previous Release) ✅
**fix: traceability skill trigger phrases expanded to prevent architecture-docs skill hijacking**

- Added 7 compound trigger phrases: `architecture deviation`, `architecture deviation check`, `traceability report`, `traceability matrix`, `coverage check`, `PO spec vs architecture`, `check PO spec`
- Previously, "architecture deviation check" was captured by the broader `architecture-docs` skill instead of `architecture-traceability`

### v3.3.16 (Previous Release) ✅
**fix: traceability skill enforces PO Spec "what" vs architecture "how" boundary**

- Added PO Spec Scope Rule: evaluate business capabilities, not implementation paths
- Requirement extraction now strips "how" details (technologies, integration paths) from PO Spec — keeps only business capability as traceable requirement
- Architecture satisfying a requirement via a different path than PO expected is ✅ Covered (not a gap)
- Only flags gaps when the business capability itself is missing from the architecture

### v3.3.15 (Previous Release) ✅
**feat: architecture-traceability skill — PO Spec use cases vs architecture coverage report**

- New `architecture-traceability` skill comparing PO Spec use cases against architecture documentation
- Generates portable `TRACEABILITY_REPORT.md` — designed for tickets, emails, and external platforms
- Per-use-case coverage tables with evidence citations (section + quote)
- Summary statistics with per-phase breakdown and coverage percentages
- Gap Report consolidating all Not Covered and Partial items with suggested architecture sections
- Parses requirements from primary flows, alternative flows, edge cases, preconditions, postconditions, and success metrics

### v3.3.14 (Previous Release) ✅
**fix: suppress false-positive peer review finding on file prefix vs section number offset**

- Added explicit clarification to PEER_REVIEW_CRITERIA.md checks STRUCT-04, NAMING-02, and NAMING-05
- Reviewer agents no longer flag the intentional two-number offset between docs/ file prefixes (01–10) and internal section numbers (S1–S12)
- Offset is by design: S1+S2 share `01-system-overview.md`, S5 uses `docs/components/` (no numbered file)
- Updated: PEER_REVIEW_CRITERIA.md (STRUCT-04, NAMING-02, NAMING-05 "What to Look For" columns)

### v3.3.13 (Previous Release) ✅
**fix: use case count is a complexity indicator, not a hard minimum**

- Reframed use case count across all architecture-readiness scoring and elicitation files
- Previously enforced "minimum 3 use cases" as a hard constraint; now treated as architecture complexity signal
- Simple systems may need 1-2 use cases, complex ones may need 5+ — no fixed minimum
- Updated: PO_SPEC_SCORING_GUIDE.md (evaluation criteria, completeness scoring, gap analysis), REQUIREMENTS_ELICITATION_GUIDE.md (Phase 3 goal, target, phase transition), PRODUCT_OWNER_SPEC_GUIDE.md (scoring prep, self-assessment checklist), SKILL.md (Phase 3 description)

### v3.3.12 (Previous Release) ✅
**fix: NAMING-04 ADR file naming pattern false positive**

- Fixed peer review NAMING-04 check: pattern was `NNN-kebab-case.md` but correct ADR convention is `ADR-NNN-kebab-case.md`
- Previously flagged valid ADR files (e.g., `ADR-001-architecture-type-selection.md`) as incorrectly named

### v3.3.11 (Previous Release) ✅
**perf: persist peer review results as JSON + fast-path playground regeneration**

- Review data now saved to `architecture-peer-review-<date>.json` after each run (Step 6.1)
- New Step 0 fast path: "regenerate playground" reads saved JSON and skips agent evaluation entirely
- Staleness detection: compares source file timestamps to warn if architecture changed since review
- Enables instant playground regeneration without re-running 13 parallel agents (saves 40s-3min)
- JSON schema matches the playground `reviewData` structure exactly — validated with test HTML

### v3.3.10 (Previous Release) ✅
**fix: clean up old compliance contracts before regeneration**

- Added Step 3.2.1 to compliance skill: deletes existing contracts for selected types before spawning generators, preventing stale dated files from accumulating
- Previously, regenerating contracts on a different date left old files behind (e.g., both `_2026-04-04.md` and `_2026-04-06.md` coexisted)
- Post-generation pipeline cleanup (Phase 4) retained as a safety net
- Updated Regeneration Behavior documentation to reflect new pre-generation cleanup

### v3.3.9 (Previous Release) ✅
**perf: remove document panel from peer review playground**

- Eliminated the left-side document viewer from the peer review playground — findings already carry `file` + `lineRef` on each card, making full document embedding redundant
- Removed `doc_files` from Step 7 embed list in `SKILL.md` — playground agent no longer reads and embeds all architecture files
- Removed `renderDocument()`, `findingForLine()`, `docContent` state field, `#doc-panel` HTML element, and all associated CSS from `PLAYGROUND_TEMPLATE.md`
- Layout simplified to single-column: scorecard → findings → prompt output
- Runtime token savings: ~50-80K tokens per review (no more reading and embedding ~2,000 lines of architecture files as HTML)
- Net: ~143 lines removed from PLAYGROUND_TEMPLATE.md

### v3.3.8 (Previous Release) ✅
**refactor: reduce peer review token usage — eliminate duplicated content across skill files**

- Replaced 13 near-identical Task() examples in SKILL.md with a concise loop instruction referencing the Scoring Weights table (~53 lines removed)
- Removed Active Categories table and Rating Bands table from SKILL.md — both are now single references to `PEER_REVIEW_CRITERIA.md` as the source of truth
- Removed per-finding `category`, `categoryName`, `depthLevel` fields from agent output schema — orchestrator injects them during merge (Step 5.2), eliminating ~3 redundant fields per finding × 30+ findings in HARD depth
- Collapsed score formula in agent file to a reference to `PEER_REVIEW_CRITERIA.md`; removed duplicate "no findings" example (one sentence suffices)
- Removed Pre-Populating section from `PLAYGROUND_TEMPLATE.md` (duplicated SKILL.md Step 7); collapsed 13-row hardcoded scorecard example to a 2-line comment
- Net: 1,285 → 1,168 lines (−117 lines, ~11% reduction across the 4 skill files)

### v3.3.7 (Previous Release) ✅
**perf: eliminate redundant file reads in peer review playground generation**

- Removed orchestrator's Step 7 file-read/concatenation loop — no longer reads all architecture files between agent completion and playground spawn
- Playground generator now receives `doc_files` (path list) and reads + concatenates once, replacing the previous triple-read pattern (agents → orchestrator → playground agent)
- `PLAYGROUND_TEMPLATE.md` updated with explicit instruction: generator reads `doc_files` via Read tool and builds `docContent` itself
- Eliminates ~100KB of redundant token usage per HARD depth review (~66% reduction in doc-related tokens)

### v3.3.6 (Previous Release) ✅
**fix: peer review playground syntax error + agent scorecard delegation**

- Fixed `Uncaught SyntaxError: missing } in template string` in generated playground HTML — root cause was nested template literals in `PLAYGROUND_TEMPLATE.md` `renderDocument()` function; extracted to local variables + added warning comment
- Category agents now compute their own score (start 10.0, deduct per severity, floor 0.0) and return `score` + `weight` in `CATEGORY_REVIEW_RESULT` — orchestrator assembles scorecard directly without recalculation
- Simplified `SKILL.md` Step 6: reads `score`/`weight` from agent results, applies renormalization, computes weighted average — no per-finding deduction logic in orchestrator

### v3.3.5 (Previous Release) ✅
**refactor: peer review category agents read files directly instead of receiving inline content**

- Category agents now receive a `FILES:` list of file paths and read them via the Read tool — no more full document text duplicated 13× in HARD depth prompts
- `SKILL.md` Step 4 now resolves `doc_files` (ordered path list) instead of concatenating content; Step 7 handles concatenation for the playground `docContent` embed
- `peer-review-category-agent.md` Step 2 updated: reads each file in `FILES:` using the Read tool, tracks per-file line numbers for accurate `lineRef` values

### v3.3.4 (Previous Release) ✅
**feat: parallel category agents for architecture peer review**

- New universal `agents/peer-review-category-agent.md` sub-agent — evaluates one review category's checks against architecture docs and returns a `CATEGORY_REVIEW_RESULT` JSON block
- Peer review skill now fans out all active categories in a single parallel message (3 agents for Light, 7 for Medium, 13 for Hard)
- Dramatic speed improvement: Light ~40s (was ~2 min), Medium ~90s (was ~5 min), Hard ~2-3 min (was ~10 min)
- Added Step 5.2 (merge + renumber): collects all `CATEGORY_REVIEW_RESULT` blocks, merges findings, renumbers IDs globally, handles per-agent failures gracefully
- Added `Agent(sa-skills:peer-review-category-agent)` to `.claude/settings.json.example` and CLAUDE.md permissions

### v3.3.3 (Previous Release) ✅
**fix: peer review playground layout for large finding counts**

- Added structural layout CSS to `PLAYGROUND_TEMPLATE.md`: viewport constraints, flex containers, panel scroll isolation
- Document panel and findings panel now scroll independently — no more full-page scroll with 19+ findings
- Filter bar (All/Pending/Approved/Rejected tabs + dropdowns) is now sticky at top of findings panel
- Added explicit HTML structure reference (`#app`, `#main`, `#doc-panel`, `#findings-filters`, `#findings-list`, etc.) so generated playground uses correct IDs

### v3.3.2 (Previous Release) ✅
**fix: compliance-docs write permission glob pattern for subdirectories**

- Fixed `.claude/settings.json` permission glob: `Write(compliance-docs/*)` → `Write(compliance-docs/**)` to allow writing to subdirectories
- Fixed README.md installation verification version (was stuck at v3.2.7)

### v3.3.1 (Previous Release) ✅
**fix: references file (`docs/10-references.md`) now included in downstream propagation**

- Added `docs/10-references.md` to cross-cutting files in Step 5.5 Downstream Documentation Propagation
- S5 (Components), S8 (Tech Stack), S12 (ADRs) now list `docs/10-references.md` as downstream in Reverse Dependency Table
- New propagation rule: ADR changes update ADR index table, technology changes update doc links, new terms update glossary
- S12 ADR special rule now always syncs references after ADR file creation

### v3.3.0 (Previous Release) ✅
**feat: IcePanel C4 model sync skill (beta) + Section 12 ADR propagation fix**

- New `architecture-icepanel-sync` skill (beta): extracts C4 elements from architecture docs, generates IcePanel-compatible import YAML, checks IcePanel API for existing objects, and imports or reports drift
- Three workflows: Full Sync (online/offline), Drift Report Only, YAML Export Only
- Online mode uses IcePanel REST API (`ICEPANEL_API_KEY` + `ICEPANEL_LANDSCAPE_ID`) for check/import/drift detection
- Offline mode generates `icepanel-sync/c4-model.yaml` for manual import via IcePanel UI
- Includes `ICEPANEL_IMPORT_REFERENCE.md` with LandscapeImportData schema, type mapping, and tag conventions
- Fix: Section 12 ADR table updates now trigger ADR file creation via `/skill architecture-definition-record` delegation
- Added S12 to Reverse Dependency Table in architecture-docs skill

### v3.2.10 (Previous Release) ✅
**feat: theme-aware diagram generation — light/dark mode support for all Mermaid diagrams**

- Theme detection: asks user light/dark once, persists as `<!-- DIAGRAM_THEME: light|dark -->` in `docs/03-architecture-layers.md`
- Dark mode C4/sequence diagrams: `%%{init: {'theme': 'dark'}}%%` init block prepended automatically
- Dark classDef palettes for all 4 architecture types (META/BIAN, 3-Tier, N-Layer, Microservices) with WCAG AA contrast
- Generation Workflow step 5.5 added for theme detection before diagram generation
- Updated across 4 files: DIAGRAM-GENERATION-GUIDE, MERMAID_DIAGRAMS_GUIDE, SKILL.md, ARCHITECTURE_TYPE_SELECTION_WORKFLOW

### v3.2.9 (Previous Release) ✅
**feat: system-folder-aware component add with L1+L2 structure creation for external systems**

- Step 3a added: detects existing system folders and prompts user to select target system
- New system creation workflow: asks Internal/External classification and creates L1 descriptor + L2 container folder
- External system "explode" support: promotes external system references into full C4 L1+L2 hierarchy
- Change Propagation Report now shows system context (new vs existing, Internal/External)
- Flow C updated to reflect system selection and L1+L2 creation steps

### v3.2.8 ✅
**fix: mandatory diagram cascade on component add/remove — replace optional prompt with `/skill architecture-docs` delegation**

- Step 6e now mandatory: diagrams are regenerated automatically after add/remove operations (no Yes/No prompt)
- Explicit `/skill architecture-docs` invocation with structured context block (component name, type, system, connections)
- Post-generation verification: grep diagrams for component name to confirm it appears in C4 L2 and Detailed View
- Fallback path if generation fails: PENDING marker + manual instructions (does not block component operation)
- M8.3 (C4 migration) updated with same mandatory pattern
- Step 6f Change Propagation Report now includes diagram update status row

### v3.2.7 ✅
**fix: delegate README.md creation to guardian skill during initial architecture creation**

- Step 4e now invokes `architecture-component-guardian` with `sync` instead of creating README.md directly
- Fixes 6 format inconsistencies: title ("Component Details"), em dash comment, 5.N numbering, intro paragraph, Key Relationships section, Related Documentation section
- Fallback to manual creation using guardian format spec when skill is unavailable

### v3.2.6 ✅
**feat: always nest C4 L2 containers in system folders — remove flat single-system exception**

- All architectures now use nested folder structure: `docs/components/<system-name>/NN-component.md`
- Removed single-system flat layout exception — system descriptor file and folder always created
- README.md component index always uses grouped tables with `### System Name` headers
- Updated across 5 files: workflow, guardian, C4 migration reference, restructuring guide, README

### v3.2.5 (Previous Release) ✅
**feat: ADR Context Block — pre-identify decisions from PO Spec and propagate through creation**

- New Step 0.5 in Workflow 1: derives ADR candidate list from PO Spec analysis (Sections 1, 3, 4, 7) before architecture design begins
- ADR Context Block maintained through all creation steps — decisions tracked from PENDING to DECIDED with rationale
- Step 2 (architecture type selection) resolves first ADR candidate automatically
- Step 5 (section creation) references the block for consistency across principles, tech stack, security, and ADR table
- Step 6 (ADR generation) passes enriched context with drivers, decisions, and rationale to the ADR skill

### v3.2.4 (Previous Release) ✅
**feat: pure C4 grouping for Level 2 Container diagram — no architecture-specific layers**

- C4 L2 Container diagram now groups by C4 element type (`Container()`, `ContainerDb()`, `ContainerQueue()`) instead of architecture-specific layers/tiers
- Architecture Type Adaptation table scoped to Diagrams 1 and 4 only — C4 diagrams use pure C4 conventions
- All 5 C4 translation files updated (META, BIAN, 3-Tier, N-Layer, Microservices) to enforce pure C4 grouping at L2
- Layer/tier visual grouping explicitly directed to Logical View (Diagram 1) and Detailed View (Diagram 4)

### v3.2.3 (Previous Release) ✅
**fix: dynamic principle count in Section 3 header — 9 or 10 based on content**

- Section 3 heading now reflects actual principle count: "(9 Core Principles)" or "(10 Core Principles)" when optional Decouple Through Events is included
- Document Header Rule added to ARCHITECTURE_DOCUMENTATION_GUIDE.md template
- Validation checklist updated to verify heading matches principle count
- Creation workflow enforcement block includes header rule

### v3.2.2 (Previous Release) ✅
**fix: enforce Section 3 (Architecture Principles) 9-principle template across all paths**

- Creation workflow (Workflow 1) now explicitly enforces the mandatory 9-principle template with exact order, three subsections (Description/Implementation/Trade-offs), and validation checklist reference
- Migration workflow (Workflow 9) now validates Section 3 against the template during extraction, with update workflow for non-standard source documents
- Universal enforcement gate added to SKILL.md for any write to `docs/02-architecture-principles.md` — creation, migration, or edit

### v3.2.1 (Previous Release) ✅
**fix: recommended VS Code setup — Mermaid Chart extension replaces Office Viewer**

- Removed Office Viewer from recommended extensions
- Replaced Mermaid Preview with Mermaid Chart (official extension from Mermaid.js creators, v11.4.1)
- Recommended setup simplified to 2 extensions: Claude Code + Mermaid Chart

### v3.2.0 (Previous Release) ✅
**feat: Mermaid v11.4.1 target — native C4 diagrams + classic sequenceDiagram**

- All generated Mermaid diagrams now target **Mermaid v11.4.1** (Mermaid Chart VS Code extension 2.1.0+)
- Data flow diagrams reverted from ZenUML to Mermaid `sequenceDiagram` with full modern syntax (`-)` async, `par/and/end`, `critical/break`)
- C4 Level 1 uses native `C4Context` with `Person()`, `System()`, `System_Ext()`, `Rel()`
- C4 Level 2 uses native `C4Container` with `Container()`, `ContainerDb()`, `ContainerQueue()`, `Container_Boundary()`
- Diagrams 1 (Logical View) and 4 (Detailed View) remain `graph TB` with `classDef` styling
- DIAGRAM-GENERATION-GUIDE.md updated with complete syntax references, templates, and compatibility rules for v11
- All secondary files updated: SKILL.md, ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md, MERMAID_DIAGRAMS_GUIDE.md

### v3.1.6 (Previous Release) ✅
**feat: data flow diagrams migrated to ZenUML syntax**

- Data flow diagrams used Mermaid ZenUML syntax (reverted in v3.2.0)

### v3.1.5 ✅
**feat: multi-architecture diagram generation guide — 4 standard diagrams for all 5 architecture types**

- New `references/DIAGRAM-GENERATION-GUIDE.md` defining 4 standard architecture diagrams: Logical View (ASCII), C4 L1 System Context, C4 L2 Container, and Detailed View (Mermaid)
- Architecture Type Adaptation table maps grouping, naming, and color conventions for META, BIAN, 3-Tier, N-Layer, and Microservices
- C4 L1 translation table per architecture type (what collapses into Internal System vs External)
- Diagram 4 color convention tables per architecture type
- Mermaid 8.x compatibility rules (DO/DON'T) and generation workflow algorithm
- Workflow 8 now references DIAGRAM-GENERATION-GUIDE (primary) + MERMAID_DIAGRAMS_GUIDE (authoring)
- Step 7 in Architecture Type Selection generates all 4 diagrams + data flow sequences
- CLAUDE.md Diagram Enforcement Policy updated to list 4 mandatory standard diagrams

### v3.1.4 (Previous Release) ✅
**feat: dev handoff enforces C4 L2-only gate — no Level 1 components processed**

- Dev handoff skill now explicitly scoped to C4 Level 2 (Container) components only
- Two-layer filter in Step 1.3: file naming heuristic + `**C4 Level:**` metadata check
- C4 Level Validation Gate in Step 2.1: rejects System (L1) components with clear warning message
- Missing `**C4 Level:**` metadata triggers a warning but proceeds (assumes L2)
- If all selected components are L1, skill stops before Phase 3
- SECTION_EXTRACTION_GUIDE.md updated with C4 L2 scope note
- CLAUDE.md dev-handoff description updated to reflect L2-only scope

### v3.1.3 (Previous Release) ✅
**feat: C4 L1 system descriptor files + cross-skill impact fixes**

- Multi-system architectures now create C4 L1 system descriptor files at `docs/components/` root (`{system-name}.md`) alongside system subfolders
- System files contain: C4 Level (System L1), Type (Internal/External), Owner, Containers table, System Boundaries, Communication patterns
- README.md system headers now link to system files: `### [System Name](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/system-name.md)`
- Guardian scan distinguishes `NN-*.md` (L2 containers) from `{name}.md` (L1 system descriptors)
- Migration workflow Phase M4.1b creates system files automatically
- Dev handoff excludes system descriptor files from handoff targets
- Peer review NAMING-03 recognizes both L1 (no NN- prefix) and L2 (NN- prefix) naming patterns

### v3.1.2 (Previous Release) ✅
**feat: guardian loads architecture-type C4 translation on every invocation**

- Component guardian now detects `<!-- ARCHITECTURE_TYPE: -->` from `docs/03-architecture-layers.md` on every operation (sync, add, migrate)
- Loads the matching C4 translation guide (`{TYPE}-TO-C4-TRANSLATION.md`) to apply type-specific container rules
- Type-specific validation: flags components that violate the translation guide (e.g., "Service Layer" in 3-Tier = C3, not a valid C2 component)
- Graceful fallback: if no architecture type detected, uses generic C4 L2 rules only

### v3.1.1 (Previous Release) ✅
**feat: C4 migration workflow + guardian governance cleanup**

- Added `migrate` operation to component guardian — 8-phase automated workflow converting flat `docs/components/` to C4 multi-system structure (detect → classify → fix metadata → move files → update references → regenerate README → update ARCHITECTURE.md → verify)
- Supports both git repos (`git mv`) and non-git folders (Read → Write → delete)
- `C4-MIGRATION-REFERENCE.md` — type mapping table (28 entries), ownership heuristics, cross-reference impact map, edge cases from live migration session
- C4 Model Governance section cleaned — removed redundancies with ICEPANEL-C4-MODEL.md, kept only guardian-specific enforcement rules (canonical types table, ambiguous cases)
- Removed unsupported `triggers` frontmatter from component guardian

### v3.1.0 (Previous Release) ✅
**feat: C4 model integration, architecture reference docs, multi-system components, async intake reorder**

- **C4 Model Integration**: Components follow C4 L2 (Container diagram) — boundary test, App/Store classification, IcePanel bracket convention for technology
- **11 architecture reference docs** in `references/`: C4 model + 5 architecture rules + 5 C4 translation guides (Microservices, 3-Tier, N-Layer, META, BIAN)
- **C4 component structure**: C4 L1 systems → folders under `docs/components/`, C4 L2 containers → component files nested in system folders (all architectures)
- **5-column component index**: `#`, `Component`, `File`, `Type`, `Technology` with grouped system headers
- **C4 metadata header** on all component templates: Type, Technology `[in brackets]`, C4 Level, Deploys as, Communicates via
- **Architecture type selection reordered**: Industry Standard (1-3) first, Enterprise (4-5) after, with `STANDARD`/`ENTERPRISE`/`BANKING` tags
- **Reference doc gate**: Types without both reference docs are greyed out and cannot be selected
- **Component guardian** governed by `ICEPANEL-C4-MODEL.md` — enforces C4 boundary test and canonical types
- **Async intake** reordered to flow #1 in readiness skill with email-ready gap report output
- **Canonical ADR template rule** enforced across all write workflows (1, 2, 4) with explicit gate checks
- **Validator personalities** moved from generators to validators; validators load domain config at runtime
- Cross-skill compatibility: handoff, peer review, ADR, docs-export all updated for 5-column index + system subfolders

### v3.0.2 (Previous Release) ✅
**fix: align validator names, enforce canonical ADR template, async intake isolation + email-ready output**

- Validator spawn descriptions now use full codename + domain format (e.g., `Aegis — Business Continuity Validator`)
- Config `agent_description` fields aligned with validator frontmatter (single source of truth)
- Removed `Glob` from validator tools — prevents wildcard permission prompts
- ADR canonical template rule enforced across all workflows (Workflows 1, 2, 4) with explicit gate checks
- Async intake reordered to flow #1 in readiness skill, with `⛔ NEVER transitions to elicitation` isolation rule
- PO Spec menu reordered: (1) Elicitation, (2) Async intake, (3) Inline context, (4) Skip
- Added Ready-to-Send Message template to async intake gap report — email/ticket-ready copyable block

### v3.0.1 (Previous Release) ✅
**docs: update README Phase 3 with v3.0.0 architecture — two-phase diagram, CC-004 sequence flow**

- Rewrote Phase 3 Compliance Documentation section for the universal generator architecture
- Added two-phase parallel execution diagram (validators → universal generator ×10)
- Added CC-004 Development example sequence showing EOL-first WebSearch flow
- Contract types table now includes Validator codename column
- Documented key principles: validators own personality, generator is pure template-filler, EOL is blocking

### v3.0.0 (Previous Release) ✅
**major: universal compliance generator — 10 agents consolidated to 1 + config-driven validators**

- Replaced 10 domain-specific generator agents with a single `agents/compliance-generator.md` that reads domain config at runtime
- Personality, key data points, focus areas, and agent notes moved from generators to validators — generators are pure template-fillers
- Validators read their domain config (`agents/base/configs/*.json`) at startup for extensibility
- Removed build system (`scripts/build-agents.ts`, `agents/base/AGENT_BASE.md`, `agents/base/sections/`, `agents/base/overrides/`) — no longer needed
- Removed `Glob` from validator tools (caused wildcard permission prompts)
- Simplified permissions: 10 generator Agent rules → 1 (`compliance-generator`)
- Cleaned redundant `validation_agent`/`validation_agent_name` fields from configs
- Architecture: Orchestrator → 10 validators (parallel, with personality + EOL) → 1 universal generator ×10 (parallel, config-driven)

### v2.16.1 (Previous Release) ✅
**fix: clean up agent permissions — remove unused Bash commands, align CLAUDE.md with settings.json.example**

- Removed unused Bash permissions (`ls`, `cat`, `cp`, `grep`, `python3`) — agents self-constrain via TOOL DISCIPLINE
- Added 10 validator Agent permissions and WebSearch to CLAUDE.md permissions block
- Verified all 20 agent references (SKILL.md → agent names → permissions) are in sync

### v2.16.0 (Previous Release) ✅
**refactor: standardized External Validation Summary across all 10 contracts + generators folder**

- All 10 compliance templates now have a consistent `## External Validation Summary` section (table with Status, Validator, Date, Items, Result + Deviations + Recommendations)
- Step 4.6 (Populate External Validation Summary) moved from development-only override into the base template — all agents now have it
- Development-specific overrides removed (development-step46.md, development-validation-summary.md) — no longer needed
- Generated agents moved to `agents/generators/` for clean separation from `agents/validators/` and `agents/base/`
- Validator name parameterized per domain (e.g., `Atlas Validator (cloud-validator)`, `Prometheus Validator (sre-validator)`)

### v2.15.1 (Previous Release) ✅
**fix: add WebSearch permission to settings.json.example for validator EOL checks**

- Added `WebSearch` to the permissions allow list in `.claude/settings.json.example`

### v2.15.0 (Previous Release) ✅
**refactor: orchestrator-spawned validators — validators run before generators with results passed via prompt**

- Validators are now spawned by the orchestrator (SKILL.md Step 3.3) in parallel, before generators
- Each validator's VALIDATION_RESULT is collected and passed into its generator's prompt (Step 3.4)
- Generators no longer attempt nested sub-agent spawning — they parse the pre-provided VALIDATION_RESULT
- Fixes EOL detection failure: validators now run at orchestrator level with full WebSearch access
- Architecture: Orchestrator → 10 validators (parallel) → collect results → 10 generators (parallel, with results)

### v2.14.4 (Previous Release) ✅
**fix: harden EOL enforcement — WebSearch in tools, context7 forbidden for EOL, Spring Boot 3.2 example**

- Added `WebSearch` to development validator tools frontmatter (was missing — agent couldn't invoke it)
- Explicitly forbids context7 for EOL checks in 3 locations — context7 provides docs, not lifecycle data
- Spring Boot 3.2 EOL example in mission section as concrete FAIL reference
- Phase 1 marked ⛔ DO NOT SKIP with non-negotiable ordering enforcement

### v2.14.3 (Previous Release) ✅
**fix: EOL-first validation — Phase 1 gathers EOL data before any stack checks**

- Restructured development validator: Phase 1 now builds an EOL lookup table via WebSearch BEFORE Phase 2 evaluates the 26 stack items
- 6-month safety period: versions within 6 months of EOL are treated as FAIL, not just past-EOL
- Version-bearing items (1, 2, 7, 8, 13, 19-23) consult the EOL table — approved + EOL = FAIL regardless of catalog status
- Evidence now includes EOL dates: `"Spring Boot 3.2 — approved but EOL since 2024-12-31 — endoflife.date"`
- Glob permission for marketplace directory added to settings.json.example

### v2.14.2 (Previous Release) ✅
**fix: EOL checks integrated into Phase 1 version items — approved does not mean supported**

- Version-bearing validation items (1, 2, 7, 8, 13, 19, 20, 21, 22, 23) now verify EOL status via WebSearch as part of PASS/FAIL criteria — a technology on the approved list but past end-of-support is marked FAIL
- Evidence includes both facts: `"Spring Boot 3.2 is in approved list but EOL since 2024-12-31 — endoflife.date"`
- Phase 2 simplified to supplementary catch-all for technologies not covered by the 26 standard items
- Compact VALIDATION_RESULT format maintained across all 10 validators

### v2.14.1 (Previous Release) ✅
**feat: development validator as sole validation point + EOL checks + compact VALIDATION_RESULT**

- Development validator is now the single source of truth for stack validation — Step 4.6 override no longer duplicates criteria, only maps VALIDATION_RESULT to template placeholders
- Added Phase 2: EOL Validation to development validator — uses WebSearch to check technology version lifecycle status against endoflife.date and vendor documentation
- EOL items (DEV-EOL-*) are supplementary: PASS (supported), FAIL (EOL), UNKNOWN (no info); included in deviations/recommendations
- Compact VALIDATION_RESULT format across all 10 validators — single-line summary + pipe-delimited items table replaces verbose per-item YAML blocks
- Graceful degradation when WebSearch is unavailable — Phase 2 silently skipped

### v2.14.0 (Previous Release) ✅
**refactor: compliance contract naming — CC-prefixed kebab-case with numbered types**

- Renamed all compliance contracts to `CC-NNN-{type}` convention: templates, output files, validation configs, and type identifiers
- Template files: `TEMPLATE_BUSINESS_CONTINUITY.md` → `cc-001-business-continuity.template.md` (10 templates)
- Output files: `BUSINESS_CONTINUITY_Project_Date.md` → `CC-001-business-continuity_Project_Date.md`
- Fixed numbering: CC-001 (Business Continuity) through CC-010 (SRE Architecture)
- Updated all TypeScript registries, validation schemas (20 files), utility CLIs, tests (334 pass), and documentation references

### v2.13.0 (Previous Release) ✅
**refactor: compliance agent build system — base template + domain configs + 10 validation agents**

- Refactored 10 compliance agents (~85% shared boilerplate) into a build-time generation system: `agents/base/AGENT_BASE.md` + 9 shared sections + 10 domain config JSONs → 10 generated agent .md files via `bun run build:agents`
- Added 10 new validation agents (`agents/validators/`) — one per compliance domain — that perform external standard checks (stack validation, security controls, SRE readiness, etc.)
- Each compliance agent now invokes its domain validator in Step 3.4 before populating the template
- Build script (`scripts/build-agents.ts`) handles `{{variable}}` substitution, `@foreach`/`@if` directives, section injection, and domain-specific overrides
- Integrated into `bun run build` pipeline; generated files marked `linguist-generated` via `.gitattributes`

### v2.12.12 (Previous Release) ✅
**feat: dependency-based ordering for batch dev handoff generation**

- Added Step 2.2 to `architecture-dev-handoff`: when generating multiple handoffs, components are sorted ascending by inter-component dependency count (least → most)
- Ensures foundational components are generated first so heavily-dependent components can cross-reference upstream handoffs for consistency

### v2.12.11 (Previous Release) ✅
**docs: add context7 MCP integration guide to README**

- Added context7 to "What's Included" feature list as optional MCP integration
- New "Optional: Enable context7" section in Quick Start with MCP server JSON config (recommended), CLI setup, and headless alternative
- Documented which skills use context7 (`architecture-dev-handoff`, `architecture-docs`) with usage table
- Fixed stale installation verification version

### v2.12.10 (Previous Release) ✅
**docs: merge propagation gates — unified ADR and downstream propagation node in workflow diagram**

- Merged `{Propagation}` (ADR status change) and `{Downstream Propagation}` (section edit) diamond nodes into a single `{Propagation}` gate in the Workflow Integration diagram
- Both triggers — `Status Change` from ADRs and `Section Edit` from ARCHITECTURE.md — now feed into one propagation gate with unified `Updates` outputs to ARCHITECTURE.md and Dev Handoffs

### v2.12.9 (Previous Release) ✅
**feat: asset regeneration advisory in downstream propagation workflows**

- Added **Phase 5: Asset Regeneration Advisory** after Phase 4 Propagation Report in both `architecture-docs` (Step 5.5) and `architecture-definition-record` (Workflows 3 & 4)
- After propagation completes, scans fact-deltas for asset-impact keywords (API, database, Redis, deployment, Kafka, Avro, Protobuf, cron) and cross-references against actual asset files in `handoffs/assets/`
- When stale assets are detected, displays advisory listing affected components and asset types, then asks the user whether to re-run `/skill architecture-dev-handoff`
- Skips silently when no handoffs were affected or no asset-impact keywords match; also fires on propagation skip to warn that both text and assets may be stale

### v2.12.8 (Previous Release) ✅
**feat: context7 MCP integration for asset generation and component documentation**

- `architecture-dev-handoff`: added Step 3.3b (Spec Documentation Lookup) — fetches current spec docs via context7 (`resolve-library-id` + `get-library-docs`) for each asset type before generation; caches per session
- `ASSET_GENERATION_GUIDE.md`: new "Spec Documentation Integration (context7)" section with asset→library mapping table; per-asset `context7 validation` callouts for all 8 asset types (OpenAPI, DDL, Kubernetes Deployment, AsyncAPI, CronJob, Avro, Protobuf, Redis)
- `architecture-docs`: new "Technology Context Enrichment (context7)" subsection — fetches framework docs during Workflow 1 component creation and presents advisory Technology Context Brief (never auto-fills)
- All 4 Section 5 templates: HTML comment hint on `**Technology**:` field directing Claude to use context7 advisory lookup
- `CLAUDE.md`: documented context7 as an optional MCP dependency with graceful degradation
- Syntax/structure only — "no invention" / Asset Fidelity Rule unchanged; all data values still come exclusively from architecture docs

### v2.12.7 (Previous Release) ✅
**feat: architecture-docs downstream propagation — cascade updates to dependent sections, components, and handoffs after any substantive section edit**

- Added Step 5.5 to the architecture-docs editing workflow: Downstream Documentation Propagation
- Embedded reverse dependency table mapping each section to its structurally-dependent downstream files
- 4-phase propagation: fact-delta extraction → user-approval checklist → tier-ordered Context Anchor updates → completion report
- Cross-cutting scan always covers `docs/components/` and `handoffs/` regardless of section tier
- Cosmetic edit heuristic skips propagation silently for formatting/typo changes
- Anti-recursion rule: propagation edits do not re-trigger propagation
- Component file edits cascade through S5's full dependency row + always include matching handoff doc

### v2.12.6 (Previous Release) ✅
**feat: ADR change propagation — downstream documentation impact tracking and execution**

When an ADR is updated (status change) or superseded (Workflow 3/4), the `architecture-definition-record` skill now runs a 4-phase Documentation Impact Propagation step. Phase 1 (Impact Discovery): greps all `docs/`, `docs/components/`, and `handoffs/` for explicit ADR citations, applies a keyword-to-file topic mapping table to find conceptually-affected files without explicit citations, and extracts concrete fact changes from the ADR content. Phase 2 (Checklist): presents a "Documentation Updates Required" checklist grouped by file type (Architecture Docs / Component Files / Handoff Docs) — each entry states what needs updating and why; user approves all or deselects items for manual handling. Phase 3 (Execute): applies each approved update following the architecture-docs Context Anchor Protocol (load foundation + section-specific parents + changed ADR, update citations and derived facts, run 5-check Post-Write Audit); handoff updates follow the dev-handoff Documentation Fidelity Policy. If user skips, adds `<!-- PROPAGATION PENDING -->` marker to the ADR file. Phase 4 (Report): completion report with `[x]` completed / `[ ]` deselected / `⚠️` failed items. For supersede: also migrates `per [ADR-old]` citations to `per [ADR-new]` across all docs and updates ARCHITECTURE.md Section 12 table. Integration table and Success Criteria updated.

### v2.12.5 (Previous Release) ✅
**feat: focus mode filters sidebar to connected nodes for scoped knowledge cycling and learning prompts**

When a node is clicked (focus mode), the sidebar node list now filters to show only the focused node and its direct connections — with a header showing "Exploring: [node name] (N nodes)" and a "Show All" button to exit. The focused node appears bold in accent color. Knowledge cycling (Know/Fuzzy/Unknown) works within this filtered scope, so users can mark what they know about just the connected concepts. The learning prompt also scopes to the focused subset: only edges and nodes touching the focused node are included, and the prompt opens with "I'm currently exploring: **[node name]** and its N direct connections." Clicking empty canvas or "Show All" restores the full node list and global prompt.

### v2.12.4 (Previous Release) ✅
**feat: concept map node focus mode — click to highlight connections, dim unrelated nodes**

Clicking a node in the onboarding concept map now enters focus mode: the clicked node and all directly connected nodes stay at full opacity while every unrelated node dims to 12% and unrelated edges dim to 6%. Clicking the same node again or clicking empty canvas clears focus and restores full rendering. Implementation: added `focusedNode` state variable; updated `draw()` to build a `connectedIds` set (node + both-direction edge neighbors) and pass it to `drawNode()`/`drawEdge()`; updated `drawNode()` to apply `alpha=0.12` for dimmed nodes; updated `drawEdge()` to apply `globalAlpha=0.06` for dimmed edges and `0.04` for their labels; updated `mouseup` to toggle focus on click-without-drag; updated `mousedown` to clear focus when clicking empty canvas. Drag behavior is unchanged — focus only triggers on click (mousedown + mouseup with no movement).

### v2.12.3 (Previous Release) ✅
**fix: enforce lowercase kebab-case naming convention for component files across all skills**

Component file names under `docs/components/` must follow `NN-kebab-case-name.md` (e.g., `01-api-gateway.md`, `02-payment-service.md`) — lowercase, hyphens only, no spaces, no uppercase, no underscores. This was defined in RESTRUCTURING_GUIDE.md but not enforced downstream. Fixed in 4 skills: (1) `architecture-component-guardian` — added naming validation on scan with auto-rename offer for violations, and kebab-case conversion on `add component`; (2) `architecture-peer-review` NAMING-03 check — now explicitly requires `NN-kebab-case-name.md` with examples (was ambiguous `NN-component-name.md`); (3) `architecture-docs` SKILL.md — added component file examples alongside section file examples in naming convention; (4) `architecture-dev-handoff` — stated that handoff filenames derive from component file names using kebab-case.

### v2.12.2 (Previous Release) ✅
**fix: ADR generation uses full template with populated body sections, not abbreviated stubs**

When ADRs are generated from the ARCHITECTURE.md Section 12 table (Workflow 1 in `architecture-definition-record`), all 10 template sections are now populated from architecture documentation context — not just the metadata placeholders. Root cause: Step 1.5 only instructed replacing ADR number, title, status, date, and authors, leaving Context, Decision, Rationale, Consequences, and Alternatives empty for the user to fill in later. Fixed by rewriting Step 1.5 with: (1) a keyword-based topic-to-docs mapping table that identifies which `docs/` files are relevant per ADR title, (2) a section-by-section population guide mapping every template section to its architecture doc source, (3) an explicit "CRITICAL: use the full canonical template — do NOT produce abbreviated stubs" directive. Comparison tables must use real data (not placeholder rows). Only Implementation Plan and Success Metrics remain as optional stubs. Step 1.6 summary now says "review and refine" instead of "fill in Context, Decision, and Rationale". Step 6 delegation in ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md also updated to explicitly pass the full-template instruction to the ADR skill.

### v2.12.1 (Previous Release) ✅
**fix: concept map auto-layout — rectangle-aware repulsion, band gravity, and overlap resolution**

Rewrote `autoLayout()` in the `architecture-onboarding` PLAYGROUND_TEMPLATE.md to eliminate node overlap. Three root causes fixed: (1) **Rectangle-aware collision** — replaced point-based `REPULSION/dist²` with bounding-box overlap detection; overlapping nodes are pushed apart along the axis of minimum penetration (push strength 0.55× overlap), while non-overlapping nodes use mild long-range repulsion (3000/dist²). (2) **Band gravity** — added a Y-axis restoring force (`BAND_GRAVITY=0.3`) per iteration that pulls each node back toward its group's proportional lane (15%/45%/80% of canvas height), preserving the Use Cases → Sections → Components traceability spine through the simulation. (3) **Weaker edge attraction** — reduced `ATTRACTION` from 0.04 → 0.02 and cross-group edges (`traces-to`, `served-by`) to 0.01 so band gravity and repulsion win locally. Also shortened `REST_LEN` 180→120, increased max iterations 200→300, and added early exit when kinetic energy drops below 0.1. `initializePositions()` band centers updated to proportional values (H×0.15/0.45/0.80) matching the simulation.

### v2.12.0 (Previous Release) ✅
**feat: new `architecture-definition-record` skill — single owner of all ADR write operations**

Extracted ADR handling from `architecture-docs` into a dedicated `architecture-definition-record` skill (9th skill). The new skill owns five workflows: generate ADR files from ARCHITECTURE.md Section 12 table, create individual ADRs interactively (guided interview), update ADR status (Proposed → Accepted / Deprecated / Rejected), supersede an ADR (creates new + marks old as superseded), and list/audit the ADR inventory. All other skills now delegate write operations here while retaining direct read access to `adr/*.md`. Moved `ADR_GUIDE.md` and `ADR-000-template.md` into the new skill directory. Removed ~500-line Step 6 implementation from `ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md`, replaced with a single delegation instruction. Updated CLAUDE.md, README.md, and 4 other skills with delegation notes.

### v2.11.2 (Previous Release) ✅
**feat: use case traceability in onboarding concept map; focus on UC → Sections → Components spine**

Redesigned the `architecture-onboarding` concept map around a business-to-technical traceability spine. Adds a **Use Cases** node group (pink) extracted from PO Spec Section 4 or `docs/01-system-overview.md` Section 2.3 — placed at the top band, tracing down through Architecture Sections (middle) to Components (bottom). New edge types: `traces-to` (UC → section, dashed pink) and `served-by` (UC → component, from handoff docs' Business Context field). Removed lifecycle, compliance, principles, and skill groups entirely — they don't add value to onboarding exploration. Concept map now contains exactly 3 node groups and 3 presets (Use Case Traceability, Section Dependencies, Component Map). Default preset is "Use Case Traceability".

### v2.11.1 (Previous Release) ✅
**fix: complete concept map rendering — full JS implementation in PLAYGROUND_TEMPLATE.md**

Rewrote `PLAYGROUND_TEMPLATE.md` for the `architecture-onboarding` skill to include complete, verbatim JavaScript implementations for all canvas rendering functions. Previously, key functions (`initializePositions`, `autoLayout`, `drawEdge`, drag handlers, tooltip) had elided `// ...` bodies that the playground plugin could not fill in — causing most nodes to render at undefined positions (invisible). All functions are now fully specified: grid-based initial node placement per group band, force-directed auto-layout with pairwise repulsion + edge attraction, full Canvas 2D arrowhead drawing, bounding-box drag, and absolute-positioned tooltips.

### v2.11.0 (Previous Release) ✅
**feat: new architecture-onboarding skill with interactive concept map playground; rename architecture-doc-export → architecture-docs-export**

New `architecture-onboarding` skill — generates a canvas-based interactive concept map via the `playground` plugin for onboarding new team members. Draggable nodes represent lifecycle phases (5), architecture sections S1-S12, components, compliance contracts (10 slots), required principles (9), and available skills (9) — connected by dependency, workflow, and validation edges. Users cycle knowledge levels per node (Know/Fuzzy/Unknown) and copy a targeted learning prompt. Includes 6 preset views (Full Map, Lifecycle Flow, Section Dependencies, Component Map, Compliance Coverage, Principles View), ghost nodes for missing artifacts, and force-directed auto-layout. Also renamed `architecture-doc-export` to `architecture-docs-export` for consistency across all references.

### v2.10.39 (Previous Release) ✅
**fix: remove dead instruction blocks from generated compliance contracts — wrap compliance-score-calculation fragment in internal tags; remove duplicate Dynamic Field Instructions from Development template**

Two agent-guidance blocks were appearing verbatim in generated contracts: (1) `**CRITICAL - Compliance Score Calculation**` from `shared/fragments/compliance-score-calculation.md` — included in all 9 non-SRE templates but not wrapped in `<!-- BEGIN_INTERNAL_INSTRUCTIONS -->` tags, so `--strip-internal` never removed it. Fixed by wrapping the fragment content. (2) `**Dynamic Field Instructions**: [VALIDATION_SUMMARY]...` inline block in `TEMPLATE_DEVELOPMENT_ARCHITECTURE.md` — a duplicate of the already-properly-wrapped `dynamic-field-instructions.md` include. Removed the inline duplicate and moved `[VALIDATION_SUMMARY]` replacement rule into the development agent instead.

### v2.10.38 (Previous Release) ✅
**fix: add Glob permission for plugin_dir resolution to settings.json.example and CLAUDE.md**

Added `"Glob(**/skills/architecture-compliance/SKILL.md)"` to the permissions `allow` list in both `.claude/settings.json.example` and `CLAUDE.md`. This prevents approval prompts when agents run the Glob to resolve `plugin_dir` in marketplace installations.

### v2.10.37 (Previous Release) ✅
**fix: plugin_dir Glob pattern now works for marketplace installations — remove hardcoded repo name from path**

The Glob pattern used to resolve `plugin_dir` was `**/solutions-architect-skills/skills/architecture-compliance/SKILL.md`, which hardcodes the repo name and only matches the dev directory structure. When running as an installed plugin, the marketplace directory is named `shadowx4fox-solution-architect-marketplace/` (not `solutions-architect-skills/`), so the Glob failed and agents fell back to a wrong path that appended `solutions-architect-skills/` as a subdirectory — producing `Module not found` errors on every compliance contract run. Fixed in `skills/architecture-compliance/SKILL.md` (orchestrator) and all 10 agent files by changing the pattern to `**/skills/architecture-compliance/SKILL.md`, which matches both dev and marketplace paths correctly.

### v2.10.36 (Previous Release) ✅
**fix: Responsible Role always populated — BC/SRE templates now use category-specific roles; all agents forbidden from defaulting to N/A**

Business Continuity and SRE compliance contracts were generating N/A in the Responsible Role column because both templates used a generic `[Role or N/A]` placeholder with no role hint, and all 10 agent instructions permitted defaulting to N/A. Fix: (1) BC template now maps roles by category — BC-GEN → Solution Architect, BC-DR/BC-RTO → Business Continuity Manager, BC-BACKUP → Infrastructure Architect, BC-AUTO → Platform Engineer, BC-CLOUD → Cloud Architect — across all 86 occurrences (summary table + detailed sections). (2) SRE template table rows now use Practice/Observability → SRE Lead, Automation → Platform Engineer; detailed section entries cleaned up from `SRE Engineer or N/A` to plain `SRE Engineer`. (3) All 10 agent instructions updated: role placeholders must resolve to the template-specified role name; N/A is only permitted when Status = "Not Applicable".

### v2.10.35 (Previous Release) ✅
**fix: auto-populate [NEXT_REVIEW_DATE] as generation date +6 months; fix Section 1.6 stack validation placeholders left unreplaced in Development contract**

Two fixes in one release: (1) `[NEXT_REVIEW_DATE]` in the Document Control table was never replaced — added `getNextReviewDate()` to `date-utils.ts` and wired it into `field-updater.ts` so it computes generation date + 6 months with correct month-end clamping. (2) Development contract Section 1.6 "Stack Validation Checklist" had ~30 unreplaced placeholders (`[JAVA_ITEM_1]`–`[JAVA_ITEM_6]`, `[DOTNET_*]`, `[FRONTEND_*]`, `[OTHER_STACKS_*]`, `[EXCEPTIONS_*]`, `[TOTAL_ITEMS]`, etc.) — removed the dead "Dynamic Field Mapping Instructions" block from the template and added Step 4.6 to the development agent with full 26-item evaluation criteria (Java, .NET, Frontend, Other Stacks, Exceptions). Added 6 new tests for `getNextReviewDate` and `[NEXT_REVIEW_DATE]` field-updater replacement.

### v2.10.34 (Previous Release) ✅
**fix: shorten Compliance Summary table Requirement columns in Business Continuity and SRE templates to use section titles instead of full descriptions; simplify SRE Category column to prefix-only (Practice/Observability/Automation)**

Aligns the two remaining outlier templates (Business Continuity: 43 rows, SRE: 57 rows) with the short-title pattern already used by the other 8 compliance templates. BC Requirement column now uses H2 section titles (e.g., "Application or Initiative Name" instead of the full question). SRE Requirement column uses H2 section titles and Category column simplified from "Practice - Log Management" to just "Practice".

### v2.10.33 (Previous Release) ✅
**feat: standardize Questions & Gaps Register across all 10 compliance contracts; add Word export for compliance contracts; fix TypeScript errors; expand test coverage**

Replaces three inconsistent post-appendix gap sections (5-col "Missing Data", 3-col "Not Applicable", 4-col "Unknown Status") with a single unified `## Questions & Gaps Register` (8 columns: Code | Requirement | Type | Status | Owner | ARCHITECTURE.md Section | Action Required | Priority) populated automatically by the post-generation pipeline. New `questions-register-populator.ts` derives priority (Critical/High/Medium/Low) and action text from the domain validation JSON — agents are explicitly forbidden from populating it. Added `compliance` doc type to `generate-doc.js` (purple `#7B2D8E`) with yellow-highlighted editable cells (Owner, Action Required, Priority) and status-conditional coloring in the Compliance Summary table. Added full Workflow C to `architecture-docs-export/SKILL.md` for exporting compliance contracts to Word. Fixed inline A.2 schema violations in Development and Integration templates (now use shared `@include-with-config`). Fixed 2 pre-existing TypeScript errors. Added 78 new tests across 4 new test files (questions-register-populator, manifest-generator, resolve-includes, contract-types). Deleted 3 deprecated shared section templates.

### v2.10.28 ✅
**feat: enforce internal section numbers (S1-S12) across all skills and agents; add supplementary context file intake to architecture creation**

Adds explicit S1-S12 section number disambiguation throughout all architecture skills and compliance agents — file prefix numbers (01-10) now never conflate with internal section numbers (S9 = `docs/07-security-architecture.md`, not `docs/09-*`). Added canonical S-prefix mapping table and WARNING blocks to ARCHITECTURE_DOCUMENTATION_GUIDE.md, RESTRUCTURING_GUIDE.md, SKILL.md, QUERY_SECTION_MAPPING.md, SECTION_MAPPING_GUIDE.md, and VALIDATIONS.md. Updated all 10 compliance generator agents with a disambiguation note at their Section Mapping. Fixed all legacy `Section N.M` source references in validation examples, test fixtures, and compliance guides to use file paths. Also added Step 0.5 to the architecture creation workflow: after the PO Spec gate, the user is prompted for supplementary context files (ADRs, HLD PDFs, tech stack specs, OpenAPI/AsyncAPI, data models, NFRs, IaC templates) before architecture type selection — HLD documents are enforced as PDF-only.

### v2.10.27 (Previous Release) ✅
**feat: add Async Intake mode to architecture-readiness skill**

New 4th mode for file-based requirements extraction from tickets, emails, or documents. Reads a context file, maps content to the 8 PO Spec sections using keyword indicators, scores against the weighted rubric, and produces `PO_SPEC_GAP_REPORT.md` with ready-to-send questions prioritized by section weight. If score ≥7.5, also drafts `PRODUCT_OWNER_SPEC.md` automatically. No interactive interview — fully async. Added `ASYNC_INTAKE_GUIDE.md`, updated `architecture-docs` PO Spec gate with Option 4, and updated CLAUDE.md and README.

See [CHANGELOG.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/CHANGELOG.md) for full version history.

### v2.10.26 (Previous Release) ✅
**feat: auto-delete superseded compliance contracts in post-generation pipeline**

The pipeline now detects when multiple contracts of the same type exist with different dates, keeps only the newest, and deletes the older ones automatically. Each removal is logged. The JSON summary includes a `removedContracts` field and the SKILL.md orchestrator reporting was updated to relay the cleanup notice to the user.

### v2.10.25 (Previous Release) ✅
**docs: expand compliance approval paths in Workflow Integration diagram**

Updated the Workflow Integration diagram to show both compliance approval paths: auto-approval (score ≥8.0) and manual review (score 7.0–7.9), with both converging on Dev Handoffs before proceeding to Export.

### v2.10.24 (Previous Release) ✅
**docs: add refinement feedback edge from peer review Quality Gate back to Architecture Team**

Added `Refine` edge from the peer review Quality Gate back to the Architecture Team node in the Workflow Integration diagram, reflecting that failed reviews loop back for architecture refinement before re-submission.

### v2.10.23 (Previous Release) ✅
**docs: convert Workflow Integration diagram to top-down layout**

Changed the Workflow Integration mermaid diagram from left-to-right (`graph LR`) to top-down (`graph TD`) for better readability on standard screen widths.

### v2.10.22 (Previous Release) ✅
**docs: overhaul README to reflect four-phase workflow and migrate version history to CHANGELOG**

Rewrote README from ~1048 to ~581 lines: corrected three-phase → four-phase workflow, updated overview diagram, Quick Start, and Features section to include Phase 4 (Dev Handoff + Doc Export); documented `architecture-blueprint` and quality gate skills (peer review, compliance review); removed stale version markers; replaced the 530-line roadmap/changelog block with a slim current-version summary linked to CHANGELOG.md; migrated all version history (v1.2.0–v2.10.21) to CHANGELOG.md.

### v2.10.21 (Previous Release) ✅
**feat: add redis-key-schema.md asset type for Redis/Cache components in dev handoff**

### Future Releases 🚀

- Improved playground interactivity for compliance review and peer review
- Additional architecture type templates

---

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

### Reporting Issues

If you encounter problems:
1. Check the [Troubleshooting Guide](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/docs/TROUBLESHOOTING.md)
2. Search [existing issues](https://github.com/shadowx4fox/solutions-architect-skills/issues)
3. Open a new issue with detailed description

### Feature Requests

Have an idea for improvement? Open an issue with the `enhancement` label.

## Version History

See [CHANGELOG.md](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/CHANGELOG.md) for detailed version history.

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/shadowX4fox/solutions-architect-skills/tree/HEAD/LICENSE) file for details.

## Author

**shadowx4fox**
- GitHub: [@shadowx4fox](https://github.com/shadowx4fox)
- Repository: [solutions-architect-skills](https://github.com/shadowx4fox/solutions-architect-skills)

## Acknowledgments

- Built for [Claude Code](https://claude.com/claude-code) by Anthropic
- Follows enterprise architecture best practices
- Inspired by organizational compliance frameworks

---

**Get Started:** Download the [latest release](https://github.com/shadowX4fox/solutions-architect-skills/releases) and transform your architecture workflow today!