@hdwebsoft/hdcode-ai-darwin-x64 0.0.6 → 0.0.8

package/resources/skills/hd-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hd-code-review
-description: "Review code changes between branches with a skeptical gatekeeper mindset. Reviews git diff across 11 aspects (requirements, correctness, possible breakage, better approach, redundancy, tests, security, breaking changes, implication assessment, code quality, completeness). Reads CODING_STANDARDS.md for project-specific rules. Outputs Approved / Approved with Comments / Changes Requested verdict."
+description: "Review code changes between branches with a skeptical gatekeeper mindset. Reviews git diff across 12 aspects (requirements, correctness, possible breakage, better approach, redundancy, tests, security, breaking changes, implication assessment, code quality, completeness, architecture & design). Reads CODING_STANDARDS.md for project-specific style rules and REVIEW_STANDARDS.md for tech-stack presets, aspect escalations, and custom aspects. Outputs Approved / Approved with Comments / Changes Requested verdict."
 license: proprietary
 metadata:
   version: "1.0.0"
@@ -9,16 +9,16 @@ metadata:
 
 # Code Review Skill
 
-> [IMPORTANT] This skill is THINKING-HEAVY — it relies on reading the diff and applying
-> the 11-aspect checklist from `reference/review-checklist.md`. It does NOT replace
-> `hd-security-review` for deep security analysis.
+> [IMPORTANT] This skill orchestrates 3 parallel subagents (`code-review-security`, `code-review-logic`, `code-review-quality`)
+> that each embed the relevant aspect checklists from `reference/review-checklist.md`.
+> It does NOT replace `hd-security-review` for deep security analysis.
 > For comprehensive security review, run `/hd-security-review code-review` separately.
 
 ## Pipeline
 
 ```
 INPUT → Arg Parse → Standards Load → Diff Fetch → Task Context →
-11-Aspect Review → Breaking Change Gate → Verdict → File Output → (TODO: Post to VCS)
+Context Assembly → [code-review-security ‖ code-review-logic ‖ code-review-quality] → Gate → Verdict → File Output → (TODO: Post to VCS)
 ```
 
 ---
@@ -39,20 +39,7 @@ Parse the invocation:
 
 ### Natural Language Resolution
 
-If the first argument is not a task URL and contains branch-like patterns,
-extract branch names before treating the remainder as task context:
-
-| Pattern | Example | Resolution |
-|---------|---------|------------|
-| `against <branch>` | "against develop" | `TARGET_BRANCH = develop` |
-| `vs <branch>` | "vs main" | `TARGET_BRANCH = main` |
-| `compare with <branch>` | "compare with staging" | `TARGET_BRANCH = staging` |
-| `from <branch>` | "from feat/auth" | `SOURCE_BRANCH = feat/auth` |
-| `<branch> against <branch>` | "feat/x against main" | SOURCE = feat/x, TARGET = main |
-
-After extracting branch names, treat any remaining text as task context (Path B).
-If remaining text is empty or only articles/prepositions, treat as no task context (Path C).
-Explicit flags (`--source`, `--target`) always take precedence over natural language.
+Extract branch names from patterns like "against `<b>`", "vs `<b>`", "from `<b>`", "`<s>` against `<t>`". Remaining text = task context (Path B); empty remainder = Path C. Explicit flags always take precedence.
 
 Determine:
 - `SOURCE_BRANCH` — from `--source` flag, natural language, or `git branch --show-current`
