@simplysm/sd-claude 13.0.72 → 13.0.74

package/claude/skills/sd-readme/SKILL.md

@@ -7,73 +7,59 @@ model: sonnet
 
 # sd-readme
 
-Sync package README.md source index with current exports from `index.ts`.
+Sync package README.md with current source code by comparing exports against documentation.
 
 ## Purpose
 
-`@simplysm/*` packages ship `.ts` source and test files. Claude Code reads source files directly from `node_modules/` for API details (props, types, signatures, usage patterns).
+README.md is the **sole API documentation source for Claude Code**. When Claude Code works in a consumer app using `@simplysm/*` packages, it reads README.md from `node_modules/` to understand the library API. Claude Code does NOT read JSDoc from source files.
 
-**README.md is a source file index** — it tells Claude Code **which files to read**, not the API itself.
+**Therefore: every exported symbol must be documented in README.**
 
 ## Modes
 
 - **Single package** (`$ARGUMENTS` = package name or path): Update one package's README
 - **Batch** (`$ARGUMENTS` empty): Discover and update all packages in parallel
 
-## What Goes Where
+## README Writing Rules
 
-| In README | NOT in README (read from source) |
-|-----------|----------------------------------|
-| Package description (one-line) | Prop tables |
-| Installation + peer dependencies | Code examples |
-| Setup/configuration (Provider tree, Tailwind preset) | Type/interface definitions |
-| **Source index table** | API signatures |
-| License | Behavioral descriptions |
+- Written in **English**
+- All code examples must include **import paths**: `import { ... } from "@simplysm/..."`
+- **Every export** from `index.ts` must be documented — including those with `@internal` JSDoc
+- No changelog, version history, or "recently updated" sections
+- Section organization follows `index.ts` `#region` structure
+- Heading levels: `##` for major sections, `###` for sub-sections
 
-## README Structure
+### Standard Structure
 
 ```markdown
 # @simplysm/{package-name}
 
-{One-line description from package.json}
+{One-line description}
 
 ## Installation
 
-pnpm add @simplysm/{package-name}
-
-**Peer Dependencies:** (if any)
+## Main Modules
 
-## Configuration
+### {Category matching index.ts #region}
 
-{Only for setup patterns — Provider wrapping, Tailwind preset, etc.}
-{Include brief code snippets for wiring, NOT per-component API}
+- Description + code examples per export
 
-## Source Index
+## Types
 
-### {Category matching index.ts #region}
+## Dependencies (only when peer deps exist)
+```
 
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/path/to/File.tsx` | `ComponentA`, `ComponentB` | Brief one-line description | `File.test.tsx` |
-| `src/path/to/types.ts` | `TypeA`, `TypeB` | Type definitions for X | - |
+### docs/ Subfolder Rules
 
-## License
-```
+When README exceeds ~500 lines, split detailed documentation into `docs/`:
 
-**Source index table rules:**
-- One row per `export *` statement in `index.ts`
-- Exports column: list all exported symbols from that file
-- Description column: brief one-line summary of what the file provides (enough for Claude Code to decide whether to read the source)
-- Test column: test file name if exists, `-` if not
-- Source paths relative to package root
+- README.md becomes an **overview/index** with links: `[functionName](docs/category.md#anchor)`
+- docs/ files contain detailed descriptions, full code examples, parameter tables
+- File organization follows index.ts `#region` (e.g., `docs/types.md`, `docs/utils.md`)
 
-## General Rules
+When README is under ~500 lines, keep everything inline.
 
-- Written in **English**
-- Sections follow `index.ts` `#region` structure
-- **Every `export *`** from `index.ts` must appear in source index
-- No changelog, version history, or "recently updated" sections
-- Configuration section: only setup/wiring patterns, NOT per-component API
+**If docs/ already exists, maintain and update it. Do not remove an existing docs/ structure.**
 
 ## Single Package Mode
 
