llm-mock-server 1.0.1 → 1.0.2

package/.claude/skills/desloppify/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: desloppify
+description: >
+  Codebase health scanner and technical debt tracker. Use when the user asks
+  about code quality, technical debt, dead code, large files, god classes,
+  duplicate functions, code smells, naming issues, import cycles, or coupling
+  problems. Also use when asked for a health score, what to fix next, or to
+  create a cleanup plan. Supports 29 languages.
+allowed-tools: Bash(desloppify *)
+---
+
+<!-- desloppify-begin -->
+<!-- desloppify-skill-version: 5 -->
+
+# Desloppify
+
+## 1. Your Job
+
+Maximise the **strict score** honestly. Your main cycle: **scan → plan → execute → rescan**. Follow the scan output's **INSTRUCTIONS FOR AGENTS** — don't substitute your own analysis.
+
+**Don't be lazy.** Do large refactors and small detailed fixes with equal energy. If it takes touching 20 files, touch 20 files. If it's a one-line change, make it. No task is too big or too small — fix things properly, not minimally.
+
+## 2. The Workflow
+
+Three phases, repeated as a cycle.
+
+### Phase 1: Scan and review — understand the codebase
+
+```bash
+desloppify scan --path .       # analyse the codebase
+desloppify status              # check scores — are we at target?
+```
+
+The scan will tell you if subjective dimensions need review. Follow its instructions. To trigger a review manually:
+```bash
+desloppify review --prepare    # then follow your runner's review workflow
+```
+
+### Phase 2: Plan — decide what to work on
+
+After reviews, triage stages and plan creation appear in the execution queue surfaced by `next`. Complete them in order — `next` tells you what each stage expects in the `--report`:
+```bash
+desloppify next                                        # shows the next execution workflow step
+desloppify plan triage --stage observe --report "themes and root causes..."
+desloppify plan triage --stage reflect --report "comparison against completed work..."
+desloppify plan triage --stage organize --report "summary of priorities..."
+desloppify plan triage --complete --strategy "execution plan..."
+```
+
+For automated triage: `desloppify plan triage --run-stages --runner codex` (Codex) or `--runner claude` (Claude). Options: `--only-stages`, `--dry-run`, `--stage-timeout-seconds`.
+
+Then shape the queue. **The plan shapes everything `next` gives you** — `next` is the execution queue, not the full backlog. Don't skip this step.
+
+```bash
+desloppify plan                          # see the living plan details
+desloppify plan queue                    # compact execution queue view
+desloppify plan reorder <pat> top        # reorder — what unblocks the most?
+desloppify plan cluster create <name>    # group related issues to batch-fix
+desloppify plan focus <cluster>          # scope next to one cluster
+desloppify plan skip <pat>              # defer — hide from next
+```
+
+### Phase 3: Execute — grind the queue to completion
+
+Trust the plan and execute. Don't rescan mid-queue — finish the queue first.
+
+**Branch first.** Create a dedicated branch — never commit health work directly to main:
+```bash
+git checkout -b desloppify/code-health    # or desloppify/<focus-area>
+desloppify config set commit_pr 42        # link a PR for auto-updated descriptions
+```
+
+**The loop:**
+```bash
+# 1. Get the next item from the execution queue
+desloppify next
+
+# 2. Fix the issue in code
+
+# 3. Resolve it (next shows the exact command including required attestation)
+
+# 4. When you have a logical batch, commit and record
+git add <files> && git commit -m "desloppify: fix 3 deferred_import findings"
+desloppify plan commit-log record      # moves findings uncommitted → committed, updates PR
+
+# 5. Push periodically
+git push -u origin desloppify/code-health
+
+# 6. Repeat until the queue is empty
+```
+
+Score may temporarily drop after fixes — cascade effects are normal, keep going.
+If `next` suggests an auto-fixer, run `desloppify autofix <fixer> --dry-run` to preview, then apply.
+
+**When the queue is clear, go back to Phase 1.** New issues will surface, cascades will have resolved, priorities will have shifted. This is the cycle.
+
+## 3. Reference
+
+### Key concepts
+
+- **Tiers**: T1 auto-fix → T2 quick manual → T3 judgment call → T4 major refactor.
+- **Auto-clusters**: related findings are auto-grouped in `next`. Drill in with `next --cluster <name>`.
+- **Zones**: production/script (scored), test/config/generated/vendor (not scored). Fix with `zone set`.
+- **Wontfix cost**: widens the lenient↔strict gap. Challenge past decisions when the gap grows.
+
+### Scoring
+
+Overall score = **25% mechanical** + **75% subjective**.
+
+- **Mechanical (25%)**: auto-detected issues — duplication, dead code, smells, unused imports, security. Fixed by changing code and rescanning.
+- **Subjective (75%)**: design quality review — naming, error handling, abstractions, clarity. Starts at **0%** until reviewed. The scan will prompt you when a review is needed.
+- **Strict score** is the north star: wontfix items count as open. The gap between overall and strict is your wontfix debt.
+- **Score types**: overall (lenient), strict (wontfix counts), objective (mechanical only), verified (confirmed fixes only).
+
+### Reviews
+
+Four paths to get subjective scores:
+
+- **Local runner (Codex)**: `desloppify review --run-batches --runner codex --parallel --scan-after-import` — automated end-to-end.
+- **Local runner (Claude)**: `desloppify review --prepare` → launch parallel subagents → `desloppify review --import merged.json` — see skill doc overlay for details.
+- **Cloud/external**: `desloppify review --external-start --external-runner claude` → follow session template → `--external-submit`.
+- **Manual path**: `desloppify review --prepare` → review per dimension → `desloppify review --import file.json`.
+
+- Import first, fix after — import creates tracked state entries for correlation.
+- Target-matching scores trigger auto-reset to prevent gaming. Use the blind-review workflow described in your agent overlay doc (e.g. `docs/CLAUDE.md`, `docs/HERMES.md`).
+- Even moderate scores (60-80) dramatically improve overall health.
+- Stale dimensions auto-surface in `next` — just follow the queue.
+
+**Integrity rules:** Score from evidence only — no prior chat context, score history, or target-threshold anchoring. When evidence is mixed, score lower and explain uncertainty. Assess every requested dimension; never drop one.
+
+#### Review output format
+
+Return machine-readable JSON for review imports. For `--external-submit`, include `session` from the generated template:
+
+```json
+{
+  "session": {
+    "id": "<session_id_from_template>",
+    "token": "<session_token_from_template>"
+  },
+  "assessments": {
+    "<dimension_from_query>": 0
+  },
+  "findings": [
+    {
+      "dimension": "<dimension_from_query>",
+      "identifier": "short_id",
+      "summary": "one-line defect summary",
+      "related_files": ["relative/path/to/file.py"],
+      "evidence": ["specific code observation"],
+      "suggestion": "concrete fix recommendation",
+      "confidence": "high|medium|low"
+    }
+  ]
+}
+```
+
+`findings` MUST match `query.system_prompt` exactly (including `related_files`, `evidence`, and `suggestion`). Use `"findings": []` when no defects found. Import is fail-closed: invalid findings abort unless `--allow-partial` is passed. Assessment scores are auto-applied from trusted internal or cloud session imports. Legacy `--attested-external` remains supported.
+
+#### Import paths
+
+- Robust session flow (recommended): `desloppify review --external-start --external-runner claude` → use generated prompt/template → run printed `--external-submit` command.
+- Durable scored import (legacy): `desloppify review --import findings.json --attested-external --attest "I validated this review was completed without awareness of overall score and is unbiased."`
+- Findings-only fallback: `desloppify review --import findings.json`
+
+#### Reviewer agent prompt
+
+Runners that support agent definitions (Cursor, Copilot, Gemini) can create a dedicated reviewer agent. Use this system prompt:
+
+```
+You are a code quality reviewer. You will be given a codebase path, a set of
+dimensions to score, and what each dimension means. Read the code, score each
+dimension 0-100 from evidence only, and return JSON in the required format.
+Do not anchor to target thresholds. When evidence is mixed, score lower and
+explain uncertainty.
+```
+
+See your editor's overlay section below for the agent config format.
+
+### Plan commands
+
+```bash
+desloppify plan reorder <cluster> top       # move all cluster members at once
+desloppify plan reorder <a> <b> top        # mix clusters + findings in one reorder
+desloppify plan reorder <pat> before -t X  # position relative to another item/cluster
+desloppify plan cluster reorder a,b top    # reorder multiple clusters as one block
+desloppify plan resolve <pat>              # mark complete
+desloppify plan reopen <pat>               # reopen
+desloppify backlog                          # broader non-execution backlog
+```
+
+### Commit tracking
+
+```bash
+desloppify plan commit-log                      # see uncommitted + committed status
+desloppify plan commit-log record               # record HEAD commit, update PR description
+desloppify plan commit-log record --note "why"  # with rationale
+desloppify plan commit-log record --only "smells::*"  # record specific findings only
+desloppify plan commit-log history              # show commit records
+desloppify plan commit-log pr                   # preview PR body markdown
+desloppify config set commit_tracking_enabled false  # disable guidance
+```
+
+After resolving findings as `fixed`, the tool shows uncommitted work, committed history, and a suggested commit message. After committing externally, run `record` to move findings from uncommitted to committed and auto-update the linked PR description.
+
+### Quick reference
+
+```bash
+desloppify next --count 5                         # top 5 execution items
+desloppify next --cluster <name>                  # drill into a cluster
+desloppify backlog --count 5                      # top 5 backlog items outside execution
+desloppify show <pattern>                         # filter by file/detector/ID
+desloppify show --status open                     # all open findings
+desloppify plan skip --permanent "<id>" --note "reason" --attest "..." # accept debt
+desloppify exclude <path>                         # exclude a directory from scanning
+desloppify config show                            # show all config including excludes
+desloppify scan --path . --reset-subjective       # reset subjective baseline to 0
+```
+
+## 4. Fix Tool Issues Upstream
+
+When desloppify itself appears wrong or inconsistent — a bug, a bad detection, a crash, confusing output — **fix it and open a PR**. If you can't confidently fix it, file an issue instead.
+
+### Fix and PR (preferred)
+
+Clone the tool repo to a temp directory, make the fix there, and verify it works against the project you're scanning before pushing.
+
+```bash
+git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify-fix
+cd /tmp/desloppify-fix
+git checkout -b fix/<short-description>
+```
+
+Make your changes, then run the test suite and verify the fix against the original project:
+
+```bash
+python -m pytest desloppify/tests/ -q
+python -m desloppify scan --path <project-root>   # the project you were scanning
+```
+
+Once it looks good, push and open a PR:
+
+```bash
+git add <files> && git commit -m "fix: <what and why>"
+git push -u origin fix/<short-description>
+gh pr create --title "fix: <short description>" --body "$(cat <<'EOF'
+## Problem
+<what went wrong — include the command and output>
+
+## Fix
+<what you changed and why>
+EOF
+)"
+```
+
+Clean up after: `rm -rf /tmp/desloppify-fix`
+
+### File an issue (fallback)
+
+If the fix is unclear or the change needs discussion, open an issue at `https://github.com/peteromallet/desloppify/issues` with a minimal repro: command, path, expected output, actual output.
+
+## Prerequisite
+
+`command -v desloppify >/dev/null 2>&1 && echo "desloppify: installed" || echo "NOT INSTALLED — run: pip install --upgrade git+https://github.com/peteromallet/desloppify.git"`
+
+<!-- desloppify-end -->
+
+## Claude Code Overlay
+
+Use Claude subagents for subjective scoring work. **Do not use `--runner codex`** — use Claude subagents exclusively.
+
+### Review workflow
+
+Run `desloppify review --prepare` first to generate review data, then use Claude subagents:
+
+1. **Prepare**: `desloppify review --prepare` — writes `query.json` and `.desloppify/review_packet_blind.json`.
+2. **Launch subagents**: Split the review across N parallel Claude subagents (one message, multiple Task calls). Each agent reviews a subset of dimensions.
+3. **Merge & import**: Merge agent outputs, then `desloppify review --import merged.json --manual-override --attest "Claude subagents ran blind reviews against review_packet_blind.json" --scan-after-import`.
+
+#### How to split dimensions across subagents
+
+- Read `dimension_prompts` from `query.json` for dimensions with definitions and seed files.
+- Read `.desloppify/review_packet_blind.json` for the blind packet (no score targets, no anchoring data).
+- Group dimensions into 3-4 batches by theme (e.g., architecture, code quality, testing, conventions).
+- Launch one Task agent per batch with `subagent_type: "general-purpose"`. Each agent gets:
+  - The codebase path and list of dimensions to score
+  - The blind packet path to read
+  - Instruction to score from code evidence only, not from targets
+- Each agent writes output to a separate file. Merge assessments (average overlapping dimension scores) and concatenate findings.
+
+### Subagent rules
+
+1. Each agent must be context-isolated — do not pass conversation history or score targets.
+2. Agents must consume `.desloppify/review_packet_blind.json` (not full `query.json`) to avoid score anchoring.
+
+### Triage workflow
+
+Orchestrate triage with per-stage subagents:
+1. `desloppify plan triage --run-stages --runner claude` — prints orchestrator instructions
+2. For each stage (observe → reflect → organize → enrich):
+   - Get prompt: `desloppify plan triage --stage-prompt <stage>`
+   - Launch a subagent with that prompt
+   - Verify: `desloppify plan triage` (check dashboard)
+   - Confirm: `desloppify plan triage --confirm <stage> --attestation "..."`
+3. Complete: `desloppify plan triage --complete --strategy "..." --attestation "..."`
+
+<!-- desloppify-overlay: claude -->
+<!-- desloppify-end -->