@@ -80,6 +67,41 @@ Display: `Standards loaded. Active policies: [comma-separated list of policies w
 
 ---
 
+## Phase 1.5: Review Standards Load
+
+Load `REVIEW_STANDARDS.md` via two-layer inheritance:
+
+| Layer | Path | Role |
+|-------|------|------|
+| Layer 1 (always) | `skills/hd-code-review/REVIEW_STANDARDS.md` | Schema + empty defaults |
+| Layer 2 (if exists) | `<project-root>/docs/REVIEW_STANDARDS.md` | Project overrides — wins on conflict |
+
+Extract:
+- `TECH_STACK` — from `tech_stack:` field (`~` = none)
+- `ASPECT_ESCALATIONS` — aspects promoted from Tier 2 advisory to Tier 1 blocker
+- `CUSTOM_ASPECTS` — project-specific review dimensions
+
+If `TECH_STACK` is explicitly set (not `~`): record it as the forced stack — skip auto-detection in Phase 4.
+
+Apply `ASPECT_ESCALATIONS`: escalated aspect numbers are passed to agents via the Review Context payload; agents mark those findings as 🔴 Blocker. The skill also checks ALL agent outputs (including quality) for 🔴 markers when escalations are active.
+
+Display: `Review standards loaded. Stack: <explicit value or 'auto-detect'> | Escalations: <count> | Custom aspects: <count>`
+
+---
+
+## Phase 1.6: Known Issues Load
+
+Load `docs/KNOWN_ISSUES.md` if it exists in the project root:
+
+| Condition | Action |
+|-----------|--------|
+| File exists | Parse all `## KI-NNN` entries into `KNOWN_ISSUES` list. Each entry captures: ID, title, scope, reason, accepted-on, target-fix. |
+| File does not exist | `KNOWN_ISSUES` = empty list. |
+
+Display: `Known issues loaded: <N> entries.` or `Known issues: none (docs/KNOWN_ISSUES.md not found).`
+
+---
+
 ## Phase 2: Diff Fetch
 
 Run:
@@ -98,103 +120,240 @@ Assess diff size:
 
 Display: `Diff: <N> lines changed across <M> files`
 
+**Remote URL detection** (run in parallel with diff, does not block):
+
+```bash
+git remote get-url origin
+```
+
+Parse the output into `PLATFORM_LINK_BASE`:
+
+| Remote URL pattern | Platform | `PLATFORM_LINK_BASE` |
+|--------------------|----------|----------------------|
+| `https://github.com/<owner>/<repo>[.git]` | GitHub | `https://github.com/<owner>/<repo>/blob/<SOURCE_BRANCH>` |
+| `git@github.com:<owner>/<repo>.git` | GitHub | `https://github.com/<owner>/<repo>/blob/<SOURCE_BRANCH>` |
+| `https://gitlab.com/<owner>/<repo>[.git]` | GitLab | `https://gitlab.com/<owner>/<repo>/-/blob/<SOURCE_BRANCH>` |
+| `git@gitlab.com:<owner>/<repo>.git` | GitLab | `https://gitlab.com/<owner>/<repo>/-/blob/<SOURCE_BRANCH>` |
+| `https://bitbucket.org/<owner>/<repo>[.git]` | Bitbucket | `https://bitbucket.org/<owner>/<repo>/src/<SOURCE_BRANCH>` |
+| Any other host (self-hosted) | unknown | `~` |
+| Command fails / no remote | none | `~` |
+
+If `REVIEW_STANDARDS.md` has `remote_url` set (Layer 2 override), use it instead and skip `git remote get-url origin` parsing. The `remote_url` value IS the `PLATFORM_LINK_BASE` (append `/<SOURCE_BRANCH>` if the value ends with the repo path and has no branch segment, or use as-is if it already includes the branch path).
+
+Store as `PLATFORM_LINK_BASE` (`~` = unavailable — fall back to IDE-only links).
+
 ---
 
 ## Phase 3: Task Context
 
-Three paths — check in order:
+**Path A — URL provided:** Detect platform (Linear `linear.app`, Jira `atlassian.net`, ClickUp `app.clickup.com`, Asana `app.asana.com`). Fetch title + description + labels via MCP; if MCP inactive, ask user to paste.
+
+Detect task type:
+| Signal | Type |
+|--------|------|
+| Labels: `bug`/`defect`/`regression`/`hotfix` | Bug |
+| Branch prefix: `fix/` `hotfix/` `bugfix/` `patch/` | Bug |
+| Otherwise | Feature (default) |
+
+**Feature:** Parse `- [ ]`/`- [x]` items as ACs; fall back to full description if none. Display: `Task context loaded: <title> — <N> ACs`. Aspects 1 + 11: cross-reference each AC.
 
-**Path A — Task URL provided:**
-- Detect platform from URL pattern: Linear (`linear.app`), Jira (`atlassian.net`), ClickUp (`app.clickup.com`), Asana (`app.asana.com`)
-- If MCP is active: call `get_task` with the detected platform to fetch title + description
-- If MCP is inactive: ask the user to paste the task title and description
+**Bug:** Fetch comments + priority via MCP. Display: `Task context loaded: <title> — Bug (Priority: <P>) | Repro: <first comment or "none">`. Elevate Aspects 2, 3, 6 (require regression test).
 
