@softspark/ai-toolkit 2.6.1 → 2.7.0

package/app/skills/mcp-builder/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: mcp-builder
+description: "Build production-grade MCP (Model Context Protocol) servers from scratch using the 4-phase methodology: research, implement, test, evaluate. Use when creating new MCP integrations for external APIs, databases, or internal services."
+effort: high
+disable-model-invocation: true
+argument-hint: "[service name or API description]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# MCP Builder
+
+$ARGUMENTS
+
+Build a production-grade MCP server following Anthropic's 4-phase methodology.
+
+## When to Use
+
+- Wrapping a third-party REST API as MCP tools
+- Exposing an internal database or service to Claude
+- Creating reusable integrations for the team
+- Migrating a custom tool into the MCP ecosystem
+
+For MCP protocol theory, see `mcp-patterns` knowledge skill (auto-loaded).
+
+## 4-Phase Workflow
+
+### Phase 1 — Research & Planning
+
+1. Read the target API's documentation (OpenAPI spec, README, changelog).
+2. Identify the 5-15 most useful operations. Prefer workflow-oriented tools over 1:1 API mirror.
+3. Decide transport: `stdio` for local dev tools, `streamable-http` for remote/shared.
+4. Decide language: **TypeScript recommended** (best SDK), Python acceptable (`mcp` package).
+5. List required secrets (API keys, tokens) and their env var names.
+
+Output: `PLAN.md` with tool list, transport choice, auth model.
+
+### Phase 2 — Implementation
+
+Scaffold:
+```
+my-mcp/
+├── package.json         # or pyproject.toml
+├── src/
+│   ├── server.ts        # entry point
+│   ├── client.ts        # API client (axios/httpx)
+│   ├── tools/           # one file per tool
+│   ├── schemas.ts       # Zod/Pydantic schemas
+│   └── errors.ts        # typed errors
+├── .env.example
+└── README.md
+```
+
+Per tool:
+- Input/output schemas (Zod for TS, Pydantic for Python)
+- Clear `name` with service prefix (e.g. `github_create_issue`)
+- Description starts with a verb, mentions trigger keywords
+- Annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`
+- Pagination support via `cursor` or `page` parameters
+- Focused responses — filter noise, don't dump raw API payloads
+
+### Phase 3 — Review & Testing
+
+- TypeScript: `npm run typecheck && npm run lint && npm test`
+- Python: `ruff check . && mypy --strict src/ && pytest`
+- MCP Inspector dry-run:
+  ```bash
+  npx @modelcontextprotocol/inspector node dist/server.js
+  ```
+- Verify each tool's schema validates a real request and rejects malformed input.
+
+### Phase 4 — Evaluation
+
+Write 10 realistic end-user questions that an LLM should be able to answer using your server. Run them through Claude with the server attached. Grade: did the model call the right tool? Did the response give enough to answer? Fix the description, schema, or response format of any tool that failed.
+
+Example eval questions for a `github-mcp`:
+1. "What issues are open on repo X with label `bug`?"
+2. "Create an issue titled Y in repo Z"
+3. "Who has the most commits this month in repo X?"
+
+## Tool Design Checklist
+
+- [ ] Name has service prefix and is verb-led
+- [ ] Description mentions when to use it and includes trigger keywords
+- [ ] Input schema is strict, no free-form `object` with `additionalProperties: true`
+- [ ] Output is focused — essential fields only, with pagination cursor if applicable
+- [ ] Error responses are actionable ("API returned 403 — check `GITHUB_TOKEN` env var")
+- [ ] Annotations set correctly (readonly/destructive/idempotent)
+- [ ] No secrets logged or echoed in errors
+- [ ] Rate limiting respects the upstream API
+
+## Transport Cheat Sheet
+
+| Scenario | Transport |
+|----------|-----------|
+| Local dev tool, 1 user | `stdio` |
+| Remote server, multiple users | `streamable-http` with SSE |
+| Internal company tool, auth required | `streamable-http` + OAuth proxy |
+| Embedded in IDE/editor | `stdio` spawned by editor |
+
+## Registration Cheat Sheet
+
+Local Claude Code (`.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "my-mcp": {
+      "command": "node",
+      "args": ["dist/server.js"],
+      "env": { "API_KEY": "$MY_API_KEY" }
+    }
+  }
+}
+```
+
+Global Claude Code (user-scope):
+```bash
+claude mcp add my-mcp --scope user -- node /path/to/server.js
+```
+
+Claude Desktop: same JSON, placed in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS).
+
+## Common Pitfalls
+
+| Mistake | Fix |
+|---------|-----|
+| 1:1 API mirror with 80 tools | Pick 10 workflow-oriented tools |
+| `description: "wrapper for /users endpoint"` | `description: "Find users by email, role, or team. Use when the user mentions employees, staff, or access"` |
+| Dumping raw JSON responses | Filter to 3-5 fields the agent actually needs |
+| Logging API keys on error | Redact all env vars in error formatters |
+| `exit 1` on transient errors | Retry with exponential backoff, surface final error |
+| Stdout pollution (MCP stdio) | All logs go to **stderr**, stdout is JSON-RPC only |
+
+## Related
+
+- `mcp-patterns` — protocol reference (auto-loaded knowledge skill)
+- `mcp-specialist` agent — for deep MCP design questions
+- `mcp-testing-engineer` agent — for protocol conformance testing
+- https://modelcontextprotocol.io/
+- https://github.com/anthropics/skills/tree/main/skills/mcp-builder

package/app/skills/model-routing-patterns/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: model-routing-patterns
+description: "Loaded when user builds multi-model pipelines (Haiku/Sonnet/Opus). Covers cost-optimized routing, escalation, sub-agent delegation, and fallback chains."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Model Routing Patterns
+
+Three Claude tiers. Using Opus for everything is 10-40x more expensive than it needs to be. Using Haiku for everything loses accuracy on hard tasks. The craft is routing.
+
+## Model Characteristics (2026)
+
+| Model | Latency | Cost (rel.) | Strengths | When |
+|-------|---------|-------------|-----------|------|
+| Haiku 4.5 | Fastest | 1x | Classification, extraction, simple tools, moderation | Bulk processing, triage, labels |
+| Sonnet 4.6 | Medium | 3-5x | General coding, reasoning, most agent tasks | Default workhorse |
+| Opus 4.7 | Slowest | 15-30x | Complex reasoning, orchestration, architecture, large context | Hard, rare, high-stakes |
+
+Ratios are approximate and shift between releases. Re-check pricing before committing a production path.
+
+## Pattern 1 — Complexity Router (pre-classify)
+
+Cheap model classifies the request, then routes to the right tier:
+
+```python
+def route(user_message: str) -> str:
+    complexity = classify_with_haiku(user_message)  # returns: simple | medium | hard
+    return {"simple": "haiku", "medium": "sonnet", "hard": "opus"}[complexity]
+```
+
+Good when ~60% of traffic is simple. Overhead: one Haiku call per request (~100 tokens).
+
+## Pattern 2 — Confidence-Based Escalation
+
+Try the cheap model first, escalate only when it hesitates:
+
+```python
+def solve(problem: str):
+    haiku = call_haiku(problem)
+    if haiku.confidence > 0.85:
+        return haiku.answer
+    sonnet = call_sonnet(problem + haiku.reasoning)
+    if sonnet.confidence > 0.8:
+        return sonnet.answer
+    return call_opus(problem)
+```
+
+Haiku must be prompted to output confidence (e.g. via tool-use structured output — see `json-mode-patterns`). Pure self-reported confidence is noisy; combine with a heuristic (output length, tool calls, hedging words).
+
+## Pattern 3 — Sub-agent Delegation (Opus orchestrates, Haiku workers)
+
+Orchestrator reasons about the plan, workers execute atomic steps:
+
+```
+Opus (planner)
+  ├── Haiku (extract_dates_from_doc_1)
+  ├── Haiku (extract_dates_from_doc_2)
+  ├── Haiku (extract_dates_from_doc_3)
+  └── Opus (synthesize all extractions into timeline)
+```
+
+Real example: `/orchestrate` in ai-toolkit runs Opus as planner, subagents (model per agent's frontmatter) as workers. See `app/agents/*.md` — each agent sets `model:` explicitly.
+
+## Pattern 4 — Fallback Chain (resilience, not cost)
+
+When primary is rate-limited or errors, degrade gracefully:
+
+```python
+def call_with_fallback(messages):
+    for model in ["claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5"]:
+        try:
+            return client.messages.create(model=model, messages=messages, ...)
+        except (RateLimitError, OverloadedError):
+            continue
+    raise AllModelsExhausted()
+```
+
+Useful in production, not for cost optimization — you lose quality on fallback.
+
+## Pattern 5 — Task-Specific Routing
+
+Skip generic complexity scoring when you know the task type:
+
+| Task | Route |
+|------|-------|
+| Commit message from diff | Haiku |
+| Summarize 5-10 lines | Haiku |
+| Classify intent | Haiku |
+| Fix a failing test | Sonnet |
+| Write new feature | Sonnet |
+| Code review, architecture decision | Opus |
+| Multi-agent orchestration | Opus |
+| Complex debugging across systems | Opus |
+
+Encode this as a map in code, not a prompt.
+
+## Anti-patterns
+
+| Anti-pattern | Consequence | Fix |
+|--------------|-------------|-----|
+| Opus for everything | 10-40x bill | Start with Sonnet, measure, demote |
+| Haiku for code review | Misses subtle bugs | Sonnet minimum for code quality |
+| Router overhead > savings | Haiku classifier eats the margin | Skip router if >80% of traffic is one tier |
+| Different prompts per tier | Maintenance nightmare | Same prompt, just swap model |
+| No telemetry | Can't optimize | Log model + tokens + cost per request |
+
+## Measuring
+
+Track per-route:
+- Cost per request
+- Latency p50/p95
+- Quality score (human-labeled or auto-evaluated)
+- Escalation rate (how often you fell back to a bigger model)
+
+Target: move the Pareto curve — cheaper at equal quality OR better at equal cost.
+
+## Related
+
+- `llm-ops-engineer` agent — production routing strategy
+- `prompt-caching-patterns` — stack caching on top of routing
+- `json-mode-patterns` — structured confidence from Haiku
+- Anthropic cookbook: https://github.com/anthropics/claude-cookbooks — see "sub-agents" notebook

package/app/skills/prompt-caching-patterns/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: prompt-caching-patterns
+description: "Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Prompt Caching Patterns
+
+Anthropic's prompt caching cuts input-token cost by ~90% on cached prefixes and reduces latency. Worth learning because one mistake (putting a dynamic value before a stable prefix) disables the whole cache.
+
+## Cache Mechanics
+
+- **TTL**: default 5 minutes; `ttl: "1h"` for 1-hour cache (higher base cost but longer-lived).
+- **Minimum size**: 1024 tokens per cache block for Sonnet/Opus, 2048 for Haiku.
+- **Max breakpoints**: 4 per request.
+- **Order matters**: everything BEFORE a `cache_control` block is part of that cache key. Dynamic content AFTER the cached block doesn't break the cache.
+
+## Anatomy of a Cached Request
+
+```python
+from anthropic import Anthropic
+
+client = Anthropic()
+response = client.messages.create(
+    model="claude-opus-4-7",
+    max_tokens=1024,
+    system=[
+        {
+            "type": "text",
+            "text": LONG_SYSTEM_PROMPT,  # stable across requests
+            "cache_control": {"type": "ephemeral"}
+        }
+    ],
+    messages=[
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": LARGE_DOCUMENT_CONTEXT,
+                 "cache_control": {"type": "ephemeral"}},
+                {"type": "text", "text": user_question}  # dynamic
+            ]
+        }
+    ]
+)
+```
+
+## Layering Pattern (4 breakpoints)
+
+```
+[ system prompt              ] ← breakpoint 1 (most stable)
+[ tool definitions           ] ← breakpoint 2
+[ long reference docs        ] ← breakpoint 3
+[ conversation history up to turn N ] ← breakpoint 4
+[ current user message       ] ← not cached (dynamic)
+```
+
+Put the MOST stable content earliest. A change to breakpoint 2 invalidates 3 and 4.
+
+## Anti-patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Timestamp in system prompt | Every request is unique | Remove timestamp, or put it AFTER the cache block |
+| User name inserted into cached text | Cache misses per user | Inject user name AFTER the cache block |
+| Reordering tool definitions across requests | Cache invalidated | Sort tools deterministically |
+| Retrying with exponential jitter that changes prompt | Cache miss on retry | Keep the exact same prefix on retries |
+| Caching <1024 tokens | Silently uncached | Merge with adjacent content or drop the breakpoint |
+
+## Measuring Hit Rate
+
+Response includes:
+```python
+response.usage.cache_creation_input_tokens  # written this request
+response.usage.cache_read_input_tokens      # read from cache (billed ~10%)
+response.usage.input_tokens                 # not cached
+```
+
+Target ratio for a well-tuned loop: `cache_read / (cache_read + input) > 0.7`. Below that, you're leaving money on the table.
+
+## When NOT to Cache
+
+- One-shot calls (cost of writing cache > savings)
+- Prompts under ~1500 tokens
+- Content that changes every request (user input, current weather, live data)
+- Hot path with <1 request per 5 min (cache expires unused)
+
+## TypeScript SDK
+
+```typescript
+const response = await anthropic.messages.create({
+  model: "claude-opus-4-7",
+  max_tokens: 1024,
+  system: [
+    { type: "text", text: LONG_SYSTEM, cache_control: { type: "ephemeral" } }
+  ],
+  messages: [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: LARGE_CONTEXT, cache_control: { type: "ephemeral" } },
+        { type: "text", text: userQuestion }
+      ]
+    }
+  ]
+});
+```
+
+## Related
+
+- `claude-api` skill — full Anthropic SDK patterns
+- `llm-ops-engineer` agent — production caching strategy
+- Anthropic docs: https://docs.claude.com/en/docs/build-with-claude/prompt-caching

package/app/skills/review/scripts/diff-analyzer.py

@@ -21,20 +21,47 @@ import sys
 from typing import Any
 
 
+# Order matters: earlier patterns win. `docs` and `test` come first so a
+# README under docs/ or a test file named e.g. `role_test.py` is not miscategorised
+# as `security`. Patterns use word boundaries or path anchors to avoid matching
+# substrings in unrelated filenames.
 CATEGORY_PATTERNS: dict[str, str] = {
-    "security": r"(auth|login|password|token|secret|crypto|session|permission|role|access)",
-    "test": r"(test_|_test\.|spec\.|\.test\.|__tests__|tests/)",
-    "config": r"(\.(yml|yaml|json|toml|env|ini|cfg)$|config|settings|\.lock$)",
-    "migration": r"(migration|alembic|schema|migrate)",
-    "infra": r"(docker|kubernetes|k8s|terraform|ansible|ci|deploy|\.github)",
-    "docs": r"(readme|changelog|docs/|\.md$|license)",
+    "docs": r"(^|/)(readme|changelog|license)\b|(^|/)docs/|\.md$",
+    "test": r"(^|/)tests?/|__tests__|(^|/)test_|_test\.|\.test\.|\.spec\.",
+    "migration": r"(^|/)(migrations?|alembic)(/|$)|\bschema_migrate\b|\b(migrate|migration)\.[a-z]+$",
+    "infra": r"(^|/)(docker|kubernetes|k8s|terraform|ansible|\.github)(/|$)|\.(dockerfile|tf)$|(^|/)ci(/|$)|(^|/)deploy(/|_|-|$)",
+    "security": r"\b\w*(auth|login|password|passwd|token|secret|crypto|session|permission|role|access|oauth|jwt|mfa|totp)\w*\b",
+    "config": r"(^|/)(config|settings)(/|\.[a-z]+$)|\.(yml|yaml|json|toml|env|ini|cfg)$|\.lock$",
 }
 
+# Secret detection patterns. Combines quoted and unquoted env-style assignments,
+# common cloud provider prefixes, JWTs, and PEM private key headers.
 SECRET_PATTERNS: list[str] = [
-    r'(?i)(api[_-]?key|secret[_-]?key|password|token|bearer)\s*[=:]\s*["\'][^"\']{8,}',
-    r"AKIA[0-9A-Z]{16}",
-    r"sk-[a-zA-Z0-9]{20,}",
-    r"ghp_[a-zA-Z0-9]{36}",
+    # Quoted secret assignments: API_KEY = "..." / secret: '...'
+    # Allow prefix/suffix word chars so `some_password`, `MY_API_KEY`, `accessToken` match.
+    r'(?i)\b\w*(?:api[_-]?key|secret[_-]?key|password|passwd|token|bearer|access[_-]?key)\w*\s*[=:]\s*["\'][^"\']{8,}["\']',
+    # Unquoted env-style: API_KEY=abcdef12345678 or API_KEY=SECRET_VALUE_XYZ.
+    # The RHS must look like a secret (no snake_case identifiers) — either a
+    # dotted/hyphenated/alphanumeric blob without underscores, or an ALL_CAPS
+    # constant. This excludes ``request_token = generate_token_v2_legacy`` style
+    # function refs.
+    r'(?i)\b\w*(?:api[_-]?key|secret[_-]?key|password|passwd|token|bearer|access[_-]?key)\w*\s*=\s*(?:[A-Za-z0-9\-\.]{12,}|(?-i:[A-Z][A-Z0-9_]{11,}))\b',
+    # AWS access key ID
+    r"\bAKIA[0-9A-Z]{16}\b",
+    # OpenAI / Anthropic-style keys
+    r"\bsk-[a-zA-Z0-9]{20,}\b",
+    # GitHub PAT
+    r"\bghp_[a-zA-Z0-9]{36}\b",
+    # GitHub fine-grained PAT
+    r"\bgithub_pat_[A-Za-z0-9_]{82}\b",
+    # Google API key
+    r"\bAIza[0-9A-Za-z_\-]{35}\b",
+    # Slack tokens (bot, app, user, refresh, config)
+    r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b",
+    # JWT
+    r"\beyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\b",
+    # PEM private key header
+    r"-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----",
 ]
 
 
@@ -54,33 +81,154 @@ def categorize(path: str) -> str:
     return "logic"
 
 
+def _base_ref_exists(base: str) -> bool:
+    """Return True if ``base`` resolves to a valid git ref."""
+    result = subprocess.run(
+        ["git", "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return result.returncode == 0
+
+
+def _run_diff(args: list[str]) -> tuple[str, int]:
+    """Run a git diff command and return (stdout, returncode)."""
+    result = subprocess.run(
+        ["git", "diff", *args],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout, result.returncode
+
+
+def _parse_numstat_z(raw: str) -> list[tuple[int, int, str]]:
+    """Parse ``git diff --numstat -z`` output into ``(adds, dels, path)`` triples.
+
+    With ``-z`` each record is NUL-terminated. Rename entries are emitted
+    as three NUL-separated tokens: ``additions\\tdeletions\\t`` then
+    ``old_path`` NUL ``new_path`` NUL. The new path is reported.
+    """
+    records: list[tuple[int, int, str]] = []
+    tokens = raw.split("\0")
+    i = 0
+    while i < len(tokens):
+        token = tokens[i]
+        if not token:
+            i += 1
+            continue
+        parts = token.split("\t")
+        if len(parts) < 2:
+            i += 1
+            continue
+        add_str, del_str = parts[0], parts[1]
+        try:
+            add = int(add_str) if add_str != "-" else 0
+            delete = int(del_str) if del_str != "-" else 0
+        except ValueError:
+            i += 1
+            continue
+        if len(parts) >= 3 and parts[2]:
+            # Normal entry: "adds\tdels\tpath"
+            records.append((add, delete, parts[2]))
+            i += 1
+        else:
+            # Rename entry: "adds\tdels\t" then old\0new
+            if i + 2 < len(tokens):
+                new_path = tokens[i + 2]
+                if new_path:
+                    records.append((add, delete, new_path))
+                i += 3
+            else:
+                i += 1
+    return records
+
+
+def _scan_secrets(diff_content: str) -> list[dict[str, Any]]:
+    """Walk a unified diff, tracking current file path and line number for each
+    added line, and report any lines matching a secret pattern.
+
+    Returns a list of ``{"file": path, "line": file_line, "preview": snippet}``.
+    """
+    findings: list[dict[str, Any]] = []
+    current_file: str | None = None
+    new_line_no: int | None = None
+    hunk_re = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+    for raw_line in diff_content.split("\n"):
+        if raw_line.startswith("+++ "):
+            # Format: "+++ b/path/to/file" or "+++ /dev/null"
+            target = raw_line[4:].strip()
+            if target == "/dev/null":
+                current_file = None
+            elif target.startswith("b/"):
+                current_file = target[2:]
+            else:
+                current_file = target
+            new_line_no = None
+            continue
+        if raw_line.startswith("--- "):
+            continue
+        if raw_line.startswith("@@"):
+            match = hunk_re.match(raw_line)
+            if match:
+                new_line_no = int(match.group(1))
+            continue
+        if new_line_no is None:
+            continue
+        if raw_line.startswith("+") and not raw_line.startswith("+++"):
+            for pattern in SECRET_PATTERNS:
+                if re.search(pattern, raw_line):
+                    findings.append(
+                        {
+                            "file": current_file,
+                            "line": new_line_no,
+                            "preview": raw_line[:80],
+                        }
+                    )
+                    break
+            new_line_no += 1
+        elif raw_line.startswith("-"):
+            # Deletion does not advance the new-file line counter
+            continue
+        else:
+            # Context line advances the new-file line counter
+            new_line_no += 1
+    return findings
+
+
 def main() -> None:
     """Entry point: analyze diff and print JSON risk report to stdout."""
     base = sys.argv[1] if len(sys.argv) > 1 else "main"
 
-    # Get diff stats (try base...HEAD first, fall back to --cached)
-    r = subprocess.run(
-        ["git", "diff", "--numstat", f"{base}...HEAD"],
-        stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
-    )
-    if r.returncode != 0:
-        r = subprocess.run(
-            ["git", "diff", "--numstat", "--cached"],
-            capture_output=True, text=True,
+    warnings: list[str] = []
+
+    # Determine scope: branch diff if base exists, otherwise staged-only.
+    if _base_ref_exists(base):
+        scope = f"{base}...HEAD"
+        numstat_raw, rc1 = _run_diff(["--numstat", "-z", f"{base}...HEAD"])
+        diff_raw, rc2 = _run_diff([f"{base}...HEAD"])
+        if rc1 != 0 or rc2 != 0:
+            scope = "staged"
+            warnings.append(
+                f"branch diff against {base!r} failed; fell back to staged changes"
+            )
+            numstat_raw, _ = _run_diff(["--numstat", "-z", "--cached"])
+            diff_raw, _ = _run_diff(["--cached"])
+    else:
+        scope = "staged"
+        warnings.append(
+            f"base ref {base!r} not found; reporting staged changes only"
+        )
+        print(
+            f"[diff-analyzer] base ref {base!r} not found; using --cached",
+            file=sys.stderr,
         )
-    diff_stat = r.stdout.strip()
+        numstat_raw, _ = _run_diff(["--numstat", "-z", "--cached"])
+        diff_raw, _ = _run_diff(["--cached"])
+
     files: list[dict[str, Any]] = []
     total_add, total_del = 0, 0
 
-    for line in diff_stat.split("\n"):
-        if not line.strip():
-            continue
-        parts = line.split("\t")
-        if len(parts) < 3:
-            continue
-        add = int(parts[0]) if parts[0] != "-" else 0
-        delete = int(parts[1]) if parts[1] != "-" else 0
-        path = parts[2]
+    for add, delete, path in _parse_numstat_z(numstat_raw):
         cat = categorize(path)
         if cat in ("security", "migration") or add > 100:
             risk = "high"
@@ -112,23 +260,8 @@ def main() -> None:
         if f["additions"] > 20
     ]
 
-    # Secrets scan on added lines (try base...HEAD first, fall back to --cached)
-    r = subprocess.run(
-        ["git", "diff", f"{base}...HEAD"],
-        stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
-    )
-    if r.returncode != 0:
-        r = subprocess.run(
-            ["git", "diff", "--cached"],
-            capture_output=True, text=True,
-        )
-    diff_content = r.stdout.strip()
-    secrets: list[dict[str, Any]] = []
-    for i, line in enumerate(diff_content.split("\n")):
-        if line.startswith("+") and not line.startswith("+++"):
-            for p in SECRET_PATTERNS:
-                if re.search(p, line):
-                    secrets.append({"line": i, "preview": line[:80]})
+    # Secrets scan on added lines with accurate file + file-line tracking
+    secrets = _scan_secrets(diff_raw)
 
     # Risk score
     has_security = any(f["category"] == "security" for f in files)
@@ -150,8 +283,12 @@ def main() -> None:
     else:
         coverage = "none"
 
+    if not files:
+        warnings.append("no changes detected")
+
     result: dict[str, Any] = {
         "base": base,
+        "scope": scope,
         "files_changed": len(files),
         "additions": total_add,
         "deletions": total_del,
@@ -162,6 +299,7 @@ def main() -> None:
         "test_coverage_estimate": coverage,
         "secrets_scan": secrets,
         "parallel_review_recommended": risk_score == "high" or len(files) > 10,
+        "warnings": warnings,
     }
     print(json.dumps(result, indent=2))
 

package/kb/procedures/release-preparation-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver]
-version: "1.5.0"
+version: "1.6.0"
 created: "2026-04-10"
-last_updated: "2026-04-13"
+last_updated: "2026-04-17"
 description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag."
 ---
 
@@ -163,12 +163,15 @@ Add entry at the top of `CHANGELOG.md` (after the header, before previous releas
 
 1. Change the heading version: `## What's New in vX.Y.Z`
 2. Replace bullet points with 3-5 highlights from this release
-3. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link
+3. **Keep only the latest version block.** Delete the previous `## What's New in vA.B.C` section(s). README is the shop window, not the archive — users see the current release, full history lives in `CHANGELOG.md`.
+4. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link directly below the bullet list.
 
 > **Warning:** This section is the first thing users see after the badges.
 > A stale version here (e.g., "What's New in v2.1.3" when shipping v2.3.0)
 > signals an unmaintained project. Do NOT skip this step.
 
+> **Single-version rule:** README.md must contain **exactly one** `## What's New in vX.Y.Z` heading at any time. If you find multiple stacked (e.g. v2.6.1 + v2.6.0 + v2.5.0), that is a SOP drift — collapse to the latest on the next release commit.
+
 ---
 
 ## Phase 4: Regenerate Artifacts