@@ -84,66 +70,62 @@ If not starting with `packages/`, prepend it.
 
 ### Step 2: Build Export Map (Source of Truth)
 
-1. Read `<pkg-path>/src/index.ts` — get all `export *` statements and their `#region` grouping
-2. For each `export * from "./path/to/file"`:
-   - Resolve actual file path (`.ts`, `.tsx`)
-   - Read file to extract exported symbol names
-   - Write a brief one-line description of what the file provides
-   - Check if test file exists (e.g., `File.test.tsx`, `File.spec.ts`)
+1. Read `<pkg-path>/src/index.ts` — get all exports and their `#region` grouping
+2. For each exported module, read the source file to extract:
+   - Function signatures (params, return type, overloads)
+   - Class public API (constructor, methods, properties)
+   - Type/interface definitions
+   - Default values, options objects
 
-### Step 3: Build Index Map
+### Step 3: Build Documentation Map
 
-Read `<pkg-path>/README.md` (if exists).
-Extract existing source index table entries — map each source file to its row.
+Read `<pkg-path>/README.md` (if exists). If docs/ exists, read those files too.
+Map each documented item to its current documentation content.
 
 ### Step 4: Diff and Report
 
-Compare export map (Step 2) against index map (Step 3):
+Compare export map (Step 2) against documentation map (Step 3):
 
-| Status | Meaning |
-|--------|---------|
-| **ADDED** | `export *` in index.ts but source file not in README index |
-| **REMOVED** | In README index but no longer in index.ts |
-| **CHANGED** | Same file, but exported symbols changed |
-| **OK** | Index entry matches source |
+| Status      | Meaning                              |
+| ----------- | ------------------------------------ |
+| **ADDED**   | Exported in source but not in README |
+| **REMOVED** | In README but no longer exported     |
+| **CHANGED** | Both exist but API signature differs |
+| **OK**      | Documentation matches source         |
 
 **Report to user before editing:**
 
 ```
-ADDED (2):
-  - src/providers/i18n/I18nContext.tsx (useI18n, useI18nOptional, I18nProvider)
-  - src/providers/i18n/I18nContext.types.ts (I18nContextValue, I18nConfigureOptions, FlatDict)
+ADDED (3):
+  - strToCamelCase (from utils/str.ts)
+  - objGetChainValueByDepth (from utils/obj.ts)
+  - ZipArchiveProgress type (from zip/sd-zip.ts)
 
 REMOVED (1):
-  - src/components/SelectList.tsx (no longer exported)
+  - oldFunction (no longer exported)
 
-CHANGED (1):
-  - src/features/shared-data/SharedDataSelectList.tsx: exports changed
+CHANGED (2):
+  - objMerge: added `deep` parameter
+  - Set.toggle: added `addOrDel` optional parameter
 
-OK: 42 entries unchanged
+OK: 45 items unchanged
 ```
 
 **Wait for user confirmation before proceeding to edit.**
 
 ### Step 5: Apply Updates
 
-- **ADDED**: Add row to source index table in the section matching the item's `#region` in index.ts.
-- **REMOVED**: Delete row from source index table.
-- **CHANGED**: Update exports column.
+- **ADDED**: Write documentation matching existing style. Place in the section matching the item's `#region` in index.ts. Include description + code example with import path.
+- **REMOVED**: Delete the documentation entry.
+- **CHANGED**: Update existing entry to match current API. Preserve code examples if still valid.
 - **OK**: Do not touch.
 
-### Step 6: Cleanup Check
+**If README uses docs/ links**: update the corresponding docs/ file, not just README.
 
-If `docs/` subfolder exists from old full-documentation approach, report it:
-
-```
-NOTE: docs/ subfolder exists with old-style full documentation.
-  Source index approach makes docs/ redundant.
-  Files: docs/form-controls.md, docs/providers.md, ...
-  Remove docs/ folder? (requires user confirmation)
-```
+### Step 6: Size Check
 