-**Path B — Plain-text description provided:**
-- Use the provided text as-is for requirements context in Aspects 1 and 11
+**Path B — Plain text:** Use as-is for Aspects 1 and 11.
 
-**Path C — No context provided:**
-- Note: Aspects 1 (Requirements Coverage) and 11 (Completeness) will be marked N/A
-- Proceed with the 9 remaining aspects only
+**Path C — None:** Aspects 1 and 11 → N/A; continue with 9 remaining.
 
 ---
 
-## Phase 4: 11-Aspect Review
+## Phase 4: Context Assembly
+
+**Step 1 — Stack detection:** If `TECH_STACK` was explicitly set in Phase 1.5, use it. Otherwise, auto-detect from the diff's changed file extensions:
+
+| Extensions / path signals in diff | Stack preset(s) loaded |
+|-----------------------------------|----------------------|
+| `.cs` `.csproj` `.sln` `.razor` | `dotnet` |
+| `.ts` `.js` `.mjs` `.cjs` `package.json` (no `.tsx`/`.jsx`, no RN signals) | `nodejs` |
+| `.tsx` `.jsx` (no RN signals) | `react` |
+| `.ts` `.js` + `.tsx` `.jsx` (no RN signals) | `nodejs` + `react` |
+| `.vue` | `vuejs` |
+| `.native.ts/tsx/js` OR `react-native` in `package.json`, `android/`/`ios/` paths (no Expo) | `reactnative` |
+| RN signals + `expo` in `package.json` / `app.json` / `app.config.*` | `reactnative` + `expo` |
+| `.dart` `pubspec.yaml` | `flutter` |
+| `.go` `go.mod` | `go` |
+| `.py` (no Django path signals) | `python` |
+| `.py` + Django paths (`views.py` `models.py` `urls.py` `serializers.py` `migrations/`) | `python` + `django` |
+| `.php` (no framework signals) | `php` |
+| `.php` + Laravel signals (`artisan`, `app/Http/Controllers/`, `routes/web.php`) | `php` + `laravel` |
+| `.php` + CakePHP signals (`src/Controller/`, `config/routes.php`, `"cakephp/cakephp"` in `composer.json`) | `php` + `cakephp` |
+| `.php` + WordPress signals (`wp-config.php`, `wp-content/`, `functions.php`, WP function calls) | `php` + `wordpress` |
+| `.scala` `build.sbt` | `scala` |
+| `.cls` `.trigger` `.apex` | `apex` |
+| `.html` or `.js` under `lwc/` path | `lwc` |
+| `.cls` + `.html`/`.js` under `lwc/` path | `apex` + `lwc` |
+| `.cmp` `.app` `.evt` `.intf` | `aura` |
+| `.page` or `.component` under `pages/` path | `visualforce` |
+| Multiple sets present | all matching presets — checks scoped to relevant file types |
+| None of the above | none |
+
+Read `reference/stacks/<stack>.md` for each detected stack.
+
+**Step 2 — Build the Review Context payload** (used as the prompt for all 3 agents):
 
-**Before starting:** Read `reference/review-checklist.md` in full. Apply every aspect from that file to the diff.
+```markdown
+## Review Context
 
-**Strategy for large diffs:** Do not review linearly. Process file-by-file, then function-by-function within each file. Trace call paths where behavior is non-obvious.
+### Diff
+```diff
+<full git diff>
+```
 
-**Aspect 4 (Better Approach) rule:** ALWAYS use Grep/Glob to verify that an alternative pattern does not already exist in the codebase before suggesting it. Do not recommend an approach that is already present.
+### Task
+- Title: <title or "No task context provided">
+- Type: Bug | Feature | N/A
+- Acceptance Criteria:
+  <AC list, or "No task context provided">
 
-**Output per aspect:**
-- No issues: `✓ Aspect N (Name) — no issues`
-- Issues found: full finding block with 🔴 Blocker or 🟡 Advisory severity (see checklist for per-aspect rules)
+### Coding Standards
+<merged CODING_STANDARDS content>
 
-Track state across all aspects:
-- `has_blocker` — set to `true` if any 🔴 finding is recorded
-- `has_advisory` — set to `true` if any 🟡 finding is recorded
+### Tech Stack
+<detected stack(s), or "none">
 
----
+### Stack-Specific Checks
+<full content of reference/stacks/<stack>.md for each detected stack, or "none">
+When multiple stacks are active, scope each stack's checks to files of that type.
 
-## Phase 5: Breaking Change Gate
+### Escalated Aspects
+<comma-separated aspect numbers from ASPECT_ESCALATIONS, or "none">
 
-Regardless of other findings, check for breaking changes in the diff:
+### Custom Aspects (Tier 1)
+<CUSTOM_ASPECTS entries with tier: 1, or "none">
 
-- Public API signature changes (function name, parameter names/types/order, return type)
-- Existing interface or contract violations (removed fields, renamed fields, changed types)
-- DB schema changes without a corresponding migration
-- Config format changes that break existing deployments
-- Behavior changes for existing users without explicit versioning
+### Custom Aspects (Tier 2)
+<CUSTOM_ASPECTS entries with tier: 2, or "none">
 
-If any breaking changes found: produce a dedicated `### ⚠️ Breaking Changes` block.
-This block appears in the final verdict output **even if the overall verdict is Approved**.
-If none found, write: `No breaking changes detected.`
+### Known Issues
+<KNOWN_ISSUES list (ID, title, scope, reason, target-fix for each entry), or "none">
 
