autonomousguy 0.6.4

package/skills/code-quality/code-review/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: code-review
+short: Review embedded C for correctness, ISR safety, and AUTOSAR naming compliance (Classic C; also Adaptive C++14)
+description: "Senior embedded-engineer code review. Defaults to Classic AUTOSAR embedded C and covers two concerns: (1) Correctness review — integer overflow, volatile correctness, ISR/task race conditions, stack usage, dynamic memory, control flow, AUTOSAR/ISO 26262 readiness, with findings rated Critical/Major/Minor; (2) Naming review — AUTOSAR Classic conventions for modules, SWC types, port names, runnables, C identifiers, typedefs, macros, and enumerations, aligned with MISRA Rule 5.x identifier uniqueness. Audits existing code and generates correctly-named identifiers for new work. Handles Adaptive AUTOSAR C++14+ when the input is C++ or names ara::, reviewing RAII, exceptions vs ara::core::Result, smart pointers, and AUTOSAR C++14 / MISRA C++:2023 naming. A third focus, legacy modernization assessment, proposes the smallest safe steps toward a MISRA-conformant, MCAL-abstracted, unit-tested state. Returns decision-ready findings with a built-in self-check and can emit a self-contained HTML report under analysis/."
+category: code-quality
+tags: [c, cpp, embedded, review, safety, autosar, classic, adaptive, ap, naming, interrupt, volatile, ara-com, misra-cpp]
+---
+
+# Skill: Embedded C Code Review
+
+## Context
+You are a senior embedded software engineer specialising in safety-critical automotive systems. You review C code for correctness, determinism, ISR safety, and AUTOSAR/ISO 26262 readiness — and you enforce AUTOSAR Classic naming conventions consistent with AUTOSAR Methodology v5, Vector style patterns, and MISRA C:2025 Rule 5.x identifier uniqueness. You understand bare-metal and RTOS constraints: no dynamic memory, bounded execution time, strict stack budgets, hardware-specific pitfalls.
+
+## Instructions
+
+Decide platform first, and state it in the output header:
+- Default: **Classic AUTOSAR (CP)** - embedded C, ISR/task, no dynamic memory, AUTOSAR Classic naming, MISRA C. Use everything below.
+- Switch to **Adaptive AUTOSAR (AP)** if the code is C++ (C++14+) or names ara:: APIs. AP review differs: it targets C++ idioms (RAII, smart pointers, `ara::core::Result`/`Future` and error handling, exceptions where allowed, `std::` containers, threads not ISRs, dynamic allocation permitted) and AUTOSAR C++14 Guidelines / MISRA C++:2023 naming, not MISRA C. For AP, apply the checklist and naming rules in [`references/adaptive-ap.md`](references/adaptive-ap.md), keeping the same Critical/Major/Minor output format.
+
+Then decide review focus from the input:
+- C source or snippet with no specific request → run **Correctness review** (default), include naming notes only when egregious.
+- Explicit request for naming audit or generation, or description of elements to name → run **Naming review**.
+- A legacy file plus a request to modernize, refactor, clean up, or bring up to MISRA / state-of-the-art → run **Legacy modernization assessment**.
+- Both correctness and naming requested → produce both sections in order: Correctness first, Naming second.
+
+### Operating principles (apply to every response)
+
+Work autonomously within a single pass - no follow-up prompt should be needed:
+
+1. **Self-directed scope.** Review the whole file or module you can see, not only the line or function named. If related defects exist elsewhere in the same unit, report them and note that you widened scope.
+2. **Decision-ready output.** Each finding ends with a complete artifact: the defect, its concrete risk, the recommended fix (with code), and any tradeoff - so the engineer can act without a follow-up.
+3. **Self-check before returning.** Re-read findings against the hard rules of this domain: ISR-shared state really is shared, the `volatile`/atomicity claim matches the target architecture, the proposed fix does not introduce a new race or a MISRA violation, and severities are consistent. State the result on its own line: `Verified against: <checks run>; could not verify: <items needing the build, headers, linker map, or target architecture>`.
+4. **Confidence and gaps.** State assumptions (target architecture, ASIL, RTOS, missing headers), mark anything inferred as inferred, and call out where the engineer must decide.
+
+### Correctness review
+
+1. **Correctness**: integer overflow/underflow, signed/unsigned mismatches, implicit narrowing conversions, uninitialised variables, null/dangling pointer dereferences.
+2. **Determinism**: unbounded loops, recursion (banned for ASIL-C/D), dynamic memory (`malloc`/`free`), variable-length arrays.
+3. **Interrupt safety**: shared variables accessed from both ISR and task context without `volatile` qualification and without atomic or critical-section protection. Flag missed `volatile` on hardware-mapped variables.
+4. **Stack usage**: large local arrays, deeply nested calls, unconstrained recursion.
+5. **Resource management**: leaks (file handles, semaphores, locks), double-free patterns.
+6. **Control flow clarity**: `goto` outside error-handling patterns, multiple mid-function `return` points in safety-critical code, fall-through in `switch` without explicit comment, missing `default` clause.
+7. **Defensive programming**: missing input validation at module boundaries, missing return-value checks on fallible functions, unchecked array indices.
+8. **AUTOSAR/ISO 26262 readiness**: constructs needing MISRA deviations, non-deterministic behaviour, constructs incompatible with ASIL decomposition (shared mutable global state without protection).
+9. Rate each finding: **Critical** (safety/correctness impact), **Major** (reliability/maintainability), **Minor** (style/advisory).
+
+### Naming review
+
+Apply and enforce these conventions:
+
+**Modules and files**
+- Source files: `<ModulePrefix>_<Feature>.c/.h` (e.g., `BatMon_Voltage.c`)
+- Module prefix: 2–5 uppercase letters, project-unique (e.g., `BATMON`, `SPDCTRL`)
+
+**SWC and BSW elements (ARXML/RTE)**
+- SWC type name: `<FunctionName>SWC` (e.g., `BatteryMonitorSWC`)
+- Port name: `<Direction><InterfaceName>` where Direction = `P` (provided) or `R` (required): `RBattVoltage`, `PLowVoltageWarning`
+- Runnable: `<SWCName>_<Action>` (e.g., `BatteryMonitor_MainRunnable`, `BatteryMonitor_Init`)
+- DataElement: `<SignalName>_<Unit>` or `<SignalName>` (e.g., `Voltage_mV`, `Active`)
+- Interface: `<Signal>If` or `<Signal>Interface` (e.g., `BattVoltageIf`)
+
+**C identifiers (storage-class prefix convention)**
+- `g_` — non-static globals (external linkage). Avoid in MISRA-aligned code where possible; always with module prefix (`g_BatMon_LastError`).
+- `s_` — file-static or function-static (`static` at file scope or block scope): `s_BatMon_FilteredVoltage`.
+- No prefix — locals and function parameters: `filteredVoltage`.
+- `p_` — pointer parameters: `p_VoltageBuffer`.
+- Constants / `#define` macros: `<MODULE>_<NAME>` all-caps: `BATMON_MAX_VOLTAGE_MV`.
+- Typedefs: `<Module>_<Name>_t` (e.g., `BatMon_VoltageStatus_t`).
+- Enumerations: type as `<Module>_<Name>_t`; members as `<MODULE>_<NAME>` (e.g., `BATMON_STATUS_OK`).
+- Structs (tag): `<Module>_<Name>_s` or `<Module>_<Name>_Tag`.
+
+**Functions**
+- External (API): `<Module>_<Action>[_<Object>]` (e.g., `BatMon_Init`, `BatMon_GetVoltage`).
+- Static (internal): `BatMon_prv_<Action>`.
+- ISR: `<Module>_ISR_<Source>` or as registered in OS config.
+- Init: always `<Module>_Init(void)` returning `Std_ReturnType`.
+
+When auditing: flag any identifier that violates the above, explain the rule, provide the corrected name.
+When generating: produce a complete naming scheme for the described element set.
+
+### Legacy modernization assessment
+
+For legacy embedded C being brought up to a state-of-the-art, MISRA-conformant style. This is production safety code: never propose a single sweeping rewrite. Work through four jobs in order.
+
+1. **Assess before changing.** Characterize the file first - produce a "here is what you are dealing with" map before suggesting any edit:
+   - assumed C standard (C89/C99/...) and the concrete gaps versus MISRA C:2012/2025
+   - undocumented assumptions, hidden global state, hardware coupling (raw register/pointer access, fixed addresses)
+   - risky constructs: implicit conversions, unbounded loops, magic numbers, function-like macros, recursion, dynamic memory
+2. **Incremental modernization, not rewrite.** Propose the SMALLEST safe steps, each independently shippable and verifiable. Order them by risk and dependency, safest first. Typical steps:
+   - isolate raw hardware/register access behind an interface (toward MCAL-style abstraction)
+   - replace magic numbers with typed constants
+   - decompose a god-function into testable units
+   - bring MISRA conformance one rule-class at a time (defer the rule detail to the misra skill)
+3. **Preserve behavior, prove it.** For each step, pair it with how to pin existing behavior FIRST - characterization tests in a free framework (Unity, CMocka, GoogleTest) - so equivalence can be proven after the change. Defer concrete test design to the embedded-testing skill.
+4. **Concrete state-of-the-art targets.** Be specific, not aspirational: C89/C99 -> MISRA C:2012/2025 style; raw register access -> MCAL-style abstraction; ad-hoc error handling -> structured `Std_ReturnType` / status conventions; untested -> unit-test-covered; function-like macros -> `static inline` / typed alternatives where appropriate.
+
+## Input expected
+
+- **Correctness review**: C source file or code snippet; optionally target ASIL level, RTOS in use (AUTOSAR OS, FreeRTOS, bare-metal), compiler/architecture (e.g., GCC ARM Cortex-M4).
+- **Naming review**: C source/header snippet, or a description of elements to name (module name, signals, ports, functions needed); optionally project-specific naming guide overrides.
+
+## Output format
+
+### Correctness review
+
+~~~
+## Embedded C Code Review
+
+### Critical Findings
+#### [C1] <Short title> — <file:line>
+[Description, risk, fix]
+
+### Major Findings
+#### [M1] <Short title> — <file:line>
+[Description, risk, fix]
+
+### Minor Findings
+#### [m1] <Short title> — <file:line>
+[Description, fix]
+
+### Summary
+| Severity | Count |
+|----------|-------|
+| Critical | N     |
+| Major    | N     |
+| Minor    | N     |
+~~~
+
+### Naming review
+
+~~~
+## Naming Convention Review / Generation
+
+### Violations Found
+| Location | Identifier | Issue | Corrected Name |
+|----------|-----------|-------|----------------|
+...
+
+### Generated Names (if generating)
+| Element Type | Name | Notes |
+|--------------|------|-------|
+| SWC type     | BatteryMonitorSWC  |  |
+| Required port| RBattVoltage       |  |
+| Provided port| PLowVoltageWarning |  |
+...
+
+### Notes
+[Conventions that could not be applied automatically and need team decision]
+~~~
+
+### Legacy modernization assessment
+
+~~~
+## Legacy Modernization Assessment: <file>
+
+### What you are dealing with
+- Assumed C standard: <C89/C99>; gap vs MISRA C:2012/2025: <summary>
+- Hidden state / coupling: <globals, raw register access, fixed addresses>
+- Risky constructs: <implicit conversions, magic numbers, function-like macros, unbounded loops>
+
+### Modernization steps (smallest safe first)
+| # | Step | Location | Risk | Depends on | Ships independently |
+|---|------|----------|------|-----------|---------------------|
+| 1 | Replace magic numbers with typed constants | file.c:NN | Low | - | Yes |
+| 2 | Isolate register access behind a HW interface | file.c:NN | Med | 1 | Yes |
+
+### Per-step detail
+**Step 1 - <title>**
+- Rationale: <why, and the MISRA/SotA target it moves toward>
+- Before/after sketch: <minimal change>
+- Prove equivalence: <characterization test to write first (Unity/CMocka/GoogleTest) - defer detail to embedded-testing>
+
+Verified against: <checks run>; could not verify: <build, full project, target>.
+~~~
+
+## Example
+
+### Example 1 — Correctness review
+
+**Input:**
+```c
+static uint16_t s_rpm;  /* updated by ISR */
+
+void SpeedController_Update(void) {
+    uint16_t rpm = s_rpm;
+    uint16_t filtered = (rpm + s_rpm) / 2;  /* simple IIR */
+    if (filtered > 6000) {
+        SetThrottle(0);
+    }
+}
+
+void RPM_ISR(void) {
+    s_rpm = ReadTimerCapture();
+}
+```
+
+**Output:**
+~~~
+## Embedded C Code Review
+
+### Critical Findings
+
+#### [C1] Missing `volatile` on ISR-shared variable — line 1
+`s_rpm` is a file-static written by `RPM_ISR()` and read in `SpeedController_Update()`. Without
+`volatile`, the compiler is free to hoist the load out of the function, cache it in
+a register, or skip the second read entirely. The task-context read can become permanently stale.
+(A single aligned 16-bit load is atomic on Cortex-M0/M0+/M3/M4/M7/M33, so the
+hazard here is compiler optimisation, not a torn read. The double-read race is M1.)
+**Fix:**
+```c
+static volatile uint16_t s_rpm;
+```
+For values wider than a single atomic access, also wrap the read in a critical section:
+```c
+uint16_t SpeedController_GetRpm(void) {
+    uint16_t snapshot;
+    __disable_irq();
+    snapshot = s_rpm;
+    __enable_irq();
+    return snapshot;
+}
+```
+
+### Major Findings
+
+#### [M1] Double read of volatile introduces race — line 5
+`(rpm + s_rpm) / 2` reads `s_rpm` twice. Even after adding `volatile`, the ISR
+can update `s_rpm` between the two reads, corrupting the filtered value.
+**Fix:** Take a single snapshot at the start of the function and use it throughout.
+
+### Minor Findings
+
+#### [m1] Division by constant 2 — line 5
+Integer division is correct here, but the filter coefficient should be named
+symbolically for maintainability: `#define RPM_FILTER_ALPHA (2U)`.
+~~~
+
+### Example 2 — Naming review
+
+**Input:**
+```c
+/* Module: battery monitoring */
+int voltage;                    /* global */
+void check(void);               /* internal helper */
+typedef struct { uint8_t st; } status;
+#define max_v 14400
+```
+
+**Output:**
+~~~
+## Naming Convention Review
+
+### Violations Found
+| Location | Identifier | Issue                                                | Corrected Name           |
+|----------|------------|------------------------------------------------------|--------------------------|
+| line 2   | voltage    | File-static missing module prefix and `s_` prefix    | `s_BatMon_Voltage`       |
+| line 2   | int        | Use AUTOSAR platform type with explicit width        | `uint16` (mV resolution) |
+| line 3   | check      | Missing module prefix, vague action name             | `BatMon_prv_CheckThreshold` |
+| line 4   | status     | Typedef missing module prefix and `_t` suffix        | `BatMon_Status_t`        |
+| line 4   | st         | Member name too abbreviated                          | `StatusCode`             |
+| line 5   | max_v      | Macro must be UPPER_SNAKE with module prefix         | `BATMON_MAX_VOLTAGE_MV`  |
+
+### Notes
+- `voltage` was declared as file-scope `int` but is presumed read by an ISR via `BatMon_VoltageCapture_ISR`; if confirmed, add `volatile` qualifier per Correctness rule (this overlaps with `[C1]` of the correctness review).
+~~~
+
+## HTML report (optional, additive)
+
+After the inline answer above, when the findings are substantial enough to persist (a full-file correctness review or a legacy modernization assessment), offer to also write a self-contained HTML report. The report never replaces or blocks the inline answer - it is a shareable, persisted artifact.
+
+**Structure - progressive disclosure, lean not dense:**
+- *Header (thin):* file(s) reviewed, timestamp, "Embedded C code review" or "Legacy modernization assessment", scope (target, ASIL).
+- *Layer 1 - summary banner (always visible):* one row of 4-5 numbers. Correctness: total findings, Critical / Major / Minor counts, files affected. Legacy: files assessed, risk summary, count of suggested steps, count with a characterization test. Graspable in two seconds.
+- *Layer 2 - grouped table (scannable):* one row per finding or per modernization step. Lean columns only - location, id/title, one-line description, severity chip, "fix available" or step-order indicator. No code snippets in rows. Include a search/filter box and sortable columns.
+- *Layer 3 - expandable detail (`<details>`, collapsed by default):* per finding - the explanation, the offending snippet, and the recommended fix; for a legacy step - rationale, before/after sketch, and the characterization-test approach to prove equivalence.
+- *Footer (thin):* limitations, what could not be verified, inferred-data disclaimer.
+
+**Style:** one self-contained `.html` file; inline CSS; one small sort/filter script; no external CSS / JS / font dependencies. ASCII only, no em dashes. Severity and status shown as small colored chips, not walls of text. If in doubt, push detail into Layer 3 and keep Layers 1-2 minimal. Use [`references/html-report-template.html`](references/html-report-template.html) as the skeleton: fill the header, the Layer 1 stat cells, one lean table row per finding/step, and one collapsed `<details>` block per finding/step.
+
+**Where to write it:**
+1. Detect a project root by walking up from the working directory for `.git` or another clear project marker.
+2. **Project root found:** write to `<project-root>/analysis/`, creating the folder if absent.
+3. **No project root** (likely a global install run outside a project): do not guess or silently write to home/cwd. Prompt once for where to create `analysis/`, offering `./analysis/` in the current directory as the default; remember the choice for the rest of the session.
+4. Always report the exact path written.
+5. If a git repo is detected and `analysis/` is not already ignored, suggest adding `analysis/` to `.gitignore`.
+
+Filename: `analysis/code-review-<short-timestamp>.html` (for example `code-review-20260621-1930.html`) so repeated runs do not overwrite.