-**Do not auto-delete docs/ — always ask user first.**
+After updates, if README exceeds ~500 lines and no docs/ exists:
+suggest splitting to the user (do not auto-split without confirmation).
 
 ## Batch Mode
 
@@ -155,33 +137,31 @@ When `$ARGUMENTS` is empty:
 **Per-package subagent prompt template:**
 
 ```
-Update README.md source index for package {pkg-name} at {pkg-path}.
+Update README.md for package {pkg-name} at {pkg-path}.
 
-PURPOSE: README.md is a source file index. @simplysm/* packages ship .ts source + tests.
-Claude Code reads source files directly. README tells Claude WHICH files to read.
+PURPOSE: README.md is the sole API documentation source for Claude Code.
+Every exported symbol must be documented. Claude Code does NOT read JSDoc.
 
 STEPS:
-1. Read {pkg-path}/src/index.ts — get all `export *` statements and #region grouping.
-2. For each export, resolve source file path and find test file.
-3. Read each source file to extract exported symbol names.
-4. Read {pkg-path}/README.md (if exists).
-5. Compare exports vs README source index:
-   - ADDED: add row to source index table.
-   - REMOVED: delete row.
-   - CHANGED: update exports/description column.
+1. Read {pkg-path}/src/index.ts — get all exports and #region grouping.
+2. For each export, read the source file for signatures, classes, types.
+3. Read {pkg-path}/README.md (and docs/ if exists).
+4. Compare exports vs documentation:
+   - ADDED (in source, not in README): add documentation with description + code example.
+     Include import path: import { X } from "@simplysm/{pkg-name}"
+   - REMOVED (in README, not in source): delete documentation.
+   - CHANGED (both exist, API differs): update to match current API.
    - OK: don't touch.
-6. Section organization follows index.ts #region structure.
-7. Write in English. No changelog sections.
-8. If README doesn't exist, create with structure:
+5. Section organization follows index.ts #region structure.
+6. Write in English. No changelog sections.
+7. If README doesn't exist, create with standard structure:
    # @simplysm/{pkg-name}
    {description from package.json}
    ## Installation
-   ## Source Index (tables per #region)
-   ## License
-9. Do NOT write prop tables, code examples, or type definitions.
-   Source index table only: Source | Exports | Description | Test
-   Description: brief one-line summary of what the file provides.
-10. Report: list of ADDED/REMOVED/CHANGED items.
+   ## Main Modules (sections per #region)
+   ## Types
+8. If docs/ subfolder exists, update those files too.
+9. Report: list of ADDED/REMOVED/CHANGED items.
 ```
 
 **Project root subagent prompt:**
@@ -198,14 +178,14 @@ Report what was changed.
 
 ## Common Mistakes
 
-| Mistake | Fix |
-|---------|-----|
-| Writing prop tables or code examples | README is a source index — Claude reads source files for API details |
-| Missing or vague Description | Each row needs a brief description so Claude can decide whether to read the file |
-| Skipping exports from index.ts | Every `export *` must appear in the source index |
-| Putting per-component API in Configuration | Configuration = setup patterns only (Provider tree, Tailwind preset) |
-| Arbitrary section reorganization | Follow index.ts `#region` structure |
-| Writing in Korean | README must be in English |
-| Adding changelog sections | Never add version history |
-| Editing before reporting diff | Always report and wait for confirmation |
-| Auto-deleting docs/ folder | Report docs/ existence, ask user before removing |
+| Mistake                               | Fix                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------- |
+| Skipping exports with @internal JSDoc | Document ALL exports — Claude Code doesn't read JSDoc               |
+| Rewriting OK sections                 | Only touch ADDED/REMOVED/CHANGED items                              |
+| Ignoring existing docs/ structure     | If docs/ exists, update those files too                             |
+| Arbitrary section reorganization      | Follow index.ts `#region` structure                                 |
+| Missing import paths in examples      | Always: `import { X } from "@simplysm/..."`                         |
+| Writing in Korean                     | README must be in English                                           |
+| Adding changelog sections             | Never add version history                                           |
+| Editing before reporting diff         | Always report ADDED/REMOVED/CHANGED and wait for confirmation       |
+| Destroying docs/ link format          | If README uses `[name](docs/file.md#anchor)`, preserve that pattern |