----
+### Cross-Reference Instruction
+When generating findings: if a finding topic or file scope overlaps with a known issue entry above, append `[Known Issue: KI-NNN — <title>]` to that finding and downgrade its severity to **INFO**. Do NOT omit the finding — preserve full visibility. A finding can match at most one KI entry.
 
-## Phase 6: Verdict
+### Platform Link Base
+<PLATFORM_LINK_BASE value, or "~" if unavailable>
 
-Determine verdict from tracked state:
+### Finding Format (REQUIRED)
+Every finding header MUST include the affected file AND line number as clickable links.
 
+**When `Platform Link Base` is set (not `~`)** — produce dual links: IDE link + platform link:
 ```
-has_blocker = true                              →  ❌ Changes Requested
-has_blocker = false AND has_advisory = true     →  ⚠️ Approved with Comments
-has_blocker = false AND has_advisory = false    →  ✅ Approved
+**<PREFIX>:<N>** — <🔴/🟡> <Label> · [<file>:<line>](<file>#L<line>) · [↗](<PLATFORM_LINK_BASE>/<file>#L<line>)
+**<PREFIX>:<N>** — <🔴/🟡> <Label> · [<file>:<start>-<end>](<file>#L<start>-L<end>) · [↗](<PLATFORM_LINK_BASE>/<file>#L<start>-L<end>)
 ```
 
-Output in this format:
+**When `Platform Link Base` is `~`** — IDE link only:
+```
+**<PREFIX>:<N>** — <🔴/🟡> <Label> · [<file>:<line>](<file>#L<line>)
+**<PREFIX>:<N>** — <🔴/🟡> <Label> · [<file>:<start>-<end>](<file>#L<start>-L<end>)
+```
 
-```markdown
+Rules:
+- Extract line numbers from the diff `@@` hunk headers and `+`/`-` line markers
+- Use the **new file** (post-patch) line number where the issue appears
+- For a range, use `start-end` in display text and `#L<start>-L<end>` as the anchor
+- The anchor MUST be `#L<line>` (e.g., `#L140`) — never `#<line>` or `:<line>`
+- If no specific line can be determined, omit the line number rather than guess
+```
+
+---
+
+## Phase 4.5: Parallel Agent Review
+
+Print the review header before spawning agents:
+
+```
 ## Code Review: `<SOURCE_BRANCH>` → `<TARGET_BRANCH>`
 **Reviewed:** <YYYY-MM-DD>
 **Task:** <task title or 'No task context'>
 **Standards:** <comma-separated required policies, or 'defaults only'>
 
 ---
