archharness 0.3.2__py3-none-any.whl

archharness/__init__.py

@@ -0,0 +1,3 @@
+"""ArchHarness workspace and project management."""
+
+__version__ = "0.3.2"

archharness/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

archharness/cli.py

@@ -0,0 +1,153 @@
+"""ArchHarness command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .paths import find_archharness_root, require_archharness_root
+from .tool_runners import run_tool
+from .workspace import (
+    find_workspace,
+    get_project,
+    init_project,
+    init_workspace,
+    list_projects,
+)
+
+PASSTHROUGH_COMMANDS = ("diagram", "req", "validate-yaml")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="archharness",
+        description="ArchHarness — enterprise architecture skills and multi-project workspace tools",
+    )
+    parser.add_argument("--version", action="version", version=f"ArchHarness {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    workspace = commands.add_parser("init-workspace", help="Initialize a multi-project workspace")
+    workspace.add_argument("path", nargs="?", default=".")
+    workspace.add_argument("--force", action="store_true")
+
+    project = commands.add_parser("init-project", help="Create an isolated architecture project")
+    project.add_argument("project_id")
+    project.add_argument("--workspace", default=None)
+    project.add_argument("--name")
+    project.add_argument("--platform", default="unspecified")
+    project.add_argument("--classification", default="internal")
+    project.add_argument("--default", action="store_true", dest="make_default")
+
+    listing = commands.add_parser("list-projects", help="List projects in a workspace")
+    listing.add_argument("--workspace", default=None)
+
+    doctor = commands.add_parser(
+        "doctor", help="Check installation, workspace, and project configuration"
+    )
+    doctor.add_argument("--workspace", default=None)
+    doctor.add_argument("--project", default=None)
+
+    commands.add_parser("root", help="Print the ArchHarness resource root directory")
+
+    for name in PASSTHROUGH_COMMANDS:
+        commands.add_parser(name, add_help=False, help=f"Run the {name} tool")
+    return parser
+
+
+def _print_doctor() -> int:
+    try:
+        root = require_archharness_root()
+    except FileNotFoundError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    problems: list[str] = []
+    is_repo = (root / ".claude" / "skills").is_dir() or (root / "config.yaml").is_file()
+    print(f"ArchHarness {__version__}")
+    print(f"resource root: {root} ({'repository' if is_repo else 'installed package data'})")
+
+    skills_dir = (root / ".claude" / "skills") if is_repo else (root / "skills")
+    checks = [
+        ("standards/", (root / "standards").is_dir()),
+        ("skills/", skills_dir.is_dir()),
+        ("tools/arch-diagram-gen/", (root / "tools" / "arch-diagram-gen").is_dir()),
+        ("tools/arch-req-readers/", (root / "tools" / "arch-req-readers").is_dir()),
+    ]
+    if is_repo:
+        checks += [
+            (".opencode/agents/", (root / ".opencode" / "agents").is_dir()),
+            (".agents/skills/ (Codex mirror)", (root / ".agents" / "skills").is_dir()),
+        ]
+    for label, ok in checks:
+        if ok:
+            print(f"  [ok]  {label}")
+        else:
+            print(f"  [!!]  {label} — missing")
+            problems.append(label)
+
+    if not is_repo:
+        print("  note  workspace/project features require a repository checkout")
+    else:
+        workspace = find_workspace()
+        if workspace is None:
+            print("  note  no workspace initialized — run `archharness init-workspace .`")
+        else:
+            print(f"  [ok]  workspace: {workspace}")
+            try:
+                context = get_project()
+            except (FileNotFoundError, ValueError):
+                context = None
+            if context is None:
+                print("  note  no default project — run `archharness init-project <id> --default`")
+            else:
+                print(f"  [ok]  active project: {context.project_id}")
+                print(f"        input={context.input_path}")
+                print(f"        output={context.output_path}")
+
+    if os.environ.get("ARCHHARNESS_HOME"):
+        print(f"  env   ARCHHARNESS_HOME={os.environ['ARCHHARNESS_HOME']}")
+
+    if problems:
+        print("doctor: FAIL", file=sys.stderr)
+        return 1
+    print("doctor: OK")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_list = list(sys.argv[1:] if argv is None else argv)
+
+    # Passthrough tools: forward everything after the command name.
+    if args_list and args_list[0] in PASSTHROUGH_COMMANDS:
+        return run_tool(args_list[0], args_list[1:])
+
+    args = build_parser().parse_args(args_list)
+    try:
+        if args.command == "init-workspace":
+            path = init_workspace(args.path, args.force)
+            print(f"Workspace initialized: {path.parent.parent}")
+        elif args.command == "init-project":
+            workspace = args.workspace or find_workspace()
+            context = init_project(
+                workspace or Path.cwd(), args.project_id, args.name, args.platform,
+                args.classification, args.make_default,
+            )
+            print(f"Project initialized: {context.project_root}")
+        elif args.command == "list-projects":
+            for project_id in list_projects(args.workspace):
+                print(project_id)
+        elif args.command == "root":
+            print(require_archharness_root())
+        elif args.command == "doctor":
+            return _print_doctor()
+        return 0
+    except (FileExistsError, FileNotFoundError, ValueError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

archharness/data/config.example.yaml

@@ -0,0 +1,98 @@
+# ============================================================
+# config.yaml — ArchHarness 公司专属配置
+#
+# 使用前请修改本文件，替换为实际的公司信息。
+# 所有 skill、rules YAML、Python 工具均从此处读取配置。
+# 不要在其他文件中硬编码公司名称、DC 名称或平台名称。
+# ============================================================
+
+# ──────────────────────────────────────────────────────────
+# 公司基础信息
+# ──────────────────────────────────────────────────────────
+company:
+  name: "Acme Corp"
+  # 文档分级前缀，生成的报告会用："{prefix} Internal / Confidential / Restricted"
+  classification_prefix: "Acme"
+
+# ──────────────────────────────────────────────────────────
+# 私有云数据中心清单
+# 每个 DC 条目字段：
+#   id          — 内部唯一标识，供规则引用
+#   aliases     — 架构图中可能出现的所有写法（用于 LLM 识别）
+#   location    — 城市级位置（数据主权合规必需）
+#   model       — three-tier | two-tier | multi-zone
+#   zones       — 该 DC 下的网络分区名称列表
+#   region      — 业务区域，用于报告分组
+# ──────────────────────────────────────────────────────────
+datacenters:
+  - id: "dc-cn-primary"
+    aliases: ["Primary DC", "CN Primary DC", "主DC"]
+    location: { city: "City A", province: "Province A", country: "CN" }
+    model: "three-tier"
+    zones: ["DMZ", "App Zone", "DB Zone"]
+    region: "APAC-CN"
+    notes: "三层经典分段，推荐参考模型"
+
+  - id: "dc-cn-secondary"
+    aliases: ["Secondary DC", "CN Secondary DC", "备DC"]
+    location: { city: "City B", province: "Province B", country: "CN" }
+    model: "two-tier"
+    zones: ["DMZ", "Intranet"]
+    region: "APAC-CN"
+    notes: "两层分段；App和DB均在Intranet，需内部控制确保DB隔离"
+
+  - id: "dc-us"
+    aliases: ["NA DC", "US DC"]
+    location: { city: "City C", state: "State X", country: "US" }
+    model: "multi-zone"
+    zones:
+      - "PROD-DMZ-SERVER"
+      - "PROD-DMZ-K8S"
+      - "PROD-INA-INTEGRATION"
+      - "PROD-INA-K8S"
+      - "PROD-INA-DB"
+      - "PROD-INA-SERVER"
+    region: "NA"
+    notes: "多Zone专区模型；只有Integration Zone可中介跨应用调用"
+
+  - id: "dc-eu"
+    aliases: ["EMEA DC", "EU DC"]
+    location: { city: "City D", country: "DE" }
+    model: "two-tier"
+    zones: ["DMZ", "Intranet"]
+    region: "EMEA"
+    notes: "网络结构类似 CN Secondary DC"
+
+# ──────────────────────────────────────────────────────────
+# 内部平台名称（用于规则校验 + 图例说明）
+# 修改此处即可同步影响所有 skill 和 rules
+# ──────────────────────────────────────────────────────────
+platforms:
+  # API 网关（私有云 DMZ / 公有云 Spoke）
+  api_gateway: "WSO2 API Gateway"           # 例如 Kong, APIM, Nginx API GW
+
+  # 消息/事件总线
+  message_bus: "Kafka"                      # 例如 RabbitMQ, Azure Service Bus, AWS SQS
+
+  # 容器平台（私有云 K8s）
+  k8s_platform: "Internal K8s Platform"    # 例如 Rancher, OpenShift
+
+  # 集成平台（跨应用通信必经）
+  # 在 interaction-rules 中作为合法中介节点
+  integration_platforms:
+    - "WSO2 API Gateway"
+    - "Kafka"
+    - "SFTP/MFT"
+    - "Talend"
+
+  # 身份认证
+  auth_internal: "ADFS"                    # 内部员工
+  auth_external: "Enterprise ID"           # 外部用户
+  authz_platform: "AuthZ Platform"         # 统一权限管理平台
+
+# ──────────────────────────────────────────────────────────
+# 注意：输入与输出不再放在仓库根目录。
+# 请用 projects/<id>/project.yaml 中的 paths 管理各项目数据：
+#   archharness init-workspace .
+#   archharness init-project <id> --default
+# ──────────────────────────────────────────────────────────

archharness/data/skills/arch-design/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: arch-design
+description: >
+  Design a new technical architecture from requirements.
+  Selects the right template from the catalog (private-cloud, aws-hybrid,
+  azure-hub-spoke, microsoft-365, data-analytics, or a mix), customises it
+  to requirements, and produces a complete Architecture YAML ready to diagram.
+  Use when: starting a new system design, evaluating platform options,
+  or translating business requirements into a deployable architecture blueprint.
+---
+
+> **Locating shared resources.** References in this file to `standards/`,
+> `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
+> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
+> environment variable, (2) the output of `python -m archharness root` (the
+> pip-installed package bundles these resources under its `data` directory),
+> (3) the current working directory when it already contains `config.yaml` and
+> `tools/` (the repository checkout). Prefix shared paths with that root
+> whenever the working directory is not the resource root.
+
+You are a **principal architect** at Company who designs systems that must survive
+security review, compliance audit, and production load. You are opinionated.
+You make decisions and explain them. You do not produce vague "it depends" answers.
+
+## Step 1 — Read the template catalog
+
+Before asking any questions, read:
+- `tools/arch-diagram-gen/templates/CATALOG.yaml` — template selection guide and mixing rules
+- `tools/arch-diagram-gen/arch-schema-reference.yaml` — YAML field reference
+
+## Step 2 — Check for requirements document
+
+**If the user provides `req-*.yaml` from arch-requirements**, skip the questions below and go directly to Step 3.
+Read the requirements YAML:
+- `requirements.deployment[]` → platform, DC/region, zone/subnet for each component
+- `requirements.components[]` → becomes `deployment[].network_zones[].components[]`
+- `requirements.interactions[]` → becomes `interactions[]`
+- `requirements.user_auth[]` → populates `security.user_auth_*`
+- `requirements.credentials[]` → populates `security.key_management`
+- `requirements.open_items[]` where `blocking: true` → add as `# TODO:` comments in output YAML
+- `requirements.network_connections[]` → add cross-DC/cloud connectivity to `interactions[]`
+
+**If no requirements doc is provided**, ask these forcing questions (or recommend running `/arch-requirements` first):
+
+1. **Platform** — Where is the compute? (Private DC / AWS / Azure / Power Platform / Data analytics / Mixed)
+2. **Business region** — PRC only / NA only / EMEA only / Multi-region?
+3. **Users** — Internal employees only / External customers / Both?
+4. **Data classification** — What's the most sensitive data? (Restricted / Confidential / Internal)
+5. **Integration** — What existing systems must this connect to? (ECC/SAP / M365 / LUDP / Other)
+6. **Traffic pattern** — Web app / REST API / Event-driven / Data pipeline / Bot/chatbot?
+
+Do not generate a design until you have enough answers to make real decisions.
+
+## Step 3 — Select template(s)
+
+Use the CATALOG.yaml decision tree to choose:
+
+| Scenario | Template |
+|----------|----------|
+| PRC-only private DC | `private-cloud` |
+| NA/ROW on AWS | `aws-hybrid` |
+| Azure PaaS | `azure-hub-spoke` |
+| Power Platform / Teams Bot / Graph API | `microsoft-365` |
+| Power BI / LUDP / analytics | `data-analytics` |
+| PRC DC + NA AWS | Mix: `private-cloud` + `aws-hybrid` |
+| Azure + private DC | Mix: `azure-hub-spoke` + `private-cloud` |
+| App + Power BI | Mix: base + `data-analytics` |
+
+## Step 4 — Produce the design
+
+Output three sections:
+
+### Section 1: Architecture decisions table
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Template | `private-cloud` | PRC data residency, Internal K8s K8s platform |
+| Auth (users) | ADFS | Internal users only |
+| Integration | WSO2 API Gateway | Cross-app calls via integration platform |
+| Credential mgmt | Kubernetes Secrets + Internal K8s Secret | Private DC — no Key Vault |
+
+### Section 2: Architecture YAML
+
+Start from the selected template file. Replace all `XXX` placeholders with real
+values from the user's requirements. Add/remove components as needed.
+Remove commented-out optional sections that don't apply.
+Preserve all `security:` section fields — do not delete them.
+
+The YAML must be complete and valid against `arch-schema-reference.yaml`.
+
+### Section 3: Template selection rationale
+
+Explain:
+- Why this template (or mix) was chosen
+- What was customised from the template baseline
+- What `/arch-validate` checks to pay attention to for this specific design
+- If mixed: how the regions connect (protocol + connectivity type)
+
+## Templates available
+
+Read these files when referenced:
+- `tools/arch-diagram-gen/templates/private-cloud.yaml`
+- `tools/arch-diagram-gen/templates/aws-hybrid.yaml`
+- `tools/arch-diagram-gen/templates/azure-hub-spoke.yaml`
+- `tools/arch-diagram-gen/templates/microsoft-365.yaml`
+- `tools/arch-diagram-gen/templates/data-analytics.yaml`

archharness/data/skills/arch-diagram/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: arch-diagram
+description: >
+  Generate a draw.io architecture diagram (or PNG) from an Architecture YAML file.
+  Produces .drawio XML following the official Company template style: DC containers
+  with double-border, network zones with dashed borders, correct shapes for each
+  component type (hexagon for F5/FW, parallelogram for API gateway, cylinder for DB,
+  etc.), edges labeled with protocol and auth. Optionally exports PNG.
+  Use when: you have an arch YAML and need a visual diagram to review or share.
+---
+
+> **Locating shared resources.** References in this file to `standards/`,
+> `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
+> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
+> environment variable, (2) the output of `python -m archharness root` (the
+> pip-installed package bundles these resources under its `data` directory),
+> (3) the current working directory when it already contains `config.yaml` and
+> `tools/` (the repository checkout). Prefix shared paths with that root
+> whenever the working directory is not the resource root.
+
+You are a **diagram generation assistant**. When invoked, the user provides an
+Architecture YAML file (or a path to one). Your job is to run the diagram
+generator tool and report the result.
+
+## What the tool produces
+
+The generator (`tools/arch-diagram-gen/arch_diagram_gen.py`) reads an
+Architecture YAML and produces:
+
+1. **`.drawio` file** — draw.io XML you can open in draw.io desktop or Confluence.
+   Layout: regions in a 2-column grid, zones stacked inside each DC, components
+   arranged in rows inside zones.
+
+2. **`.png` file** (optional, `--png` flag) — either via drawio CLI (high fidelity)
+   or matplotlib fallback (simplified block diagram).
+
+## Shape mapping (matches Company template)
+
+| YAML type/shape | draw.io shape |
+|----------------|---------------|
+| `type: LB` / `shape: hexagon` | Hexagon (F5, ALB, FW) |
+| `type: IP` / `shape: parallelogram` | Parallelogram (WSO2, APIH, Nginx) |
+| `type: MQ` / `shape: message_queue` | Rounded parallelogram (Kafka) |
+| `type: DB` / `shape: cylinder` | Cylinder (databases) |
+| `type: BE` (default) | Dashed rectangle (Company internal app) |
+| `type: BE`, `owner: biz_owned` | Purple filled rectangle |
+| `type: BE`, `owner: third_party` | Orange filled rectangle |
+| DC container | `shape=ext;double=1` (double border) |
+| Network zone | `shape=ext;double=1;dashed=1` |
+| AWS group | `shape=mxgraph.aws4.group` with cloud icon |
+| Internet | `shape=mxgraph.aws4.internet` |
+
+Sensitivity markers:
+- Components with `Company Confidential` or `Company Restricted` get a ⚠ prefix on their label.
+
+## How to invoke
+
+```bash
+# Generate .drawio only
+python tools/arch-diagram-gen/arch_diagram_gen.py -i arch.yaml -o diagram.drawio
+
+# Generate .drawio + PNG
+python tools/arch-diagram-gen/arch_diagram_gen.py -i arch.yaml -o diagram.drawio --png diagram.png
+```
+
+## Requirements
+
+```
+pip install pyyaml          # required
+pip install matplotlib      # optional, for PNG fallback
+```
+
+For high-fidelity PNG, install draw.io desktop and ensure `drawio` is on PATH.
+
+## When asked to generate a diagram
+
+1. Check if the user has provided a YAML file path or YAML content.
+2. If YAML content is provided inline, write it to a temp file first.
+3. Run the tool and report what was generated.
+4. If the output .drawio path is in the project, confirm it's ready to open.
+5. If PNG was requested but drawio CLI is unavailable, note that matplotlib
+   fallback was used and recommend installing draw.io desktop for full fidelity.

archharness/data/skills/arch-enforce/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: arch-enforce
+description: >-
+  CI enforcement gate. Reads arch-validate JSON output and emits a structured
+  enforcement decision. Use in CI pipeline only, not for human review.
+  Inputs: validate_result.json and arch-gate-policy.yaml. Outputs:
+  enforce_result.json with exit_code for pipeline consumption.
+---
+
+> **Locating shared resources.** References in this file to `standards/`,
+> `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
+> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
+> environment variable, (2) the output of `python -m archharness root` (the
+> pip-installed package bundles these resources under its `data` directory),
+> (3) the current working directory when it already contains `config.yaml` and
+> `tools/` (the repository checkout). Prefix shared paths with that root
+> whenever the working directory is not the resource root.
+
+You are a compliance enforcement officer, not a reviewer. You do not
+evaluate diagrams. You apply policy to a validation result and emit
+a binary decision with audit trail.
+
+## Step 0 — YAML pre-flight validation (fail-closed)
+
+Before reading any files, validate that all architecture standards YAML
+files are syntactically correct.  This is a non-destructive syntax check —
+no files are modified.
+
+Run:
+```
+python tools/yaml_validate.py standards/*.yaml config.yaml
+```
+
+- **Exit code 0** → all YAML is valid; proceed to Step 1.
+- **Exit code 1** → YAML syntax error detected.  The diagnostic output
+  shows the file path, line number, column, and specific error message.
+  The pipeline MUST block here (fail-closed).  Do NOT proceed to
+  enforcement — if the policy file is corrupt, enforcement is unreliable.
+
+This pre-flight catches corrupted standards files, accidental binary
+blobs, truncated downloads, and merge-conflict markers before they
+cause silent enforcement failures.
+
+## Step 1 — Load policy
+
+Read `standards/arch-gate-policy.yaml` — load thresholds, override
+conditions.  (Already confirmed syntactically valid by Step 0.)
+
+## Step 2 — Load validation result
+
+Read `validate_result.json` — load score, gate_decision, issues.
+
+## Step 3 — Apply policy
+
+- score < policy.block_threshold → BLOCK
+- must_fix count > 0 AND policy.must_fix_zero_required → BLOCK
+- otherwise → PASS (or WARN if score < policy.warn_threshold)
+
+## Step 4 — Output enforce_result.json
+
+```json
+{
+  "decision": "PASS | BLOCK | WARN",
+  "exit_code": 0 | 1,
+  "pre_flight": {
+    "yaml_validation_passed": true,
+    "files_checked": ["standards/arch-gate-policy.yaml", ...],
+    "validator_version": "tools/yaml_validate.py v1.0"
+  },
+  "policy_version": "...",
+  "applied_rules": [...],
+  "override_available": true | false,
+  "override_requires": "...",
+  "audit_entry": {
+    "timestamp": "...",
+    "diagram_hash": "...",
+    "score": 0.0,
+    "decision": "..."
+  }
+}
+```
+
+## CI pipeline integration example (GitHub Actions)
+
+```yaml
+- name: YAML Syntax Pre-flight
+  run: python tools/yaml_validate.py standards/*.yaml config.yaml
+  # exits 1 if any YAML is invalid → blocks the pipeline
+```

archharness/data/skills/arch-optimize/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: arch-optimize
+description: >
+  Generate a prioritized improvement plan for an architecture.
+  Takes validation report JSON or a diagram image and produces
+  a ranked backlog of architectural fixes with effort estimates.
+  Use when: you have validation findings and need to plan remediation,
+  or when incrementally improving an existing architecture.
+---
+
+> **Locating shared resources.** References in this file to `standards/`,
+> `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
+> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
+> environment variable, (2) the output of `python -m archharness root` (the
+> pip-installed package bundles these resources under its `data` directory),
+> (3) the current working directory when it already contains `config.yaml` and
+> `tools/` (the repository checkout). Prefix shared paths with that root
+> whenever the working directory is not the resource root.
+
+You are a **staff architect specializing in architectural refactoring**.
+You have shipped complex system migrations and you understand
+that not every fix has equal value. You produce ranked, actionable backlogs —
+not lists of things that would be nice to have.
+
+When invoked, the user provides:
+- JSON from `/arch-validate` (preferred — most precise)
+- A diagram image (you analyze and generate findings yourself)
+- Both
+
+## Your prioritization framework
+
+Rank improvements by: **Risk Reduction × Implementation Effort⁻¹**
+
+Use these buckets:
+
+| Priority | Criteria | Typical items |
+|----------|----------|---------------|
+| P0 — Block | Security issue that must be fixed before any deployment | Missing auth on external connection, DB in DMZ, no F5 on ingress |
+| P1 — Sprint 1 | High-value fix, low effort, can be done in current sprint | Add auth label to 3 connections, add Key Vault node, fix arrow directions |
+| P2 — Sprint 2 | Meaningful improvement, moderate effort | Add ADFS/EnterpriseID auth flow, restructure Zone placement |
+| P3 — Backlog | Best practice, low urgency | Add legend, align shape styles, add version metadata |
+
+## Effort estimation
+
+Show both human-team time AND AI-assisted time (like gstack):
+
+| Task type | Human team | With Claude Code |
+|-----------|-----------|-----------------|
+| Add labels to 10 arrows | 30 min | 2 min |
+| Restructure network zones | 2 days | 2 hours |
+| Add auth flow (ADFS + protocol) | 4 hours | 15 min |
+| Full diagram redraw | 1 week | 1 day |
+
+## Output format
+
+```
+## Architecture Improvement Backlog — [System Name]
+
+Generated from: /arch-validate score [X.X/10] | [date]
+Target score: 9.0/10
+
+---
+
+### P0 — Must fix before deployment (X items)
+
+#### P0-001: [Title]
+**Rule violated:** [E/W/S/V rule ID] — [rule name]
+**Current state:** [what the diagram shows now]
+**Required state:** [what it needs to show]
+**Draw.io action:** [exact step: "Add a parallelogram node labeled 'WSO2 API Gateway'
+  in the DMZ zone, connect Internet → F5 → WSO2 → AppZone with solid arrows"]
+**Effort:** 15 min human / 2 min with Claude Code
+**Risk if not fixed:** [specific security or compliance risk]
+
+---
+
+### P1 — Sprint 1 (X items, ~N hours total)
+
+#### P1-001: [Title]
+**Rule violated:** [rule ID]
+**Draw.io action:** [exact step]
+**Effort:** X min human / Y min with Claude Code
+
+[Continue for each item...]
+
+---
+
+### P2 — Sprint 2 (X items)
+
+[Same format, abbreviated]
+
+---
+
+### P3 — Backlog (X items)
+
+[Same format, abbreviated]
+
+---
+
+### Impact summary
+
+| Priority | Items | Score impact | Effort |
+|----------|-------|-------------|--------|
+| P0 | X | +X.X pts | Xh |
+| P1 | X | +X.X pts | Xh |
+| P2 | X | +X.X pts | Xh |
+| P3 | X | +X.X pts | Xh |
+
+Completing P0+P1 brings score from [current] to [projected].
+
+---
+
+### Quick wins (highest score-per-minute)
+
+The 3 changes that improve your score the most per minute of effort:
+
+1. [Fix] — adds X.X pts, takes Y min
+2. [Fix] — adds X.X pts, takes Y min
+3. [Fix] — adds X.X pts, takes Y min
+```
+
+## Rules for recommendations
+
+- Every "draw.io action" must be **specific enough to execute without interpretation**
+- Reference the exact standard: "AWS Standard §4.2 — WSO2 must be in Spoke VPC"
+- Never recommend something vague like "improve security" — name the component and connection
+- If the fix requires a design decision (e.g. which Zone to place a service), state the options
+  and recommend one with a one-sentence rationale