@wazir-dev/cli 1.2.0 → 1.4.0

package/docs/research/2026-03-20-deep-research-complete.md

@@ -0,0 +1,101 @@
+# Deep Research Complete — 2026-03-20
+
+## 25 Research Agents — ALL COMPLETED
+
+Total output: ~6.8MB across 25 agents. Full transcripts at:
+`/private/tmp/claude-501/-Users-mohamedabdallah-Work-Wazir/96398c18-9868-43bc-a4d6-d7f388880d4a/tasks/`
+
+## Executive Summary
+
+### The Architecture for Wazir v2
+
+**Three-layer enforcement pyramid:**
+1. **Hooks** (mechanical, can't bypass): Stop blocks completion, PreToolUse blocks writes/commits/pushes
+2. **Subagent isolation** (architectural, can't see full pipeline): one agent per phase, controller holds the loop
+3. **Persuasion engineering** (behavioral, won't bypass): superpowers-style rationalization tables, red flags, authority language
+
+### Key Findings
+
+**Hooks:**
+- Stop hook CAN block completion (`{"decision": "block"}`) — proven by ralph-loop (492+ iterations)
+- PreToolUse has 7 decision patterns: silent allow, advisory, systemMessage, modify, JSON deny, exit-code deny, echo-trick redirect
+- State tracking via `pipeline-state.json` — hooks read, CLI writes, atomic temp+rename
+- Critical limitations: hooks can block but not compel; "hook error" labels poison the model; SubagentStop is broken; agent can escape via AskUserQuestion
+- Must check `stop_hook_active` to prevent infinite loops; must allow context-limit and user-abort stops
+
+**Subagent Architecture:**
+- Controller-as-orchestrator: wz:wazir holds the loop, dispatches one subagent per phase
+- Each subagent gets fresh 200K context (~165K usable after overhead)
+- No nesting (depth=1) — controller dispatches ALL subagents directly
+- File-mediated handoff (MetaGPT pattern): artifacts on disk, not in context
+- Artifact dependency: each artifact has `requires` block with predecessor digest for staleness detection
+- Guardrail functions per phase boundary with concrete pass/fail criteria
+- Retry ladder: same-model×2 → model-escalation×1 → human escalation
+- Error classification: transient (retry), quality (retry+feedback), deterministic (escalate), resource (model-escalate)
+
+**Persuasion Engineering:**
+- Superpowers is 100% prompt engineering, zero mechanical enforcement — and agents STILL skip (issue #463)
+- Meincke et al. 2025: persuasion doubles compliance (33%→72%, N=28,000, p<.001)
+- Best combination: Authority + Commitment + Scarcity
+- CSO critical: skill descriptions must be triggers only, never process summaries
+- 47 rationalization entries across 5 superpowers skills — Wazir has ZERO
+- "Violating the letter is violating the spirit" — single most impactful sentence
+- TDD for skills: RED (observe baseline failures) → GREEN (write skill addressing those) → REFACTOR (close new loopholes)
+
+**Learning System:**
+- 4-stage pipeline: Tally → Candidate → Promote → Active
+- Findings classified by 8 categories × 4 severity levels
+- Recurrence detection via finding_hash dedup (PagerDuty pattern)
+- Semi-automatic promotion: auto-propose, human-approve (CodeGuru + Snyk model)
+- Drift prevention: 30 active project learnings max, 90-day TTL, 5% hit-rate demotion, principle consolidation at 25+ entries
+- Decision audit trail: v2 schema with category, alternatives, confidence, outcome_ref, supersedes
+- User feedback: capture corrections/approvals in ndjson, classify signal vs noise
+
+**Review Architecture:**
+- Two-tier: internal (Sonnet, expertise-loaded, pattern-matching) → external (Codex, fresh eyes, unknown-unknowns)
+- Critical finding: reviewer always-layer is 99K tokens against 50K ceiling — 5 of 8 modules are dropped
+- Fix: mode-specific reviewer composition (different modules per review mode)
+- Reviewer digest modules: 3-5K tokens each (not 12K originals)
+- Findings classified by 8 categories (correctness, security, completeness, wiring, verification, drift, performance, style)
+- Auto-classification rules per category with severity floors
+- Feedback-to-learning: 7-step loop, LLM-assisted clustering for pattern detection
+
+**Interactive UX:**
+- AskUserQuestion: 1-4 questions, 2-4 options each, arrow-key selection, multiSelect supported
+- Bug: DO NOT list in skill's allowed-tools (causes empty answers)
+- Progressive disclosure: status line (what) → paragraph (why) → full report (everything)
+- Key formula: "Name the action. State the dependency. Omit the journey."
+- 5 progress patterns: phase map, meaningful updates, artifact previews, time estimates, heartbeat
+- Heartbeat: never >2min silence (standard), >90s (deep), >3min (quick)
+- Steerability: classify mutation level → show impact → selective regeneration → preserve completed work
+- Three modes: auto (gating agent steers) / guided (checkpoints steer) / interactive (continuous steer)
+
+## Agent Output Index
+
+| # | Agent | Key Deliverable |
+|---|-------|----------------|
+| 1 | Stop hook patterns | Complete blueprint for pipeline-gate Stop hook with 10 edge cases |
+| 2 | PreToolUse catalog | 7 decision patterns with code examples from 4 real plugins |
+| 3 | State machine design | pipeline-state.json schema with 30+ fields, update rules, session isolation |
+| 4 | Hook limitations | 13 limitations with workarounds, including "hook error" label poisoning |
+| 5 | Persuasion playbook | 10 patterns, 47 rationalization entries, CSO rules, implementation checklist |
+| 6 | Controller pattern | Hybrid architecture: flat orchestration with file-mediated handoff |
+| 7 | Artifact dependencies | Per-phase schemas with requires/digest, write-time validation |
+| 8 | Context isolation | 200K per subagent, no nesting, MCP tool caveats, MetaGPT pub-sub |
+| 9 | Guardrail validation | 6 guardrail functions with concrete pass/fail criteria per phase |
+| 10 | Failure + retry | 3-tier ladder (same-model→escalate→human), error classification |
+| 11 | AskUserQuestion API | Full schema, 2-4 options, multiSelect, known bugs, plugin examples |
+| 12 | Showing reasoning | Progressive disclosure templates at 3 levels with anti-patterns |
+| 13 | Depth parameters | (in bladnman analysis) 4 depth levels with per-parameter tables |
+| 14 | Steerability | Mutation classification, impact assessment, selective regeneration |
+| 15 | Progress reporting | 5 patterns (phase map, finding updates, previews, time estimates, heartbeat) |
+| 16 | Findings → antipatterns | 4-stage promotion pipeline, 3+ occurrence threshold, human gate |
+| 17 | Cumulative tracking | SQLite schema (5 tables), dedup algorithm, recurrence detection |
+| 18 | Drift prevention | 7 mechanisms with concrete limits (30 active, 90-day TTL, 5% demotion) |
+| 19 | Decision audit trail | v2 schema with alternatives, confidence, outcome correlation |
+| 20 | User feedback capture | Signal classification, correction weighting, ndjson format |
+| 21 | Two-tier review | Internal→external, critical asymmetry (known vs unknown unknowns) |
+| 22 | Reviewer composition | Mode-specific modules, 3-5K digests, 50K budget analysis |
+| 23 | Findings classification | 8 categories × 4 severities, auto-classification rules |
+| 24 | Feedback-to-learning | 7-step loop, LLM clustering, minimum viable phases A-D |
+| 25 | Proof-of-implementation | Per-type matrix (web/API/CLI/library), Playwright MCP, Symphony model |

package/docs/research/2026-03-20-deep-research-status.md

@@ -0,0 +1,38 @@
+# Deep Research Status — 2026-03-20
+
+## 25 Research Agents — Progress
+
+### Completed (14/25)
+1. Hook: Stop hook patterns (ralph-loop analysis) ✅
+2. Hook: PreToolUse catalog (7 decision patterns) ✅
+3. Hook: State machine design (pipeline-state.json) ✅
+4. Subagent: Artifact dependencies (per-phase schemas) ✅
+5. Subagent: Guardrail validation (per-phase functions) ✅
+6. Subagent: Failure + retry (3-tier ladder) ✅
+7. Interactive: Showing reasoning (progressive disclosure) ✅
+8. Learning: Findings → antipatterns (4-stage pipeline) ✅
+9. Learning: Cumulative tracking (SQLite schema) ✅
+10. Learning: Drift prevention (7 mechanisms) ✅
+11. Learning: User feedback capture ✅
+12. Review: Feedback-to-learning pipeline (7-step loop) ✅
+13. Review: Proof-of-implementation (per-type matrix) ✅
+14. Hook: Persuasion engineering (superpowers analysis) — in first batch ✅
+
+### Pending (11/25)
+15. Hook: Limitations + workarounds
+16. Subagent: Controller pattern
+17. Subagent: Context isolation
+18. Interactive: AskUserQuestion API
+19. Interactive: Depth parameters
+20. Interactive: Steerability
+21. Interactive: Progress reporting
+22. Review: Two-tier architecture
+23. Review: Reviewer composition
+24. Review: Findings classification
+25. Learning: Decision audit trail
+
+## Key Findings So Far
+
+All research output files at: /private/tmp/claude-501/-Users-mohamedabdallah-Work-Wazir/96398c18-9868-43bc-a4d6-d7f388880d4a/tasks/
+
+Full synthesis will be compiled when all 25 agents complete.

package/docs/research/2026-03-20-enforcement-research.md

@@ -0,0 +1,107 @@
+# Enforcement Research — 2026-03-20
+
+## The Answer
+
+**Prose instructions don't work. The agent will always rationalize skipping them.** Every framework that achieves reliable enforcement uses the same pattern: **the framework holds the loop, not the agent.**
+
+## The Three-Layer Strategy
+
+### Layer 1: Mechanical Hooks (agent CANNOT bypass)
+
+**Stop hook** blocks completion: `{"decision": "block", "reason": "..."}` — proven by ralph-loop plugin (official marketplace). The agent literally cannot stop until all artifacts exist.
+
+**PreToolUse hooks** block actions:
+- `PreToolUse:Write|Edit` — blocks implementation code if no plan artifact exists
+- `PreToolUse:Bash` — blocks `git commit` if no tests run, blocks `git push` if no review
+- Returns `permissionDecision: "deny"` — the tool call is prevented entirely
+
+**State tracking** via `pipeline-state.json` — hooks READ state, CLI WRITES state. No race conditions.
+
+**Key: command hooks only, never prompt hooks.** Prompt hooks re-introduce the rationalization problem.
+
+### Layer 2: Subagent Isolation (agent CANNOT see full pipeline)
+
+From every framework (CrewAI, LangGraph, Symphony, ideation_team_skill): **give the agent a task, not a plan.**
+
+- Each phase is a separate subagent invocation
+- Phase N+1 receives phase N's artifact as input — if it doesn't exist, the call fails
+- The controller (wazir skill) holds the loop and decides what runs next
+- No single agent can rationalize skipping from research to code
+
+### Layer 3: Persuasion Engineering (agent WON'T bypass — 72% compliance)
+
+From superpowers (100K stars, backed by Meincke et al. 2025, N=28,000):
+
+- **Rationalization tables** — enumerate exact thoughts the agent has when skipping, with rebuttals
+- **"Violating the letter is violating the spirit"** — kills the #1 escape pattern
+- **Red flags lists** — specific phrases that mean STOP
+- **Authority + Commitment + Social Proof** — doubles compliance (33% → 72%)
+- **CSO (Claude Search Optimization)** — skill descriptions must be triggers, never process summaries
+
+## Key Findings Per Source
+
+### Claude Code Hooks
+- Stop hook CAN block (`{"decision": "block"}`) — proven by ralph-loop
+- PreToolUse CAN deny AND modify tool calls — proven by context-mode plugin
+- Hooks are stateless but can read/write files for state
+- Hooks loaded at session start, can't be added mid-session
+- **Limitation: hooks block actions but can't compel them**
+
+### Superpowers (100K stars)
+- 100% prompt engineering, zero mechanical enforcement
+- Single SessionStart hook injects meta-skill in `<EXTREMELY_IMPORTANT>` tags
+- **Issue #463: agents STILL skip reviews** — the author knows it's unsolved
+- Commenter: "The only reliable fix is making reviews structural, not instructional"
+- TDD skill is best-in-class prompt engineering but still fails sometimes
+- Persuasion research: authority language doubles compliance but doesn't reach 100%
+
+### Framework Enforcement Patterns
+- **CrewAI:** Python for-loop + guardrail functions. Agent produces output, framework validates.
+- **LangGraph:** Channel triggers + NamedBarrierValue. Node can't fire until inputs ready.
+- **Temporal:** `await` keyword is the enforcement. Language-level blocking.
+- **Symphony:** State machine + data dependencies. Each phase produces data the next requires.
+- **GitHub Actions:** `needs:` DAG. Scheduler prevents jobs from starting without dependencies.
+- **Universal pattern:** framework holds program counter, not agent.
+
+### UX / User Engagement
+- **bladnman/ideation_team_skill:** AskUserQuestion for pre-flight interview, depth-aware parameters, cognitive role separation across agents
+- **Devin:** PR-as-proof, screen recordings, conversational Slack updates, async delegation
+- **Copilot Workspace:** Spec → Plan → Code, each editable. Steerability = trust.
+- **Anthropic:** Show planning steps explicitly, programmatic checks at intermediate steps
+
+## What Wazir Must Build
+
+### 1. Pipeline State Machine (hooks + state file)
+
+```
+SessionStart → initialize pipeline-state.json
+PreToolUse:Write|Edit → deny if phase gate not passed
+PreToolUse:Bash → deny git commit/push without tests/review
+Stop → deny if any enabled workflow incomplete or proof missing
+```
+
+### 2. Subagent-Per-Phase Architecture
+
+The `/wazir` skill becomes a CONTROLLER that:
+- Spawns a clarifier subagent → receives clarification artifact
+- Spawns a spec subagent → receives spec artifact
+- Spawns a design subagent → receives design artifact
+- Spawns an executor subagent → receives implementation
+- Spawns a reviewer subagent → receives review verdict
+- Each subagent sees ONLY its phase, not the full pipeline
+
+### 3. Superpowers-Style Persuasion on Every Skill
+
+For each discipline rule:
+- Iron Law statement
+- Rationalization table (empirically derived)
+- Red flags list
+- "Violating the letter is violating the spirit"
+- `<EXTREMELY_IMPORTANT>` wrapper on session injection
+
+### 4. User Engagement Templates
+
+- Pre-flight interview via AskUserQuestion (batched, not serial)
+- Three-tier progress reporting (status line / key decisions / full record)
+- Artifacts as proof (self-describing, contain lineage and reasoning)
+- Steerability at phase boundaries (edit upstream, regenerate downstream)

package/expertise/antipatterns/process/ai-coding-antipatterns.md

@@ -917,6 +917,121 @@ Plan: "10 tasks covering all 10 items. Suggested order: [...]"
 
 ---
 
+### AP-23: Stale Documentation Counts
+
+**Also known as:** Count Drift, Number Rot, Metric Desync
+**Frequency:** Very Common
+**Severity:** Medium
+**Detection difficulty:** Low (mechanical)
+
+**What it looks like:**
+
+Documentation claims "268 expertise modules" when the actual count is 315. README says "7 hooks" when 8 exist. Counts in multiple files diverge from each other and from reality. The numbers were correct when written but drifted as the project grew.
+
+**Why AI agents do it:**
+
+Agents update the source of truth (add a new hook, write new expertise modules) but do not grep for every downstream reference. Each file is edited in isolation. No automated check enforces that prose counts match filesystem reality.
+
+**What goes wrong:**
+
+Users see contradictory numbers across docs and lose trust. Reviewers waste time verifying which number is correct. Launch materials ship with wrong counts, creating a first impression of sloppiness.
+
+**Detection signals:**
+
+- `find expertise -name '*.md' | wc -l` disagrees with counts in README, architecture docs, and readmes
+- `ls hooks/definitions/ | wc -l` disagrees with hook count claims
+- Different files claim different counts for the same metric
+
+**The fix:**
+
+1. **Self-audit loop** — run `wazir validate docs` which cross-references prose claims against filesystem counts
+2. **Single source of truth** — reference manifest counts programmatically where possible; avoid hardcoding counts in prose
+3. **Grep sweep on every addition** — when adding a new module, hook, or skill, grep for the old count and update all references
+4. **CI enforcement** — `wazir validate docs` in CI catches drift before merge
+
+**Example:**
+
+Bad:
+```
+README.md: "268 expertise modules"
+architecture.md: "268 curated knowledge modules"
+expertise/README.md: "268 knowledge modules"
+Actual count: 315
+```
+
+Good:
+```
+README.md: "315 expertise modules"
+architecture.md: "315 curated knowledge modules"
+expertise/README.md: "315 knowledge modules"
+Actual count: 315
+All references match.
+```
+
+**Related:** AP-06 (Partial Updates — same root cause applied to code), `wazir validate docs`, self-audit skill
+
+---
+
+### AP-24: Silent Checkpoint Bypass
+
+**Also known as:** Gate Ghosting, Approval Amnesia, Review Skipping
+**Frequency:** Common
+**Severity:** Critical
+**Detection difficulty:** Moderate
+
+**What it looks like:**
+
+The agent reaches an approval gate (spec-challenge, plan-review, or final review) and proceeds without obtaining explicit reviewer approval. The gate exists in the workflow definition but the agent treats it as advisory, not blocking. Review artifacts are either missing or contain self-generated approvals.
+
+**Why AI agents do it:**
+
+The agent conflates "review" with "self-review." Without a hard external gate (different model, different session, or user confirmation), the agent reviews its own work and approves it. Optimism bias means self-review almost never rejects. The agent also optimizes for speed, and gates are the slowest part of the pipeline.
+
+**What goes wrong:**
+
+Spec errors propagate to implementation. Design flaws survive to production. The entire adversarial review structure becomes theater — gates exist on paper but provide no actual quality assurance. Bugs caught in final review could have been caught in spec-challenge at 10x lower cost.
+
+**Detection signals:**
+
+- Review pass files authored by the same agent that authored the reviewed artifact
+- Approval granted on the first pass with zero findings
+- Missing review artifacts in the run state directory
+- `wazir capture loop-check` shows 0 review iterations for a gate phase
+
+**The fix:**
+
+1. **External reviewer enforcement** — gate phases must invoke a different model or require user confirmation via `AskUserQuestion`
+2. **Minimum findings threshold** — first-pass reviews that report zero findings trigger a warning; real adversarial review almost always finds something
+3. **Artifact validation** — `wazir validate runtime` checks that review artifacts exist and were not authored by the same role as the reviewed artifact
+4. **Loop cap guard** — `hooks/loop-cap-guard` tracks review iterations; zero iterations at a gate phase is a validation failure
+
+**Example:**
+
+Bad:
+```
+# spec-challenge pass 1
+Reviewer: executor (same agent)
+Findings: 0
+Decision: APPROVED
+```
+
+Good:
+```
+# spec-challenge pass 1
+Reviewer: codex-cli (external model)
+Findings: 3 (ambiguous acceptance criteria, missing edge case, unclear priority)
+Decision: REVISE
+
+# spec-challenge pass 2
+Reviewer: codex-cli (external model)
+Findings: 0 (all 3 resolved)
+Decision: APPROVED
+```
+
+**Related:** AP-21 (Pipeline Phase Skipping — bypassing the gate entirely vs. rubber-stamping it), AP-08 (Test Theater — similar pattern of going through motions without rigor), `docs/reference/review-loop-pattern.md`, `hooks/loop-cap-guard`
+
+---
+
 ## Code Smell Quick Reference
 
 | Anti-Pattern | Severity | Frequency | Key Signal | First Action |
@@ -943,6 +1058,8 @@ Plan: "10 tasks covering all 10 items. Suggested order: [...]"
 | AP-20 Resumption Errors | High | Common | Mixed ID types across files | Architecture file in every session |
 | AP-21 Pipeline Phase Skipping | Critical | Common | Missing clarified/* artifacts | Enforce hard gates in skills + CLI |
 | AP-22 Autonomous Scope Reduction | Critical | Common | Plan has fewer tasks than input items | Scope coverage guard + user approval |
+| AP-23 Stale Documentation Counts | Medium | Very Common | Doc counts disagree with filesystem | Grep sweep + `wazir validate docs` |
+| AP-24 Silent Checkpoint Bypass | Critical | Common | Self-approved gate with 0 findings | External reviewer + minimum findings |
 
 ---
 

package/expertise/composition-map.yaml

@@ -27,19 +27,38 @@ always:
     - antipatterns/code/state-management-antipatterns.md
     - quality/evidence-based-verification.md
   reviewer:
-    - antipatterns/process/ai-coding-antipatterns.md
-    - antipatterns/code/code-smells.md
-    - antipatterns/process/code-review-antipatterns.md
-    - antipatterns/code/dependency-antipatterns.md
-    - architecture/foundations/architectural-thinking.md
-    - architecture/foundations/coupling-and-cohesion.md
-    - antipatterns/code/architecture-antipatterns.md
-    - architecture/foundations/domain-driven-design.md
+    # Mode-agnostic core — loaded for ALL review modes (~6K tokens)
+    - digests/reviewer/review-methodology-digest.md
+    - digests/reviewer/ai-coding-digest.md
   content-author:
     - i18n/content/translation-management.md
     - i18n/foundations/string-externalization.md
     - i18n/foundations/pluralization-and-gender.md
 
+# Mode-specific reviewer composition
+# Loaded ON TOP of always.reviewer based on the --mode flag
+# Total budget per mode: ~15-25K tokens (digests + auto + stack modules)
+reviewer_modes:
+  task-review:
+    - digests/reviewer/code-smells-digest.md
+    - digests/reviewer/error-handling-digest.md
+  spec-challenge:
+    - digests/reviewer/architectural-thinking-digest.md
+    - digests/reviewer/ddd-digest.md
+  design-review:
+    - digests/reviewer/architectural-thinking-digest.md
+    - digests/reviewer/coupling-cohesion-digest.md
+  plan-review:
+    - digests/reviewer/architectural-thinking-digest.md
+    - digests/reviewer/coupling-cohesion-digest.md
+    - digests/reviewer/ai-coding-digest.md
+  final:
+    - digests/reviewer/code-smells-digest.md
+    - digests/reviewer/architecture-antipatterns-digest.md
+    - digests/reviewer/dependency-risk-digest.md
+  research-review: []
+  clarification-review: []
+
 auto:
   all-stacks:
     all-roles:

package/expertise/digests/reviewer/ai-coding-digest.md

@@ -0,0 +1,83 @@
+# AI Coding Antipatterns — Reviewer Digest
+
+> Detection-focused extract for reviewer context. For full analysis, see `antipatterns/process/ai-coding-antipatterns.md`.
+
+## Specification Drift (AP-01)
+- **Signal:** Implementation differs from stated requirements without documented reason
+- **Check:** Compare task spec acceptance criteria against actual code behavior
+- **Severity:** high
+
+## Hallucinated APIs (AP-02)
+- **Signal:** Import or call to function/class/module that doesn't exist in the dependency tree
+- **Check:** Verify every imported symbol resolves to an actual export
+- **Severity:** critical
+
+## Outdated Patterns (AP-03)
+- **Signal:** Using deprecated APIs, class components in React 2025, callback-based async when promises are standard
+- **Check:** Compare patterns against current library version best practices
+- **Severity:** high
+
+## Premature Abstraction (AP-04)
+- **Signal:** Generic utility/helper that is used exactly once
+- **Check:** Count call sites for each abstraction introduced
+- **Severity:** medium
+
+## Context Window Stuffing (AP-05)
+- **Signal:** Agent reads 10+ files without index queries; loads entire modules instead of targeted slices
+- **Check:** Review tool call patterns — excessive Read calls without preceding search
+- **Severity:** low (efficiency, not correctness)
+
+## Fake Testing (AP-06)
+- **Signal:** Tests that assert implementation details, use mocks that mirror the implementation, or test tautologies
+- **Check:** Would the test fail if the implementation had a real bug? If not, it's fake.
+- **Severity:** high
+
+## Scope Creep (AP-07)
+- **Signal:** Files modified or features added that were not in the task spec
+- **Check:** Diff includes changes outside the task's specified file scope
+- **Severity:** medium
+
+## Optimistic Error Handling (AP-08)
+- **Signal:** Missing try/catch around I/O operations, network calls, file operations, JSON parsing
+- **Check:** Every async operation and external call has error handling
+- **Severity:** high
+
+## Stale Dependency (AP-09)
+- **Signal:** Importing deprecated APIs, using outdated package versions with known CVEs
+- **Check:** Package versions against known vulnerability databases
+- **Severity:** medium-high
+
+## Cargo-Cult Patterns (AP-10)
+- **Signal:** Design patterns applied without the problem they solve (Factory for single type, Observer for single listener)
+- **Check:** Does the pattern's complexity serve a real need?
+- **Severity:** medium
+
+## Gold Plating (AP-11)
+- **Signal:** Extra configuration, extensibility points, or features not in the spec
+- **Check:** Is every public API/config option traceable to a requirement?
+- **Severity:** medium
+
+## Sycophantic Compliance (AP-12)
+- **Signal:** Agent implements exactly what was asked even when the request contains contradictions or obvious errors
+- **Check:** Look for requirements that conflict with each other or with the codebase's existing contracts
+- **Severity:** high
+
+## Phantom Error Handling (AP-13)
+- **Signal:** Error handling code that looks comprehensive but handles errors incorrectly (swallows, retries without backoff, logs without propagating)
+- **Check:** Trace each error path — does it actually reach a handler that does the right thing?
+- **Severity:** high
+
+## Inconsistent State After Failure (AP-14)
+- **Signal:** Multi-step operations where a failure in step N leaves steps 1..N-1 committed
+- **Check:** Are multi-step mutations wrapped in transactions or compensating actions?
+- **Severity:** high
+
+## Over-Confident Comments (AP-15)
+- **Signal:** Comments claiming "this handles all edge cases" or "this is thread-safe" without evidence
+- **Check:** Does the code actually handle what the comment claims?
+- **Severity:** medium
+
+## Training Data Leakage (AP-16)
+- **Signal:** Code that closely mirrors common training examples but doesn't fit the actual use case
+- **Check:** Does the implementation structure match the problem, or does it match a textbook example?
+- **Severity:** medium

package/expertise/digests/reviewer/architectural-thinking-digest.md

@@ -0,0 +1,63 @@
+# Architectural Thinking — Reviewer Digest
+
+> Evaluation-focused extract for reviewer context. For full guidance, see `architecture/foundations/architectural-thinking.md`.
+
+## Architecture Review Checklist
+
+### Separation of Concerns
+- Does each module/file have a single clear responsibility?
+- Are business logic, data access, and presentation in separate layers?
+- Can you describe what a module does in one sentence without "and"?
+
+### Dependency Direction
+- Do dependencies point inward (toward core domain), not outward?
+- Are infrastructure details (DB, HTTP, filesystem) behind abstractions?
+- Could you swap the database without changing business logic?
+
+### Interface Design
+- Are public APIs minimal (expose only what is needed)?
+- Are contracts (types, schemas, interfaces) explicit and documented?
+- Do functions have clear input/output contracts without hidden side effects?
+
+### Change Impact
+- Can you add a feature without modifying existing code (Open-Closed)?
+- Are changes localized (changing one feature doesn't cascade across modules)?
+- Is the dependency graph shallow (max 3-4 levels deep)?
+
+### Reversibility Assessment
+- Which decisions in this diff are hard to reverse?
+- Are irreversible decisions (data models, service boundaries, consistency models) justified with documented reasoning?
+- Are reversible decisions (naming, folder structure, library choices) made quickly without over-analysis?
+
+### Trade-off Reasoning
+Every architectural decision involves trade-offs. During review, check:
+- Is the trade-off acknowledged? ("We chose X because Y, accepting Z")
+- Is the trade-off appropriate for the context? (startup vs. enterprise, prototype vs. production)
+- Are rejected alternatives documented?
+
+## Architecture Smells (Quick Detection)
+
+| Smell | Signal | Severity |
+|-------|--------|----------|
+| **Big Ball of Mud** | No discernible module boundaries; any module calls any other | critical |
+| **Layering Violation** | UI code calling database directly; domain importing from infrastructure | high |
+| **Circular Module Dependency** | Module A depends on Module B depends on Module A | high |
+| **God Module** | One module >1000 LOC handling multiple concerns | medium |
+| **Leaky Abstraction** | Internal implementation details exposed in public interface | medium |
+| **Distributed Monolith** | Multiple services that must be deployed together | high |
+| **Accidental Complexity** | Architecture complexity not justified by problem complexity | medium |
+| **Architecture Astronaut** | Abstractions solving problems no one has yet | medium |
+| **Dead End Architecture** | Design choices that prevent future evolution (no extension points, hardcoded assumptions) | high |
+
+## Quality Attribute Checklist
+
+When reviewing architectural decisions, verify the relevant quality attributes are addressed:
+
+| Attribute | Review Question |
+|-----------|----------------|
+| **Performance** | Are there obvious bottlenecks? N+1 queries? Unbounded loops? |
+| **Scalability** | Can this handle 10x load without structural changes? |
+| **Security** | Are trust boundaries enforced? Input validated at boundaries? |
+| **Availability** | What happens when a dependency fails? Is there a fallback? |
+| **Modifiability** | How many files change to add a typical feature? |
+| **Testability** | Can components be tested in isolation without complex setup? |

package/expertise/digests/reviewer/architecture-antipatterns-digest.md

@@ -0,0 +1,49 @@
+# Architecture Antipatterns — Reviewer Digest
+
+> Detection-focused extract for reviewer context. For full analysis, see `antipatterns/code/architecture-antipatterns.md`.
+
+## Structural Antipatterns
+
+| Antipattern | Detection Signal | Severity |
+|-------------|-----------------|----------|
+| **Big Ball of Mud** | No discernible module boundaries; any module calls any other; package diagram is fully connected | critical |
+| **God Object / God Service** | Class/module with >10 public methods touching >3 concerns; single service handling unrelated domains | high |
+| **Golden Hammer** | Same pattern/library used for every problem regardless of fit (everything is a microservice, everything uses Redux) | medium |
+| **Architecture Astronaut** | Layers of abstraction solving problems no one has; meta-frameworks, plugin systems with zero plugins | medium |
+| **Dead Code / Lava Flow** | Unreachable code paths, unused exports, commented-out blocks; code preserved "because it might be needed" | medium |
+| **Copy-Paste Architecture** | Duplicated modules with minor variations instead of shared abstraction | high |
+| **Boat Anchor** | Unused infrastructure "for future use" (empty interfaces, unused config, skeleton services) | medium |
+| **Accidental Complexity** | System complexity far exceeds problem complexity; over-engineered for the actual requirements | medium |
+| **Stovepipe System** | Modules built in isolation with no integration architecture; each uses different patterns, different data formats | high |
+| **Swiss Army Knife** | One component tries to serve every use case; endlessly configurable but hard to use for any single purpose | medium |
+
+## Integration Antipatterns
+
+| Antipattern | Detection Signal | Severity |
+|-------------|-----------------|----------|
+| **Distributed Monolith** | Multiple services that must be deployed together; shared database; lock-step releases | critical |
+| **Chatty Interface** | >5 sequential API calls to complete one logical operation | medium |
+| **Shared Database** | Multiple services reading/writing the same database tables directly | critical |
+| **Circular Dependency** | Service A calls B calls C calls A (or module-level equivalent) | high |
+| **Hardcoded Endpoints** | URLs, hostnames, or ports as string literals in source code | medium |
+| **Missing Circuit Breaker** | External service calls without timeout or failure handling | high |
+| **Sinkhole Anti-pattern** | Requests pass through multiple layers that add no value (pure pass-through) | medium |
+
+## Layering Antipatterns
+
+| Antipattern | Detection Signal | Severity |
+|-------------|-----------------|----------|
+| **Upward Dependency** | Core/domain module imports from UI/API layer | critical |
+| **Layer Bypass** | UI code calling database/repository directly, skipping service layer | high |
+| **Anemic Domain** | Domain objects are pure data holders; all logic in services | medium |
+| **Fat Controller** | Controller/handler contains business logic instead of delegating | high |
+| **Inner Platform Effect** | Building a general-purpose engine inside the application that reimplements what the platform already provides | high |
+
+## Root Cause Patterns
+
+Most architecture antipatterns share a few root causes:
+- **Shipping pressure:** Shortcuts that accumulate into structural debt
+- **Missing boundaries:** No enforced module boundaries in build tooling
+- **Conway's Law misalignment:** Architecture doesn't match team structure
+- **Premature optimization:** Distributed complexity without proven need
+- **BDUF backlash:** Avoiding all upfront design, resulting in no design