@sitar_fiercer4c/skills 0.1.0

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

@@ -0,0 +1,247 @@
+---
+name: frontend-code-review
+description: Reviews Next.js App Router frontend code against the project's layered architecture rules in code_rules_frontend.md (api / app / components / lib / types / utils), flagging every misplaced-code violation with the exact rule broken, why it matters, and a concrete fix. Use this whenever the user asks to review frontend code, check a diff or PR against architecture rules, asks "does this follow our conventions / rules", asks where a piece of code belongs, or mentions code_rules_frontend.md or frontend code review — even if they just paste a component, page, or api file and ask what's wrong with it.
+---
+
+# Frontend code review
+
+You are reviewing code against a layered architecture. The bugs you are hunting are almost never
+syntax errors — the compiler and the linter already catch those. They are **placement** errors:
+correct code sitting in the wrong layer, where it quietly erodes the boundary that makes the
+codebase navigable. A `formatBytes` defined inside a route file works fine and gets rewritten by
+the next person. An axios call outside `api/` works fine until the day the token policy changes in
+one place and not the other.
+
+So read for *location*, not correctness. The question is never "does this run?" but "is this the
+folder where the next person would look for it?"
+
+## Step 1: Establish which layer the code is in
+
+If the user gave you a path, use it. If they didn't, infer it and **say what you inferred and why**,
+because every rule below is conditional on the layer — the same `export { x } from "./y"` is a
+firing offence in `api/` and the intended design in `components/ui/`. Getting the layer wrong
+inverts the verdict.
+
+Signals: `page.tsx` / `layout.tsx` / a `route.ts` under a URL-shaped folder ⇒ `app`. A default-
+exported React component that isn't a page ⇒ `components`. Plain async functions calling
+`apiClient` ⇒ `api`. Only `interface` / `type` / shape constants ⇒ `types`. Exported pure
+functions ⇒ `utils`.
+
+If a file's *contents* argue for a different layer than its *path*, that mismatch is itself the
+finding — that is the whole point of the review.
+
+## Step 2: Check every rule for that layer, plus the cross-cutting ones
+
+The full rule catalogue is below. Two disciplines matter more than speed:
+
+**Check the rules that pass, not just the ones that fail.** The user needs to know what you looked
+at. A review that lists three problems tells them nothing about the twelve things you didn't
+examine versus the twelve you cleared.
+
+**Quote the code you are accusing.** A finding without a line reference and the offending
+expression is an assertion the reader has to re-derive. Cite `file:line` where you have it.
+
+## The rules
+
+Rules are grouped by folder, then by DOS (positive obligations) and DONTS (prohibitions). The IDs
+are for citation — use them verbatim in your output so findings are traceable back to the source
+document.
+
+### Architecture context
+
+Next.js App Router, layered like the backend's MVCS. `app` is routes + controllers, `api` is
+services, `types` is models, `utils` is utils + validators. The backend's `config` and `middleware`
+layers have no folder here: config lives in `api/axios.ts`, and middleware's job (auth gating) is
+done by `layout.tsx` guards.
+
+### api — one file per backend resource, holding every HTTP call to it
+
+Each function wraps one endpoint, returns `res.data`, and is typed with the matching interface from
+`types`. `api/axios.ts` is the shared client: it owns the base URL, attaches the JWT, and owns the
+401 policy. It is also the only module in the app that reads an environment variable
+(e.g. `NEXT_PUBLIC_API_URL`).
+
+- **API-DO1** — Name the function after what the endpoint does, and comment it with the method and
+  path it calls. Eg: `// GET /email/inbox`.
+- **API-DO2** — Keep that comment true. A wrong path in a comment is worse than no comment, because
+  the next person reasons from it instead of from the code.
+- **API-DO3** — Return `res.data`, not the raw axios response, and type the return with the
+  interface from `types`. Leaking the envelope makes every caller unwrap it again.
+- **API-D1** — Don't create or call an axios instance outside this folder. Every request goes
+  through `apiClient` so the token interceptor stays the single place auth is attached.
+  *Importing axios **types** elsewhere is fine* — `utils/apiError.ts` legitimately needs
+  `AxiosError` to narrow an error. The ban is on instances and calls, not on the type namespace.
+- **API-D2** — Don't re-export functions imported from other files, for any reason whatsoever.
+  This is absolute inside `api/`. A service that re-exports its neighbour hides which module a
+  caller actually depends on.
+- **API-D3** — Don't put React in here. No hooks, no components, no state — these are plain async
+  functions. A hook in `api/` cannot be called from a server component or from another hook's
+  branch.
+- **API-D4** — Don't read `process.env` outside `api/axios.ts`. One module owns configuration; a
+  second reader is a second thing to update when the variable is renamed.
+
+### app — file-system routes
+
+A `page.tsx` coordinates: it calls `api` functions, holds the screen's state, and renders
+components. A `layout.tsx` wraps a subtree and is where that subtree's auth guard runs, so pages
+underneath can assume the user is signed in.
+
+- **APP-DO1** — Keep a page to coordination. When a page needs to decide something, that decision
+  should be a call into `api` or `utils`, not logic written inline. Tax maths, totals, retry
+  policy, and payload shaping are decisions.
+- **APP-DO2** — Handle an expired session the same way in every route. If one page signs the user
+  out on a 401 and another tells them to reconnect a third-party account, one of them is lying to
+  the user.
+- **APP-DO3** — Persist what you let the user change. If a control edits state, that state belongs
+  in the save payload — an edit the UI accepts and silently drops on reload is worse than no
+  control at all.
+- **APP-D1** — Don't define generic helpers in a route file. Date formatters, byte-size formatters,
+  currency formatters and the like belong in `utils`, where the next page can find them instead of
+  writing them again.
+- **APP-D2** — Don't reach the network except through `api`. No `fetch`, no axios, no direct URL
+  strings in a page.
+- **APP-D3** — Don't leave reusable markup here. A sub-view used by a second route moves to
+  `components`.
+
+### components — reusable UI, grouped by feature
+
+Feature folders (`auth`, `dashboard`, `email`, `quotation`) plus `ui` for generic primitives. `ui`
+is the generic layer — a `Button` or a `Modal` knows nothing about quotations or Outlook. The
+feature folders may know the domain, and may call `api` when the component owns a self-contained
+piece of the workflow (e.g. a preview modal that loads its own attachment).
+
+- **CMP-DO1** — An `index.ts` that re-exports a folder's public components **is allowed here, and
+  only here**. It is the folder's front door, not a service hiding its dependencies — which is why
+  API-D2 does not apply to it. Eg: `components/ui/index.ts`.
+- **CMP-D1** — Don't read or clear the token in an ordinary component. The one exception is the
+  guard shell a layout renders to protect its subtree (eg `components/dashboard/DashboardShell.tsx`).
+  Everything else takes a callback from that shell. A component that signs the user out itself, on
+  top of the handler it was already given, does the job twice — and the second `removeToken()` runs
+  against already-cleared storage, so the bug hides.
+- **CMP-D2** — Don't let a `ui/` primitive learn the domain. A prop named `quotation` or
+  `taxRate` on a generic `Modal` means the primitive is no longer reusable.
+
+### lib — app-level modules that are neither a network call nor a helper
+
+Today this is only sample data standing in for endpoints that don't exist yet (eg `lib/mockData.ts`).
+
+- **LIB-D1** — Don't let anything permanent settle here. When a mock is replaced by a real endpoint
+  the fetching moves to `api`, its shapes move to `types`, and the file goes away.
+
+### types — the structure of data crossing the network boundary
+
+The mirror of `models` on the backend. One file per backend resource, mirroring that resource's
+response envelope exactly (eg `types/email.types.ts`).
+
+- **TYP-DO1** — Keep these honest about what the server actually sends. A field typed as
+  always-present that the backend sometimes omits produces a crash the compiler promised could not
+  happen.
+- **TYP-D1** — Don't put logic here. Interfaces, type aliases, and constants that describe a default
+  shape are fine; **functions and network calls are not**. A type guard, a mapper, a
+  `formatX(t: T): string` — all of these are code wearing a types file as a hat, and they belong in
+  `utils` (generic) or with the feature (domain).
+
+### utils — generic helpers with nothing to do with business logic
+
+Every function is pure, and any function that touches `window` or `localStorage` guards for it
+first so it is safe to import from a server component (eg `utils/auth.ts`).
+
+- **UTL-DO1** — Check this folder before writing a helper. Most helpers that get written twice are
+  written twice because nobody looked.
+- **UTL-DO2** — Guard `window` / `localStorage` access with `typeof window === "undefined"` so the
+  module is importable from a server component.
+- **UTL-D1** — Don't implement the same helper in two places. If a copy already exists, import it or
+  move it here — two copies of a formatter drift, and the one that drifts is never the one you are
+  reading. A renamed duplicate (`formatDate` vs `formatFullDate` with the same body) is still a
+  duplicate.
+- **UTL-D2** — Don't let domain logic accumulate here. A helper that knows what a quotation, a tax
+  rate or a supplier column is has stopped being generic, and belongs with the feature it serves.
+
+## Traps — the distinctions that decide most reviews
+
+These are the places where a fast read gives the wrong verdict. Work through them before you write.
+
+| Looks like a violation | But it's fine when | Rule |
+|---|---|---|
+| `export { Button } from "./Button"` | it's `components/*/index.ts` — the folder's front door | CMP-DO1 beats API-D2 |
+| `import type { AxiosError } from "axios"` | anywhere — it's a type, not an instance | API-D1 permits it |
+| `removeToken()` in a component | it's the layout's guard shell (`DashboardShell.tsx`) | CMP-D1 exception |
+| a `const DEFAULT_X = {...}` in `types/` | it describes a default *shape*, not behaviour | TYP-D1 permits it |
+| a feature component calling `api` | it owns a self-contained piece of the workflow | `components` intro |
+
+And the inverse — things that look innocent and are not:
+
+- `import axios from "axios"` (default import, not `import type`) in any non-`api` file is API-D1,
+  even if the file never fires a request yet. The instance is the violation.
+- A re-export in `api/` is API-D2 **even if the re-exported thing is a type or a constant** — the
+  rule says "for any reason whatsoever" and it is the one absolute in the document.
+- A helper in `utils/` that reads generically but takes a domain-shaped argument
+  (`(row: QuotationRow)`) is UTL-D2. The name is not the tell; the parameter type is.
+- A page that computes a total inline is APP-DO1 *and* usually APP-D1 — flag whichever fits, don't
+  double-count the same lines under two IDs unless they genuinely name different problems.
+
+## Severity
+
+Match the repo's existing review convention:
+
+| | Meaning |
+|---|---|
+| 🔴 | Rule violation with a live consequence — security, correctness, or a boundary that will break under change |
+| 🟡 | Real violation, contained blast radius — drift, duplication, fragile coupling |
+| ⚠️ | Observation or nit — worth knowing, not worth blocking |
+| ✅ | Checked and clean |
+
+Anything touching auth, tokens, or the network boundary starts at 🔴. Placement violations with no
+current consequence (a formatter in the wrong folder) are 🟡. Style preferences are ⚠️.
+
+## Output format
+
+Use this structure. Adapt the depth to the size of the input — a ten-line snippet does not need
+five sections — but never drop the coverage table, because "what did you check?" is the question the
+user cannot answer for themselves.
+
+```markdown
+## Review: <file or diff under review>
+
+**Layer:** `<folder>` — <one line: stated by the user, or how you inferred it>
+
+### Findings
+
+| Sev | Rule | Location | Finding |
+|-----|------|----------|---------|
+| 🔴 | API-D1 | `line 4` | <what is wrong, in one sentence> |
+
+Then, for each finding, a short block:
+
+#### 🔴 API-D1 — <short title> (`file:line`)
+
+<The offending code, quoted — two or three lines, enough to locate it.>
+
+**Why it matters.** <The consequence, concretely. Not "violates the rule" — what breaks, and when.>
+
+**Fix.** <A concrete change: which file it moves to, what the call site becomes. Show the code where
+a sentence would be ambiguous.>
+
+### Rules checked and clean
+
+| Rule | Verdict |
+|------|---------|
+| API-DO1 method/path comment present | ✅ |
+| API-D2 no re-exports | ✅ |
+```
+
+Some real problems have no rule behind them — a missing null guard, an import that resolves to
+nothing, a typo in a comment. Report them, but put them under a separate **"Outside the rules"**
+heading rather than in the findings table with an empty Rule column. Mixing them in makes the table
+lie about what the architecture document actually requires, and a reader skimming the Rule column
+cannot tell which items they are obliged to fix.
+
+If the code is clean, say so per rule category rather than emitting a bare "looks good" — list every
+rule you checked with a ✅ and state plainly that you found no violations. A clean review that shows
+its work is useful; one that doesn't is indistinguishable from a review that wasn't done.
+
+If you cannot verify a rule from what you were given — UTL-D1 needs the rest of `utils/` to know
+whether a helper is a duplicate, APP-DO2 needs the other routes to know whether 401 handling is
+consistent — say that explicitly rather than passing it silently. If you have filesystem access,
+read the folder and check properly; only fall back to "not verifiable from this snippet" when you
+genuinely can't look.

