novahiz 0.1.0

package/bundled-skills/security-guidance/references/pretooluse_hook_canon.md

@@ -0,0 +1,141 @@
+# PreToolUse Hook Discipline — When To Block, When To Warn
+
+This reference answers one decision: **when designing a PreToolUse hook for Claude Code, when should it block the tool call (exit 2) vs. just warn (exit 0 with stderr message)?** The answer depends on **reversibility × severity × false-positive rate**.
+
+## The Three Exit Codes
+
+Claude Code PreToolUse hooks have three meaningful exit codes:
+
+| Exit code | Effect | Use when |
+|---|---|---|
+| `0` | Allow the tool call to proceed | No issue detected, or warning-only emission |
+| `1` | Allow but log error | Hook itself errored — don't block the user |
+| `2` | Block the tool call | Detected pattern is severe enough to require Claude to revisit |
+
+## The Decision Matrix
+
+```
+                  High severity     Low severity
+                  ─────────────     ───────────────
+Hard to reverse   BLOCK (exit 2)    WARN (stderr + exit 0)
+Easy to reverse   WARN              ALLOW (exit 0, no message)
+```
+
+Examples:
+
+- **`eval(<user_input>)`** in production code: high severity (RCE), hard to reverse if it ships → **BLOCK**
+- **`document.write` in a test file**: medium severity, easy to reverse → **WARN** (so the user can override deliberately)
+- **`pickle.load` in a one-off script for the user's own data**: low severity in context, easy to reverse → **WARN**
+- **Editing `.env` file**: high severity (secrets), but the user explicitly asked → **WARN** (let the user proceed)
+
+## Session-State Caching
+
+The security-guidance hook caches "warning shown" state per session. This is critical UX:
+
+**Without caching:** Every Edit/Write to the same file triggers the same warning. Claude burns through tokens re-explaining + the user trains themselves to ignore. **Anti-pattern.**
+
+**With caching:** First trigger blocks → Claude/user acknowledges → subsequent edits to same file+rule allowed for rest of session. **Correct.**
+
+The caching is keyed by `<file_path>-<rule_name>`. Different rules on the same file each trigger independently (a file might warn for both `eval(` and `os.system` — and should).
+
+## False-Positive Tolerance
+
+A PreToolUse hook with a 50% false-positive rate is a hook nobody listens to. The pattern table needs to be calibrated for **high precision, accepting some recall loss**.
+
+Calibration questions per pattern:
+
+1. **Specificity:** Does the pattern uniquely identify the anti-pattern, or does it match many safe uses?
+2. **Context-blindness:** Does the substring trigger inside string literals or comments? (Acceptable cost for cross-language detection.)
+3. **Override path:** Can the user document a legitimate use case? (E.g., comment annotation.)
+
+For the security-guidance hook's 12 patterns, false-positive rates are roughly:
+
+| Pattern | FP rate (estimated) | Why |
+|---|---|---|
+| `eval(` | ~5% | Mostly only appears in code-eval contexts; very low FP |
+| `pickle` | ~30% | Includes `import pickle` and any reference to the module |
+| `innerHTML =` | ~10% | Pretty specific to the anti-pattern |
+| GitHub Actions path-check | ~0% | Path-based, never false-positive |
+| SQL f-string | ~15% | Could match harmless f-strings |
+
+Higher-FP patterns rely on session-caching: user dismisses once, no nag for rest of session.
+
+## When Substring Detection Is Enough
+
+For Claude Code PreToolUse hooks, substring detection is sufficient when:
+
+- The substring is rare in non-anti-pattern contexts (e.g., `dangerouslySetInnerHTML`)
+- The user can quickly dismiss a false positive (one-key acknowledgment)
+- The cost of a false negative is high (security regression)
+
+When substring detection is **NOT** enough:
+
+- Patterns with high natural occurrence (e.g., the word "password" — appears in legitimate docs)
+- Patterns where context matters semantically (a function called `safe_eval` should not match `eval(`)
+- Patterns that require taint analysis (knowing if data came from user input)
+
+For taint-aware analysis, layer in proper SAST in CI — don't push that complexity into the PreToolUse hook.
+
+## Hook Performance Discipline
+
+The hook runs **before every Edit/Write/MultiEdit**. Performance matters:
+
+- Substring scan of 12 patterns: ~1ms for typical file content
+- State file load/save: ~5ms (JSON, single file)
+- Total overhead: ~10ms per tool call
+
+This is well within tolerance. If a hook adds >100ms per tool call, it slows down Claude Code interactively.
+
+**Don't:** Spawn child processes from the hook (kills latency).
+**Don't:** Make network calls from the hook (kills latency + introduces failure modes).
+**Do:** Keep all logic in-process; only use stdlib.
+
+## Disable-Via-Env-Var Discipline
+
+`ENABLE_SECURITY_REMINDER=0` disables the hook for a session. Use sparingly. The pattern:
+
+- **Default ON** (this is the safe default)
+- **Disable when:** doing a verified-safe operation that would otherwise trip a pattern (e.g., writing a deliberately-unsafe sandboxed REPL, doing security research)
+- **Re-enable immediately** after the operation
+
+Don't put `export ENABLE_SECURITY_REMINDER=0` in your shell rc file. That's the anti-pattern of training-yourself-to-ignore-warnings.
+
+## Anti-Patterns
+
+### Hook that always exits 0
+
+If a hook never blocks and never warns, it has no effect. Remove it.
+
+### Hook that always exits 2 on a pattern hit
+
+If a hook always blocks, even on the 5th occurrence of a pattern the user already saw 4 times, the user disables the hook. Session-state caching is required.
+
+### Hook with network I/O
+
+Defeats latency budget + adds failure modes (what if the API is down?). Hooks should be hermetic.
+
+### Hook that modifies state Claude can't see
+
+If the hook silently mutates files or env vars, Claude doesn't know about the changes and may produce inconsistent next actions. Hooks should be observation-only or emit explicit warnings.
+
+### Hook with regex that's hard to read
+
+The pattern table should be reviewable by a non-author. If the regex is dense Perl-style, port to plain substring or simplify the regex. Maintainability >> cleverness for security code.
+
+## Citations (7 sources)
+
+1. **Anthropic — Claude Code hooks documentation (2024-2026).** Source for the canonical PreToolUse exit code semantics, hook input/output format, and ~10ms latency budget. https://docs.claude.com/en/docs/claude-code/hooks
+
+2. **OWASP — Top 10 Web Application Security Risks (2021, current ed.).** Source for which patterns to detect: injection (A03), insecure design (A04), security misconfiguration (A05), broken authentication (A07). The hook's pattern table maps directly to these categories.
+
+3. **CWE (Common Weakness Enumeration) — Top 25 Most Dangerous Software Weaknesses (current ed.).** Source for the specific weakness classes the hook catches: CWE-78 (OS command injection), CWE-79 (XSS), CWE-89 (SQL injection), CWE-94 (code injection), CWE-502 (deserialization). https://cwe.mitre.org/top25/
+
+4. **GitHub Security Lab — "How to catch GitHub Actions workflow injections before attackers do" (2023).** Source for the GitHub Actions workflow path-based pattern. The cited blog post is referenced in the hook's warning text. https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/
+
+5. **Python.org — `pickle` module documentation (security warnings).** Source for the warning text on pickle deserialization RCE risk. https://docs.python.org/3/library/pickle.html
+
+6. **PyYAML — Documentation on yaml.load vs yaml.safe_load (security warnings).** Source for the yaml.unsafe_load pattern. https://pyyaml.org/wiki/PyYAMLDocumentation
+
+7. **React documentation — `dangerouslySetInnerHTML` security warnings.** Source for the React XSS pattern. https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html
+
+8. **NIST — Secure Software Development Framework (SSDF, current ed.).** Source for the "shift-left" principle that motivates PreToolUse hooks: detect security issues at the earliest possible point in the development lifecycle, before they hit version control.