package/claude/skills/sd-review/SKILL.md

@@ -9,104 +9,100 @@ description: "Comprehensive multi-perspective code review (explicit invocation o
 
 Perform a multi-perspective code review of a package or specified path, producing a comprehensive report. **Analysis only — no code modifications.**
 
-Analyzes code via the built-in Explore agent, then runs up to 4 subagents in parallel for specialized review. Collects subagent results, verifies each finding against actual code, and writes the final report.
+Dispatches up to 3 reviewer agents in parallel using prompt templates. Each agent independently explores the codebase from its own perspective. Collects results, verifies findings against actual code, and compiles the final report.
 
 ## Usage
 
-- `/sd-review packages/solid` — review source code at the given path
+- `/sd-review packages/solid` — full review (all 3 perspectives)
+- `/sd-review packages/solid focus on bugs` — selective review based on request
 - `/sd-review` — if no argument, ask the user for the target path
 
-## When to Use
-
-- Before merging major features or after significant refactoring
-- When assessing overall code quality of a package
-- When onboarding to unfamiliar code and want a quality overview
-
-**When NOT to use:**
-
-- Single-file or trivial changes (typo, config tweak)
-- When you need code modifications (sd-review is analysis-only)
-
 ## Target Selection
 
-- With argument: `/sd-review packages/solid` — review source code at the given path
+- With argument: review source code at the given path
 - Without argument: ask the user for the target path
 
 **Important:** Review ALL source files under the target path. Do not use git status or git diff to limit scope.
 
-## Reviewer Agents
+## Reviewer Perspectives
 
-Run subagents in parallel via the Task tool:
+| Reviewer | Prompt Template | Perspective |
+|----------|----------------|-------------|
+| **Code Reviewer** | `code-reviewer-prompt.md` | Correctness & Safety — bugs, security, logic errors |
+| **API Reviewer** | `api-reviewer-prompt.md` | Usability & DX — naming, types, consistency |
+| **Code Simplifier** | `code-simplifier-prompt.md` | Maintainability — complexity, duplication, structure |
 
-| Agent Type             | Role                                                | Condition                                                  |
-| ---------------------- | --------------------------------------------------- | ---------------------------------------------------------- |
-| `sd-code-reviewer`     | Bugs, security, logic errors, convention issues     | Always                                                     |
-| `sd-code-simplifier`   | Complexity, duplication, readability issues         | Always                                                     |
-| `sd-api-reviewer`      | DX/usability, naming, type hints                    | Always                                                     |
-| `sd-security-reviewer` | ORM SQL injection, input validation vulnerabilities | When target path contains ORM queries or service endpoints |
+## Reviewer Selection
 
-## Workflow
+By default, run **all 3 reviewers**. If the user specifies a focus in natural language, select only the relevant reviewer(s):
 
-### Step 1: Code Analysis via Explore Agent
+| User says | Run |
+|-----------|-----|
+| "bugs", "security", "safety" | Code Reviewer only |
+| "API", "naming", "types", "DX" | API Reviewer only |
+| "complexity", "duplication", "structure", "maintainability" | Code Simplifier only |
+| "bugs and API" | Code Reviewer + API Reviewer |
+| (no specific focus) | All 3 |
 
-Invoke the built-in Explore agent via the Task tool to analyze the target path:
+Use judgment for ambiguous requests. When in doubt, run all 3.
 
-```
-Task(subagent_type=Explore)
-Prompt: "very thorough" analysis of <target-path>:
-- Entry points, core files, module boundaries
-- Call chains, data transformations, state changes
-- Abstraction layers, design patterns, dependency graph
-- Error handling, public API surface
-```
+## Workflow
 