+⏳ Running parallel review (security · logic · quality)...
+```
+
+Record `T1_START` = current timestamp (seconds).
 
-### Review Findings
-
-✓ Aspect 1 (Requirements Coverage) — no issues
-✓ Aspect 2 (Correctness) — no issues
-**Aspect 3 — Possible Breakage** 🔴 Blocker
-- Unhandled null case in createUser() when email is undefined — src/users.ts:42
-✓ Aspect 4 (Better Approach) — no issues
-✓ Aspect 5 (Redundancy) — no issues
-**Aspect 6 — Tests** 🔴 Blocker
-- No test covers the null email path added in src/users.ts
-✓ Aspect 7 (Security) — no issues
-✓ Aspect 8 (Breaking Changes) — see Breaking Changes block below
-✓ Aspect 9 (Implication Assessment) — no issues
-✓ Aspect 10 (Code Quality) — no issues
-✓ Aspect 11 (Completeness) — no issues
+**Spawn all 3 agents simultaneously** (single parallel tool call):
 
+| Agent | Aspects | Model | Context |
+|-------|---------|-------|---------|
+| `code-review-security` | 3, 7, 8 + Tier 1 custom | sonnet | Review Context payload |
+| `code-review-logic` | 2, 6, 1, 11 + Tier 1 custom | sonnet | Review Context payload |
+| `code-review-quality` | 4, 5, 9, 10, 12 + Tier 2 custom | haiku | Review Context payload |
+
+Wait for all 3 agents to complete. Record `T1_END` = current timestamp (seconds).
+
+**Print results:** Output each agent's full response **verbatim** (do NOT reconstruct, summarize, or reformat findings — preserve the original finding headings, description, suggestion, and the fenced `markdown` copy block exactly as the agent emitted them):
+1. `code-review-security` output (Tier 1 — security & safety)
+2. `code-review-logic` output (Tier 1 — correctness & coverage)
+3. *(hold `code-review-quality` output — apply gate first)*
+
+**Gate check:** Scan the combined security + logic outputs for any 🔴 marker.
+
+If blockers found:
+
+```
 ---
+⏱ Tier 1 completed in <T1_END - T1_START>s
+**Tier 1 complete.** 🔴 Blocker(s) found — this branch needs rework before advisories matter.
+Continue to advisory aspects (better approach, redundancy, implications, quality, architecture)? [y/n]
+```
 
-### ⚠️ Breaking Changes
-- Changed signature of `createUser(name)` → `createUser(name, options)` — check all callers
+Wait for user input. If **n** → skip to Phase 6 immediately.
+
+If no blockers (or user says **y**):
+
+```
+---
+⏱ Tier 1 completed in <T1_END - T1_START>s · no blockers — continuing to advisory aspects...
+```
+
+Record `T2_START` = current timestamp (seconds).
+
+Print `code-review-quality` output now.
+
+Record `T2_END` = current timestamp (seconds). Print timing line:
+
+```
+⏱ Tier 2 completed in <T2_END - T2_START>s
+```
+
+**Track state from agent outputs:**
+- `has_blocker` — `true` if any 🔴 found across all agent outputs
+- `has_advisory` — `true` if any 🟡 found across all agent outputs
+- `findings[]` — collect all findings from all agents; assign global sequential IDs (F:1, F:2, …) mapping from agent-local IDs (SEC:N, LOG:N, QUA:N). These global IDs are used **only** in Phase 7 file output (HTML comment markers) and Phase 8 copy menu — the live display above prints verbatim agent output with original IDs
+
+Print total timing:
+
+```
+⏱ Total review: <(T1_END - T1_START) + (T2_END - T2_START)>s (Tier 1: <T1_END - T1_START>s · Tier 2: <T2_END - T2_START>s)
+```
 
 ---
 
+## Phase 6: Verdict
+
+Determine verdict from tracked state:
+
+```
+has_blocker = true                              →  ❌ Changes Requested
+has_blocker = false AND has_advisory = true     →  ⚠️ Approved with Comments
+has_blocker = false AND has_advisory = false    →  ✅ Approved
+```
+
+Print the closing verdict (aspects were already printed progressively — do NOT re-list them):
+
+```markdown
+---
 ## Verdict: ❌ Changes Requested
 Fix all 🔴 Blocker findings before merging.
 