package/bundled-skills/senior-architect/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: "senior-architect"
+description: This skill should be used when the user asks to "design system architecture", "evaluate microservices vs monolith", "create architecture diagrams", "analyze dependencies", "choose a database", "plan for scalability", "make technical decisions", or "review system design". Use for architecture decision records (ADRs), tech stack evaluation, system design reviews, dependency analysis, and generating architecture diagrams in Mermaid, PlantUML, or ASCII format.
+---
+
+# Senior Architect
+
+Architecture design and analysis tools for making informed technical decisions.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Tools Overview](#tools-overview)
+  - [Architecture Diagram Generator](#1-architecture-diagram-generator)
+  - [Dependency Analyzer](#2-dependency-analyzer)
+  - [Project Architect](#3-project-architect)
+- [Decision Workflows](#decision-workflows)
+  - [Database Selection](#database-selection-workflow)
+  - [Architecture Pattern Selection](#architecture-pattern-selection-workflow)
+  - [Monolith vs Microservices](#monolith-vs-microservices-decision)
+- [Reference Documentation](#reference-documentation)
+- [Tech Stack Coverage](#tech-stack-coverage)
+- [Common Commands](#common-commands)
+
+---
+
+## Quick Start
+
+```bash
+# Generate architecture diagram from project
+python scripts/architecture_diagram_generator.py ./my-project --format mermaid
+
+# Analyze dependencies for issues
+python scripts/dependency_analyzer.py ./my-project --output json
+
+# Get architecture assessment
+python scripts/project_architect.py ./my-project --verbose
+```
+
+---
+
+## Tools Overview
+
+### 1. Architecture Diagram Generator
+
+Generates architecture diagrams from project structure in multiple formats.
+
+**Solves:** "I need to visualize my system architecture for documentation or team discussion"
+
+**Input:** Project directory path
+**Output:** Diagram code (Mermaid, PlantUML, or ASCII)
+
+**Supported diagram types:**
+- `component` - Shows modules and their relationships
+- `layer` - Shows architectural layers (presentation, business, data)
+- `deployment` - Shows deployment topology
+
+**Usage:**
+```bash
+# Mermaid format (default)
+python scripts/architecture_diagram_generator.py ./project --format mermaid --type component
+
+# PlantUML format
+python scripts/architecture_diagram_generator.py ./project --format plantuml --type layer
+
+# ASCII format (terminal-friendly)
+python scripts/architecture_diagram_generator.py ./project --format ascii
+
+# Save to file
+python scripts/architecture_diagram_generator.py ./project -o architecture.md
+```
+
+**Example output (Mermaid):**
+```mermaid
+graph TD
+    A[API Gateway] --> B[Auth Service]
+    A --> C[User Service]
+    B --> D[(PostgreSQL)]
+    C --> D
+```
+
+---
+
+### 2. Dependency Analyzer
+
+Analyzes project dependencies for coupling, circular dependencies, and outdated packages.
+
+**Solves:** "I need to understand my dependency tree and identify potential issues"
+
+**Input:** Project directory path
+**Output:** Analysis report (JSON or human-readable)
+
+**Analyzes:**
+- Dependency tree (direct and transitive)
+- Circular dependencies between modules
+- Coupling score (0-100)
+- Outdated packages
+
+**Supported package managers:**
+- npm/yarn (`package.json`)
+- Python (`requirements.txt`, `pyproject.toml`)
+- Go (`go.mod`)
+- Rust (`Cargo.toml`)
+
+**Usage:**
+```bash
+# Human-readable report
+python scripts/dependency_analyzer.py ./project
+
+# JSON output for CI/CD integration
+python scripts/dependency_analyzer.py ./project --output json
+
+# Check only for circular dependencies
+python scripts/dependency_analyzer.py ./project --check circular
+
+# Verbose mode with recommendations
+python scripts/dependency_analyzer.py ./project --verbose
+```
+
+**Example output:**
+```
+Dependency Analysis Report
+==========================
+Total dependencies: 47 (32 direct, 15 transitive)
+Coupling score: 72/100 (moderate)
+
+Issues found:
+- CIRCULAR: auth → user → permissions → auth
+- OUTDATED: lodash 4.17.15 → 4.17.21 (security)
+
+Recommendations:
+1. Extract shared interface to break circular dependency
+2. Update lodash to fix CVE-2020-8203
+```
+
+---
+
+### 3. Project Architect
+
+Analyzes project structure and detects architectural patterns, code smells, and improvement opportunities.
+
+**Solves:** "I want to understand the current architecture and identify areas for improvement"
+
+**Input:** Project directory path
+**Output:** Architecture assessment report
+
+**Detects:**
+- Architectural patterns (MVC, layered, hexagonal, microservices indicators)
+- Code organization issues (god classes, mixed concerns)
+- Layer violations
+- Missing architectural components
+
+**Usage:**
+```bash
+# Full assessment
+python scripts/project_architect.py ./project
+
+# Verbose with detailed recommendations
+python scripts/project_architect.py ./project --verbose
+
+# JSON output
+python scripts/project_architect.py ./project --output json
+
+# Check specific aspect
+python scripts/project_architect.py ./project --check layers
+```
+
+**Example output:**
+```
+Architecture Assessment
+=======================
+Detected pattern: Layered Architecture (confidence: 85%)
+
+Structure analysis:
+  ✓ controllers/  - Presentation layer detected
+  ✓ services/     - Business logic layer detected
+  ✓ repositories/ - Data access layer detected
+  ⚠ models/       - Mixed domain and DTOs
+
+Issues:
+- LARGE FILE: UserService.ts (1,847 lines) - consider splitting
+- MIXED CONCERNS: PaymentController contains business logic
+
+Recommendations:
+1. Split UserService into focused services
+2. Move business logic from controllers to services
+3. Separate domain models from DTOs
+```
+
+---
+
+## Decision Workflows
+
+### Database Selection Workflow
+
+Use when choosing a database for a new project or migrating existing data.
+
+**Step 1: Identify data characteristics**
+| Characteristic | Points to SQL | Points to NoSQL |
+|----------------|---------------|-----------------|
+| Structured with relationships | ✓ | |
+| ACID transactions required | ✓ | |
+| Flexible/evolving schema | | ✓ |
+| Document-oriented data | | ✓ |
+| Time-series data | | ✓ (specialized) |
+
+**Step 2: Evaluate scale requirements**
+- <1M records, single region → PostgreSQL or MySQL
+- 1M-100M records, read-heavy → PostgreSQL with read replicas
+- >100M records, global distribution → CockroachDB, Spanner, or DynamoDB
+- High write throughput (>10K/sec) → Cassandra or ScyllaDB
+
+**Step 3: Check consistency requirements**
+- Strong consistency required → SQL or CockroachDB
+- Eventual consistency acceptable → DynamoDB, Cassandra, MongoDB
+
+**Step 4: Document decision**
+Create an ADR (Architecture Decision Record) with:
+- Context and requirements
+- Options considered
+- Decision and rationale
+- Trade-offs accepted
+
+**Quick reference:**
+```
+PostgreSQL → Default choice for most applications
+MongoDB    → Document store, flexible schema
+Redis      → Caching, sessions, real-time features
+DynamoDB   → Serverless, auto-scaling, AWS-native
+TimescaleDB → Time-series data with SQL interface
+```
+
+---
+
+### Architecture Pattern Selection Workflow
+
+Use when designing a new system or refactoring existing architecture.
+
+**Step 1: Assess team and project size**
+| Team Size | Recommended Starting Point |
+|-----------|---------------------------|
+| 1-3 developers | Modular monolith |
+| 4-10 developers | Modular monolith or service-oriented |
+| 10+ developers | Consider microservices |
+
+**Step 2: Evaluate deployment requirements**
+- Single deployment unit acceptable → Monolith
+- Independent scaling needed → Microservices
+- Mixed (some services scale differently) → Hybrid
+
+**Step 3: Consider data boundaries**
+- Shared database acceptable → Monolith or modular monolith
+- Strict data isolation required → Microservices with separate DBs
+- Event-driven communication fits → Event-sourcing/CQRS
+
+**Step 4: Match pattern to requirements**
+
+| Requirement | Recommended Pattern |
+|-------------|-------------------|
+| Rapid MVP development | Modular Monolith |
+| Independent team deployment | Microservices |
+| Complex domain logic | Domain-Driven Design |
+| High read/write ratio difference | CQRS |
+| Audit trail required | Event Sourcing |
+| Third-party integrations | Hexagonal/Ports & Adapters |
+
+See `references/architecture_patterns.md` for detailed pattern descriptions.
+
+---
+
+### Monolith vs Microservices Decision
+
+**Choose Monolith when:**
+- [ ] Team is small (<10 developers)
+- [ ] Domain boundaries are unclear
+- [ ] Rapid iteration is priority
+- [ ] Operational complexity must be minimized
+- [ ] Shared database is acceptable
+
+**Choose Microservices when:**
+- [ ] Teams can own services end-to-end
+- [ ] Independent deployment is critical
+- [ ] Different scaling requirements per component
+- [ ] Technology diversity is needed
+- [ ] Domain boundaries are well understood
+
+**Hybrid approach:**
+Start with a modular monolith. Extract services only when:
+1. A module has significantly different scaling needs
+2. A team needs independent deployment
+3. Technology constraints require separation
+
+---
+
+## Reference Documentation
+
+Load these files for detailed information:
+
+| File | Contains | Load when user asks about |
+|------|----------|--------------------------|
+| `references/architecture_patterns.md` | 9 architecture patterns with trade-offs, code examples, and when to use | "which pattern?", "microservices vs monolith", "event-driven", "CQRS" |
+| `references/system_design_workflows.md` | 6 step-by-step workflows for system design tasks | "how to design?", "capacity planning", "API design", "migration" |
+| `references/tech_decision_guide.md` | Decision matrices for technology choices | "which database?", "which framework?", "which cloud?", "which cache?" |
+
+---
+
+## Tech Stack Coverage
+
+**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin, Rust
+**Frontend:** React, Next.js, Vue, Angular, React Native, Flutter
+**Backend:** Node.js, Express, FastAPI, Go, GraphQL, REST
+**Databases:** PostgreSQL, MySQL, MongoDB, Redis, DynamoDB, Cassandra
+**Infrastructure:** Docker, Kubernetes, Terraform, AWS, GCP, Azure
+**CI/CD:** GitHub Actions, GitLab CI, CircleCI, Jenkins
+
+---
+
+## Common Commands
+
+```bash
+# Architecture visualization
+python scripts/architecture_diagram_generator.py . --format mermaid
+python scripts/architecture_diagram_generator.py . --format plantuml
+python scripts/architecture_diagram_generator.py . --format ascii
+
+# Dependency analysis
+python scripts/dependency_analyzer.py . --verbose
+python scripts/dependency_analyzer.py . --check circular
+python scripts/dependency_analyzer.py . --output json
+
+# Architecture assessment
+python scripts/project_architect.py . --verbose
+python scripts/project_architect.py . --check layers
+python scripts/project_architect.py . --output json
+```
+
+---
+
+## Getting Help
+
+1. Run any script with `--help` for usage information
+2. Check reference documentation for detailed patterns and workflows
+3. Use `--verbose` flag for detailed explanations and recommendations