-This runs in a **separate context**, so it does not consume the main context window.
+### Step 1: Dispatch Reviewers
 
-### Step 2: Dispatch Analysis to Reviewers
+Read the prompt template files from this skill's directory. Replace `[TARGET_PATH]` with the actual target path. Then dispatch using `Agent(general-purpose)`:
 
-Run subagents **in parallel** via the Task tool. Include the Explore analysis results in each subagent's prompt:
+```
+Agent(subagent_type=general-purpose, prompt=<filled template>)
+```
 
-- **sd-code-reviewer**: Based on the analysis, find bugs, security vulnerabilities, logic errors, and convention issues. Each finding must include **file:line** and **evidence**.
-- **sd-code-simplifier**: Based on the analysis, find unnecessary complexity, code duplication, and readability issues. Each finding must include **file:line** and **evidence**. **No code modifications.**
-- **sd-api-reviewer**: Based on the analysis, review API intuitiveness, naming consistency, type hints, error messages, and configuration complexity. Each finding must include **file:line** and **evidence**.
-- **sd-security-reviewer** _(conditional)_: If the Explore analysis reveals ORM queries (`orm-common`, `orm-node`, query builders, `expr.eq`, `.where()`, `.result()`) or service endpoints (`ServiceServer`, RPC handlers), also dispatch this agent. Based on the analysis, find SQL injection risks, missing input validation, and unvalidated user input reaching ORM queries. Each finding must include **file:line** and **evidence**.
+Run selected reviewers **in parallel** (multiple Agent calls in a single message).
 
-### Step 3: Verify Issues
+### Step 2: Verify Findings
 
-After collecting results from all 3 subagents, verify each issue against the actual code:
+After collecting results from all reviewers, **Read the actual code** for each finding and verify:
 
-- **Valid**: the issue is real → include in the report
+- **Valid**: the issue is real AND within scope → include in the report
+- **Invalid — self-contradicted**: the reviewer's own analysis shows the issue is mitigated (e.g., "exploitability is limited because..."). Drop it.
+- **Invalid — type-only**: reports a type definition as a runtime issue without showing actual runtime code that triggers it. Drop it.
+- **Invalid — out of scope**: the issue is about code outside the target path (e.g., how other packages use this code). Drop it.
+- **Invalid — duplicate**: another reviewer already reported the same issue. Keep only the one from the correct domain (bugs→Code, API→API, structure→Simplifier).
+- **Invalid — bikeshedding**: minor style preference on stable, well-commented code (magic numbers with clear comments, small interface field duplication, naming when used consistently). Drop it.
+- **Invalid — severity inflated**: downgrade or drop findings where the stated severity doesn't match the actual impact.
 - **Invalid — already handled**: handled elsewhere in the codebase (provide evidence)
 - **Invalid — intentional pattern**: by-design architectural decision
 - **Invalid — misread**: the reviewer misinterpreted the code
 
-### Step 4: Final Report
+### Step 3: Final Report
 
-Compile only **verified findings** into a comprehensive report.
+Compile only **verified findings** grouped by severity (not by reviewer):
 
-### Report Structure
+```
+## Review Report: <target-path>
 
-| Section                          | Priority | Source                                                          |
-| -------------------------------- | -------- | --------------------------------------------------------------- |
-| **Architecture Summary**         | —        | Explore analysis                                                |
-| **Critical Issues**              | P0       | Bugs, security vulnerabilities                                  |
-| **Security Issues**              | P0       | SQL injection, input validation (when sd-security-reviewer ran) |
-| **Quality Issues**               | P1       | Logic errors, missing error handling, performance               |
-| **DX/Usability Issues**          | P2       | API intuitiveness, naming, type hints                           |
-| **Simplification Opportunities** | P3       | Complexity removal, duplicate code, abstractions                |
-| **Convention Issues**            | P4       | Project convention mismatches                                   |
+### CRITICAL
+[verified critical findings from all reviewers]
 
-Each issue includes **file:line**, **description**, and **suggestion**.
+### WARNING
+[verified warning findings from all reviewers]
+
+### INFO
+[verified info findings from all reviewers]
+
+### Invalid Findings Summary (optional)
+[findings filtered out and why]
+```
 