@@ -203,6 +362,11 @@ Fix all 🔴 Blocker findings before merging.
 > automated testing, and security scanning.
 ```
 
+Verdict line variants:
+- `❌ Changes Requested` → `Fix all 🔴 Blocker findings before merging.`
+- `⚠️ Approved with Comments` → `Address 🟡 advisory findings where practical.`
+- `✅ Approved` → `No blocking issues found.`
+
 ---
 
 ## Phase 7: File Output
@@ -216,6 +380,19 @@ Determine output path:
 
 Write the full verdict output to the file. Create intermediate directories as needed.
 
+When writing findings to the file, wrap each finding block with HTML comment markers so they can be extracted individually. Preserve the agent-local ID (e.g., `SEC:2`, `LOG:1`, `QUA:3`) in the heading so findings are searchable by ID:
+```
+<!-- F:1 -->
+### LOG:1 — 🔴 Correctness · `src/auth.ts:42`
+...finding content...
+
+<!-- F:2 -->
+### SEC:2 — 🟡 Security · `src/api.ts:15`
+...finding content...
+```
+
+The markers are hidden when rendered on GitHub/GitLab — safe to paste as-is.
+
 Display: `Review saved to <path>`
 
 Then output:
@@ -230,28 +407,75 @@ For full OWASP Top 10, PII audit, compliance gate, and tenant isolation — scop
 
 ---
 
-## Phase 8: Future Hook (TODO)
+## Phase 8: Interactive Finding Copy
+
+Only enter this phase if `findings[]` is non-empty.
+
+Display the findings menu:
 
 ```
-## TODO: VCS Integration
-Post review as PR/MR comment when platform integration is available.
+📋 Copy a finding to clipboard — paste directly into GitHub/GitLab:
 
-Planned endpoints:
-- GitHub: POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews
-- GitLab: POST /projects/{id}/merge_requests/{iid}/notes
+  [1] 🔴 Correctness · src/auth.ts:42
+  [2] 🟡 Security · src/api.ts:15
+  [3] 🟡 Code Quality · src/utils.ts:88
 
-For now: copy the review output and paste it as a PR comment manually.
+Enter number to copy, or Enter to skip:
 ```
 
----
+Wait for user input.
+
+**On a valid number N:**
+
+Run via Bash — extract finding block N from the saved file and copy to clipboard:
+
+```bash
+# Extract block between <!-- F:N --> and next <!-- F: --> marker (or EOF)
+# Windows
+awk '/<!-- F:N -->/{found=1;next} /<!-- F:[0-9]/{if(found)exit} found{print}' "<path>" | clip
 
-## Quick Reference
+# macOS
+awk '/<!-- F:N -->/{found=1;next} /<!-- F:[0-9]/{if(found)exit} found{print}' "<path>" | pbcopy
 
+# Linux
+awk '/<!-- F:N -->/{found=1;next} /<!-- F:[0-9]/{if(found)exit} found{print}' "<path>" | xclip -sel clip
 ```
-/hd-code-review                                    — review HEAD vs main
-/hd-code-review --source=feat/my-branch            — specific source branch
-/hd-code-review --target=develop                   — review against develop
-/hd-code-review "Add user auth feature"            — with plain-text task
-/hd-code-review https://linear.app/.../PROJ-123    — with Linear task URL
-/hd-code-review --source=feat/x -- src/auth/       — scope diff to path
+
+Replace `N` with the actual finding number. Use the platform detected during Phase 7.
+
+Display: `Finding [N] copied ✓ — paste into your PR comment`
+
+Then prompt again (loop until empty input).
+
+**On empty input / Enter:** Exit the loop silently.
+
+## Known Issues Suggestion Hook
+
+After the copy loop exits, scan all findings in the review for language indicating accepted or deferred debt:
+
+**Trigger signals** (in finding text, task description, or PR description):
+- "known issue", "known limitation", "we know", "already known"
+- "accepted", "acceptable for now", "accepted debt", "acknowledged"
+- "workaround", "temporary fix", "deferred", "won't fix", "can't fix now"
+- "TODO", "FIXME", "tech debt", "legacy"
+
+For each finding that **matches a trigger signal but has no existing KI entry** (i.e., not already annotated `[Known Issue: KI-NNN]`):
+
 ```
+> Finding [SEC:2] appears to be accepted/deferred debt ("workaround for legacy auth").
+> Add to docs/KNOWN_ISSUES.md as a known issue? (y/n)
+```
+
+On **yes**: append a new KI entry to `docs/KNOWN_ISSUES.md` with:
+- Auto-assigned next sequential ID (scan existing KI-NNN headings to determine next number)
+- Title from finding label
+- Scope from affected file
+- Reason left as `<fill in reason>` placeholder
+- Accepted by: `<fill in>`
+- Accepted on: today's date
+- Target fix: `<fill in>`
+
+Display: `KI-NNN added to docs/KNOWN_ISSUES.md — fill in Reason, Accepted by, and Target fix.`
+
+On **no**: skip silently. Only prompt once per matching finding.
+