v3.1.0: version traceability, prerequisites, timeout guards, core re-…

…injection

docs: rewrite rationale as surprise management design document

Grounds the ways architecture in cognitive science (active inference,
predictive processing, situated cognition, relevance realization) and
practical LLM research (lost-in-the-middle, context scarcity, JIT
delivery). Explains the surprise test as the unifying principle: ways
reduce prediction error via timely injection, and use surprise as the
signal for when to capture new knowledge.

v2.0.0 - Ways System

A JIT context injection engine for Claude Code.

🎯 Ways System:
- Pattern-triggered guidance that loads once per session
- Triggers: user prompts, bash commands, file edits
- Session gating via marker files (no re-triggering)
- 21 built-in ways covering common dev workflows

🧠 Matching Modes:
- match: regex - fast pattern matching (default)
- match: semantic - gzip NCD + keyword counting
- Tunable thresholds per-way

🔧 Dynamic Context:
- Macros inject runtime info (git status, contributor count, etc.)
- Project-local ways with security trust model
- Unified frontmatter schema (pattern, vocabulary, threshold)

🔒 Security:
- Project-local macros require explicit trust
- ~/.claude/trusted-project-macros whitelist
- Static way content always safe, only macros gated

📁 Structure:
- ~/.claude/hooks/ways/{domain}/{way}/way.md
- Optional macro.sh for dynamic context
- Project override: $PROJECT/.claude/ways/

Reviewed by: Gemini, Claude (x2)
Status: Production-ready

v1.0.0 - First Stable Release

A disciplined software engineering methodology for Claude Code featuring:

🤖 Specialized Subagents:
- requirements-analyst: Translates needs into user stories
- system-architect: Creates ADRs and enforces SOLID principles
- task-planner: Decomposes work with requirement traceability
- code-reviewer: Prevents monolithic patterns
- github-project-manager: Handles GitHub CLI operations
- workflow-orchestrator: Enforces task-first rule
- workspace-curator: Maintains organized documentation

📋 Methodology:
- Requirements-driven development with user stories
- Architecture Decision Records (ADR) format
- Phase-gated workflow preventing premature implementation
- Task-first rule: no code without active sub-task

🔧 Features:
- Dual tracking: local files (requirements.md/design.md/tasks.md) or GitHub integration
- Pre-commit security hooks with secret detection
- Auto-update checker for forked configurations
- SOLID principles enforcement and anti-monolith patterns

📚 Documentation:
- De-jargonified agent documentation
- Clear terminology (task-first rule, stable decisions)
- Configurable upstream tracking via .canonical-upstream