-Optionally include an **Invalid Findings Summary** appendix showing which findings were filtered out and why.
+Each finding includes: **source reviewer**, **file:line**, **evidence**, **issue**, and **suggestion**.
 
 ## Common Mistakes
 
-| Mistake                              | Fix                                                 |
-| ------------------------------------ | --------------------------------------------------- |
-| Using git diff to limit review scope | Review ALL source files under target path           |
-| Skipping verification step           | Always verify subagent findings against actual code |
-| Reporting unverified issues          | Only include verified findings in final report      |
+| Mistake | Fix |
+|---------|-----|
+| Using git diff to limit review scope | Review ALL source files under target path |
+| Skipping verification step | Always verify reviewer findings against actual code |
+| Reporting unverified issues | Only include verified findings in final report |
+| Running all reviewers for focused requests | Match reviewer selection to user's request |
 
 ## Completion Criteria
 

package/claude/skills/sd-review/api-reviewer-prompt.md

@@ -0,0 +1,90 @@
+# API Reviewer Prompt
+
+Template for `Agent(general-purpose)`. Fill in `[TARGET_PATH]`.
+
+```
+You are reviewing a library's public API for developer experience (DX).
+Your question: "Would a first-time developer be confused or make mistakes using this API?"
+
+## Target
+
+Review ALL source files at [TARGET_PATH].
+
+## Step 1: List all source files
+
+Use Glob to list all .ts files under the target path (exclude node_modules, dist).
+
+## Step 2: Map the public API surface
+
+- Read index.ts to list all exports (types, functions, constants)
+- Read each exported type/interface/function definition
+- Read test files and consumer code to see actual usage patterns
+
+## Step 3: Find issues
+
+Look for:
+- Naming consistency: same concept with different names, inconsistent prefix/suffix
+- Intuitiveness: behavior can't be predicted from the name alone
+- Type design: insufficient types for autocompletion, `any` in public interfaces, generic inference failures
+- Defaults: basic use cases requiring excessive configuration
+- Pattern consistency: similar tasks requiring different patterns
+
+Important: Internal consistency takes priority over external standards.
+Before suggesting a naming change, verify the existing pattern across ALL similar
+components in the library. Do NOT suggest external conventions that break internal consistency.
+
+Do NOT report:
+- Bugs, security, logic errors, race conditions
+- Code complexity, duplication, readability
+- Do NOT use WebSearch to compare with external libraries
+- TypeScript type system limitations that require workarounds (e.g., discriminated unions not narrowing due to template literals) — these are language constraints, not API design flaws
+- Naming preferences where the current name is used consistently across the codebase — consistency > personal preference
+- Minor field duplication in small interfaces (< 10 fields) where extraction adds indirection without real benefit
+
+## Step 4: Self-verify before reporting
+
+Before including ANY finding, verify:
+
+1. **Severity check**: CRITICAL = developers WILL write wrong code because of this API. Not "could theoretically be confusing."
+2. **Consistency check**: Before suggesting a rename, search ALL usages. If the name is used consistently everywhere, it's NOT a finding.
+3. **Scope check**: Only report on the PUBLIC API of the target package. Do not report on how consumers should use it differently.
+
+**Quality over quantity: 3 verified findings > 10 maybe-findings.**
+
+## Constraints
+
+- Analysis only. Do NOT modify any files.
+- Only report issues with real evidence from the code.
+- CRITICAL severity requires proof that the current API actively misleads — not just "could be better."
+
+## Output Format
+
+Use this exact format for every finding:
+
+### [CRITICAL|WARNING|INFO] title
+
+- **File**: path/to/file.ts:42
+- **Evidence**: what you observed (include code snippet)
+- **Issue**: what the problem is
+- **Suggestion**: how to improve it
+
+Severity:
+- CRITICAL: API misleads developers or types are insufficient for correct usage
+- WARNING: Significant DX friction — unnecessary complexity or inconsistency
+- INFO: Minor improvement — better naming or defaults exist
+
+Start your report with:
+
+## API Review Results
+
+### Summary
+- Files reviewed: N
+- Public API surface: brief description
+- Findings: X CRITICAL, Y WARNING, Z INFO
+
+### Findings
+[findings here]
+
+### Positive Observations
+[what's already well-designed — keep these]
+```