package/.desloppify/external_review_sessions/ext_20260315_000339_a6cdc3e6/canonical_import_20260315_000801.json

@@ -0,0 +1,242 @@
+{
+  "assessments": {
+    "cross_module_architecture": 92.0,
+    "convention_outlier": 88.5,
+    "error_consistency": 84.0,
+    "abstraction_fitness": 93.0,
+    "api_surface_coherence": 86.0,
+    "authorization_consistency": 100.0,
+    "ai_generated_debt": 82.0,
+    "incomplete_migration": 97.0,
+    "package_organization": 93.0,
+    "high_level_elegance": 93.0,
+    "mid_level_elegance": 90.0,
+    "low_level_elegance": 87.0,
+    "design_coherence": 84.0
+  },
+  "findings": [
+    {
+      "dimension": "cross_module_architecture",
+      "identifier": "types_barrel_reexport_indirection",
+      "summary": "src/types.ts is a pure re-export barrel with 19 importers, adding an unnecessary indirection hop",
+      "related_files": [
+        "src/types.ts",
+        "src/types/request.ts",
+        "src/types/reply.ts",
+        "src/types/rule.ts"
+      ],
+      "evidence": [
+        "src/types.ts has 19 importers (highest in the codebase) and consists of exactly 3 re-export lines with zero logic or value-add",
+        "Both src/ modules and src/formats/ modules import from src/types.ts rather than from the actual definition files in src/types/",
+        "This creates a hub module that any type change routes through, inflating apparent coupling"
+      ],
+      "suggestion": "This is borderline since barrel exports are common in TypeScript libraries, but the dual-layer (src/types.ts re-exporting from src/types/*.ts, plus src/index.ts re-exporting again) adds navigational friction. Consider having internal modules import directly from src/types/request.ts, src/types/reply.ts, src/types/rule.ts and reserving src/types.ts only for the public API surface.",
+      "confidence": "low"
+    },
+    {
+      "dimension": "convention_outlier",
+      "identifier": "makeReq_helper_inconsistent_fields",
+      "summary": "Test helper makeReq() has inconsistent field sets across test files -- some include headers/path, others do not",
+      "related_files": [
+        "test/rule-engine.test.ts",
+        "test/history.test.ts",
+        "test/loader.test.ts"
+      ],
+      "evidence": [
+        "test/rule-engine.test.ts makeReq() omits headers and path fields entirely",
+        "test/history.test.ts and test/loader.test.ts makeReq() includes headers: {} and path: '/v1/chat/completions'",
+        "This means rule-engine tests create MockRequest objects that are structurally incomplete versus the interface defined in src/types/request.ts which has required headers and path fields"
+      ],
+      "suggestion": "Extract a shared test factory into a test/helpers/ module (e.g., test/helpers/make-req.ts) that always provides all required MockRequest fields. Import it in all test files to ensure consistency and prevent type drift.",
+      "confidence": "medium"
+    },
+    {
+      "dimension": "error_consistency",
+      "identifier": "resolver_error_swallowed_silently",
+      "summary": "When a resolver function throws, the error is logged but the server silently returns the fallback reply with 200 OK",
+      "related_files": [
+        "src/route-handler.ts"
+      ],
+      "evidence": [
+        "In resolveReply() at lines 34-37: catch (err) logs the error then returns the fallback reply with ruleDesc still set, giving no signal to the caller that something went wrong",
+        "The matched rule's remaining count was already decremented (line 95 in rule-engine.ts) before the resolver was called, so the rule is consumed even on failure",
+        "This means a resolver that intermittently throws will consume its match count, return a fallback, and give the test client no indication that the intended reply was not produced"
+      ],
+      "suggestion": "Consider making resolver errors more visible: either (a) propagate the error as an error reply (e.g., 500 status) so callers can detect it, or (b) at minimum, record the error in the history entry so test assertions can detect resolver failures. The current silent fallback makes debugging flaky test setups difficult.",
+      "confidence": "medium"
+    },
+    {
+      "dimension": "error_consistency",
+      "identifier": "cli_validators_mixed_sync_async",
+      "summary": "parseHost is async while all sibling validators (parsePort, parseLogLevel, parseChunkSize, parseLatency) are synchronous",
+      "related_files": [
+        "src/cli-validators.ts"
+      ],
+      "evidence": [
+        "parseHost performs DNS lookup via await lookup(value) making it the only async function among 5 sibling validators",
+        "The caller in cli.ts must use await for parseHost but not for the others, creating an asymmetric call pattern",
+        "The api_surface holistic_context explicitly flags src/cli-validators.ts as having a sync_async_mix"
+      ],
+      "suggestion": "This is inherent to the DNS lookup requirement, but document it explicitly with a JSDoc comment explaining why parseHost is async while siblings are sync. Alternatively, consider making all validators async for a uniform API, or doing the DNS check at server.start() time rather than at parse time.",
+      "confidence": "low"
+    },
+    {
+      "dimension": "ai_generated_debt",
+      "identifier": "type_files_high_comment_ratio",
+      "summary": "Type definition files have 35-38% comment ratio vs 5% codebase average -- JSDoc comments restate obvious field names",
+      "related_files": [
+        "src/types/reply.ts",
+        "src/types/request.ts",
+        "src/types/rule.ts"
+      ],
+      "evidence": [
+        "src/types/reply.ts: '/** Text content to send back. */' on a field named 'text' (line 9)",
+        "src/types/reply.ts: '/** Tool calls the model wants to make. */' on a field named 'tools' (line 13)",
+        "src/types/request.ts: '/** The last user message text. This is what most matchers check. */' -- first sentence restates the name, second adds genuine value (line 14)",
+        "src/types/rule.ts: '/** Human-readable description of what the rule matches. */' on a field named 'description' (line 63)",
+        "Codebase average comment ratio is 0.05 (5%), these files are at 0.35-0.38 (35-38%)"
+      ],
+      "suggestion": "Keep comments that add non-obvious context (like 'This is what most matchers check' or 'Falls back to { input: 10, output: 5 } if omitted') but remove comments that merely restate the type+name (e.g., '/** Text content to send back. */' on a field called text?: string). A good rule: if deleting the comment loses zero information beyond what the name+type already convey, delete it.",
+      "confidence": "medium"
+    },
+    {
+      "dimension": "ai_generated_debt",
+      "identifier": "logger_high_log_density",
+      "summary": "Logger class has a log density of 4.0 -- every method is a formatting wrapper around console with identical structure",
+      "related_files": [
+        "src/logger.ts"
+      ],
+      "evidence": [
+        "All four methods (error, warn, info, debug) follow an identical pattern: check threshold, destructure style, format with template literal, call console",
+        "The only variation between methods is which LEVEL_STYLE entry and which console method is used",
+        "This repetitive structure is a hallmark of AI-generated code where each method is written independently rather than factored"
+      ],
+      "suggestion": "Extract a private _log(level, consoleFn, msg, args) method that contains the shared threshold-check and formatting logic. Each public method becomes a one-liner delegating to _log with the appropriate level key and console method. This reduces the four near-identical 5-line methods to four 1-line methods plus one shared implementation.",
+      "confidence": "medium"
+    },
+    {
+      "dimension": "design_coherence",
+      "identifier": "openai_serialize_usage_duplication",
+      "summary": "Usage object construction is duplicated verbatim between serialize() and serializeComplete() in all three format serializers",
+      "related_files": [
+        "src/formats/openai/serialize.ts",
+        "src/formats/anthropic/serialize.ts",
+        "src/formats/responses/serialize.ts"
+      ],
+      "evidence": [
+        "OpenAI serialize.ts lines 41-47 and lines 80-86 construct identical prompt_tokens_details and completion_tokens_details objects",
+        "Anthropic serialize.ts lines 55 and 85 both construct { input_tokens: usage.input, output_tokens: usage.output }",
+        "Responses serialize.ts lines 98 and 123 both construct { input_tokens: usage.input, output_tokens: usage.output, total_tokens: usage.input + usage.output }",
+        "Each format repeats its usage construction logic in both the streaming and non-streaming serialization paths"
+      ],
+      "suggestion": "Extract format-specific usage builders into small helpers within each serializer file. For example in openai/serialize.ts, add a buildUsage(usage) function that returns the full usage object with details, then call it from both serialize() and serializeComplete(). This eliminates the duplicated object literals.",
+      "confidence": "high"
+    },
+    {
+      "dimension": "design_coherence",
+      "identifier": "replySequence_duplicated_in_loader_and_server",
+      "summary": "Sequence replay logic (index tracking, last-entry fallback, options mutation) is duplicated between MockServer.when().replySequence() and loader.ts addSequenceRule()",
+      "related_files": [
+        "src/mock-server.ts",
+        "src/loader.ts"
+      ],
+      "evidence": [
+        "mock-server.ts lines 107-121: replySequence creates a closure with index++, entries[index] ?? last, and mutates rule.options",
+        "loader.ts lines 102-129: addSequenceRule creates a nearly identical closure with index++, resolved[index] ?? lastStep, and mutates rule.options",
+        "Both implementations also set rule.remaining = entries.length"
+      ],
+      "suggestion": "Extract a createSequenceResolver(entries) function into a shared location (e.g., rule-engine.ts or a new sequence-helpers.ts) that returns { resolver, entryCount }. Both mock-server.ts replySequence() and loader.ts addSequenceRule() can call this shared function, eliminating the duplicated closure logic.",
+      "confidence": "high"
+    },
+    {
+      "dimension": "low_level_elegance",
+      "identifier": "cli_start_function_mixed_concerns",
+      "summary": "The cli.ts start() function mixes server setup, banner printing, file watching, and signal handling in a single 80-line function",
+      "related_files": [
+        "src/cli.ts"
+      ],
+      "evidence": [
+        "Lines 24-104: start() handles option parsing, server construction, rule/handler loading, fallback setup, banner printing, fs.watch setup with debouncing, and SIGINT/SIGTERM handlers",
+        "The file watch setup (lines 70-89) is nested inside start() with its own state (reloading flag, setTimeout)",
+        "Signal handlers (lines 91-103) are also wired inline"
+      ],
+      "suggestion": "Extract the file-watch setup into a watchRulesPath(server, rulesPath, fallback, logger) function, and the signal handling into a setupShutdown(server, logger) function. The start() function should read as a linear composition of setup steps rather than containing all the implementation details inline.",
+      "confidence": "medium"
+    },
+    {
+      "dimension": "low_level_elegance",
+      "identifier": "responses_serialize_deeply_nested_object_literals",
+      "summary": "responses/serialize.ts builds deeply nested inline object literals making the streaming event structure hard to read",
+      "related_files": [
+        "src/formats/responses/serialize.ts"
+      ],
+      "evidence": [
+        "Line 42-43: textStreamBlock constructs a 3-level deep inline object: { type: 'response.output_item.added', output_index: i, item: { type: 'message', id: itemId, status: 'in_progress', role: 'assistant', content: [] } }",
+        "Line 62: toolStreamBlock spreads an outputItem into a modified copy inline: { ...outputItem, status: 'in_progress', arguments: '' }",
+        "These long inline constructions make it difficult to scan the event structure at a glance"
+      ],
+      "suggestion": "Extract the repeated item shapes into named local variables or small builder functions. For example, const inProgressItem = { ...outputItem, status: 'in_progress', arguments: '' } on a separate line before passing it to c(). This improves scanability without adding abstraction overhead.",
+      "confidence": "low"
+    },
+    {
+      "dimension": "api_surface_coherence",
+      "identifier": "format_serialize_return_type_unknown",
+      "summary": "serializeComplete and serializeError return 'unknown' in the Format interface, losing type information at the boundary",
+      "related_files": [
+        "src/formats/types.ts",
+        "src/formats/openai/serialize.ts",
+        "src/formats/anthropic/serialize.ts",
+        "src/formats/responses/serialize.ts"
+      ],
+      "evidence": [
+        "Format interface line 15: serializeComplete returns 'unknown'",
+        "Format interface line 16: serializeError returns 'unknown'",
+        "Each concrete implementation also returns 'unknown' rather than a typed object",
+        "Callers in route-handler.ts pass the result directly to reply.send() without any type checking"
+      ],
+      "suggestion": "Since these are JSON response bodies sent to the client, at minimum type them as Record<string, unknown> or JsonValue. Ideally, use a generic Format<TComplete, TError> or define a union type covering the three format response shapes. This prevents accidental primitive returns and improves IDE support for callers.",
+      "confidence": "medium"
+    },
+    {
+      "dimension": "mid_level_elegance",
+      "identifier": "route_handler_history_records_before_streaming",
+      "summary": "History records the request before the streaming response is written, so history.count() may increment before the client has received any data",
+      "related_files": [
+        "src/route-handler.ts"
+      ],
+      "evidence": [
+        "Line 89: history.record(mockReq, ruleDesc) is called unconditionally before the streaming/non-streaming branch",
+        "Line 85: For error replies, history.record is called before returning the error response",
+        "If writeSSE (line 111) fails mid-stream, the history already recorded the request as handled"
+      ],
+      "suggestion": "This is a minor timing issue but worth acknowledging. Consider recording the history entry after the response is fully written (after writeSSE completes or after reply.send() returns). Alternatively, add a 'status' field to RecordedRequest indicating whether the response was successfully delivered.",
+      "confidence": "low"
+    },
+    {
+      "dimension": "convention_outlier",
+      "identifier": "parse_helpers_mixed_responsibility",
+      "summary": "parse-helpers.ts mixes request-building utilities (buildMockRequest) with serialization utilities (splitText, genId, toolId, finishReason, shouldEmitText)",
+      "related_files": [
+        "src/formats/parse-helpers.ts"
+      ],
+      "evidence": [
+        "buildMockRequest (line 53) is used only by parse.ts files for constructing MockRequest objects from incoming requests",
+        "splitText, genId, toolId, shouldEmitText, finishReason are used only by serialize.ts files for constructing outgoing responses",
+        "isStreaming (line 37) is used by both parsing (index.ts) and is a third concern (request detection)",
+        "The file has 11 importers across very different use contexts"
+      ],
+      "suggestion": "Split parse-helpers.ts into two files: serialize-helpers.ts (for splitText, genId, toolId, shouldEmitText, finishReason, DEFAULT_USAGE, MS_PER_SECOND) and request-helpers.ts (for buildMockRequest, isStreaming, RequestMeta). This aligns each file with a single direction of data flow.",
+      "confidence": "medium"
+    }
+  ],
+  "provenance": {
+    "kind": "blind_review_batch_import",
+    "blind": true,
+    "runner": "claude",
+    "run_stamp": "ext_20260315_000339_a6cdc3e6",
+    "created_at": "2026-03-15T00:08:01+00:00",
+    "packet_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/review_packet_blind.json",
+    "packet_sha256": "61563983650626757ab21c4b1e8ea4db0d723c4ce1fde659f2bbff0a59e56044",
+    "external_session_id": "ext_20260315_000339_a6cdc3e6"
+  }
+}