@1aboveio/skills 0.20.2 → 0.20.4

package/skills/compliance/doc-authenticity/scripts/validate_verdict.py

@@ -0,0 +1,308 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""Validate a schema-version 2.2 routed dual-axis authenticity verdict."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+AUTH_VERDICTS = {
+    "NO_EVIDENCE_OF_MODIFICATION",
+    "SUSPICIOUS",
+    "LIKELY_MODIFIED",
+    "INCONCLUSIVE",
+}
+VALIDITY_VERDICTS = {"VALID", "INVALID", "INCONCLUSIVE"}
+CONFIDENCES = {"HIGH", "MEDIUM", "LOW"}
+RESULTS = {"PASS", "FLAG", "FAIL", "NA"}
+DOC_TYPES = {"bank_statement", "conversation_log", "invoice", "agreement", "other"}
+SCHEMA_VERSION = "2.2"
+PDF_AUTH_IDS = [f"F{i}" for i in range(1, 10)]
+IMAGE_AUTH_IDS = [f"I{i}" for i in range(1, 10)]
+VALIDITY_IDS = {
+    "bank_statement": [f"C{i}" for i in range(1, 6)] + [f"D{i}" for i in range(1, 6)],
+    "invoice": [f"N{i}" for i in range(1, 9)],
+    "agreement": [f"A{i}" for i in range(1, 9)],
+    "conversation_log": [],
+    "other": [],
+}
+EXPECTED = {
+    **{f"F{i}": ("authenticity", "file_forensics") for i in range(1, 10)},
+    **{f"I{i}": ("authenticity", "file_forensics") for i in range(1, 10)},
+    **{f"C{i}": ("validity", "content") for i in range(1, 6)},
+    **{f"D{i}": ("validity", "domain") for i in range(1, 6)},
+    **{f"N{i}": ("validity", "content") for i in (2, 3, 4, 7)},
+    **{f"N{i}": ("validity", "domain") for i in (1, 5, 6, 8)},
+    **{f"A{i}": ("validity", "content") for i in (2, 4, 5, 7)},
+    **{f"A{i}": ("validity", "domain") for i in (1, 3, 6, 8)},
+}
+
+
+def nonempty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def expected_authenticity(
+    seen: dict[str, dict], auth_ids: list[str], file_type: str
+) -> str:
+    results = [seen[cid]["result"] for cid in auth_ids]
+    fails = results.count("FAIL")
+    flags = results.count("FLAG")
+    decisive_fail = any(
+        seen[cid]["result"] == "FAIL" and seen[cid]["decisive"] for cid in auth_ids
+    )
+    if decisive_fail or fails >= 2 or (fails == 1 and flags >= 2):
+        return "LIKELY_MODIFIED"
+    if (
+        fails == 1
+        or flags >= 3
+        or (file_type == "image" and seen["I2"]["result"] == "FLAG")
+    ):
+        return "SUSPICIOUS"
+    if results.count("NA") * 2 >= len(results):
+        return "INCONCLUSIVE"
+    return "NO_EVIDENCE_OF_MODIFICATION"
+
+
+def expected_validity(seen: dict[str, dict], validity_ids: list[str]) -> str:
+    if not validity_ids:
+        return "INCONCLUSIVE"
+    results = [seen[cid]["result"] for cid in validity_ids]
+    fails = results.count("FAIL")
+    decisive_fail = any(
+        seen[cid]["result"] == "FAIL" and seen[cid]["decisive"] for cid in validity_ids
+    )
+    if decisive_fail or fails >= 2:
+        return "INVALID"
+    if fails or results.count("FLAG") > 2 or results.count("NA") * 2 >= len(results):
+        return "INCONCLUSIVE"
+    return "VALID"
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: validate_verdict.py <verdict.json>", file=sys.stderr)
+        return 2
+    try:
+        verdict = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        print(f"ERROR: not valid JSON: {exc}")
+        return 1
+
+    if not isinstance(verdict, dict):
+        print("ERROR: verdict root must be an object")
+        return 1
+
+    errors: list[str] = []
+    required = {
+        "schema_version",
+        "artifact",
+        "authenticity",
+        "validity",
+        "checks",
+        "summary",
+        "checked_at",
+    }
+    missing = required - set(verdict)
+    extra = set(verdict) - required
+    if missing:
+        errors.append(f"missing keys: {sorted(missing)}")
+    if extra:
+        errors.append(f"unknown top-level keys: {sorted(extra)}")
+    if verdict.get("schema_version") != SCHEMA_VERSION:
+        errors.append(f"schema_version must be {SCHEMA_VERSION!r}")
+
+    artifact = verdict.get("artifact", {})
+    artifact_keys = {
+        "path",
+        "file_type",
+        "media_type",
+        "size_bytes",
+        "sha256",
+        "extension_magic_match",
+        "doc_type",
+        "detail",
+        "claimed_issuer",
+        "supplied_claim",
+    }
+    if not isinstance(artifact, dict):
+        errors.append("artifact must be an object")
+        artifact = {}
+    else:
+        missing_artifact = artifact_keys - set(artifact)
+        extra_artifact = set(artifact) - artifact_keys
+        if missing_artifact:
+            errors.append(f"artifact missing keys: {sorted(missing_artifact)}")
+        if extra_artifact:
+            errors.append(f"artifact has unknown keys: {sorted(extra_artifact)}")
+    file_type = artifact.get("file_type")
+    doc_type = artifact.get("doc_type")
+    media_type = artifact.get("media_type")
+    if file_type not in {"pdf", "image"}:
+        errors.append("artifact.file_type must be pdf or image")
+    if doc_type not in DOC_TYPES:
+        errors.append(f"artifact.doc_type must be one of {sorted(DOC_TYPES)}")
+    for key in ("path", "media_type"):
+        if not nonempty_string(artifact.get(key)):
+            errors.append(f"artifact.{key} must be a non-empty string")
+    size_bytes = artifact.get("size_bytes")
+    if (
+        isinstance(size_bytes, bool)
+        or not isinstance(size_bytes, int)
+        or size_bytes < 1
+    ):
+        errors.append("artifact.size_bytes must be a positive integer")
+    sha256 = artifact.get("sha256")
+    if (
+        not isinstance(sha256, str)
+        or len(sha256) != 64
+        or any(char not in "0123456789abcdef" for char in sha256)
+    ):
+        errors.append("artifact.sha256 must be 64 lowercase hexadecimal characters")
+    if not isinstance(artifact.get("extension_magic_match"), bool):
+        errors.append("artifact.extension_magic_match must be boolean")
+    if file_type == "pdf" and media_type != "application/pdf":
+        errors.append("pdf file_type requires media_type application/pdf")
+    if file_type == "image" and (
+        not isinstance(media_type, str) or not media_type.startswith("image/")
+    ):
+        errors.append("image file_type requires an image/* media_type")
+    for key in ("detail", "claimed_issuer", "supplied_claim"):
+        if (
+            key in artifact
+            and artifact[key] is not None
+            and not isinstance(artifact[key], str)
+        ):
+            errors.append(f"artifact.{key} must be a string or null")
+
+    auth = verdict.get("authenticity", {})
+    validity = verdict.get("validity", {})
+    if not isinstance(auth, dict):
+        errors.append("authenticity must be an object")
+        auth = {}
+    if not isinstance(validity, dict):
+        errors.append("validity must be an object")
+        validity = {}
+    if auth.get("verdict") not in AUTH_VERDICTS:
+        errors.append(f"invalid authenticity verdict: {auth.get('verdict')!r}")
+    if validity.get("verdict") not in VALIDITY_VERDICTS:
+        errors.append(f"invalid validity verdict: {validity.get('verdict')!r}")
+    axis_keys = {"verdict", "confidence", "summary"}
+    for label, axis in (("authenticity", auth), ("validity", validity)):
+        missing_axis = axis_keys - set(axis)
+        extra_axis = set(axis) - axis_keys
+        if missing_axis:
+            errors.append(f"{label} missing keys: {sorted(missing_axis)}")
+        if extra_axis:
+            errors.append(f"{label} has unknown keys: {sorted(extra_axis)}")
+        if axis.get("confidence") not in CONFIDENCES:
+            errors.append(f"{label}.confidence must be HIGH, MEDIUM, or LOW")
+        if not nonempty_string(axis.get("summary")):
+            errors.append(f"{label}.summary must be non-empty")
+
+    auth_ids = (
+        PDF_AUTH_IDS
+        if file_type == "pdf"
+        else IMAGE_AUTH_IDS
+        if file_type == "image"
+        else []
+    )
+    validity_ids = VALIDITY_IDS.get(doc_type, [])
+    wanted = auth_ids + validity_ids
+    checks = verdict.get("checks", [])
+    seen: dict[str, dict] = {}
+    if not isinstance(checks, list):
+        errors.append("checks must be an array")
+        checks = []
+    check_keys = {"id", "name", "axis", "dimension", "result", "decisive", "evidence"}
+    for index, check in enumerate(checks):
+        if not isinstance(check, dict):
+            errors.append(f"checks[{index}] must be an object")
+            continue
+        missing_check = check_keys - set(check)
+        extra_check = set(check) - check_keys
+        if missing_check:
+            errors.append(f"checks[{index}] missing keys: {sorted(missing_check)}")
+        if extra_check:
+            errors.append(f"checks[{index}] has unknown keys: {sorted(extra_check)}")
+        cid = check.get("id")
+        if cid not in EXPECTED:
+            errors.append(f"checks[{index}]: unknown id {cid!r}")
+            continue
+        if cid in seen:
+            errors.append(f"checks[{index}]: duplicate id {cid}")
+        seen[cid] = check
+        want_axis, want_dimension = EXPECTED[cid]
+        if check.get("axis") != want_axis:
+            errors.append(f"{cid}: axis must be {want_axis}")
+        if check.get("dimension") != want_dimension:
+            errors.append(f"{cid}: dimension must be {want_dimension}")
+        if check.get("result") not in RESULTS:
+            errors.append(f"{cid}: invalid result {check.get('result')!r}")
+        if not isinstance(check.get("decisive"), bool):
+            errors.append(f"{cid}: decisive must be boolean")
+        elif check["decisive"] and check.get("result") != "FAIL":
+            errors.append(f"{cid}: only a FAIL can be decisive")
+        if not nonempty_string(check.get("name")):
+            errors.append(f"{cid}: name must be non-empty")
+        if not nonempty_string(check.get("evidence")):
+            errors.append(f"{cid}: evidence must be non-empty")
+    absent = [cid for cid in wanted if cid not in seen]
+    unexpected = [cid for cid in seen if cid not in wanted]
+    if absent:
+        errors.append(f"missing checks: {absent}")
+    if unexpected:
+        errors.append(f"checks do not belong to the selected route: {unexpected}")
+
+    if not nonempty_string(verdict.get("summary")):
+        errors.append("summary must be non-empty")
+    try:
+        checked_at = datetime.fromisoformat(
+            str(verdict.get("checked_at", "")).replace("Z", "+00:00")
+        )
+        if checked_at.tzinfo is None:
+            raise ValueError("timezone missing")
+    except ValueError:
+        errors.append("checked_at must be a valid ISO 8601 timestamp with timezone")
+
+    if not errors:
+        wanted_authenticity = expected_authenticity(seen, auth_ids, file_type)
+        wanted_validity = expected_validity(seen, validity_ids)
+        if auth["verdict"] != wanted_authenticity:
+            errors.append(
+                "authenticity verdict must be "
+                f"{wanted_authenticity} for these check results"
+            )
+        if validity["verdict"] != wanted_validity:
+            errors.append(
+                f"validity verdict must be {wanted_validity} for these check results"
+            )
+        if (
+            auth["verdict"] == "NO_EVIDENCE_OF_MODIFICATION"
+            and auth["confidence"] == "HIGH"
+        ):
+            provenance_id = "F8" if file_type == "pdf" else "I9"
+            if seen[provenance_id]["result"] != "PASS":
+                errors.append(
+                    f"HIGH confidence requires trusted provenance ({provenance_id} PASS)"
+                )
+
+    for error in errors:
+        print(f"ERROR: {error}")
+    if errors:
+        print(f"invalid: {len(errors)} error(s)")
+        return 1
+    print(
+        f"valid: {file_type}/{doc_type} route, {len(wanted)} checks, "
+        f"authenticity {auth['verdict']}, validity {validity['verdict']}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/compliance/report-writing/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/compliance/report-writing/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: report-writing
+description: "Convert compliance audit findings into audience-formatted reports. Four styles: VARS Review Report (Visa's official 2025 template, required verbatim for VARS engagements), Audit Report (compliance team), External Assessment (regulators/external auditors), Management Report (board/C-suite). Use whenever audit output needs to become a deliverable, even just 'write up the findings'."
+---
+
+# Report Writing
+
+Generate compliance reports from structured audit findings. Four report styles target
+different audiences — same data, different depth and tone.
+
+## Input Format
+
+Structured findings in Markdown with per-item:
+- **Status:** Pass / Fail / Partial / N/A
+- **Severity:** Critical / Major / Minor / Observation
+- **Category:** e.g., Access Control, Data Protection, Incident Response
+- **Observations:** What was found
+- **Evidence:** Logs, configs, screenshots, code references
+- **Recommendations:** Suggested remediation
+
+If the input deviates, normalize it to the above structure before generating the report.
+
+### VARS-specific input requirement
+
+The VARS Review Report must be generated from the **full** per-control assessment —
+typically the `tracker.md` produced by the `compliance-audit` skill running against the
+VARS checklist (`skills/compliance/compliance-audit/references/vars-checklist.md`, or a
+parsed equivalent from `reg-parser`). Do **not** start a VARS report from a summary,
+verbal findings, or a partial sub-domain review — Visa's report aggregates a complete
+control-by-control assessment, and Section 5 of the deliverable explicitly references
+the *VARS Control Testing and Remediation Tracking* spreadsheet (which is the same
+tracker, in Visa's Excel format).
+
+If the user asks for a VARS report and you don't see a complete tracker covering all
+nine sub-domains, **stop and ask** for it — or offer to run `compliance-audit` first.
+A VARS report without the underlying control-level evidence is not a deliverable Visa
+will accept.
+
+## Report Style Selection
+
+| Style | Audience | When to use |
+|---|---|---|
+| **VARS Review Report** | Visa, acquirer leadership | Visa Acceptance Risk Standards engagements — uses Visa's official 2025 template |
+| **Audit Report** | Compliance team, internal auditors | Day-to-day remediation tracking, technical deep-dives |
+| **External Assessment** | Regulators, external auditors, certification bodies | Formal submissions, certification audits, regulatory filings |
+| **Management Report** | C-suite, board, leadership | Quarterly reviews, risk committee briefings, budget justification |
+
+Select the style based on the stated audience or purpose. If unclear, ask. Default to
+Audit Report when the requestor is technical. **If the framework is VARS / Visa
+Acceptance Risk Standards, always use the VARS Review Report style** — Visa requires
+its template verbatim.
+
+## Workflow
+
+### 1. Ingest Findings
+
+1. Read the audit findings file (Markdown). For VARS, this is the `compliance-audit`
+   tracker produced against the VARS checklist — it must cover all nine sub-domains.
+2. Parse each finding into: ID, title, category, status, severity, observations, evidence, recommendations.
+3. Validate completeness — flag any finding missing severity or status. For VARS,
+   additionally verify every sub-domain is represented; if any are missing, stop and
+   surface the gap to the user before drafting.
+
+### 2. Select Style
+
+Confirm the target style with the user or infer from context:
+- "VARS" / "Visa Acceptance Risk Standards" / "for Visa" → **VARS Review Report**
+- "for the regulator" → External Assessment
+- "for the board" / "executive summary" → Management Report
+- "full technical report" / default → Audit Report
+
+### 3. Generate Report
+
+Follow the style-specific template. Reference files provide the full structure:
+
+- **VARS Review Report:** Read `references/vars-report-template.md` (Visa's official 2025 template)
+- **Audit Report:** Read `references/audit-report-template.md`
+- **External Assessment:** Read `references/external-assessment-template.md`
+- **Management Report:** Read `references/management-report-template.md`
+
+### 4. Review and Finalize
+
+1. Verify coverage:
+   - Audit Report: every finding from the input has its own section.
+   - External Assessment: every finding is mapped to a regulatory requirement.
+   - Management Report / VARS: findings are aggregated by category/sub-domain with no category dropped.
+2. Confirm severity counts match the input data. For VARS: Section 3.d is **executive**
+   (a headline plus a 2–3 sentence business posture per sub-domain, no operational
+   detail); Section 4 is **department-manager** detail, with "Compliance Status" carrying
+   the tracker's Control Effectiveness Rating (Satisfactory / Improvement Recommended /
+   Unsatisfactory / N/A; worst rating across the row) and "Findings and Comments" written
+   as an inline observed → finding → comments narrative in the report's own words (no
+   source-document/clause/sample citations — those stay in the tracker) with the Actions
+   Required / Recommendations reproduced verbatim. When the ATPA archetype is in scope,
+   confirm all TPA controls are consolidated into a single "Third Party Agent" row rather
+   than scattered across the AACQ sub-domains.
+3. Check that no placeholder text remains (e.g. `{{...}}`, `____`, `MM/YEAR`).
+4. Output as Markdown. If DOCX is requested (the VARS deliverable is typically distributed as
+   DOCX to match Visa's template), **do not rely on a plain `pandoc` Markdown→DOCX conversion
+   for the Section 4 table** — pandoc collapses the `<br>` line breaks inside the wide
+   Findings-and-Comments cells, so the enumerated Actions Required / Recommendations items run
+   together and appear to be missing. Instead render the DOCX so each cell's `<br>`-separated
+   lines become **separate paragraphs** (e.g. build it with `python-docx`, or post-process the
+   pandoc output). In Section 4 specifically:
+   - split every `<br>` into its own paragraph in the cell, so each Actions Required /
+     Recommendations item is on its own visible line;
+   - render `**…**` labels (`Actions Required:`, `Recommendations:`) as real **bold**, not
+     literal asterisks;
+   - shade the **Compliance Status** cell by rating (Satisfactory = green, Improvement
+     Recommended = amber, Unsatisfactory = red, N/A = grey);
+   - set the page to **landscape** to give the table room.
+   For PDF, the same line-break requirement applies.
+
+---
+
+## Style Summaries
+
+### VARS Review Report
+
+Visa's official 2025 template, used verbatim. Six fixed sections with mandated
+boilerplate (Purpose paragraph, reliance statement, recommendation summary stem) and
+nine fixed sub-domains in canonical order — plus a consolidated **Third Party Agent**
+row when the ATPA archetype is in scope. Detailed per-control findings live in the
+companion *VARS Control Testing and Remediation Tracking* Excel — the report itself
+aggregates one row per sub-domain. The two summary layers serve different audiences:
+**Section 3.d is executive** (business posture, 2–3 sentences per sub-domain) and
+**Section 4 is for department managers / control owners** (an inline observed → finding
+→ comments narrative in the report's own words, with verbatim Actions Required /
+Recommendations and no duplication of the tracker's evidence citations).
+
+**Key sections:** Cover, Document History, Distribution List, Executive Summary
+(Purpose / Background / VARS Control Assessment / Summary of Findings / Recommendation
+Summary), Observations Overview (sub-domain table), Detailed Information (pointer to
+Excel tracker), Next Steps.
+
+**Tone:** Formal, third-person, Visa-facing. Preserve the boilerplate paragraphs
+verbatim — paraphrasing breaks reviewer expectations.
+
+### Audit Report
+
+Full technical detail. Every finding gets its own section with evidence, root cause analysis,
+remediation steps, priority, and suggested timeline. Appendices contain raw evidence.
+
+**Key sections:**
+1. Report metadata (scope, period, assessor, framework)
+2. Executive summary (pass/fail counts)
+3. Findings (one per item — full detail)
+4. Remediation plan (prioritized)
+5. Appendices (evidence, methodology, glossary)
+
+**Tone:** Technical, precise, neutral. Use passive voice sparingly. Reference specific
+controls, configurations, and code paths.
+
+### External Assessment
+
+Formal language suitable for regulatory submission. Organized by regulatory requirement,
+not by internal finding ID. Includes gap analysis matrix and attestation-ready statements.
+
+**Key sections:**
+1. Cover page and scope statement
+2. Assessment methodology
+3. Compliance status by requirement (article/section mapping)
+4. Gap analysis matrix (requirement × status × severity)
+5. Remediation roadmap
+6. Attestation statement
+7. Appendices (evidence index, assessor qualifications)
+
+**Tone:** Formal, objective, structured. Reference regulation articles explicitly
+(e.g., "Article 32(1)(a) of Regulation (EU) 2016/679"). Avoid colloquial language.
+
+### Management Report
+
+Concise, business-oriented. Leads with a one-page executive summary. Uses visual
+indicators (counts, heatmap descriptions) rather than technical evidence.
+
+**Key sections:**
+1. Executive summary (1 page max — overall posture, key risks, headline numbers)
+2. Risk heatmap (critical/major/minor counts by category)
+3. Business impact analysis (what gaps mean operationally and financially)
+4. Recommended actions with effort estimates (cost, time, owner)
+5. Progress since last assessment (if prior data available)
+6. Appendix (methodology note, detailed data reference)
+
+**Tone:** Business language, action-oriented. Quantify impact where possible.
+Avoid jargon — explain technical concepts in business terms.
+
+---
+
+## Output Conventions
+
+- **File naming:** `{style}-{framework}-{YYYY-MM-DD}.md`
+  - Example: `audit-report-SOC2-2026-03-30.md`
+  - VARS example: `vars-review-report-{acquirer}-2026-03-30.md`
+- **Severity color coding** (for Markdown rendering):
+  - 🔴 Critical | 🟠 Major | 🟡 Minor | 🔵 Observation
+- **Finding IDs:** Preserve original IDs from the input. If absent, assign sequential IDs: `F-001`, `F-002`, etc.
+- **Cross-references:** Link findings to remediation items and evidence appendices by ID.
+
+## Edge Cases
+
+- **No critical findings:** Lead the executive summary with overall compliance posture, not absence of criticals.
+- **Mixed frameworks:** If findings span multiple frameworks (e.g., SOC 2 + PCI DSS), organize by framework first, then by requirement.
+- **Incomplete evidence:** Flag as "Evidence Pending" — do not omit the finding.
+- **Prior assessment data unavailable:** Omit the "Progress" section in Management Report; note "Baseline assessment — no prior data" in methodology.
+- **VARS sub-domain with no findings:** Still include the row in Section 4 and the bullet in Section 3.d — Compliance Status "Satisfactory", Findings and Comments an inline observed-then-finding narrative closing with "No remediation required." (matching the tracker's Satisfactory Issue Description) — Visa expects all nine sub-domains to appear (plus the Third Party Agent row when ATPA is in scope).
+- **VARS legacy numbering:** The official 2025 template skips index 9 in the Section 4 table (Regulatory Risk is labelled #10). The `references/vars-report-template.md` uses sequential 1–9; switch to legacy numbering only if the Visa engagement lead asks.

package/skills/compliance/report-writing/references/audit-report-template.md

@@ -0,0 +1,121 @@
+# Audit Report Template
+
+Use this structure for the full technical audit report (audience: compliance team).
+
+---
+
+## Report Metadata
+
+| Field | Value |
+|---|---|
+| Report Title | {Framework} Compliance Audit Report |
+| Assessment Period | {Start Date} – {End Date} |
+| Report Date | {YYYY-MM-DD} |
+| Assessor(s) | {Name(s), Role(s)} |
+| Framework / Standard | {e.g., SOC 2 Type II, ISO 27001, PCI DSS v4.0} |
+| Scope | {Systems, processes, and data in scope} |
+| Classification | {Confidential / Internal / Restricted} |
+
+---
+
+## 1. Executive Summary
+
+Brief overview (1–2 paragraphs) of the audit scope, approach, and headline results.
+
+### Finding Summary
+
+| Severity | Count | % of Total |
+|---|---|---|
+| 🔴 Critical | {n} | {%} |
+| 🟠 Major | {n} | {%} |
+| 🟡 Minor | {n} | {%} |
+| 🔵 Observation | {n} | {%} |
+| **Total** | **{n}** | **100%** |
+
+### Overall Compliance Posture
+
+{One sentence: e.g., "The organization demonstrates a mature control environment with
+two critical gaps requiring immediate remediation."}
+
+---
+
+## 2. Findings
+
+Repeat this block for each finding, ordered by severity (Critical → Observation).
+
+### F-{NNN}: {Finding Title}
+
+| Field | Detail |
+|---|---|
+| **ID** | F-{NNN} |
+| **Category** | {e.g., Access Control} |
+| **Control Reference** | {e.g., CC6.1, A.9.2.3} |
+| **Status** | {Pass / Fail / Partial} |
+| **Severity** | {Critical / Major / Minor / Observation} |
+
+**Observation:**
+{Detailed description of what was found. Reference specific systems, configurations,
+or processes. Be precise — include paths, parameter names, versions where relevant.}
+
+**Evidence:**
+{Reference evidence items: E-001, E-002. Describe what each evidence item shows.
+Full evidence in Appendix A.}
+
+**Root Cause:**
+{Why the gap exists. Distinguish between process failure, technical misconfiguration,
+resource constraint, or design gap.}
+
+**Risk:**
+{Impact if unaddressed. Quantify where possible: number of records exposed,
+blast radius, regulatory penalty exposure.}
+
+**Recommendation:**
+{Specific remediation steps.}
+
+| Priority | Timeline | Estimated Effort | Owner |
+|---|---|---|---|
+| {P1/P2/P3} | {e.g., 30 days} | {e.g., 2 engineer-weeks} | {Role/Team} |
+
+---
+
+## 3. Remediation Plan
+
+Consolidated view of all findings requiring action, sorted by priority.
+
+| ID | Title | Severity | Priority | Timeline | Owner | Status |
+|---|---|---|---|---|---|---|
+| F-001 | {Title} | 🔴 Critical | P1 | 14 days | {Owner} | Open |
+| F-002 | {Title} | 🟠 Major | P2 | 30 days | {Owner} | Open |
+| ... | | | | | | |
+
+---
+
+## Appendix A: Evidence Index
+
+| Evidence ID | Description | Type | Source | Date Collected |
+|---|---|---|---|---|
+| E-001 | {Description} | {Screenshot / Log / Config / Interview} | {System/Person} | {Date} |
+| E-002 | {Description} | {Type} | {Source} | {Date} |
+
+{Include raw evidence below or attach as separate files.}
+
+### E-001: {Description}
+
+```
+{Raw evidence: log excerpt, configuration snippet, or screenshot reference}
+```
+
+---
+
+## Appendix B: Assessment Methodology
+
+{Describe the audit approach: document review, technical testing, interviews,
+sampling methodology, tools used.}
+
+---
+
+## Appendix C: Glossary
+
+| Term | Definition |
+|---|---|
+| {Term} | {Definition} |