package/claude/skills/sd-review/code-reviewer-prompt.md

@@ -0,0 +1,85 @@
+# Code Reviewer Prompt
+
+Template for `Agent(general-purpose)`. Fill in `[TARGET_PATH]`.
+
+```
+You are reviewing code for correctness and safety.
+Your question: "Does this code produce wrong results or pose risks?"
+
+## Target
+
+Review ALL source files at [TARGET_PATH].
+
+## Step 1: List all source files
+
+Use Glob to list all .ts files under the target path (exclude node_modules, dist).
+This is your review scope — every file in this list must be examined.
+
+## Step 2: Understand the codebase
+
+Read the project's CLAUDE.md for conventions. Then:
+- Read index.ts to map the module structure
+- Read each source file to understand logic flows, data transformations, error paths
+
+## Step 3: Find issues
+
+Look for:
+- Bugs: null/undefined risks, off-by-one, wrong conditions, missing return values
+- Security: injection, XSS, auth/authz gaps, sensitive data exposure, input validation
+- Race conditions: async ordering, shared state without synchronization
+- Resource leaks: uncleared subscriptions/listeners, unclosed handles
+- Error handling: swallowed exceptions, wrong fallbacks, missing propagation
+
+Do NOT report:
+- Naming consistency, API design, type quality (including `any` types)
+- Code complexity, duplication, readability improvements
+- Style preferences unless they cause actual bugs
+- Type definitions alone — a type allowing `stack?: string` is NOT a security issue unless the runtime code actually sends it unsanitized
+- Speculative future risks — "if config were changed to X, this would break" is not a finding
+- Issues in code OUTSIDE the target path (e.g., how other packages consume these types)
+
+## Step 4: Self-verify before reporting
+
+Before including ANY finding, ask yourself:
+
+1. **Is there runtime code here that actually triggers this?** (Not just a type definition)
+2. **Does the evidence contradict my conclusion?** (If you find a bound/limit that prevents the issue, drop it)
+3. **Is this within the target scope?** (Not about how other packages use this code)
+
+If you write "in practice this is unlikely because..." or "exploitability is limited because..." — that means it's NOT a real finding. Drop it.
+
+**Quality over quantity: 3 verified findings > 10 maybe-findings.**
+
+## Constraints
+
+- Analysis only. Do NOT modify any files.
+- Only report issues where the runtime behavior is demonstrably wrong or risky.
+- If your own analysis shows the issue is mitigated, do NOT report it.
+
+## Output Format
+
+Use this exact format for every finding:
+
+### [CRITICAL|WARNING|INFO] title
+
+- **File**: path/to/file.ts:42
+- **Evidence**: what you observed (include code snippet)
+- **Issue**: what the problem is
+- **Suggestion**: how to fix it
+
+Severity:
+- CRITICAL: Will cause bugs, outages, or security breaches
+- WARNING: Real problem that can occur in practice
+- INFO: Defensive improvement, low risk
+
+Start your report with:
+
+## Code Review Results
+
+### Summary
+- Files reviewed: N
+- Findings: X CRITICAL, Y WARNING, Z INFO
+
+### Findings
+[findings here]
+```