package/skills/frontend-code-review-2/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: frontend-code-review-2
+description: Verifies frontend code against a set of PR review comments and reports pass / fail / unclear per comment, with quoted evidence from the code as it exists on disk right now — and changes nothing. Writes a markdown + JSON report. Use this whenever the user asks to check, verify, audit or confirm whether review comments, PR feedback, or review-document findings have actually been addressed — "did we fix these PR comments", "audit the frontend against PR #3", "which of these are still open", "give me a pass/fail report, don't change anything", "verify the fixes landed", "my colleague says these are done, check". Use it even if the user never says the word "audit". This is comment-verification, not fresh review: reach for it when the findings already exist and the question is whether the code satisfies them. Do NOT use it when the user wants the issues actually fixed — this skill deliberately never edits code.
+---
+
+# Frontend code audit (review-only)
+
+This is a verification pass, not a review and not a fix. Someone already reviewed the code and left
+comments; someone may since have claimed to address them. Your job is to answer one question per
+comment: **is this true of the code on disk right now?**
+
+You are not looking for new problems. The comment list is the spec, and a comment that turns out to
+be wrong is still the thing you report against.
+
+The entire value of an audit is that it is trustworthy. A finding you guessed at is worse than no
+finding, because it launders a guess into a checkmark that the next person acts on. So every status
+you write carries quoted code behind it, read from the current tree.
+
+## The one hard rule: don't touch the code
+
+Read-only on the source. The only files you write are the two report files.
+
+Two reasons, and they both matter more than the convenience of a quick fix. First, an auditor who
+repairs what they audit destroys the evidence — the reader can no longer tell what state the branch
+was actually in, and the report becomes a record of your edits rather than of the code. Second, the
+user has a separate workflow for fixing; mixing the two means an unreviewed change rides in under
+the cover of a report.
+
+So when a fix is one line and obvious, that is still a `fail`. Write the evidence, and if it helps,
+one line on what the fix would be. If you notice yourself reaching for Edit or Write on a source
+file, treat that impulse as the signal that you have found a real `fail` and write it down instead.
+
+## Step 1 — Pin down the inputs, and say what you resolved
+
+Three things: where the comments come from, what code they are about, where the report goes.
+
+- **Comments** — a PR URL or number, or a list the user pastes inline. For a PR, use
+  `scripts/fetch_pr_comments.py` rather than hand-rolling `gh` calls; it handles pagination, thread
+  replies and path filtering, which are easy to get subtly wrong.
+- **Code under audit** — defaults to
+  `/home/dev/workspaces/murtaza-workspaces/murtaza-hotel-project/Frontend`. The review documents the
+  comments are anchored to live in that folder's `review/` subdirectory.
+- **Output** — defaults to `<code path>/FRONTEND_AUDIT.md` and `.json`.
+
+If the user scoped it ("just the api layer", "only the types comments"), filter by the review
+document path — `Frontend/review/API_REVIEW.md` for api, `APP_REVIEW.md` for app, and so on. State
+the scope and the comment count before you start checking, so a mis-scoped run is caught in one line
+rather than at the end of a long report.
+
+```bash
+python3 scripts/fetch_pr_comments.py --pr 3 --path-prefix Frontend/review/API_REVIEW.md \
+  --out /tmp/audit-comments.json
+```
+
+## Step 2 — Resolve each comment to the code it is about
+
+This step decides whether the audit is accurate, and it has a trap in it.
+
+**The comment's anchor is not the code.** These comments are attached to lines in review documents
+(`Frontend/review/API_REVIEW.md:44`), which are markdown — usually a row in a findings table or a
+paragraph in a detail section. The comment is *about* a source file that the review document names.
+So read the anchored region of the document to learn which file and symbol is meant, then leave the
+document behind. **You are grading the code, not the review.** A report that quotes the review
+document back at the user has verified nothing.
+
+Many comments name the file and symbol themselves ("Delete `formatFullDate` from
+`email/[messageId]/page.tsx`"). Those need no lookup — go straight to the source.
+
+**Expect paired duplicates.** A reviewer typically comments once on the summary-table row and again
+on the detail section for the same finding, sometimes in nearly identical words. Report both, since
+each comment id is something a person will search for, but mark the second `duplicate_of` the first.
+Without that, a reader sees eight problems where there were four, and the summary counts mislead.
+
+**Some comments reject the finding rather than request a change** — e.g. "no need to store it in the
+backend database, it is only for the user to hide it in the frontend." Here the requested state is
+the current state, so it is a `pass`. Say explicitly that the comment asked for no change and that
+the code matches, because a reader scanning a column of statuses will otherwise assume someone did
+work here.
+
+## Step 3 — Decide the status from the code on disk
+
+Re-derive everything. Do not trust the review document's line numbers (they were written against an
+older tree), a commit message, a changelog, an earlier audit, or the user telling you a colleague
+already did it. Those tell you what someone intended; the file tells you what is true. Being told
+the work is done is a reason to look more carefully, not less.
+
+| Status | When |
+|---|---|
+| `pass` | The code now satisfies what the comment asked for, in full. |
+| `fail` | The problem is still there, or only part of the request landed. |
+| `unclear` | You genuinely cannot locate the code, or the comment is too vague to have a testable meaning. |
+
+**Partial is `fail`, and name the remainder.** This is the status most often got wrong, because a
+half-applied change looks like a fix at the point you happen to look at. A change can land in one
+place and not in its counterpart: the return statement updated but not the function's declared
+return type, the helper extracted but the old copy still exported, the field added but left optional
+when the comment asked for required, one of four call sites migrated. Before you write `pass`, ask
+what else had to move for this change to be complete, and go look at that too. A half-applied fix
+is often worse than none, since it can leave the code not even compiling — and that is exactly the
+thing an audit exists to surface.
+
+**`unclear` is honest, and it is expensive.** It hands the work back to the reader, so spend a real
+search first: try the symbol name, the old name, the file the review names, and a repo-wide grep. If
+you can find the code but the comment is a judgement call, don't hide behind `unclear` — give your
+reading and say it is a judgement call.
+
+**The trap that produces false passes: a name matching in the wrong place.** Grep tells you a string
+exists somewhere, not that the request was satisfied. `canSendEmail` appearing as an optional field
+on a duplicate interface in `quotation.types.ts` is not the required field the comment asked for on
+`EmailStatusConnected` in `email.types.ts`. Before you write `pass`, confirm all three: the right
+file, the right symbol, the right shape. Grep locates; reading decides.
+
+### Evidence, and its fidelity
+
+Every finding carries a quote with a `file:line` from the current tree. This is what makes the
+report checkable by someone who doesn't trust you — and being checkable is the point.
+
+- For a `fail`, quote the offending code as it stands.
+- For a `pass`, quote the code that now satisfies the comment.
+- When the pass is an *absence* ("the duplicate is gone"), a quote is impossible, so state the
+  search that establishes it and its scope: "`grep -rn "escapeHtml" Frontend/` returns only
+  `utils/sanitizeHtml.ts:12`." An unscoped "I couldn't find it" is not evidence.
+
+**If you cite a command and its result, the result has to be real.** Writing "grep returns exactly
+one hit" when it returns two is the one error that discredits the whole report — a reader who
+re-runs your command and gets a different answer now has to re-verify every other line you wrote.
+Line numbers and counts drift as you work, so when you are about to state one, re-run the command
+and read the output rather than recalling it from earlier in the session. Nobody minds "returns two
+hits, one of which is a prose comment"; they mind being told something they can disprove in five
+seconds.
+
+## Step 4 — Write the report
+
+Build a findings JSON, then render the markdown from it with `scripts/render_report.py`. The script
+computes the counts and the per-file breakdown from the findings themselves, so the summary table
+cannot drift out of step with the detail below it — which is the failure mode when both files are
+written by hand. It also keeps the two files sharing one basename, so the pair is findable.
+
+```bash
+python3 scripts/render_report.py --findings /tmp/findings.json --out-base <output path>/FRONTEND_AUDIT
+```
+
+The findings JSON you write:
+
+```json
+{
+  "audit": {
+    "source": "https://github.com/owner/repo/pull/3",
+    "scope": "Frontend/review/API_REVIEW.md — 8 comments",
+    "target": "/abs/path/Frontend",
+    "commit": "0a8162d"
+  },
+  "findings": [
+    {
+      "comment_id": "3923087999",
+      "comment_url": "https://github.com/owner/repo/pull/3#discussion_r3923087999",
+      "comment_location": "Frontend/review/API_REVIEW.md:44",
+      "comment": "Update the 4 comments to use the correct /api/... paths.",
+      "target_files": ["Frontend/api/email.api.ts"],
+      "status": "fail",
+      "evidence": "email.api.ts:19 still reads `// GET /email/status`; :26, :34, :41 likewise. None carry the /api prefix.",
+      "remaining": "All four comments still need the /api prefix.",
+      "duplicate_of": null
+    }
+  ]
+}
+```
+
+`remaining` is for partial work and may be omitted. `duplicate_of` carries the earlier comment id
+when two comments describe one finding.
+
+## Step 5 — Reply in chat with the summary only
+
+Three to five lines: the counts, the two file paths, and at most a one-sentence headline (the
+cluster that dominates the failures, or that nothing has been addressed yet). The user asked for a
+report on disk precisely so they don't have to read it in the transcript — reproducing its substance
+in chat makes the deliverable harder to find, not easier, and quietly doubles the length of the
+thing they have to read.
+
+Something like:
+
+> Audited 8 comments from PR #3 against `Frontend/api` (4 distinct findings; 4 of the comments are
+> duplicate pairs). **0 pass, 8 fail, 0 unclear** — none of the api-layer feedback has landed yet.
+> Report: `Frontend/FRONTEND_AUDIT.md` and `.json`. No source files were modified.
+
+## Bundled scripts
+
+- `scripts/fetch_pr_comments.py` — pulls review comments from a PR via `gh`, paginated, optionally
+  filtered by file path, and normalises them to `{id, url, path, line, body, in_reply_to}`. Run
+  with `--help` for options.
+- `scripts/render_report.py` — turns the findings JSON into `<base>.md` and `<base>.json`, deriving
+  the summary counts and the by-file breakdown so the two files always agree.

package/skills/frontend-code-review-2/scripts/fetch_pr_comments.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Fetch a PR's review comments via `gh`, normalised for auditing.
+
+Usage:
+  python3 fetch_pr_comments.py --pr 3 [--repo owner/name] \
+      [--path-prefix Frontend/review/] [--out comments.json]
+
+Emits a JSON list of {id, url, path, line, body, in_reply_to}, ordered by path then line,
+so the audit works through the review document top to bottom.
+"""
+import argparse
+import json
+import subprocess
+import sys
+
+
+def gh_json(args):
+    proc = subprocess.run(["gh"] + args, capture_output=True, text=True)
+    if proc.returncode != 0:
+        sys.exit(f"gh failed: {proc.stderr.strip()}")
+    return json.loads(proc.stdout)
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--pr", required=True)
+    p.add_argument("--repo", help="owner/name; defaults to the current repo's origin")
+    p.add_argument("--path-prefix", default="", help="only keep comments on paths starting with this")
+    p.add_argument("--out", help="write JSON here instead of stdout")
+    args = p.parse_args()
+
+    repo = args.repo
+    if not repo:
+        repo = gh_json(["repo", "view", "--json", "nameWithOwner"])["nameWithOwner"]
+
+    raw = gh_json(["api", f"repos/{repo}/pulls/{args.pr}/comments", "--paginate"])
+
+    out = []
+    for c in raw:
+        path = c.get("path") or ""
+        if args.path_prefix and not path.startswith(args.path_prefix):
+            continue
+        out.append(
+            {
+                "id": str(c["id"]),
+                "url": c.get("html_url"),
+                "path": path,
+                "line": c.get("line") or c.get("original_line"),
+                "body": (c.get("body") or "").strip(),
+                "in_reply_to": str(c["in_reply_to_id"]) if c.get("in_reply_to_id") else None,
+            }
+        )
+
+    out.sort(key=lambda c: (c["path"], c["line"] or 0))
+    text = json.dumps(out, indent=2)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(text + "\n")
+        print(f"{len(out)} comments -> {args.out}", file=sys.stderr)
+    else:
+        print(text)
+
+
+if __name__ == "__main__":
+    main()

package/skills/frontend-code-review-2/scripts/render_report.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Render an audit findings JSON into <base>.md and <base>.json.
+
+Counts and the by-file breakdown are derived here rather than written by hand, so the
+summary can never disagree with the detail below it.
+
+Usage:
+  python3 render_report.py --findings findings.json --out-base /path/FRONTEND_AUDIT
+"""
+import argparse
+import json
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+
+ICON = {"pass": "✅", "fail": "❌", "unclear": "❓"}
+ORDER = {"fail": 0, "unclear": 1, "pass": 2}
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--findings", required=True)
+    p.add_argument("--out-base", required=True)
+    args = p.parse_args()
+
+    with open(args.findings) as f:
+        doc = json.load(f)
+
+    meta = doc.get("audit", {})
+    findings = doc["findings"]
+
+    for i, f_ in enumerate(findings):
+        st = f_.get("status")
+        if st not in ICON:
+            raise SystemExit(f"finding {i} ({f_.get('comment_id')}): bad status {st!r}")
+
+    counts = Counter(f_["status"] for f_ in findings)
+    summary = {
+        "pass": counts.get("pass", 0),
+        "fail": counts.get("fail", 0),
+        "unclear": counts.get("unclear", 0),
+        "total": len(findings),
+        "distinct_findings": len([f_ for f_ in findings if not f_.get("duplicate_of")]),
+    }
+    meta.setdefault("generated_at", datetime.now(timezone.utc).isoformat(timespec="seconds"))
+
+    out = {"audit": meta, "summary": summary, "findings": findings}
+    with open(args.out_base + ".json", "w") as f:
+        json.dump(out, f, indent=2)
+        f.write("\n")
+
+    by_file = defaultdict(list)
+    for f_ in findings:
+        for path in f_.get("target_files") or ["(unresolved)"]:
+            by_file[path].append(f_)
+
+    L = []
+    L.append("# Frontend code audit")
+    L.append("")
+    L.append("Review-only pass. No source files were modified by this audit.")
+    L.append("")
+    for key, label in (
+        ("source", "Comments"),
+        ("scope", "Scope"),
+        ("target", "Code audited"),
+        ("commit", "At commit"),
+        ("generated_at", "Generated"),
+    ):
+        if meta.get(key):
+            L.append(f"- **{label}:** {meta[key]}")
+    L.append("")
+    L.append("## Summary")
+    L.append("")
+    L.append("| Status | Count |")
+    L.append("|---|---|")
+    L.append(f"| ✅ pass | {summary['pass']} |")
+    L.append(f"| ❌ fail | {summary['fail']} |")
+    L.append(f"| ❓ unclear | {summary['unclear']} |")
+    L.append(f"| **total comments** | **{summary['total']}** |")
+    if summary["distinct_findings"] != summary["total"]:
+        L.append(f"| distinct findings (duplicates collapsed) | {summary['distinct_findings']} |")
+    L.append("")
+
+    L.append("## By file")
+    L.append("")
+    L.append("| File | ✅ | ❌ | ❓ |")
+    L.append("|---|---|---|---|")
+    for path in sorted(by_file):
+        c = Counter(f_["status"] for f_ in by_file[path])
+        L.append(f"| `{path}` | {c.get('pass',0)} | {c.get('fail',0)} | {c.get('unclear',0)} |")
+    L.append("")
+
+    L.append("## Findings")
+    L.append("")
+    L.append("| Status | Comment | Location | Files |")
+    L.append("|---|---|---|---|")
+    ordered = sorted(findings, key=lambda f_: (ORDER[f_["status"]], f_.get("comment_id") or ""))
+    for f_ in ordered:
+        files = ", ".join(f"`{x}`" for x in (f_.get("target_files") or [])) or "—"
+        dup = " *(dup)*" if f_.get("duplicate_of") else ""
+        L.append(
+            f"| {ICON[f_['status']]} {f_['status']} | `{f_.get('comment_id','')}`{dup} "
+            f"| {f_.get('comment_location','—')} | {files} |"
+        )
+    L.append("")
+
+    for f_ in ordered:
+        cid = f_.get("comment_id", "")
+        url = f_.get("comment_url")
+        head = f"### {ICON[f_['status']]} {f_['status'].upper()} — comment "
+        head += f"[{cid}]({url})" if url else f"`{cid}`"
+        L.append(head)
+        L.append("")
+        loc = f_.get("comment_location")
+        if loc:
+            L.append(f"- **Anchored at:** `{loc}`")
+        if f_.get("target_files"):
+            L.append(f"- **Code audited:** {', '.join('`' + x + '`' for x in f_['target_files'])}")
+        if f_.get("duplicate_of"):
+            L.append(f"- **Duplicate of:** `{f_['duplicate_of']}` — same finding, restated.")
+        L.append("")
+        L.append("> " + (f_.get("comment", "").strip().replace("\n", "\n> ") or "_(empty)_"))
+        L.append("")
+        L.append(f"**Evidence.** {f_.get('evidence', '_none given_')}")
+        L.append("")
+        if f_.get("remaining"):
+            L.append(f"**Still outstanding.** {f_['remaining']}")
+            L.append("")
+
+    with open(args.out_base + ".md", "w") as f:
+        f.write("\n".join(L))
+
+    print(
+        f"{summary['total']} comments: {summary['pass']} pass / {summary['fail']} fail / "
+        f"{summary['unclear']} unclear -> {args.out_base}.md, {args.out_base}.json"
+    )
+
+
+if __name__ == "__main__":
+    main()