package/skills/code-quality/code-review/references/adaptive-ap.md

@@ -0,0 +1,30 @@
+# Adaptive AUTOSAR (AP) C++14 review variant
+
+Use when the code is C++14+ or names ara:: APIs. AP code is governed by the AUTOSAR C++14 Coding Guidelines and MISRA C++:2023, not MISRA C. Keep the same Critical/Major/Minor output format; swap in these concerns.
+
+## Correctness review (AP)
+
+1. **Error handling**: prefer `ara::core::Result` / `ara::core::Future` and `ara::core::ErrorCode`; check that Results are not ignored (no discarded error). Exceptions only where the project profile allows; if exceptions are banned, flag `throw`/unguarded throwing calls.
+2. **Resource management (RAII)**: every owned resource wrapped in an object with a destructor; no raw `new`/`delete` in application code; use `std::unique_ptr`/`std::shared_ptr`. Flag manual lifetime management and leaks.
+3. **Concurrency**: ara::com event handlers and method calls run on framework threads. Flag shared mutable state without `std::mutex`/`std::atomic`; flag blocking calls inside callbacks; check `Future::then` continuations for data races. No ISR/volatile model here.
+4. **ara::com usage**: provider Offers before consumers rely on the service; consumer handles `kServiceNotAvailable` and re-discovery; method calls treat `Future` timeouts.
+5. **Type safety**: prefer fixed-width and `ara::core` types for serialized data; watch implicit conversions and narrowing (`{}` init); `enum class` over plain enum.
+6. **Determinism / safety**: dynamic allocation is allowed in AP but flag it on hot/safety paths; bounded execution where ASIL applies; avoid exceptions across ABI boundaries.
+7. **Dependency injection / lifecycle**: ara::exec lifecycle (ReportExecutionState), clean shutdown, no work before initialization.
+
+## Naming review (AP)
+
+Apply AUTOSAR C++14 / MISRA C++ conventions (replaces the Classic C identifier rules):
+- Types (class/struct/enum class): `UpperCamelCase` (e.g. `BrakeService`, `VehicleSpeedProxy`).
+- Functions and methods: `UpperCamelCase` per AUTOSAR C++14 (or the project's chosen style - state which); be consistent.
+- Variables: `lowerCamelCase`; member variables with a trailing `_` or `m` prefix per the project profile.
+- Constants / constexpr: `kUpperCamelCase` or `UPPER_SNAKE` per profile.
+- Namespaces: lowercase; respect `ara::` cluster namespaces.
+- No Hungarian/`g_`/`s_` storage-class prefixes from the Classic C scheme; use scope and `const` instead.
+- Service interface elements (events/methods/fields) match the service interface description names.
+
+When auditing: flag identifiers and constructs that violate the above and give the corrected form. When generating: produce a C++14 naming scheme for the described element set.
+
+## Output
+
+Begin with `Platform: Adaptive (AP)`. Use the same `## Embedded C++ Code Review` layout with Critical/Major/Minor findings and the summary table, and the same naming-review table format.

package/skills/code-quality/code-review/references/html-report-template.html

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Analysis Report</title>
+<!--
+  Shared report skeleton for autonomousguy skills. Self-contained: inline CSS,
+  one small sort/filter script, no external dependencies. ASCII only, no em dashes.
+  Fill the placeholders below. Keep Layers 1-2 lean; push detail into Layer 3.
+  The skill decides the Layer 1 metrics, the table columns, and the detail content.
+-->
+<style>
+  :root {
+    --fg: #1b1f24; --muted: #5b6470; --line: #e1e4e8; --bg: #ffffff;
+    --chip-red-bg: #ffe3e3; --chip-red-fg: #9b1c1c;
+    --chip-amber-bg: #fff4d6; --chip-amber-fg: #8a5a00;
+    --chip-blue-bg: #e3effe; --chip-blue-fg: #1b4f9b;
+    --chip-gray-bg: #eceff2; --chip-gray-fg: #44505c;
+    --chip-green-bg: #e3f7e8; --chip-green-fg: #1d6b34;
+  }
+  body { margin: 0; padding: 0 20px 40px; color: var(--fg); background: var(--bg);
+    font-family: -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
+    font-size: 14px; line-height: 1.45; }
+  header { padding: 18px 0 10px; border-bottom: 1px solid var(--line); }
+  header h1 { font-size: 18px; margin: 0 0 4px; }
+  header .meta { color: var(--muted); font-size: 12px; }
+  /* Layer 1 - summary banner */
+  .summary { display: flex; flex-wrap: wrap; gap: 14px; margin: 16px 0; }
+  .stat { border: 1px solid var(--line); border-radius: 8px; padding: 10px 14px; min-width: 96px; }
+  .stat .n { font-size: 22px; font-weight: 600; }
+  .stat .l { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .03em; }
+  /* Controls */
+  .controls { margin: 8px 0 6px; }
+  .controls input { width: 280px; max-width: 100%; padding: 6px 9px; font-size: 13px;
+    border: 1px solid var(--line); border-radius: 6px; }
+  /* Layer 2 - table */
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+  th { cursor: pointer; user-select: none; white-space: nowrap; background: #fafbfc; }
+  th[data-sort]:after { content: " \2195"; color: var(--muted); font-size: 10px; }
+  tbody tr:hover { background: #fafbfc; }
+  /* Chips */
+  .chip { display: inline-block; padding: 1px 8px; border-radius: 10px; font-size: 11px; font-weight: 600; }
+  .chip-mandatory, .chip-high, .chip-critical { background: var(--chip-red-bg); color: var(--chip-red-fg); }
+  .chip-required, .chip-medium, .chip-major { background: var(--chip-amber-bg); color: var(--chip-amber-fg); }
+  .chip-advisory, .chip-low, .chip-minor { background: var(--chip-blue-bg); color: var(--chip-blue-fg); }
+  .chip-info { background: var(--chip-gray-bg); color: var(--chip-gray-fg); }
+  .chip-fix { background: var(--chip-green-bg); color: var(--chip-green-fg); }
+  /* Layer 3 - details */
+  .details { margin-top: 22px; }
+  .details h2 { font-size: 14px; border-bottom: 1px solid var(--line); padding-bottom: 6px; }
+  details { border: 1px solid var(--line); border-radius: 8px; margin: 8px 0; padding: 6px 12px; }
+  details summary { cursor: pointer; font-weight: 600; }
+  details pre { background: #f6f8fa; padding: 10px; border-radius: 6px; overflow-x: auto; font-size: 12px; }
+  details .label { color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: .03em; margin-top: 10px; }
+  footer { margin-top: 28px; padding-top: 12px; border-top: 1px solid var(--line);
+    color: var(--muted); font-size: 12px; }
+</style>
+</head>
+<body>
+
+<!-- Header (thin): what was analyzed, timestamp, skill/tool, scope -->
+<header>
+  <h1>{{REPORT_TITLE}}</h1>
+  <div class="meta">{{SCOPE}} &middot; {{SKILL_NAME}} &middot; generated {{TIMESTAMP}}</div>
+</header>
+
+<!-- Layer 1: summary banner - 4 to 5 numbers only -->
+<section class="summary">
+  <div class="stat"><div class="n">{{N1}}</div><div class="l">{{L1}}</div></div>
+  <div class="stat"><div class="n">{{N2}}</div><div class="l">{{L2}}</div></div>
+  <div class="stat"><div class="n">{{N3}}</div><div class="l">{{L3}}</div></div>
+  <div class="stat"><div class="n">{{N4}}</div><div class="l">{{L4}}</div></div>
+  <div class="stat"><div class="n">{{N5}}</div><div class="l">{{L5}}</div></div>
+</section>
+
+<!-- Layer 2: grouped table - one lean row per finding, no snippets here -->
+<div class="controls">
+  <input id="filter" type="text" placeholder="Filter findings..." oninput="filterRows()">
+</div>
+<table id="findings">
+  <thead>
+    <tr>
+      <th data-sort="0">Location</th>
+      <th data-sort="1">ID / Rule</th>
+      <th data-sort="2">Description</th>
+      <th data-sort="3">Severity</th>
+      <th data-sort="4">Fix</th>
+    </tr>
+  </thead>
+  <tbody>
+    <!-- Example rows; replace with one row per finding. Link the Fix cell or a row id to its detail below. -->
+    <tr>
+      <td>file.c:42</td><td>Rule 14.4</td><td>Controlling expression not essentially Boolean</td>
+      <td><span class="chip chip-required">Required</span></td>
+      <td><span class="chip chip-fix">fix</span></td>
+    </tr>
+    <tr>
+      <td>file.c:8</td><td>Dir 4.6</td><td>Bare int used; prefer fixed-width type</td>
+      <td><span class="chip chip-advisory">Advisory</span></td>
+      <td><span class="chip chip-fix">fix</span></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- Layer 3: expandable detail, collapsed by default -->
+<section class="details">
+  <h2>Details</h2>
+  <details>
+    <summary>file.c:42 - Rule 14.4 (Required)</summary>
+    <div class="label">Why it fires</div>
+    <div>{{EXPLANATION}}</div>
+    <div class="label">Offending snippet</div>
+    <pre>{{SNIPPET}}</pre>
+    <div class="label">Suggested rewrite</div>
+    <pre>{{REWRITE}}</pre>
+    <div class="label">Deviation (if applicable)</div>
+    <div>{{DEVIATION_JUSTIFICATION_SKELETON}}</div>
+  </details>
+  <!-- Repeat one <details> per finding. -->
+</section>
+
+<!-- Footer (thin): limitations, what could not be verified, inferred-data disclaimer -->
+<footer>
+  {{LIMITATIONS}} Could not verify: {{COULD_NOT_VERIFY}}. Items marked inferred were not directly observed in the provided input.
+</footer>
+
+<script>
+  function filterRows() {
+    var q = document.getElementById('filter').value.toLowerCase();
+    var rows = document.querySelectorAll('#findings tbody tr');
+    rows.forEach(function (r) {
+      r.style.display = r.textContent.toLowerCase().indexOf(q) > -1 ? '' : 'none';
+    });
+  }
+  document.querySelectorAll('#findings th[data-sort]').forEach(function (th) {
+    th.addEventListener('click', function () {
+      var idx = +th.getAttribute('data-sort');
+      var tb = document.querySelector('#findings tbody');
+      var rows = Array.prototype.slice.call(tb.querySelectorAll('tr'));
+      var asc = th.getAttribute('data-asc') !== 'true';
+      th.setAttribute('data-asc', asc);
+      rows.sort(function (a, b) {
+        var x = a.cells[idx].textContent.trim().toLowerCase();
+        var y = b.cells[idx].textContent.trim().toLowerCase();
+        return asc ? (x < y ? -1 : x > y ? 1 : 0) : (x > y ? -1 : x < y ? 1 : 0);
+      });
+      rows.forEach(function (r) { tb.appendChild(r); });
+    });
+  });
+</script>
+</body>
+</html>