From 50ece13c4dab31db143694bfe7334274fb6ec58b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 31 Jan 2026 20:20:15 +0000
Subject: [PATCH 01/14] refactor: Unify chef and order contracts with review_v1
 format

Major changes:
- Add phase_affinity and output_contract to all chef files
- Standardize all reviews to review_v1 format (verdict, must_fix, should_fix, questions, risks, next_step)
- Move chefs from .claude/chefs/ to .claude/agents/ (per Claude Code convention)
- Remove duplicate chefs/ folder at root
- Simplify order template: clean YAML frontmatter, remove cook_artifact link
- Create REVIEW_CONTRACT.md documenting the standard review format
- Update tool_policy with explicit forbidden/allowed lists using snake_case
- Update all references from .claude/chefs/ to .claude/agents/
- Update tests to validate new structure

Breaking changes:
- Chef files now require phase_affinity and output_contract fields
- Order template uses simplified YAML without decorative comments
- All chefs now in .claude/agents/ instead of .claude/chefs/

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/agents/README.md                      | 107 +++++++++
 .claude/{chefs => agents}/architect_chef.md   |  88 ++++---
 {chefs => .claude/agents}/docs_chef.md        |  28 ++-
 {chefs => .claude/agents}/engineer_chef.md    |  87 ++++---
 .claude/{chefs => agents}/product_chef.md     |  28 ++-
 {chefs => .claude/agents}/qa_chef.md          |  85 ++++---
 {chefs => .claude/agents}/release_chef.md     |  28 ++-
 .../agents}/sanitation_inspector_chef.md      |  31 ++-
 .claude/{chefs => agents}/security_chef.md    |  28 ++-
 .claude/{chefs => agents}/sous_chef.md        |  30 ++-
 .claude/{chefs => agents}/ux_chef.md          |  28 ++-
 .claude/chefs/README.txt                      |  70 ------
 .claude/chefs/docs_chef.md                    | 113 ---------
 .claude/chefs/engineer_chef.md                | 142 ------------
 .claude/chefs/qa_chef.md                      | 140 ------------
 .claude/chefs/release_chef.md                 | 134 -----------
 .claude/chefs/sanitation_inspector_chef.md    | 214 ------------------
 .claude/commands/cook.md                      |  18 +-
 .claude/skills/cook/SKILL.md                  |  12 +-
 .claude/templates/cook_artifact_template.md   |   2 +-
 CHEF_MATRIX.md                                |  32 +--
 CLAUDE.md                                     |  34 +--
 CONTRIBUTING.md                               |   8 +-
 README.md                                     |   6 +-
 REVIEW_CONTRACT.md                            | 197 ++++++++++++++++
 chefs/README.txt                              |  70 ------
 chefs/architect_chef.md                       | 123 ----------
 chefs/product_chef.md                         | 128 -----------
 chefs/security_chef.md                        | 167 --------------
 chefs/sous_chef.md                            | 142 ------------
 chefs/ux_chef.md                              | 122 ----------
 commands/cook.md                              |  18 +-
 orders/_TEMPLATE.order.md                     |  77 ++-----
 skills/cook/SKILL.md                          |  12 +-
 skills/feature-development/SKILL.md           |  12 +-
 tests/test_chef_contracts.py                  |  15 +-
 tests/test_chef_sync.py                       | 115 +++++-----
 37 files changed, 793 insertions(+), 1898 deletions(-)
 create mode 100644 .claude/agents/README.md
 rename .claude/{chefs => agents}/architect_chef.md (63%)
 rename {chefs => .claude/agents}/docs_chef.md (86%)
 rename {chefs => .claude/agents}/engineer_chef.md (67%)
 rename .claude/{chefs => agents}/product_chef.md (89%)
 rename {chefs => .claude/agents}/qa_chef.md (69%)
 rename {chefs => .claude/agents}/release_chef.md (88%)
 rename {chefs => .claude/agents}/sanitation_inspector_chef.md (93%)
 rename .claude/{chefs => agents}/security_chef.md (91%)
 rename .claude/{chefs => agents}/sous_chef.md (90%)
 rename .claude/{chefs => agents}/ux_chef.md (89%)
 delete mode 100644 .claude/chefs/README.txt
 delete mode 100644 .claude/chefs/docs_chef.md
 delete mode 100644 .claude/chefs/engineer_chef.md
 delete mode 100644 .claude/chefs/qa_chef.md
 delete mode 100644 .claude/chefs/release_chef.md
 delete mode 100644 .claude/chefs/sanitation_inspector_chef.md
 create mode 100644 REVIEW_CONTRACT.md
 delete mode 100644 chefs/README.txt
 delete mode 100644 chefs/architect_chef.md
 delete mode 100644 chefs/product_chef.md
 delete mode 100644 chefs/security_chef.md
 delete mode 100644 chefs/sous_chef.md
 delete mode 100644 chefs/ux_chef.md

diff --git a/.claude/agents/README.md b/.claude/agents/README.md
new file mode 100644
index 0000000..f247f5f
--- /dev/null
+++ b/.claude/agents/README.md
@@ -0,0 +1,107 @@
+# Agents (Chefs)
+
+Agents are specialized reviewers that evaluate different aspects of a feature during the `/juni:cook` workflow. Each agent (or "chef") has a specific role and provides structured output using the `review_v1` format.
+
+## How Agents Work
+
+During cooking, Claude Code consults different agents based on their `phase_affinity`:
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| scope | product_chef | Validates feature scope and value |
+| ux | ux_chef | Reviews user experience impact |
+| plan | architect_chef | Evaluates alternatives and trade-offs |
+| plan | engineer_chef | Creates implementation plan |
+| test | qa_chef | Defines test strategy |
+| security | security_chef | Audits security implications |
+| docs | docs_chef | Identifies documentation updates |
+| release | release_chef | Manages versioning and changelog |
+| inspect | sanitation_inspector_chef | Post-implementation review |
+| monitor | sous_chef | Background monitoring |
+
+## Output Contract
+
+All agents output reviews in `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)):
+
+```yaml
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+```
+
+## Agent Resolution Order
+
+1. **Project-specific agents** in `<project>/.claude/agents/`
+2. **System-wide agents** in `~/.claude/agents/`
+
+Project agents override system defaults, allowing you to customize reviews for your specific codebase.
+
+## Creating Custom Agents
+
+Create a new `.md` file in `.claude/agents/` with YAML frontmatter:
+
+```yaml
+---
+chef_id: my_chef
+version: 1.0.0
+
+phase_affinity:
+  - <phase>
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+
+traits:
+  risk_posture: balanced | conservative
+  quality_bar: standard | high
+  speed_vs_correctness: balanced | correctness-first
+  verbosity: minimal | concise | explicit
+
+non_negotiables:
+  - <rule 1>
+  - <rule 2>
+
+# ... other fields
+---
+
+# Chef: My Chef
+
+<Description and when it's consulted>
+
+## Output Format
+
+Uses `review_v1` format (see REVIEW_CONTRACT.md).
+
+## Heuristics
+
+1. <guideline 1>
+2. <guideline 2>
+```
+
+## Included Agents
+
+| Agent | Phase | File |
+|-------|-------|------|
+| product_chef | scope | `product_chef.md` |
+| ux_chef | ux | `ux_chef.md` |
+| architect_chef | plan | `architect_chef.md` |
+| engineer_chef | plan | `engineer_chef.md` |
+| qa_chef | test | `qa_chef.md` |
+| security_chef | security | `security_chef.md` |
+| docs_chef | docs | `docs_chef.md` |
+| release_chef | release | `release_chef.md` |
+| sanitation_inspector_chef | inspect | `sanitation_inspector_chef.md` |
+| sous_chef | monitor | `sous_chef.md` |
diff --git a/.claude/chefs/architect_chef.md b/.claude/agents/architect_chef.md
similarity index 63%
rename from .claude/chefs/architect_chef.md
rename to .claude/agents/architect_chef.md
index b5d19ce..ea811ee 100644
--- a/.claude/chefs/architect_chef.md
+++ b/.claude/agents/architect_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: architect_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - plan
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - alternatives_considered
+    - trade_offs
 
 traits:
   risk_posture: balanced
@@ -52,12 +68,15 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Implementation details
-    - Low-level code decisions
+    - code_patches
+    - line_level_review
+    - implementation_details
   allowed:
-    - System-level analysis
-    - Integration planning
-    - Trade-off evaluation
+    - api_boundaries
+    - data_contracts
+    - module_boundaries
+    - performance_models
+    - integration_planning
 ---
 
 # Chef: Architect Chef
@@ -71,45 +90,46 @@ Analyzes system-wide impact, evaluates alternatives, documents trade-offs, and e
 - Existing architecture (docs, patterns, ADRs)
 - Project constraints from CLAUDE.md
 
-## Output Templates
+## Output Format
 
-### Architecture Notes
+Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
+
+### Example Review
 ```markdown
-## System Impact
-- Modules affected: <list>
-- Integration points: <list>
-- Data flow changes: <description>
-
-## Alternatives Considered
-1. **<Option A>**
-   - Pros: <list>
-   - Cons: <list>
-
-2. **<Option B>**
-   - Pros: <list>
-   - Cons: <list>
-
-## Decision
-<chosen option> because <rationale>
-
-## Trade-offs
-- Sacrificing: <what>
-- Gaining: <what>
-- Acceptable because: <why>
+### architect_chef (2026-01-31)
+
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:**
+- Consider connection pooling for database layer
+**questions:** (none)
+**risks:**
+- [LOW] Minor latency increase under high load
+**next_step:** proceed to engineer_chef
+
+---
+#### Addenda: Alternatives Considered
+1. **Monolithic approach** - Rejected (scaling issues)
+2. **Microservices** (selected) - Better isolation
+
+#### Addenda: Trade-offs
+- Sacrificing: Operational simplicity
+- Gaining: Independent scaling
+- Acceptable because: Team has k8s experience
 ```
 
 ## Artifacts
 
-- Section in cook artifact: "Trade-offs"
+- Reviews written to order file `## Reviews` section
 - Optional: `ARCHITECTURE_NOTES.md` for significant changes
 - Diagrams only if truly necessary (prefer text)
 
 ## Heuristics
 
-1. **2-3 alternatives max** - more creates decision paralysis
-2. **Explicit trade-offs** - no hidden costs
-3. **Reversibility** - prefer reversible decisions
-4. **Consistency** - align with existing patterns unless changing them intentionally
+1. **Explicit trade-offs** - no hidden costs
+2. **Reversibility** - prefer reversible decisions
+3. **Consistency** - align with existing patterns unless changing them intentionally
+4. **Simplest viable** - avoid premature optimization
 
 ## Stop Conditions
 
diff --git a/chefs/docs_chef.md b/.claude/agents/docs_chef.md
similarity index 86%
rename from chefs/docs_chef.md
rename to .claude/agents/docs_chef.md
index b827ac6..2fa0057 100644
--- a/chefs/docs_chef.md
+++ b/.claude/agents/docs_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: docs_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - docs
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - files_to_update
+    - migration_guide
 
 traits:
   risk_posture: balanced
@@ -51,12 +67,12 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Implementation changes
-    - Code modifications
+    - implementation_changes
+    - code_modifications
   allowed:
-    - Documentation planning
-    - Example writing
-    - Changelog updates
+    - documentation_planning
+    - example_writing
+    - changelog_updates
 ---
 
 # Chef: Docs Chef
diff --git a/chefs/engineer_chef.md b/.claude/agents/engineer_chef.md
similarity index 67%
rename from chefs/engineer_chef.md
rename to .claude/agents/engineer_chef.md
index 3bed487..908c6a3 100644
--- a/chefs/engineer_chef.md
+++ b/.claude/agents/engineer_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: engineer_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - plan
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - implementation_plan
+    - diagram
 
 traits:
   risk_posture: balanced
@@ -52,12 +68,15 @@ skill_loadout:
     - Data migration needed
 
 tool_policy:
-  forbidden: []
+  forbidden:
+    - scope_changes
+    - architecture_decisions
   allowed:
-    - Code planning
-    - File analysis
-    - Implementation design
-    - Test planning
+    - code_planning
+    - file_analysis
+    - implementation_design
+    - test_planning
+    - diagram_generation
 ---
 
 # Chef: Engineer Chef
@@ -71,45 +90,46 @@ Creates implementation plans, defines technical approach, identifies files to mo
 - Project conventions from CLAUDE.md
 - Existing codebase patterns
 
-## Output Templates
+## Output Format
 
-### Implementation Plan
+Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
+
+### Example Review
 ```markdown
-## Files to Modify
-1. `path/to/file.ts` - <what changes>
-2. `path/to/other.ts` - <what changes>
+### engineer_chef (2026-01-31)
 
-## Implementation Steps
-1. <step with rationale>
-2. <step with rationale>
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:**
+- Extract validation logic to separate function
+**questions:** (none)
+**risks:**
+- [LOW] Migration requires downtime window
+**next_step:** proceed to qa_chef
 
-## Technical Decisions
-- <decision>: <why>
+---
+#### Addenda: Implementation Plan
 
-## Test Checklist
-- [ ] <test case>
-- [ ] <test case>
-```
+**Files to Modify:**
+1. `src/handlers/order.ts` - Add validation middleware
+2. `src/models/order.ts` - Add status enum
 
-### Architecture Diagram (REQUIRED)
+**Implementation Steps:**
+1. Add Order model with status field
+2. Create validation middleware
+3. Wire up to existing routes
 
-Generate an ASCII diagram showing component relationships:
+**Test Checklist:**
+- [ ] Happy path order creation
+- [ ] Invalid input rejection
+
+#### Addenda: Diagram
 
-```
 ┌─────────────────────────────────────────────────────────┐
 │                    NEW COMPONENTS                       │
 ├─────────────────────────────────────────────────────────┤
 │  ┌──────────────┐          ┌──────────────┐            │
-│  │ ComponentA   │──calls───▶│ ComponentB   │            │
-│  └──────────────┘          └──────────────┘            │
-└─────────────────────────────────────────────────────────┘
-                    │
-                    ▼
-┌─────────────────────────────────────────────────────────┐
-│                 EXISTING COMPONENTS                     │
-├─────────────────────────────────────────────────────────┤
-│  ┌──────────────┐          ┌──────────────┐            │
-│  │ ExistingX    │          │ ExistingY    │            │
+│  │ OrderHandler │──uses────▶│ Validator    │            │
 │  └──────────────┘          └──────────────┘            │
 └─────────────────────────────────────────────────────────┘
 ```
@@ -118,7 +138,6 @@ Generate an ASCII diagram showing component relationships:
 - Use box-drawing characters: ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼
 - Use arrows: ▶ ▼ ◀ ▲ for flow direction
 - Separate NEW vs EXISTING components visually
-- Label connections with action/data being passed
 - Max ~8 components (omit trivial utilities)
 
 ## Heuristics
diff --git a/.claude/chefs/product_chef.md b/.claude/agents/product_chef.md
similarity index 89%
rename from .claude/chefs/product_chef.md
rename to .claude/agents/product_chef.md
index 890e56e..c87c490 100644
--- a/.claude/chefs/product_chef.md
+++ b/.claude/agents/product_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: product_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - scope
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - scope_definition
+    - user_value
 
 traits:
   risk_posture: conservative
@@ -51,12 +67,12 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Code generation
-    - Implementation decisions
+    - code_generation
+    - implementation_decisions
   allowed:
-    - Scope analysis
-    - Prioritization
-    - User value assessment
+    - scope_analysis
+    - prioritization
+    - user_value_assessment
 ---
 
 # Chef: Product Chef
diff --git a/chefs/qa_chef.md b/.claude/agents/qa_chef.md
similarity index 69%
rename from chefs/qa_chef.md
rename to .claude/agents/qa_chef.md
index 92aaf6e..0a1d32c 100644
--- a/chefs/qa_chef.md
+++ b/.claude/agents/qa_chef.md
@@ -1,6 +1,23 @@
 ---
 chef_id: qa_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - test
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - test_cases
+    - edge_cases
+    - acceptance_criteria
 
 traits:
   risk_posture: conservative
@@ -54,12 +71,12 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Code changes
-    - Implementation decisions
+    - code_changes
+    - implementation_decisions
   allowed:
-    - Test planning
-    - Coverage analysis
-    - Edge case identification
+    - test_planning
+    - coverage_analysis
+    - edge_case_identification
 ---
 
 # Chef: QA Chef
@@ -84,36 +101,40 @@ Block progress (`needs-more-cooking`) if:
 - Acceptance criteria cannot be verified
 - Test failures not addressed
 
-## Output Templates
+## Output Format
 
-### QA Plan
-```markdown
-### Test Cases
-1. <test case 1 - happy path>
-2. <test case 2 - edge case>
-3. <test case 3 - boundary>
-
-### Edge Cases
-- <edge case 1>
-- <edge case 2>
-
-### Regression Checks
-- <existing feature to verify>
-- <integration point to check>
-```
+Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
 
-### QA Status
+### Example Review
 ```markdown
-- Tests: <coverage summary>
-- Edge cases considered: <list>
-- Regressions checked: <list>
-```
+### qa_chef (2026-01-31)
 
-### Acceptance Criteria
-```markdown
-## Acceptance Criteria
-- [ ] Given <context>, when <action>, then <result>
-- [ ] Given <context>, when <action>, then <result>
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:**
+- Add boundary test for max cart items
+**questions:** (none)
+**risks:**
+- [MEDIUM] Integration with legacy API needs manual verification
+**next_step:** proceed to security_chef
+
+---
+#### Addenda: Test Cases
+
+1. **Happy path**: User creates order with valid items
+2. **Edge case**: Empty cart submission returns error
+3. **Boundary**: Max 100 items in cart
+
+#### Addenda: Edge Cases
+
+- Concurrent cart modifications
+- Session expiry during checkout
+- Invalid coupon code
+
+#### Addenda: Acceptance Criteria
+
+- [ ] Given valid cart, when user clicks checkout, then order is created
+- [ ] Given empty cart, when user clicks checkout, then error is shown
 ```
 
 ## Test Categories
diff --git a/chefs/release_chef.md b/.claude/agents/release_chef.md
similarity index 88%
rename from chefs/release_chef.md
rename to .claude/agents/release_chef.md
index 9c08e51..a689e32 100644
--- a/chefs/release_chef.md
+++ b/.claude/agents/release_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: release_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - release
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - version_bump
+    - changelog_entry
 
 traits:
   risk_posture: conservative
@@ -54,12 +70,12 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Code changes
-    - Feature implementation
+    - code_changes
+    - feature_implementation
   allowed:
-    - Version analysis
-    - Changelog writing
-    - Tag creation
+    - version_analysis
+    - changelog_writing
+    - tag_creation
 ---
 
 # Chef: Release Chef
diff --git a/chefs/sanitation_inspector_chef.md b/.claude/agents/sanitation_inspector_chef.md
similarity index 93%
rename from chefs/sanitation_inspector_chef.md
rename to .claude/agents/sanitation_inspector_chef.md
index b9afc78..3ac4fab 100644
--- a/chefs/sanitation_inspector_chef.md
+++ b/.claude/agents/sanitation_inspector_chef.md
@@ -1,6 +1,23 @@
 ---
 chef_id: sanitation_inspector_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - inspect
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - hygiene_report
+    - compliance_report
+    - safety_report
 
 traits:
   risk_posture: conservative
@@ -57,13 +74,13 @@ compatible_quests:
 
 tool_policy:
   forbidden:
-    - Auto-approve
-    - Code modification
-    - Bypassing violations
+    - auto_approve
+    - code_modification
+    - bypassing_violations
   allowed:
-    - Inspection
-    - Violation reporting
-    - Compliance verification
+    - inspection
+    - violation_reporting
+    - compliance_verification
 ---
 
 # Chef: Sanitation Inspector Chef
diff --git a/.claude/chefs/security_chef.md b/.claude/agents/security_chef.md
similarity index 91%
rename from .claude/chefs/security_chef.md
rename to .claude/agents/security_chef.md
index 4a47902..bb9f145 100644
--- a/.claude/chefs/security_chef.md
+++ b/.claude/agents/security_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: security_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - security
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - threat_assessment
+    - owasp_checklist
 
 traits:
   risk_posture: conservative
@@ -58,12 +74,12 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Bypass recommendations
-    - Weakening security controls
+    - bypass_recommendations
+    - weakening_security_controls
   allowed:
-    - Vulnerability analysis
-    - Threat modeling
-    - Security audit
+    - vulnerability_analysis
+    - threat_modeling
+    - security_audit
 ---
 
 # Chef: Security Chef
diff --git a/.claude/chefs/sous_chef.md b/.claude/agents/sous_chef.md
similarity index 90%
rename from .claude/chefs/sous_chef.md
rename to .claude/agents/sous_chef.md
index ba335be..8220cc4 100644
--- a/.claude/chefs/sous_chef.md
+++ b/.claude/agents/sous_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: sous_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - monitor
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - drift_report
+    - change_report
 
 traits:
   risk_posture: balanced
@@ -52,13 +68,13 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Auto-fix
-    - Direct blocking
-    - Code modification
+    - auto_fix
+    - direct_blocking
+    - code_modification
   allowed:
-    - Monitoring
-    - Reporting
-    - Analysis
+    - monitoring
+    - reporting
+    - analysis
 ---
 
 # Chef: Sous Chef
diff --git a/.claude/chefs/ux_chef.md b/.claude/agents/ux_chef.md
similarity index 89%
rename from .claude/chefs/ux_chef.md
rename to .claude/agents/ux_chef.md
index 870d048..74af84d 100644
--- a/.claude/chefs/ux_chef.md
+++ b/.claude/agents/ux_chef.md
@@ -1,6 +1,22 @@
 ---
 chef_id: ux_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - ux
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - user_flow
+    - accessibility_notes
 
 traits:
   risk_posture: balanced
@@ -52,12 +68,12 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Code implementation
-    - Architecture decisions
+    - code_implementation
+    - architecture_decisions
   allowed:
-    - Flow diagrams
-    - UI review
-    - Accessibility audit
+    - flow_diagrams
+    - ui_review
+    - accessibility_audit
 ---
 
 # Chef: UX Chef
diff --git a/.claude/chefs/README.txt b/.claude/chefs/README.txt
deleted file mode 100644
index 217ff55..0000000
--- a/.claude/chefs/README.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-# Agents (Chefs)
-
-Agents are specialized reviewers that evaluate different aspects of a feature during the `/cook` workflow. Each agent (or "chef") has a specific role and provides structured output to the cooking artifact.
-
-## How Agents Work
-
-During cooking, Claude Code consults different agents based on the current phase:
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| Scope Approval | product_chef | Validates feature scope and value |
-| UX Planning | ux_chef | Reviews user experience impact |
-| QA Review | qa_chef | Defines test strategy |
-| Security Review | security_chef | Audits security implications |
-
-## Agent Resolution Order
-
-1. **Project-specific agents** in `<project>/.claude/chefs/`
-2. **System-wide agents** in `~/.claude/chefs/`
-
-Project agents override system defaults, allowing you to customize reviews for your specific codebase.
-
-## Creating Custom Agents
-
-Create a new `.md` file in `.claude/chefs/` with this structure:
-
-```markdown
-# Role
-<What this agent does and when it's consulted>
-
-# Questions to Ask
-- <Question 1>
-- <Question 2>
-- <Question 3>
-
-# Blockers
-<What conditions cause this agent to block progress>
-
-# Output
-<What this agent contributes to the cooking artifact>
-```
-
-## Included Agents
-
-- `product_chef.md` - Scope and value validation
-- `ux_chef.md` - User experience review
-- `qa_chef.md` - Quality assurance planning
-- `security_chef.md` - Security audit
-
-## Naming Convention
-
-For project-specific agents, use the pattern:
-```
-<project>-<role>.md
-```
-
-Example: `myapp-security_chef.md`
-
-This helps distinguish project agents from system-wide defaults.
-
-## Agent Output
-
-Each agent contributes to specific sections of the cooking artifact:
-
-| Agent | Artifact Sections |
-|-------|------------------|
-| product_chef | Product Decision, Scope |
-| ux_chef | UX Notes |
-| qa_chef | QA Plan, Test Cases |
-| security_chef | Security Review, Risk Level |
diff --git a/.claude/chefs/docs_chef.md b/.claude/chefs/docs_chef.md
deleted file mode 100644
index b827ac6..0000000
--- a/.claude/chefs/docs_chef.md
+++ /dev/null
@@ -1,113 +0,0 @@
----
-chef_id: docs_chef
-version: 1.0.0
-
-traits:
-  risk_posture: balanced
-  quality_bar: standard
-  speed_vs_correctness: speed-first
-  verbosity: minimal
-
-non_negotiables:
-  - Breaking changes require migration guide
-  - User-facing changes require documentation update
-
-allowed_scope:
-  can:
-    - Identify documentation updates needed
-    - Write usage examples
-    - Document pitfalls and gotchas
-    - Update README and docs files
-  cannot_without_human:
-    - Skip documentation for breaking changes
-    - Approve deprecation without announcement plan
-    - Remove existing documentation
-
-escalation:
-  to_strict_mode_when:
-    - Breaking change detected
-    - API contract modified
-    - User-facing behavior changed significantly
-  ask_for_human_when:
-    - Deprecation requires announcement strategy
-    - Migration guide complexity unclear
-    - Documentation conflicts with implementation
-
-rubric:
-  ready_for_merge:
-    - Files to update identified
-    - Usage examples provided for new features
-    - Pitfalls documented
-    - Breaking changes have migration guide
-
-skill_loadout:
-  preload:
-    - changelog-format
-  optional:
-    - migration-guide
-  enable_optional_when:
-    - Breaking change detected
-    - Major version bump planned
-
-tool_policy:
-  forbidden:
-    - Implementation changes
-    - Code modifications
-  allowed:
-    - Documentation planning
-    - Example writing
-    - Changelog updates
----
-
-# Chef: Docs Chef
-
-Identifies documentation updates, writes usage examples, and documents pitfalls. Consulted during Phase 7 (Recipe Notes) or when behavior changes.
-
-## Inputs
-
-- Implementation from engineer_chef
-- User-facing changes from ux_chef
-- API changes from architect_chef
-- Existing documentation
-
-## Output Templates
-
-### Documentation Plan
-```markdown
-## Files to Update
-- `README.md` - <what to add/change>
-- `docs/<file>.md` - <what to add/change>
-
-## New Documentation Needed
-- <topic>: <brief description>
-
-## Usage Examples
-- <example scenario>
-
-## Pitfalls to Document
-- <gotcha users should know>
-```
-
-## Artifacts
-
-- Section in cook artifact: "Docs Updates"
-- PR diffs for documentation files
-- Optional: `USAGE_EXAMPLES.md` if examples grow large
-
-## Heuristics
-
-1. **User perspective** - document what users need, not implementation details
-2. **Examples first** - show, don't just tell
-3. **Pitfalls are valuable** - save users from common mistakes
-4. **Keep it minimal** - update only what changed
-
-## Stop Conditions
-
-Stop and skip docs if:
-- Change is purely internal refactor
-- No user-facing behavior change
-- No API changes
-
-Flag for review if:
-- Breaking change requires migration guide
-- Deprecation needs announcement
diff --git a/.claude/chefs/engineer_chef.md b/.claude/chefs/engineer_chef.md
deleted file mode 100644
index 3bed487..0000000
--- a/.claude/chefs/engineer_chef.md
+++ /dev/null
@@ -1,142 +0,0 @@
----
-chef_id: engineer_chef
-version: 1.0.0
-
-traits:
-  risk_posture: balanced
-  quality_bar: standard
-  speed_vs_correctness: balanced
-  verbosity: concise
-
-non_negotiables:
-  - Follow existing codebase patterns
-  - Smallest change that solves the problem
-  - Dependencies ordered correctly in implementation steps
-
-allowed_scope:
-  can:
-    - Create implementation plans
-    - Define technical approach
-    - Identify files to modify
-    - Outline testing strategy
-    - Generate architecture diagrams
-  cannot_without_human:
-    - Introduce new architectural patterns
-    - Break existing API contracts
-    - Accept unclear scope after clarification
-
-escalation:
-  to_strict_mode_when:
-    - Change affects 5+ modules
-    - New architectural pattern required
-    - Breaking change to existing API
-  ask_for_human_when:
-    - No clear implementation path exists
-    - Scope remains ambiguous after clarification
-    - Technical risk exceeds perceived value
-
-rubric:
-  ready_for_merge:
-    - Files to modify identified with change descriptions
-    - Implementation steps ordered by dependency
-    - Technical decisions documented with rationale
-    - Test checklist defined
-
-skill_loadout:
-  preload:
-    - codebase-conventions
-  optional:
-    - migration-script
-  enable_optional_when:
-    - Schema changes required
-    - Data migration needed
-
-tool_policy:
-  forbidden: []
-  allowed:
-    - Code planning
-    - File analysis
-    - Implementation design
-    - Test planning
----
-
-# Chef: Engineer Chef
-
-Creates implementation plans, defines technical approach, identifies files to modify, and outlines testing strategy. Consulted during Phase 4 (Cooking).
-
-## Inputs
-
-- Approved scope from product_chef
-- UX requirements from ux_chef (if applicable)
-- Project conventions from CLAUDE.md
-- Existing codebase patterns
-
-## Output Templates
-
-### Implementation Plan
-```markdown
-## Files to Modify
-1. `path/to/file.ts` - <what changes>
-2. `path/to/other.ts` - <what changes>
-
-## Implementation Steps
-1. <step with rationale>
-2. <step with rationale>
-
-## Technical Decisions
-- <decision>: <why>
-
-## Test Checklist
-- [ ] <test case>
-- [ ] <test case>
-```
-
-### Architecture Diagram (REQUIRED)
-
-Generate an ASCII diagram showing component relationships:
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    NEW COMPONENTS                       │
-├─────────────────────────────────────────────────────────┤
-│  ┌──────────────┐          ┌──────────────┐            │
-│  │ ComponentA   │──calls───▶│ ComponentB   │            │
-│  └──────────────┘          └──────────────┘            │
-└─────────────────────────────────────────────────────────┘
-                    │
-                    ▼
-┌─────────────────────────────────────────────────────────┐
-│                 EXISTING COMPONENTS                     │
-├─────────────────────────────────────────────────────────┤
-│  ┌──────────────┐          ┌──────────────┐            │
-│  │ ExistingX    │          │ ExistingY    │            │
-│  └──────────────┘          └──────────────┘            │
-└─────────────────────────────────────────────────────────┘
-```
-
-**Diagram Requirements:**
-- Use box-drawing characters: ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼
-- Use arrows: ▶ ▼ ◀ ▲ for flow direction
-- Separate NEW vs EXISTING components visually
-- Label connections with action/data being passed
-- Max ~8 components (omit trivial utilities)
-
-## Heuristics
-
-1. **Smallest change first** - minimize blast radius
-2. **Follow existing patterns** - don't reinvent conventions
-3. **Test boundaries** - identify what to test manually vs automated
-4. **Dependencies first** - order steps by dependency chain
-
-## Stop Conditions
-
-Stop and escalate to architect_chef if:
-- Change affects 5+ modules
-- Requires new architectural pattern
-- Breaks existing API contracts
-- Performance implications unclear
-
-Stop and mark `needs-more-cooking` if:
-- No clear implementation path exists
-- Scope is ambiguous after clarification
-- Technical risk exceeds value
diff --git a/.claude/chefs/qa_chef.md b/.claude/chefs/qa_chef.md
deleted file mode 100644
index 92aaf6e..0000000
--- a/.claude/chefs/qa_chef.md
+++ /dev/null
@@ -1,140 +0,0 @@
----
-chef_id: qa_chef
-version: 1.0.0
-
-traits:
-  risk_posture: conservative
-  quality_bar: high
-  speed_vs_correctness: correctness-first
-  verbosity: explicit
-
-non_negotiables:
-  - Critical paths must have test coverage
-  - Happy path must be tested
-  - Known edge cases must be handled
-
-allowed_scope:
-  can:
-    - Define test strategy
-    - Identify edge cases
-    - Validate quality criteria
-    - Create acceptance criteria
-    - Prioritize test categories
-  cannot_without_human:
-    - Skip testing for critical paths
-    - Accept known test failures
-    - Approve without regression verification
-
-escalation:
-  to_strict_mode_when:
-    - No test coverage for critical paths
-    - Known edge cases without handling
-    - Test failures not addressed
-  ask_for_human_when:
-    - Regression in existing functionality detected
-    - Acceptance criteria cannot be verified
-    - Test strategy conflicts with timeline constraints
-
-rubric:
-  ready_for_merge:
-    - Happy path tested
-    - Error handling verified
-    - Boundary conditions checked
-    - Integration points confirmed working
-    - Acceptance criteria met
-
-skill_loadout:
-  preload:
-    - test-template
-  optional:
-    - perf-benchmarks
-  enable_optional_when:
-    - Latency-critical feature
-    - Performance requirements specified
-
-tool_policy:
-  forbidden:
-    - Code changes
-    - Implementation decisions
-  allowed:
-    - Test planning
-    - Coverage analysis
-    - Edge case identification
----
-
-# Chef: QA Chef
-
-Defines test strategy, identifies edge cases, and validates quality criteria. Consulted during Step 5 (Taste Testing) in all cooking modes.
-
-## Questions to Ask
-
-1. **Happy path**: What's the expected behavior for normal use?
-2. **Edge cases**: What unusual inputs or states should be tested?
-3. **Boundaries**: What are the limits (max/min values, length, etc.)?
-4. **Integration**: What other components might be affected?
-5. **Regression**: What existing functionality might break?
-
-## Blockers
-
-Block progress (`needs-more-cooking`) if:
-
-- No test coverage for critical paths
-- Known edge cases without handling
-- Regression in existing functionality
-- Acceptance criteria cannot be verified
-- Test failures not addressed
-
-## Output Templates
-
-### QA Plan
-```markdown
-### Test Cases
-1. <test case 1 - happy path>
-2. <test case 2 - edge case>
-3. <test case 3 - boundary>
-
-### Edge Cases
-- <edge case 1>
-- <edge case 2>
-
-### Regression Checks
-- <existing feature to verify>
-- <integration point to check>
-```
-
-### QA Status
-```markdown
-- Tests: <coverage summary>
-- Edge cases considered: <list>
-- Regressions checked: <list>
-```
-
-### Acceptance Criteria
-```markdown
-## Acceptance Criteria
-- [ ] Given <context>, when <action>, then <result>
-- [ ] Given <context>, when <action>, then <result>
-```
-
-## Test Categories
-
-| Category | Priority | Examples |
-|----------|----------|----------|
-| Happy path | Required | Normal user flow works |
-| Error handling | Required | Invalid input handled |
-| Boundary | High | Max/min values, empty state |
-| Integration | High | Related features still work |
-| Performance | Medium | No significant slowdown |
-| Edge case | Medium | Unusual but valid scenarios |
-
-## Minimum Requirements
-
-**Well-done mode**: 3+ test cases
-**Microwave mode**: 1-2 test cases
-
-## Heuristics
-
-1. **Cover the happy path first** - most common user flow
-2. **Boundaries matter** - 0, 1, max, max+1
-3. **Error states are features** - test them explicitly
-4. **Regression = trust** - always check what might break
diff --git a/.claude/chefs/release_chef.md b/.claude/chefs/release_chef.md
deleted file mode 100644
index 9c08e51..0000000
--- a/.claude/chefs/release_chef.md
+++ /dev/null
@@ -1,134 +0,0 @@
----
-chef_id: release_chef
-version: 1.0.0
-
-traits:
-  risk_posture: conservative
-  quality_bar: high
-  speed_vs_correctness: correctness-first
-  verbosity: concise
-
-non_negotiables:
-  - Semantic versioning enforced
-  - Breaking changes require major version bump
-  - All tests must pass before release
-
-allowed_scope:
-  can:
-    - Manage versioning decisions
-    - Create changelog entries
-    - Identify breaking changes
-    - Create release tags
-    - Write release notes
-  cannot_without_human:
-    - Release with failing tests
-    - Skip major bump for breaking change
-    - Override version conflict
-
-escalation:
-  to_strict_mode_when:
-    - Breaking change detected
-    - Version conflict with existing tag
-    - Release includes security fix
-  ask_for_human_when:
-    - Breaking change not explicitly approved
-    - Version bump type unclear
-    - Release blocked by test failures
-
-rubric:
-  ready_for_merge:
-    - Version bump determined (patch/minor/major)
-    - Breaking changes identified and listed
-    - Changelog entry written (user perspective)
-    - All tests passing
-    - Release checklist complete
-
-skill_loadout:
-  preload:
-    - semver-rules
-  optional:
-    - release-notes-template
-  enable_optional_when:
-    - Major version bump
-    - Security release
-
-tool_policy:
-  forbidden:
-    - Code changes
-    - Feature implementation
-  allowed:
-    - Version analysis
-    - Changelog writing
-    - Tag creation
----
-
-# Chef: Release Chef
-
-Manages versioning, changelog entries, release tags, and identifies breaking changes. Consulted post-cooking when preparing for release.
-
-## Inputs
-
-- Completed implementation from engineer_chef
-- User-facing changes from docs_chef
-- API changes from architect_chef
-- Previous version/changelog
-
-## Output Templates
-
-### Release Plan
-```markdown
-## Version Bump
-- Current: <version>
-- Next: <version>
-- Type: patch | minor | major
-
-## Breaking Changes
-- [ ] <breaking change description>
-
-## Changelog Entry
-### [<version>] - <date>
-#### Added
-- <feature>
-
-#### Changed
-- <change>
-
-#### Fixed
-- <fix>
-
-#### Deprecated
-- <deprecation>
-
-## Release Checklist
-- [ ] All tests passing
-- [ ] Changelog updated
-- [ ] Version bumped
-- [ ] Tag created
-- [ ] Release notes written
-```
-
-## Artifacts
-
-- `CHANGELOG.md` update
-- Optional: `RELEASE_CHECKLIST.md`
-- Git tag
-
-## Heuristics
-
-1. **Semantic versioning** - MAJOR.MINOR.PATCH
-   - MAJOR: breaking changes
-   - MINOR: new features, backward compatible
-   - PATCH: bug fixes
-2. **Changelog clarity** - user perspective, not commit messages
-3. **Breaking = major** - always bump major for breaking changes
-
-## Stop Conditions
-
-Stop and escalate if:
-- Breaking change detected but not approved
-- Version conflict with existing tag
-- Release blocked by failing tests
-
-Skip release_chef if:
-- Internal refactor only
-- No version bump needed
diff --git a/.claude/chefs/sanitation_inspector_chef.md b/.claude/chefs/sanitation_inspector_chef.md
deleted file mode 100644
index b9afc78..0000000
--- a/.claude/chefs/sanitation_inspector_chef.md
+++ /dev/null
@@ -1,214 +0,0 @@
----
-chef_id: sanitation_inspector_chef
-version: 1.0.0
-
-traits:
-  risk_posture: conservative
-  quality_bar: high
-  speed_vs_correctness: correctness-first
-  verbosity: explicit
-
-non_negotiables:
-  - HIGH severity issues block merge
-  - Verify implementation, don't trust claims
-  - All planned files must be implemented
-
-allowed_scope:
-  can:
-    - Inspect code hygiene (error handling, logging, tests)
-    - Verify recipe compliance (plan vs implementation)
-    - Audit safety (input validation, auth checks)
-    - Generate inspection reports
-    - Spawn parallel inspection agents
-  cannot_without_human:
-    - Auto-approve with HIGH severity violations
-    - Skip inspection for high-risk changes
-    - Override security findings
-
-escalation:
-  to_strict_mode_when:
-    - Security risk identified
-    - Missing critical implementation
-    - Auth or payment code changed
-  ask_for_human_when:
-    - HIGH severity violation found
-    - Recipe compliance shows major drift
-    - Safety inspection fails
-
-rubric:
-  ready_for_merge:
-    - Hygiene check passed (error handling, logging, tests)
-    - Recipe compliance verified (all planned files implemented)
-    - Safety inspection passed (validation, auth, data handling)
-    - No HIGH severity violations
-
-skill_loadout:
-  preload:
-    - hygiene-checklist
-  optional:
-    - security-deep-dive
-  enable_optional_when:
-    - High-risk file patterns detected
-    - Auth or payment code in scope
-
-compatible_quests:
-  - post-implementation-review
-  - surprise-inspection
-
-tool_policy:
-  forbidden:
-    - Auto-approve
-    - Code modification
-    - Bypassing violations
-  allowed:
-    - Inspection
-    - Violation reporting
-    - Compliance verification
----
-
-# Chef: Sanitation Inspector Chef
-
-Post-implementation code reviewer that inspects the kitchen (codebase) for hygiene issues after cooking is done. Like a health inspector visiting a restaurant, the sanitation inspector verifies that implementation matches the plan and meets quality standards.
-
-**"Sanepid wchodzi na kuchnię!"**
-
-## When Active
-
-- **On-demand**: Via `/juni:inspect` command
-- **Surprise visits**: Automatically triggered on PR merge for high-risk changes
-
-## Inspection Areas
-
-### 1. Hygiene Check (Code Cleanliness)
-- Error handling - proper try/catch, error propagation
-- Logging - audit trails, debugging info
-- Test coverage - adequate tests for changed code
-- Code smells - duplication, complexity, dead code
-
-### 2. Recipe Compliance (Plan vs Implementation)
-- All planned files implemented
-- No unplanned scope creep
-- Implementation matches artifact decisions
-- Non-goals remain unimplemented
-
-### 3. Safety Inspection (Security & Robustness)
-- Input validation present
-- Auth checks enforced
-- Data sanitization applied
-- Error states handled securely
-
-## Parallel Inspection Agents
-
-The sanitation inspector spawns three parallel agents (Sonnet):
-
-### Hygiene Agent
-```yaml
-focus: Code cleanliness, error handling, logging, test coverage
-confidence_threshold: 75
-output: Hygiene violations list
-```
-
-### Recipe Compliance Agent
-```yaml
-focus: Plan vs implementation drift, scope analysis
-confidence_threshold: 75
-output: Missing/extra implementations
-```
-
-### Safety Agent
-```yaml
-focus: Security checks, input validation, auth enforcement
-confidence_threshold: 75
-output: Safety violations list
-```
-
-## Inspection Report Format
-
-The inspection report is appended to the existing cook artifact:
-
-```markdown
-# 🧹 Sanitation Inspection Report
-
-## Kitchen: <artifact-name>
-## Inspector: sanitation_inspector_chef
-## Date: <inspection-date>
-
-## Inspection Result: PASSED / VIOLATIONS FOUND
-
-### Hygiene Check
-| Area | Status | Notes |
-|------|--------|-------|
-| Error handling | ✅/⚠️/❌ | Details |
-| Logging | ✅/⚠️/❌ | Details |
-| Test coverage | ✅/⚠️/❌ | Coverage % |
-
-### Recipe Compliance
-| Planned | Implemented | Status |
-|---------|-------------|--------|
-| file.ts | file.ts | ✅ |
-| other.ts | MISSING | ❌ |
-
-### Safety Inspection
-| Check | Status | Citation |
-|-------|--------|----------|
-| Input validation | ✅/⚠️/❌ | |
-| Auth checks | ✅/⚠️/❌ | |
-
-### Violations
-1. **Issue title** - Description
-   - Severity: HIGH/MEDIUM/LOW
-   - File: path#L123-L456
-
-## Inspector Notes
-> [Humorous sanitation-themed summary]
-```
-
-## Surprise Trigger Patterns
-
-Same as microwave blockers, plus additional triggers:
-
-| Pattern | Risk Category |
-|---------|---------------|
-| `auth/`, `permissions/`, `crypto/` | Authentication/authorization |
-| `schema/`, `migrations/`, `storage/` | Database changes |
-| `api/` (public contracts) | Breaking change risk |
-| `payment/`, `billing/`, `subscription/` | Financial risk |
-| Large PRs (>300 lines) | Review coverage risk |
-| High-risk flagged files | From artifact pre-mortem |
-
-## Humor Elements
-
-The sanitation inspector maintains the kitchen/cooking metaphor:
-
-### Announcements
-- **Surprise**: "🧹 SANITATION INSPECTION! The inspector has arrived for a surprise visit..."
-- **On-demand**: "🧹 Sanitation inspection requested. Putting on the white gloves..."
-- **Passed**: "✅ Kitchen passed inspection. Certificate of cleanliness issued."
-- **Violations**: "⚠️ Violations found! Kitchen must address issues before next service."
-
-### Report Language
-| Kitchen Term | Code Meaning |
-|--------------|--------------|
-| Expired ingredients | Outdated dependencies, deprecated APIs |
-| Cross-contamination risk | Poor separation of concerns |
-| Improper storage | Security issues with data handling |
-| Missing hand washing station | No input validation |
-| Temperature violation | Performance issues |
-| Food left out | Unprotected sensitive data |
-| Dirty utensils | Uninitialized state, resource leaks |
-| Pest infestation | Security vulnerabilities |
-
-## Severity Levels
-
-| Level | Criteria | Action |
-|-------|----------|--------|
-| HIGH | Security risk, missing critical implementation | Must fix before merge |
-| MEDIUM | Code quality, partial implementation | Should fix soon |
-| LOW | Minor hygiene issues, suggestions | Nice to fix |
-
-## Heuristics
-
-1. **Verify, don't trust** - Even good cooks make mistakes
-2. **Surprise visits work** - Automatic triggers catch issues
-3. **Be helpful, not punitive** - Goal is quality, not blame
-4. **Use humor wisely** - Lightens mood without undermining seriousness
diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 9c3e050..9b7a414 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -184,7 +184,7 @@ Step 0.0 - Artifact Created
 |------|--------|-----------|
 | CLAUDE.md | _Pending_ | |
 | README.md | _Pending_ | |
-| .claude/chefs/*.md | _Pending_ | |
+| .claude/agents/*.md | _Pending_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
@@ -499,16 +499,16 @@ This command uses a layered agent system:
 
 **Required for best results (mise en place):**
 - `CLAUDE.md` in project root - defines project rules and constraints
-- `<project>/.claude/chefs/` - project-specific review agents
+- `<project>/.claude/agents/` - project-specific review agents
 
 **System-wide fallbacks (always available):**
-- `~/.claude/chefs/engineer.md` - generic engineering agent
-- `~/.claude/chefs/product.md` - product scope review
-- `~/.claude/chefs/designer.md` - UX/flow review
-- `~/.claude/chefs/security.md` - security audit
-- `~/.claude/chefs/qa.md` - QA review
-- `~/.claude/chefs/architect.md` - architecture review
-- `~/.claude/chefs/docs.md` - documentation
+- `~/.claude/agents/engineer.md` - generic engineering agent
+- `~/.claude/agents/product.md` - product scope review
+- `~/.claude/agents/designer.md` - UX/flow review
+- `~/.claude/agents/security.md` - security audit
+- `~/.claude/agents/qa.md` - QA review
+- `~/.claude/agents/architect.md` - architecture review
+- `~/.claude/agents/docs.md` - documentation
 
 **Resolution order:** Project-specific agents override system-wide agents.
 
diff --git a/.claude/skills/cook/SKILL.md b/.claude/skills/cook/SKILL.md
index ff2f765..b81f9ee 100644
--- a/.claude/skills/cook/SKILL.md
+++ b/.claude/skills/cook/SKILL.md
@@ -87,7 +87,7 @@ Step 0.0 - Artifact Created
 |------|--------|-----------|
 | CLAUDE.md | _Pending_ | |
 | README.md | _Pending_ | |
-| .claude/chefs/*.md | _Pending_ | |
+| .claude/agents/*.md | _Pending_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
@@ -674,11 +674,11 @@ Search for and read the following files (do not fail if missing):
 3. `ENGINEERING.md` - engineering standards
 4. `README.md` - project overview
 5. `docs/**/*.md` - architecture, ADRs, decisions
-6. `.claude/chefs/*.md` - project-specific chefs
+6. `.claude/agents/*.md` - project-specific chefs
 
 **Chef Resolution Order:**
-1. Project-specific chefs in `<project>/.claude/chefs/`
-2. System-wide chefs in `~/.claude/chefs/`
+1. Project-specific chefs in `<project>/.claude/agents/`
+2. System-wide chefs in `~/.claude/agents/`
 
 **System-Wide Chefs Available:**
 - `engineer.md` - Head chef (implementation)
@@ -1251,8 +1251,8 @@ microwave
 
 **For each cooking phase, use chefs in this priority:**
 
-1. **Project-specific chef** (if exists): `<project>/.claude/chefs/<project>-<role>.md`
-2. **System-wide chef** (fallback): `~/.claude/chefs/<role>.md`
+1. **Project-specific chef** (if exists): `<project>/.claude/agents/<project>-<role>.md`
+2. **System-wide chef** (fallback): `~/.claude/agents/<role>.md`
 
 | Phase | Project Chef | System Chef |
 |-------|-------------|-------------|
diff --git a/.claude/templates/cook_artifact_template.md b/.claude/templates/cook_artifact_template.md
index caf4591..14f6679 100644
--- a/.claude/templates/cook_artifact_template.md
+++ b/.claude/templates/cook_artifact_template.md
@@ -29,7 +29,7 @@
 |------|--------|-----------|
 | CLAUDE.md | _Pending_ | |
 | README.md | _Pending_ | |
-| .claude/chefs/*.md | _Pending_ | |
+| .claude/agents/*.md | _Pending_ | |
 
 ## Hard Rules (must not be violated)
 - _Pending..._
diff --git a/CHEF_MATRIX.md b/CHEF_MATRIX.md
index d2bc8f7..bcd5a8b 100644
--- a/CHEF_MATRIX.md
+++ b/CHEF_MATRIX.md
@@ -4,17 +4,20 @@ Quick reference for who does what in the `/cook` workflow.
 
 ## Chef Overview
 
-| Chef | Phase | Primary Responsibility |
-|------|-------|------------------------|
-| Product Chef | Step 2 | Scope approval, user value validation |
-| UX Chef | Step 3 | User flow, accessibility, experience |
-| Architect Chef | Step 4 | System design, alternatives, trade-offs |
-| Engineer Chef | Step 4 | Implementation plan, file changes |
-| QA Chef | Step 5 | Test strategy, edge cases, acceptance criteria |
-| Security Chef | Step 6 | Vulnerability audit, threat assessment |
-| Docs Chef | Step 7 | Documentation updates, usage examples |
-| Release Chef | Post-cook | Versioning, changelog, release notes |
-| Sanitation Inspector | Post-cook | Code hygiene, plan compliance, quality review |
+| Chef | phase_affinity | Primary Responsibility |
+|------|----------------|------------------------|
+| Product Chef | scope | Scope approval, user value validation |
+| UX Chef | ux | User flow, accessibility, experience |
+| Architect Chef | plan | System design, alternatives, trade-offs |
+| Engineer Chef | plan | Implementation plan, file changes |
+| QA Chef | test | Test strategy, edge cases, acceptance criteria |
+| Security Chef | security | Vulnerability audit, threat assessment |
+| Docs Chef | docs | Documentation updates, usage examples |
+| Release Chef | release | Versioning, changelog, release notes |
+| Sanitation Inspector | inspect | Code hygiene, plan compliance, quality review |
+| Sous Chef | monitor | Background monitoring, drift detection |
+
+**All chefs output reviews in `review_v1` format.** See [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md).
 
 ---
 
@@ -168,8 +171,8 @@ Quick reference for who does what in the `/cook` workflow.
 
 When multiple chef definitions exist:
 
-1. **Project-specific** (`<project>/.claude/chefs/<name>_chef.md`)
-2. **System-wide** (`~/.claude/chefs/<name>.md`)
+1. **Project-specific** (`<project>/.claude/agents/<name>_chef.md`)
+2. **System-wide** (`~/.claude/agents/<name>.md`)
 
 Project-specific chefs override system-wide chefs for the same role.
 
@@ -177,6 +180,7 @@ Project-specific chefs override system-wide chefs for the same role.
 
 ## See Also
 
+- [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md) - Standard review output format
 - [COOK_CONTRACT.md](COOK_CONTRACT.md) - What each chef must produce
 - [ANTI_PATTERNS.md](ANTI_PATTERNS.md) - Common mistakes
-- Individual chef files in `.claude/chefs/`
+- Individual chef files in `.claude/agents/`
diff --git a/CLAUDE.md b/CLAUDE.md
index aba9581..58b5724 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -34,9 +34,8 @@ docs/           # Additional documentation
 ```
 
 ### Naming
-- Chefs: `<role>_chef.md` (e.g., `engineer_chef.md`)
-- Agents use `juni:` prefix (e.g., `juni:engineer_chef`)
-- Artifacts: `<slug>.<date>.cook.md`
+- Chefs: `<role>_chef.md` in `.claude/agents/` (e.g., `engineer_chef.md`)
+- Orders: `<order_id>.order.md` in `orders/` (no dates in filename)
 - Templates: lowercase with hyphens
 
 ## Definition of Done (well-done)
@@ -54,17 +53,20 @@ See [COOK_CONTRACT.md](COOK_CONTRACT.md) for full contract.
 
 ## Chefs (Roles)
 
-| Chef | Responsibility | When Active |
-|------|----------------|-------------|
-| product_chef | Scope, value, priorities | Phase 2 (Scope) |
-| ux_chef | User flows, UI impact | Phase 3 (UX) |
-| engineer_chef | Implementation plan | Phase 4 (Cooking) |
-| architect_chef | System impact, alternatives | Phase 4 (Cooking) |
-| qa_chef | Test plan, edge cases | Phase 5 (QA) |
-| security_chef | Threat assessment | Phase 6 (Security) |
-| docs_chef | Documentation updates | Phase 7 (Docs) |
-| release_chef | Versioning, changelog | Post-cooking |
-
+| Chef | Responsibility | phase_affinity |
+|------|----------------|----------------|
+| product_chef | Scope, value, priorities | scope |
+| ux_chef | User flows, UI impact | ux |
+| architect_chef | System impact, alternatives | plan |
+| engineer_chef | Implementation plan | plan |
+| qa_chef | Test plan, edge cases | test |
+| security_chef | Threat assessment | security |
+| docs_chef | Documentation updates | docs |
+| release_chef | Versioning, changelog | release |
+| sanitation_inspector_chef | Post-implementation review | inspect |
+| sous_chef | Background monitoring | monitor |
+
+All chefs output reviews using `review_v1` format. See [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md).
 See [CHEF_MATRIX.md](CHEF_MATRIX.md) for inputs/outputs.
 
 ## Anti-patterns
@@ -91,6 +93,6 @@ Since Claude Code v2.1.16, `/juni:cook` uses the Tasks API for progress tracking
 |---------|----------|
 | "No CLAUDE.md found" | Create one or ignore (uses defaults) |
 | Output too verbose | Use `--microwave` for quick fixes |
-| Chef not activating | Check `.claude/chefs/` has the file |
+| Chef not activating | Check `.claude/agents/` has the file |
 | Stuck in Phase 0 | Provide more project context |
-| Artifact not created | Check `cook/` directory exists |
+| Order not created | Check `orders/` directory exists |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d6a0a63..ae266fc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,7 +13,7 @@
    cp -r .claude/commands ~/.claude/
    cp -r .claude/skills ~/.claude/
    cp -r .claude/templates ~/.claude/
-   cp -r .claude/chefs ~/.claude/
+   cp -r .claude/agents ~/.claude/
    ```
 
 3. Test the command:
@@ -23,9 +23,9 @@
 
 ## Adding a New Agent Template
 
-1. Create a new file in `.claude/chefs/`:
+1. Create a new file in `.claude/agents/`:
    ```
-   .claude/chefs/your_chef.md
+   .claude/agents/your_chef.md
    ```
 
 2. Follow the structure:
@@ -44,7 +44,7 @@
    <what this chef contributes to the artifact>
    ```
 
-3. Update `.claude/chefs/README.md` to document the new chef.
+3. Update `.claude/agents/README.md` to document the new chef.
 
 4. Submit a PR with:
    - The new agent file
diff --git a/README.md b/README.md
index 4ea28b1..9cc075b 100644
--- a/README.md
+++ b/README.md
@@ -264,10 +264,10 @@ The inspection report is appended to the cook artifact with violations and recom
 
 ## Customizing Agents (Chefs)
 
-Create project-specific chefs in `.claude/chefs/`:
+Create project-specific chefs in `.claude/agents/`:
 
 ```
-.claude/chefs/
+.claude/agents/
   product_chef.md    # Scope decisions
   ux_chef.md         # UX review
   qa_chef.md         # Test planning
@@ -289,7 +289,7 @@ Project chefs override system-wide defaults.
 | `CLAUDE.md` | Project rules, constraints, conventions |
 | `README.md` | Project overview, architecture summary |
 | `docs/` | Architecture decisions, API specs, ADRs |
-| `.claude/chefs/` | Project-specific review chefs |
+| `.claude/agents/` | Project-specific review chefs |
 
 ---
 
diff --git a/REVIEW_CONTRACT.md b/REVIEW_CONTRACT.md
new file mode 100644
index 0000000..0ac9759
--- /dev/null
+++ b/REVIEW_CONTRACT.md
@@ -0,0 +1,197 @@
+# Review Contract
+
+This document defines the standard output format (`review_v1`) for all chef reviews.
+
+## Why Standardization Matters
+
+Without a unified format:
+- Each chef produces different output structures
+- Orchestration tools can't reliably parse reviews
+- Order files accumulate inconsistent review sections
+- Automation becomes impossible
+
+## review_v1 Format
+
+All chefs MUST output reviews in this exact structure:
+
+```yaml
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+```
+
+### Section Definitions
+
+| Section | Type | Description |
+|---------|------|-------------|
+| `verdict` | enum | `approve` \| `block` \| `request-changes` \| `needs-clarification` |
+| `must_fix` | list | Blockers that MUST be resolved before merge |
+| `should_fix` | list | Recommended improvements (non-blocking) |
+| `questions` | list | Unresolved questions requiring human input |
+| `risks` | list | Identified risks with severity (LOW/MEDIUM/HIGH) |
+| `next_step` | string | Explicit next action (e.g., "proceed to qa_chef", "escalate to human") |
+
+### Verdict Definitions
+
+| Verdict | Meaning | Effect |
+|---------|---------|--------|
+| `approve` | Ready to proceed | Unblocks next phase |
+| `block` | Critical issues found | Stops workflow until resolved |
+| `request-changes` | Issues found, fixable | Returns to previous phase for fixes |
+| `needs-clarification` | Missing information | Escalates to human for clarification |
+
+---
+
+## Markdown Output Format
+
+When writing to order files, use this exact format:
+
+```markdown
+### <chef_id> (<ISO-date>)
+
+**verdict:** approve | block | request-changes | needs-clarification
+
+**must_fix:**
+- <item 1>
+- <item 2>
+
+**should_fix:**
+- <item 1>
+
+**questions:**
+- <question requiring human input>
+
+**risks:**
+- [HIGH] <risk description>
+- [MEDIUM] <risk description>
+- [LOW] <risk description>
+
+**next_step:** <explicit next action>
+```
+
+---
+
+## Chef-Specific Addenda
+
+Chefs MAY include additional sections AFTER the required `review_v1` sections.
+These are chef-specific and NOT required for orchestration.
+
+| Chef | Optional Addenda |
+|------|------------------|
+| architect_chef | `alternatives_considered`, `trade_offs` |
+| engineer_chef | `implementation_notes`, `diagram` |
+| qa_chef | `test_cases`, `edge_cases` |
+| security_chef | `threat_assessment`, `owasp_checklist` |
+| product_chef | `scope_definition`, `user_value` |
+| docs_chef | `files_to_update`, `migration_guide` |
+
+Addenda MUST be clearly separated:
+
+```markdown
+### architect_chef (2026-01-31)
+
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:**
+- Consider caching for performance
+**questions:** (none)
+**risks:**
+- [LOW] Minor latency increase under load
+**next_step:** proceed to qa_chef
+
+---
+#### Addenda: Trade-offs
+
+- Sacrificing: Immediate consistency
+- Gaining: Better scalability
+- Acceptable because: Use case tolerates eventual consistency
+```
+
+---
+
+## Parsing Rules
+
+For tooling and automation:
+
+1. **verdict** is always on first content line after header
+2. **Sections** use bold markers (`**section:**`)
+3. **Empty sections** use `(none)` not empty string
+4. **Risks** have severity prefix in brackets
+5. **Addenda** start after horizontal rule (`---`)
+
+---
+
+## Migration from Legacy Formats
+
+### Old architect_chef format → review_v1
+
+```markdown
+# OLD (do not use)
+## System Impact
+- Modules affected: ...
+
+## Alternatives Considered
+...
+
+## Decision
+...
+
+# NEW (review_v1)
+### architect_chef (2026-01-31)
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:** (none)
+**questions:** (none)
+**risks:**
+- [LOW] Performance impact under high load
+**next_step:** proceed to engineer_chef
+
+---
+#### Addenda: Alternatives Considered
+1. **Option A**: ...
+2. **Option B** (selected): ...
+
+#### Addenda: Trade-offs
+- Sacrificing: ...
+- Gaining: ...
+```
+
+### Old qa_chef format → review_v1
+
+```markdown
+# OLD (do not use)
+### Test Cases
+1. Happy path test
+2. Edge case test
+
+# NEW (review_v1)
+### qa_chef (2026-01-31)
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:**
+- Add boundary test for max value
+**questions:** (none)
+**risks:**
+- [MEDIUM] Integration with legacy API untested
+**next_step:** proceed to security_chef
+
+---
+#### Addenda: Test Cases
+1. Happy path: User creates order successfully
+2. Edge case: Empty cart submission
+3. Boundary: Max 100 items in cart
+```
+
+---
+
+## See Also
+
+- [COOK_CONTRACT.md](COOK_CONTRACT.md) - Artifact structure
+- [CHEF_MATRIX.md](CHEF_MATRIX.md) - Phase assignments
+- `.claude/agents/` - Individual chef definitions
diff --git a/chefs/README.txt b/chefs/README.txt
deleted file mode 100644
index 217ff55..0000000
--- a/chefs/README.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-# Agents (Chefs)
-
-Agents are specialized reviewers that evaluate different aspects of a feature during the `/cook` workflow. Each agent (or "chef") has a specific role and provides structured output to the cooking artifact.
-
-## How Agents Work
-
-During cooking, Claude Code consults different agents based on the current phase:
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| Scope Approval | product_chef | Validates feature scope and value |
-| UX Planning | ux_chef | Reviews user experience impact |
-| QA Review | qa_chef | Defines test strategy |
-| Security Review | security_chef | Audits security implications |
-
-## Agent Resolution Order
-
-1. **Project-specific agents** in `<project>/.claude/chefs/`
-2. **System-wide agents** in `~/.claude/chefs/`
-
-Project agents override system defaults, allowing you to customize reviews for your specific codebase.
-
-## Creating Custom Agents
-
-Create a new `.md` file in `.claude/chefs/` with this structure:
-
-```markdown
-# Role
-<What this agent does and when it's consulted>
-
-# Questions to Ask
-- <Question 1>
-- <Question 2>
-- <Question 3>
-
-# Blockers
-<What conditions cause this agent to block progress>
-
-# Output
-<What this agent contributes to the cooking artifact>
-```
-
-## Included Agents
-
-- `product_chef.md` - Scope and value validation
-- `ux_chef.md` - User experience review
-- `qa_chef.md` - Quality assurance planning
-- `security_chef.md` - Security audit
-
-## Naming Convention
-
-For project-specific agents, use the pattern:
-```
-<project>-<role>.md
-```
-
-Example: `myapp-security_chef.md`
-
-This helps distinguish project agents from system-wide defaults.
-
-## Agent Output
-
-Each agent contributes to specific sections of the cooking artifact:
-
-| Agent | Artifact Sections |
-|-------|------------------|
-| product_chef | Product Decision, Scope |
-| ux_chef | UX Notes |
-| qa_chef | QA Plan, Test Cases |
-| security_chef | Security Review, Risk Level |
diff --git a/chefs/architect_chef.md b/chefs/architect_chef.md
deleted file mode 100644
index b5d19ce..0000000
--- a/chefs/architect_chef.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-chef_id: architect_chef
-version: 1.0.0
-
-traits:
-  risk_posture: balanced
-  quality_bar: high
-  speed_vs_correctness: correctness-first
-  verbosity: explicit
-
-non_negotiables:
-  - Trade-offs must be explicit (no hidden costs)
-  - Maximum 2-3 alternatives evaluated
-  - Reversibility preference documented
-
-allowed_scope:
-  can:
-    - Analyze system-wide impact
-    - Evaluate architectural alternatives
-    - Document trade-offs and decisions
-    - Escalate to product_chef when scope adjustment needed
-  cannot_without_human:
-    - Approve system-wide breaking changes
-    - Accept HIGH risk without mitigation
-    - Override existing architectural patterns without justification
-
-escalation:
-  to_strict_mode_when:
-    - Change affects system-wide architecture
-    - Breaking change to existing API contracts
-    - Performance implications are unclear
-  ask_for_human_when:
-    - No acceptable alternative exists
-    - Change fundamentally conflicts with system design
-    - Risk assessment shows HIGH with no viable mitigation
-
-rubric:
-  ready_for_merge:
-    - System impact documented (modules, integration points, data flow)
-    - 2-3 alternatives considered with pros/cons
-    - Decision rationale clear
-    - Trade-offs explicit (what sacrificed, what gained, why acceptable)
-
-skill_loadout:
-  preload:
-    - system-diagram
-  optional:
-    - adr-template
-  enable_optional_when:
-    - New architectural pattern introduced
-    - Existing pattern being replaced
-
-tool_policy:
-  forbidden:
-    - Implementation details
-    - Low-level code decisions
-  allowed:
-    - System-level analysis
-    - Integration planning
-    - Trade-off evaluation
----
-
-# Chef: Architect Chef
-
-Analyzes system-wide impact, evaluates alternatives, documents trade-offs, and ensures architectural consistency. Consulted for cross-cutting concerns or when engineer_chef escalates.
-
-## Inputs
-
-- Feature scope from product_chef
-- Technical concerns from engineer_chef
-- Existing architecture (docs, patterns, ADRs)
-- Project constraints from CLAUDE.md
-
-## Output Templates
-
-### Architecture Notes
-```markdown
-## System Impact
-- Modules affected: <list>
-- Integration points: <list>
-- Data flow changes: <description>
-
-## Alternatives Considered
-1. **<Option A>**
-   - Pros: <list>
-   - Cons: <list>
-
-2. **<Option B>**
-   - Pros: <list>
-   - Cons: <list>
-
-## Decision
-<chosen option> because <rationale>
-
-## Trade-offs
-- Sacrificing: <what>
-- Gaining: <what>
-- Acceptable because: <why>
-```
-
-## Artifacts
-
-- Section in cook artifact: "Trade-offs"
-- Optional: `ARCHITECTURE_NOTES.md` for significant changes
-- Diagrams only if truly necessary (prefer text)
-
-## Heuristics
-
-1. **2-3 alternatives max** - more creates decision paralysis
-2. **Explicit trade-offs** - no hidden costs
-3. **Reversibility** - prefer reversible decisions
-4. **Consistency** - align with existing patterns unless changing them intentionally
-
-## Stop Conditions
-
-Stop and mark `needs-more-cooking` if:
-- No acceptable alternative exists
-- Change fundamentally conflicts with system design
-- Risk assessment shows HIGH with no mitigation
-
-Escalate to product_chef if:
-- Trade-offs affect user experience
-- Scope needs adjustment based on technical constraints
diff --git a/chefs/product_chef.md b/chefs/product_chef.md
deleted file mode 100644
index 890e56e..0000000
--- a/chefs/product_chef.md
+++ /dev/null
@@ -1,128 +0,0 @@
----
-chef_id: product_chef
-version: 1.0.0
-
-traits:
-  risk_posture: conservative
-  quality_bar: high
-  speed_vs_correctness: correctness-first
-  verbosity: concise
-
-non_negotiables:
-  - User value must be explicitly stated
-  - Non-goals must be documented
-  - No feature without measurable success criteria
-
-allowed_scope:
-  can:
-    - Approve, reject, or defer features
-    - Define scope boundaries
-    - Prioritize based on user value
-    - Request clarification on requirements
-  cannot_without_human:
-    - Approve features involving auth/payments/PII
-    - Resolve scope conflicts between stakeholders
-    - Override explicit user requirements
-
-escalation:
-  to_strict_mode_when:
-    - Feature involves authentication or authorization
-    - Feature involves payment processing
-    - Feature involves personal data handling
-  ask_for_human_when:
-    - Scope conflicts with existing product direction
-    - Multiple valid interpretations of requirements exist
-    - Feature has unclear success metrics after clarification
-
-rubric:
-  ready_for_merge:
-    - User value statement complete (who, problem, solution, metric)
-    - Scope clearly defined with in/out boundaries
-    - Non-goals explicitly listed
-    - Decision rationale documented
-
-skill_loadout:
-  preload: []
-  optional:
-    - roadmap-analysis
-  enable_optional_when:
-    - Feature spans multiple quarters
-    - Feature affects product roadmap priorities
-
-tool_policy:
-  forbidden:
-    - Code generation
-    - Implementation decisions
-  allowed:
-    - Scope analysis
-    - Prioritization
-    - User value assessment
----
-
-# Chef: Product Chef
-
-Evaluates feature scope, validates user value, and makes approve/reject/defer decisions. Consulted during Step 2 (Ingredient Approval) in well-done mode.
-
-## Questions to Ask
-
-1. **Scope**: Is this feature within the project's defined boundaries?
-2. **Value**: Does this solve a real user problem or business need?
-3. **Priority**: Should this be done now, or deferred?
-4. **Dependencies**: Are there prerequisites that must be completed first?
-5. **Measurability**: How will we know if this feature succeeded?
-
-## Blockers
-
-Block progress (`needs-more-cooking`) if:
-
-- Feature is clearly out of scope for the project
-- No identifiable user value
-- Dependencies are unmet and blocking
-- Feature conflicts with existing product direction
-- No way to measure success or failure
-
-## Output Templates
-
-### Product Decision
-```
-Approved / Rejected / Deferred
-- Reason: <specific rationale>
-```
-
-### Scope Definition
-```markdown
-### In Scope
-- <what's included>
-
-### Out of Scope
-- <what's explicitly excluded>
-
-### Non-goals
-- <what we're intentionally not solving>
-```
-
-### User Value Statement
-```markdown
-## User Value
-- **Who**: <target user>
-- **Problem**: <what pain point>
-- **Solution**: <how this helps>
-- **Success metric**: <how we measure>
-```
-
-## Decision Criteria
-
-| Signal | Weight |
-|--------|--------|
-| User request/feedback | High |
-| Aligns with roadmap | High |
-| Technical debt reduction | Medium |
-| Nice-to-have enhancement | Low |
-| Scope creep indicator | Negative |
-
-## Heuristics
-
-1. **User value first** - no value = no feature
-2. **Explicit non-goals** - say what you won't do
-3. **Measurable success** - if you can't measure it, reconsider
-4. **Smaller is better** - scope down aggressively
diff --git a/chefs/security_chef.md b/chefs/security_chef.md
deleted file mode 100644
index 4a47902..0000000
--- a/chefs/security_chef.md
+++ /dev/null
@@ -1,167 +0,0 @@
----
-chef_id: security_chef
-version: 1.0.0
-
-traits:
-  risk_posture: conservative
-  quality_bar: high
-  speed_vs_correctness: correctness-first
-  verbosity: explicit
-
-non_negotiables:
-  - No unvalidated user input in sensitive operations
-  - No authentication or authorization bypass
-  - No secrets or credentials in code
-
-allowed_scope:
-  can:
-    - Audit security implications
-    - Identify vulnerabilities
-    - Validate security controls
-    - Classify risk levels
-    - Apply OWASP checklist
-  cannot_without_human:
-    - Approve HIGH risk without mitigation
-    - Accept auth bypass for any reason
-    - Skip security review for sensitive topics
-
-escalation:
-  to_strict_mode_when:
-    - Authentication or authorization changes
-    - Cryptography implementation
-    - Token or secret handling
-    - Payment processing
-    - PII handling
-  ask_for_human_when:
-    - Security vulnerability detected
-    - High-risk finding cannot be mitigated
-    - Trade-off between security and functionality required
-
-rubric:
-  ready_for_merge:
-    - Input validation present
-    - Auth/authz verified
-    - No data exposure paths
-    - No injection vectors
-    - Secrets protected
-    - Rate limiting applied (if applicable)
-
-skill_loadout:
-  preload:
-    - owasp-checklist
-  optional:
-    - threat-model
-  enable_optional_when:
-    - Feature involves auth or authorization
-    - Feature handles sensitive data
-    - New external integration added
-
-tool_policy:
-  forbidden:
-    - Bypass recommendations
-    - Weakening security controls
-  allowed:
-    - Vulnerability analysis
-    - Threat modeling
-    - Security audit
----
-
-# Chef: Security Chef
-
-Audits security implications, identifies vulnerabilities, and validates security controls. Consulted during Step 6 (Safety Inspection) in all cooking modes. Security blockers override all other considerations.
-
-## Questions to Ask
-
-1. **Input**: Is all user input validated and sanitized?
-2. **Auth**: Are authentication and authorization properly enforced?
-3. **Data**: Is sensitive data protected (at rest and in transit)?
-4. **Injection**: Are there any injection vectors (SQL, XSS, command)?
-5. **Exposure**: Could this expose internal data or systems?
-
-## Blockers
-
-Block progress (`needs-more-cooking`) if:
-
-- Unvalidated user input reaches sensitive operations
-- Authentication or authorization bypass possible
-- Sensitive data exposed without protection
-- Injection vulnerability present
-- Secrets or credentials in code
-- Missing rate limiting on sensitive endpoints
-
-## Output Templates
-
-### Security Review
-```markdown
-- Reviewed: yes/no
-- Issues found: <list or "none">
-- Risk level: low/medium/high
-```
-
-### Security Checklist
-```markdown
-- [ ] Input validation
-- [ ] Auth/authz verified
-- [ ] No data exposure
-- [ ] No injection vectors
-- [ ] Secrets protected
-- [ ] Rate limiting (if applicable)
-```
-
-### Threat Assessment (for sensitive features)
-```markdown
-## Threat Assessment
-### Assets at Risk
-- <what data/system is vulnerable>
-
-### Threat Actors
-- <who might exploit this>
-
-### Attack Vectors
-- <how they might attack>
-
-### Mitigations
-- <how we prevent/detect>
-```
-
-## Risk Levels
-
-| Level | Criteria | Action |
-|-------|----------|--------|
-| Low | No sensitive data, no auth | Proceed |
-| Medium | Auth adjacent, internal APIs | Review required |
-| High | Auth, payments, PII, secrets | Block until resolved |
-
-## Auto-Escalation Topics
-
-These topics always require full security review (auto-escalate from microwave):
-
-- Authentication changes
-- Authorization/permissions
-- Cryptography
-- Token handling
-- Payment processing
-- PII handling
-- Secret management
-- Network security headers
-- Storage of sensitive data
-
-## OWASP Top 10 Checklist
-
-- [ ] Injection
-- [ ] Broken Authentication
-- [ ] Sensitive Data Exposure
-- [ ] XML External Entities (XXE)
-- [ ] Broken Access Control
-- [ ] Security Misconfiguration
-- [ ] Cross-Site Scripting (XSS)
-- [ ] Insecure Deserialization
-- [ ] Using Components with Known Vulnerabilities
-- [ ] Insufficient Logging and Monitoring
-
-## Heuristics
-
-1. **Assume hostile input** - never trust user data
-2. **Least privilege** - minimal permissions needed
-3. **Defense in depth** - multiple layers of protection
-4. **Fail secure** - errors should not expose data
diff --git a/chefs/sous_chef.md b/chefs/sous_chef.md
deleted file mode 100644
index ba335be..0000000
--- a/chefs/sous_chef.md
+++ /dev/null
@@ -1,142 +0,0 @@
----
-chef_id: sous_chef
-version: 1.0.0
-
-traits:
-  risk_posture: balanced
-  quality_bar: standard
-  speed_vs_correctness: balanced
-  verbosity: minimal
-
-non_negotiables:
-  - Advisory only (no auto-fix)
-  - Drift from artifact must be reported
-  - Sensitive file changes without artifacts must be flagged
-
-allowed_scope:
-  can:
-    - Monitor for uncooked changes
-    - Detect implementation drift from plans
-    - Analyze post-mortems
-    - Provide governance suggestions
-    - Track prediction accuracy
-  cannot_without_human:
-    - Auto-fix detected issues
-    - Block commits directly
-    - Override chef decisions
-
-escalation:
-  to_strict_mode_when:
-    - Sensitive file changed without cook artifact
-    - Significant drift detected between plan and implementation
-  ask_for_human_when:
-    - Repeated violations in same area
-    - Pattern of uncooked changes detected
-    - Post-mortem reveals systemic issue
-
-rubric:
-  ready_for_merge:
-    - Change monitoring executed
-    - Drift analysis complete (if artifact exists)
-    - Violations reported (if any)
-    - Suggestions documented
-
-skill_loadout:
-  preload:
-    - drift-detector
-  optional:
-    - git-analysis
-  enable_optional_when:
-    - Monitoring mode active
-    - Post-mortem analysis requested
-
-tool_policy:
-  forbidden:
-    - Auto-fix
-    - Direct blocking
-    - Code modification
-  allowed:
-    - Monitoring
-    - Reporting
-    - Analysis
----
-
-# Chef: Sous Chef
-
-Background monitoring assistant that watches over the kitchen (codebase) to ensure cooking discipline is maintained.
-
-## Responsibilities
-
-### 1. Change Monitoring
-- Detect commits that touch sensitive files without cook artifacts
-- Alert when changes slip through without proper planning
-- Track which areas of code are frequently changed without governance
-
-### 2. Drift Detection
-- Compare implementation against artifact plans
-- Identify scope creep (unplanned file changes)
-- Flag missing implementations (planned but not done)
-
-### 3. Post-Mortem Analysis
-- Review pre-mortem predictions against actual outcomes
-- Track prediction accuracy over time
-- Surface lessons learned for future risk assessments
-
-### 4. Proactive Suggestions
-- Identify hot files that should have cook artifacts
-- Recommend areas needing more governance
-- Surface patterns from past cooks
-
-## When Active
-
-Sous Chef is invoked manually via CLI:
-
-```bash
-# Monitor for uncooked changes
-./scripts/sous-chef monitor
-
-# Check drift for an artifact
-./scripts/sous-chef drift <artifact>
-
-# Analyze post-mortem
-./scripts/sous-chef postmortem <artifact>
-
-# Get suggestions
-./scripts/sous-chef suggest
-```
-
-## Inputs
-
-| Input | Description |
-|-------|-------------|
-| Recent commits | Git history for change analysis |
-| Cook artifacts | Plans to compare against implementation |
-| Incident reports | Outcomes for post-mortem analysis |
-
-## Outputs
-
-| Output | Description |
-|--------|-------------|
-| Change report | List of uncooked sensitive changes |
-| Drift report | Plan vs implementation differences |
-| Post-mortem | Prediction accuracy analysis |
-| Suggestions | Files needing cook governance |
-
-## Philosophy
-
-Sous Chef supports the head chef by:
-- Catching what slips through the cracks
-- Maintaining quality standards
-- Learning from past experiences
-- Providing visibility into kitchen operations
-
-Sous Chef is **advisory only** - it reports and suggests but does not block or auto-fix.
-
-## Integration
-
-Sous Chef works with:
-- `cook-stats` - analytics on past artifacts
-- `cook-validate` - artifact validation
-- `/cook` - the main cooking workflow
-
-Run Sous Chef periodically (e.g., before merges, weekly reviews) to maintain kitchen discipline.
diff --git a/chefs/ux_chef.md b/chefs/ux_chef.md
deleted file mode 100644
index 870d048..0000000
--- a/chefs/ux_chef.md
+++ /dev/null
@@ -1,122 +0,0 @@
----
-chef_id: ux_chef
-version: 1.0.0
-
-traits:
-  risk_posture: balanced
-  quality_bar: standard
-  speed_vs_correctness: balanced
-  verbosity: concise
-
-non_negotiables:
-  - No breaking established patterns without justification
-  - Accessibility must be maintained
-  - User flows must have clear entry and exit points
-
-allowed_scope:
-  can:
-    - Review user experience implications
-    - Validate interaction patterns
-    - Identify accessibility concerns
-    - Suggest flow improvements
-  cannot_without_human:
-    - Approve breaking changes to established UI patterns
-    - Override accessibility requirements
-    - Approve confusing or ambiguous UI states
-
-escalation:
-  to_strict_mode_when:
-    - Change affects accessibility (WCAG compliance)
-    - Change breaks established navigation patterns
-    - Change affects error handling for user-facing flows
-  ask_for_human_when:
-    - UI pattern is ambiguous after discussion
-    - Accessibility regression cannot be avoided
-    - User flow has no clear discovery path
-
-rubric:
-  ready_for_merge:
-    - User flow documented (entry points, path, exit)
-    - Error states handled with helpful messages
-    - Loading and empty states defined
-    - Matches existing patterns or justifies deviation
-
-skill_loadout:
-  preload:
-    - accessibility-checklist
-  optional:
-    - user-research
-  enable_optional_when:
-    - New user flow introduced
-    - Major navigation change proposed
-
-tool_policy:
-  forbidden:
-    - Code implementation
-    - Architecture decisions
-  allowed:
-    - Flow diagrams
-    - UI review
-    - Accessibility audit
----
-
-# Chef: UX Chef
-
-Reviews user experience implications, validates interaction patterns, and ensures changes don't confuse users. Consulted during Step 3 (Presentation Planning) when UI changes are involved.
-
-## Questions to Ask
-
-1. **Flow**: How does this change the user's journey?
-2. **Discoverability**: Will users find and understand this feature?
-3. **Consistency**: Does this match existing patterns in the app?
-4. **Edge cases**: What happens in error states or unusual scenarios?
-5. **Accessibility**: Are there accessibility implications?
-
-## Blockers
-
-Block progress (`needs-more-cooking`) if:
-
-- Change breaks established user patterns without justification
-- No clear path for users to discover the feature
-- Significant accessibility regression
-- Confusing or ambiguous UI states
-- Missing error handling for user-facing flows
-
-## Output Templates
-
-### UX Notes
-```markdown
-- Flow: <description of user flow>
-- Entry points: <how users discover this>
-- Considerations:
-  - <UX consideration 1>
-  - <UX consideration 2>
-- Error states: <how errors are communicated>
-```
-
-## Triggered When
-
-UX review is triggered if:
-
-- New UI components are added
-- User flow changes
-- Navigation changes
-- Form or input changes
-- Error message changes
-- Any user-facing text changes
-
-## Review Checklist
-
-- [ ] Flow is intuitive
-- [ ] Labels are clear
-- [ ] Error messages are helpful
-- [ ] Loading states exist
-- [ ] Empty states handled
-- [ ] Matches existing patterns
-
-## Heuristics
-
-1. **User journey first** - understand the full flow
-2. **Consistency over novelty** - match existing patterns
-3. **Accessibility is non-negotiable** - WCAG compliance required
-4. **Error states are features** - design them intentionally
diff --git a/commands/cook.md b/commands/cook.md
index 80afb38..deea583 100644
--- a/commands/cook.md
+++ b/commands/cook.md
@@ -184,7 +184,7 @@ Step 0.0 - Artifact Created
 |------|--------|-----------|
 | CLAUDE.md | _Pending_ | |
 | README.md | _Pending_ | |
-| .claude/chefs/*.md | _Pending_ | |
+| .claude/agents/*.md | _Pending_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
@@ -435,16 +435,16 @@ This command uses a layered agent system:
 
 **Required for best results (mise en place):**
 - `CLAUDE.md` in project root - defines project rules and constraints
-- `<project>/.claude/chefs/` - project-specific review chefs
+- `<project>/.claude/agents/` - project-specific review chefs
 
 **System-wide fallbacks (always available):**
-- `~/.claude/chefs/engineer.md` - generic engineering chef
-- `~/.claude/chefs/product.md` - product scope review
-- `~/.claude/chefs/designer.md` - UX/flow review
-- `~/.claude/chefs/security.md` - security audit
-- `~/.claude/chefs/qa.md` - QA review
-- `~/.claude/chefs/architect.md` - architecture review
-- `~/.claude/chefs/docs.md` - documentation
+- `~/.claude/agents/engineer.md` - generic engineering chef
+- `~/.claude/agents/product.md` - product scope review
+- `~/.claude/agents/designer.md` - UX/flow review
+- `~/.claude/agents/security.md` - security audit
+- `~/.claude/agents/qa.md` - QA review
+- `~/.claude/agents/architect.md` - architecture review
+- `~/.claude/agents/docs.md` - documentation
 
 **Resolution order:** Project-specific agents override system-wide agents.
 
diff --git a/orders/_TEMPLATE.order.md b/orders/_TEMPLATE.order.md
index b3bf2d2..8da0152 100644
--- a/orders/_TEMPLATE.order.md
+++ b/orders/_TEMPLATE.order.md
@@ -1,56 +1,21 @@
 ---
-# =============================================================================
-# ORDER METADATA
-# =============================================================================
-
-# REQUIRED
 order_id: "REPLACE_WITH_GENERATED_ID"
 title: "REPLACE_WITH_TITLE"
-status: "raw"                          # raw | cooking | blocked | ready-for-merge | plated
+status: "raw"
 created_at: "REPLACE_WITH_TIMESTAMP"
-created_by: "REPLACE_WITH_USER"
 
-# PRIMARY CHEF (who's cooking this order)
-chef_id: ""                            # e.g., "engineer_chef"
-recipe_id: ""                          # optional, if using recipes
+owner: ""
+priority: "medium"
+labels: []
+due_date: ""
 
-# FLAGS - trigger conditional rules in chef-mapping.yaml
-# Common flags: auth, payments, pii, crypto, ui, ux, prod, outage
 flags: []
 
-# =============================================================================
-# TRACKER INTEGRATION (OPTIONAL)
-# =============================================================================
-# Populated by `cook jira fetch` or manual entry
-# tracker.snapshot is AUTO-UPDATED ONLY - never manually edit
-
-# tracker:
-#   type: "jira"                       # jira | github | linear
-#   key: "PROJ-123"
-#   url: "https://jira.example.com/browse/PROJ-123"
-#   fetched_at: "2026-01-30T12:00:00Z"
-#   snapshot:                          # AUTO-UPDATED by tracker sync
-#     title: ""
-#     issue_type: ""                   # Bug, Story, Task, Incident, etc.
-#     priority: ""
-#     labels: []
-#     components: []
-
-# =============================================================================
-# COOK ARTIFACT LINK
-# =============================================================================
-
-# cook_artifact: "cook/<slug>.<date>.cook.md"
-# cook_status: ""                      # well-done | needs-more-cooking | etc.
-
-# =============================================================================
-# LOCAL METADATA
-# =============================================================================
-
-priority: "medium"                     # low | medium | high
-labels: []
-assignee: ""
-due_date: ""
+tracker:
+  type: ""
+  key: ""
+  url: ""
+  fetched_at: ""
 ---
 
 # Order: REPLACE_WITH_TITLE
@@ -78,13 +43,18 @@ due_date: ""
 
 
 ## Reviews
-<!-- Chef reviews appended here by /juni:cook -->
-<!-- Format:
-### <chef_id> (<date>)
-- verdict: approve|block|request-changes|clarify
-- must_fix: [...]
-- risks: [...]
-- next_step: ...
+<!-- Chef reviews in review_v1 format. See REVIEW_CONTRACT.md -->
+<!-- Example:
+### architect_chef (2026-01-31)
+
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:**
+- Consider caching
+**questions:** (none)
+**risks:**
+- [LOW] Minor latency increase
+**next_step:** proceed to engineer_chef
 -->
 
 
@@ -95,5 +65,4 @@ due_date: ""
 
 ---
 ## Related
-<!-- Links to artifacts, PRs, related orders -->
-
+<!-- Links to PRs, docs, related orders -->
diff --git a/skills/cook/SKILL.md b/skills/cook/SKILL.md
index 1e75a2d..a65ec20 100644
--- a/skills/cook/SKILL.md
+++ b/skills/cook/SKILL.md
@@ -88,7 +88,7 @@ Step 0.0 - Artifact Created
 |------|--------|-----------|
 | CLAUDE.md | _Pending_ | |
 | README.md | _Pending_ | |
-| .claude/chefs/*.md | _Pending_ | |
+| .claude/agents/*.md | _Pending_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
@@ -653,11 +653,11 @@ Search for and read the following files (do not fail if missing):
 3. `ENGINEERING.md` - engineering standards
 4. `README.md` - project overview
 5. `docs/**/*.md` - architecture, ADRs, decisions
-6. `.claude/chefs/*.md` - project-specific chefs
+6. `.claude/agents/*.md` - project-specific chefs
 
 **Chef Resolution Order:**
-1. Project-specific chefs in `<project>/.claude/chefs/`
-2. System-wide chefs in `~/.claude/chefs/`
+1. Project-specific chefs in `<project>/.claude/agents/`
+2. System-wide chefs in `~/.claude/agents/`
 
 **System-Wide Chefs Available:**
 - `engineer.md` - Head chef (implementation)
@@ -1171,8 +1171,8 @@ microwave
 
 **For each cooking phase, use chefs in this priority:**
 
-1. **Project-specific chef** (if exists): `<project>/.claude/chefs/<project>-<role>.md`
-2. **System-wide chef** (fallback): `~/.claude/chefs/<role>.md`
+1. **Project-specific chef** (if exists): `<project>/.claude/agents/<project>-<role>.md`
+2. **System-wide chef** (fallback): `~/.claude/agents/<role>.md`
 
 | Phase | Project Chef | System Chef |
 |-------|-------------|-------------|
diff --git a/skills/feature-development/SKILL.md b/skills/feature-development/SKILL.md
index 0024795..ed72dbd 100644
--- a/skills/feature-development/SKILL.md
+++ b/skills/feature-development/SKILL.md
@@ -87,7 +87,7 @@ Step 0.0 - Artifact Created
 |------|--------|-----------|
 | CLAUDE.md | _Pending_ | |
 | README.md | _Pending_ | |
-| .claude/chefs/*.md | _Pending_ | |
+| .claude/agents/*.md | _Pending_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
@@ -650,11 +650,11 @@ Search for and read the following files (do not fail if missing):
 3. `ENGINEERING.md` - engineering standards
 4. `README.md` - project overview
 5. `docs/**/*.md` - architecture, ADRs, decisions
-6. `.claude/chefs/*.md` - project-specific chefs
+6. `.claude/agents/*.md` - project-specific chefs
 
 **Chef Resolution Order:**
-1. Project-specific chefs in `<project>/.claude/chefs/`
-2. System-wide chefs in `~/.claude/chefs/`
+1. Project-specific chefs in `<project>/.claude/agents/`
+2. System-wide chefs in `~/.claude/agents/`
 
 **System-Wide Chefs Available:**
 - `engineer.md` - Head chef (implementation)
@@ -1086,8 +1086,8 @@ microwave
 
 **For each cooking phase, use chefs in this priority:**
 
-1. **Project-specific chef** (if exists): `<project>/.claude/chefs/<project>-<role>.md`
-2. **System-wide chef** (fallback): `~/.claude/chefs/<role>.md`
+1. **Project-specific chef** (if exists): `<project>/.claude/agents/<project>-<role>.md`
+2. **System-wide chef** (fallback): `~/.claude/agents/<role>.md`
 
 | Phase | Project Chef | System Chef |
 |-------|-------------|-------------|
diff --git a/tests/test_chef_contracts.py b/tests/test_chef_contracts.py
index d59aac5..5c3714a 100644
--- a/tests/test_chef_contracts.py
+++ b/tests/test_chef_contracts.py
@@ -283,18 +283,13 @@ def test_chef_file(filepath: Path) -> Tuple[str, List[str], List[str]]:
 
 
 def find_chef_files(base_path: Path) -> List[Path]:
-    """Find all chef files in chefs directories."""
+    """Find all chef files in agents directory."""
     files = []
 
-    # Check .claude/chefs/
-    claude_chefs = base_path / ".claude" / "chefs"
-    if claude_chefs.exists():
-        files.extend(claude_chefs.glob("*_chef.md"))
-
-    # Check chefs/ (root)
-    root_chefs = base_path / "chefs"
-    if root_chefs.exists():
-        files.extend(root_chefs.glob("*_chef.md"))
+    # Check .claude/agents/
+    agents_dir = base_path / ".claude" / "agents"
+    if agents_dir.exists():
+        files.extend(agents_dir.glob("*_chef.md"))
 
     return sorted(set(files))
 
diff --git a/tests/test_chef_sync.py b/tests/test_chef_sync.py
index ac87ff2..8cb86ac 100644
--- a/tests/test_chef_sync.py
+++ b/tests/test_chef_sync.py
@@ -1,14 +1,14 @@
 #!/usr/bin/env python3
 """
-Tests for chef file synchronization between directories.
-Ensures .claude/chefs/ and chefs/ are in sync.
+Tests for chef files in .claude/agents/.
+Verifies that all expected chef files exist with correct structure.
 
 Run: python3 tests/test_chef_sync.py
 """
 
 import os
 import sys
-import hashlib
+import re
 from pathlib import Path
 
 GREEN = "\033[92m"
@@ -16,72 +16,86 @@
 YELLOW = "\033[93m"
 RESET = "\033[0m"
 
+EXPECTED_CHEFS = [
+    "architect_chef.md",
+    "docs_chef.md",
+    "engineer_chef.md",
+    "product_chef.md",
+    "qa_chef.md",
+    "release_chef.md",
+    "sanitation_inspector_chef.md",
+    "security_chef.md",
+    "sous_chef.md",
+    "ux_chef.md",
+]
+
+REQUIRED_FIELDS = [
+    "chef_id",
+    "version",
+    "phase_affinity",
+    "output_contract",
+    "traits",
+    "non_negotiables",
+    "allowed_scope",
+    "escalation",
+    "rubric",
+]
+
+
+def check_chef_structure(filepath: Path) -> list[str]:
+    """Check if chef file has required YAML fields."""
+    content = filepath.read_text()
+    errors = []
+
+    for field in REQUIRED_FIELDS:
+        if f"{field}:" not in content:
+            errors.append(f"Missing field: {field}")
+
+    # Check for review_v1 output contract
+    if "format: review_v1" not in content:
+        errors.append("Missing output_contract format: review_v1")
 
-def get_file_hash(filepath: Path) -> str:
-    """Get MD5 hash of file content."""
-    return hashlib.md5(filepath.read_bytes()).hexdigest()
+    return errors
 
 
 def main():
     script_dir = Path(__file__).parent
     project_root = script_dir.parent
 
-    claude_chefs_dir = project_root / ".claude" / "chefs"
-    root_chefs_dir = project_root / "chefs"
+    agents_dir = project_root / ".claude" / "agents"
 
     print(f"\n{'='*60}")
-    print("Chef File Synchronization Test")
+    print("Chef Files Validation Test")
     print(f"{'='*60}\n")
 
-    if not claude_chefs_dir.exists():
-        print(f"{RED}.claude/chefs/ does not exist{RESET}")
+    if not agents_dir.exists():
+        print(f"{RED}.claude/agents/ does not exist{RESET}")
         sys.exit(1)
 
-    if not root_chefs_dir.exists():
-        print(f"{YELLOW}chefs/ does not exist - skipping sync check{RESET}")
-        sys.exit(0)
+    # Get all chef files
+    chef_files = {f.name: f for f in agents_dir.glob("*_chef.md")}
 
-    # Get all chef files from .claude/chefs/
-    claude_chefs = {f.name: f for f in claude_chefs_dir.glob("*_chef.md")}
-    root_chefs = {f.name: f for f in root_chefs_dir.glob("*_chef.md")}
+    print(f"Found {len(chef_files)} chef files in .claude/agents/\n")
 
     errors = []
     warnings = []
 
-    # Check for missing files
-    missing_in_root = set(claude_chefs.keys()) - set(root_chefs.keys())
-    missing_in_claude = set(root_chefs.keys()) - set(claude_chefs.keys())
-
-    for name in missing_in_root:
-        warnings.append(f"Missing in chefs/: {name}")
-
-    for name in missing_in_claude:
-        warnings.append(f"Missing in .claude/chefs/: {name}")
-
-    # Check for content differences
-    common = set(claude_chefs.keys()) & set(root_chefs.keys())
-    out_of_sync = []
-
-    for name in sorted(common):
-        claude_hash = get_file_hash(claude_chefs[name])
-        root_hash = get_file_hash(root_chefs[name])
-
-        if claude_hash != root_hash:
-            out_of_sync.append(name)
-            errors.append(f"OUT OF SYNC: {name}")
+    # Check for expected chefs
+    for expected in EXPECTED_CHEFS:
+        if expected not in chef_files:
+            errors.append(f"Missing expected chef: {expected}")
 
-    # Print results
-    print(f"Files in .claude/chefs/: {len(claude_chefs)}")
-    print(f"Files in chefs/: {len(root_chefs)}")
-    print(f"Common files: {len(common)}")
-    print()
+    # Check each chef file structure
+    for name, filepath in sorted(chef_files.items()):
+        structure_errors = check_chef_structure(filepath)
 
-    for name in sorted(common):
-        if name in out_of_sync:
-            status = f"{RED}OUT OF SYNC{RESET}"
+        if structure_errors:
+            print(f"  [{RED}INVALID{RESET}] {name}")
+            for err in structure_errors:
+                print(f"      - {err}")
+            errors.extend([f"{name}: {e}" for e in structure_errors])
         else:
-            status = f"{GREEN}IN SYNC{RESET}"
-        print(f"  [{status}] {name}")
+            print(f"  [{GREEN}VALID{RESET}] {name}")
 
     if warnings:
         print(f"\n{YELLOW}Warnings:{RESET}")
@@ -95,11 +109,10 @@ def main():
 
     print(f"\n{'='*60}")
     if errors:
-        print(f"{RED}SYNC CHECK FAILED{RESET}")
-        print(f"Run: cp .claude/chefs/*_chef.md chefs/")
+        print(f"{RED}VALIDATION FAILED{RESET}")
         sys.exit(1)
     else:
-        print(f"{GREEN}All common files are in sync{RESET}")
+        print(f"{GREEN}All chef files are valid{RESET}")
         sys.exit(0)
 
 

From da060ffee874f91011dba77e7097dc1a501c96b3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Feb 2026 08:59:28 +0000
Subject: [PATCH 02/14] fix: Remove irrelevant k8s reference from
 architect_chef example

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/agents/architect_chef.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/agents/architect_chef.md b/.claude/agents/architect_chef.md
index ea811ee..1ce231e 100644
--- a/.claude/agents/architect_chef.md
+++ b/.claude/agents/architect_chef.md
@@ -115,7 +115,7 @@ Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
 #### Addenda: Trade-offs
 - Sacrificing: Operational simplicity
 - Gaining: Independent scaling
-- Acceptable because: Team has k8s experience
+- Acceptable because: Growth projections justify complexity
 ```
 
 ## Artifacts

From e2ef47690169a0bc5b7ea86a1a15f49b7ca19af3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Feb 2026 09:05:54 +0000
Subject: [PATCH 03/14] refactor: Use generic examples instead of
 domain-specific ones

Replace e-commerce examples (cart, checkout, items) with abstract
placeholders that work for any project type.

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/agents/architect_chef.md | 12 ++++++------
 .claude/agents/qa_chef.md        | 20 ++++++++++----------
 REVIEW_CONTRACT.md               |  8 ++++----
 3 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/.claude/agents/architect_chef.md b/.claude/agents/architect_chef.md
index 1ce231e..34d8685 100644
--- a/.claude/agents/architect_chef.md
+++ b/.claude/agents/architect_chef.md
@@ -101,7 +101,7 @@ Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
 **verdict:** approve
 **must_fix:** (none)
 **should_fix:**
-- Consider connection pooling for database layer
+- Consider caching for frequently accessed data
 **questions:** (none)
 **risks:**
 - [LOW] Minor latency increase under high load
@@ -109,13 +109,13 @@ Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
 
 ---
 #### Addenda: Alternatives Considered
-1. **Monolithic approach** - Rejected (scaling issues)
-2. **Microservices** (selected) - Better isolation
+1. **Option A** - Rejected (maintainability concerns)
+2. **Option B** (selected) - Better separation of concerns
 
 #### Addenda: Trade-offs
-- Sacrificing: Operational simplicity
-- Gaining: Independent scaling
-- Acceptable because: Growth projections justify complexity
+- Sacrificing: Initial simplicity
+- Gaining: Long-term flexibility
+- Acceptable because: Requirements indicate future extensibility needs
 ```
 
 ## Artifacts
diff --git a/.claude/agents/qa_chef.md b/.claude/agents/qa_chef.md
index 0a1d32c..f2c9db5 100644
--- a/.claude/agents/qa_chef.md
+++ b/.claude/agents/qa_chef.md
@@ -112,29 +112,29 @@ Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
 **verdict:** approve
 **must_fix:** (none)
 **should_fix:**
-- Add boundary test for max cart items
+- Add boundary test for max input length
 **questions:** (none)
 **risks:**
-- [MEDIUM] Integration with legacy API needs manual verification
+- [MEDIUM] External service integration needs manual verification
 **next_step:** proceed to security_chef
 
 ---
 #### Addenda: Test Cases
 
-1. **Happy path**: User creates order with valid items
-2. **Edge case**: Empty cart submission returns error
-3. **Boundary**: Max 100 items in cart
+1. **Happy path**: Operation completes with valid input
+2. **Edge case**: Empty input returns appropriate error
+3. **Boundary**: Max allowed value handled correctly
 
 #### Addenda: Edge Cases
 
-- Concurrent cart modifications
-- Session expiry during checkout
-- Invalid coupon code
+- Concurrent modifications
+- Session/token expiry mid-operation
+- Invalid configuration
 
 #### Addenda: Acceptance Criteria
 
-- [ ] Given valid cart, when user clicks checkout, then order is created
-- [ ] Given empty cart, when user clicks checkout, then error is shown
+- [ ] Given valid input, when action triggered, then expected result occurs
+- [ ] Given invalid input, when action triggered, then error is shown
 ```
 
 ## Test Categories
diff --git a/REVIEW_CONTRACT.md b/REVIEW_CONTRACT.md
index 0ac9759..f3e73fc 100644
--- a/REVIEW_CONTRACT.md
+++ b/REVIEW_CONTRACT.md
@@ -178,14 +178,14 @@ For tooling and automation:
 - Add boundary test for max value
 **questions:** (none)
 **risks:**
-- [MEDIUM] Integration with legacy API untested
+- [MEDIUM] External integration needs manual verification
 **next_step:** proceed to security_chef
 
 ---
 #### Addenda: Test Cases
-1. Happy path: User creates order successfully
-2. Edge case: Empty cart submission
-3. Boundary: Max 100 items in cart
+1. Happy path: Operation completes successfully
+2. Edge case: Empty input handled
+3. Boundary: Max allowed value
 ```
 
 ---

From a32427b5a985282ac21cb37ceb9d5f95aa0b566d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Feb 2026 09:49:12 +0000
Subject: [PATCH 04/14] feat: Add mandatory chef loading instructions to cook
 command

Each step now explicitly requires reading the corresponding chef file
before execution. This ensures chef rules (non_negotiables, rubric,
output_contract) are loaded into context rather than relying on the
model to implicitly "know" which chef to apply.

Addresses the Vercel finding that skills aren't invoked 56% of the time
when left to model discretion.

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/commands/cook.md | 25 +++++++++++++++++++++++--
 commands/cook.md         | 25 +++++++++++++++++++++++--
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 9b7a414..85ad480 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -381,8 +381,29 @@ _Pending..._
 
 Only AFTER artifact exists:
 1. Run each cooking phase
-2. Update artifact after EACH phase
-3. Clearly label each cooking phase in output
+2. **CRITICAL: Read the chef file BEFORE each phase** (see Chef Loading below)
+3. Update artifact after EACH phase
+4. Clearly label each cooking phase in output
+
+#### Chef Loading (MANDATORY)
+
+Before executing each step, **READ the corresponding chef file** to load its rules into context:
+
+| Step | Chef to Load | Command |
+|------|--------------|---------|
+| Step 2 (Product) | product_chef | `Read(.claude/agents/product_chef.md)` |
+| Step 3 (UX) | ux_chef | `Read(.claude/agents/ux_chef.md)` |
+| Step 4 (Plan) | architect_chef + engineer_chef | `Read(.claude/agents/architect_chef.md)` then `Read(.claude/agents/engineer_chef.md)` |
+| Step 5 (QA) | qa_chef | `Read(.claude/agents/qa_chef.md)` |
+| Step 6 (Security) | security_chef | `Read(.claude/agents/security_chef.md)` |
+| Step 7 (Docs) | docs_chef | `Read(.claude/agents/docs_chef.md)` |
+
+**Why this matters:** Chef files contain `non_negotiables`, `rubric`, and `output_contract` that MUST be applied. Without reading them, you're cooking blind.
+
+After reading, apply:
+- `non_negotiables` - rules that cannot be violated
+- `rubric.ready_for_merge` - checklist that must pass
+- `output_contract` - review format (review_v1)
 
 ### Step 3: Finalize
 
diff --git a/commands/cook.md b/commands/cook.md
index deea583..a3f0fa2 100644
--- a/commands/cook.md
+++ b/commands/cook.md
@@ -381,8 +381,29 @@ _Pending..._
 
 Only AFTER artifact exists:
 1. Run each cooking phase
-2. Update artifact after EACH phase
-3. Clearly label each cooking phase in output
+2. **CRITICAL: Read the chef file BEFORE each phase** (see Chef Loading below)
+3. Update artifact after EACH phase
+4. Clearly label each cooking phase in output
+
+#### Chef Loading (MANDATORY)
+
+Before executing each step, **READ the corresponding chef file** to load its rules into context:
+
+| Step | Chef to Load | Command |
+|------|--------------|---------|
+| Step 2 (Product) | product_chef | `Read(.claude/agents/product_chef.md)` |
+| Step 3 (UX) | ux_chef | `Read(.claude/agents/ux_chef.md)` |
+| Step 4 (Plan) | architect_chef + engineer_chef | `Read(.claude/agents/architect_chef.md)` then `Read(.claude/agents/engineer_chef.md)` |
+| Step 5 (QA) | qa_chef | `Read(.claude/agents/qa_chef.md)` |
+| Step 6 (Security) | security_chef | `Read(.claude/agents/security_chef.md)` |
+| Step 7 (Docs) | docs_chef | `Read(.claude/agents/docs_chef.md)` |
+
+**Why this matters:** Chef files contain `non_negotiables`, `rubric`, and `output_contract` that MUST be applied. Without reading them, you're cooking blind.
+
+After reading, apply:
+- `non_negotiables` - rules that cannot be violated
+- `rubric.ready_for_merge` - checklist that must pass
+- `output_contract` - review format (review_v1)
 
 ### Step 3: Finalize
 

From 4e012f6dc2756f0c8bb7f9605113ea8789930137 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Feb 2026 10:03:57 +0000
Subject: [PATCH 05/14] feat: Add dynamic chef resolution for custom project
 locations

Chef loading now follows resolution order:
1. Project-specific: .claude/agents/<role>_chef.md
2. System-wide: ~/.claude/agents/<role>_chef.md
3. Custom naming: .claude/agents/*<role>*.md
4. Graceful fallback: proceed with warning if not found

This allows users to define their own chefs in any supported location
without breaking the cook workflow.

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/commands/cook.md | 28 ++++++++++++++++++----------
 commands/cook.md         | 28 ++++++++++++++++++----------
 2 files changed, 36 insertions(+), 20 deletions(-)

diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 85ad480..2335f43 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -387,16 +387,24 @@ Only AFTER artifact exists:
 
 #### Chef Loading (MANDATORY)
 
-Before executing each step, **READ the corresponding chef file** to load its rules into context:
-
-| Step | Chef to Load | Command |
-|------|--------------|---------|
-| Step 2 (Product) | product_chef | `Read(.claude/agents/product_chef.md)` |
-| Step 3 (UX) | ux_chef | `Read(.claude/agents/ux_chef.md)` |
-| Step 4 (Plan) | architect_chef + engineer_chef | `Read(.claude/agents/architect_chef.md)` then `Read(.claude/agents/engineer_chef.md)` |
-| Step 5 (QA) | qa_chef | `Read(.claude/agents/qa_chef.md)` |
-| Step 6 (Security) | security_chef | `Read(.claude/agents/security_chef.md)` |
-| Step 7 (Docs) | docs_chef | `Read(.claude/agents/docs_chef.md)` |
+Before executing each step, **load the corresponding chef** following resolution order:
+
+| Step | Chef Role | Resolution Order |
+|------|-----------|------------------|
+| Step 2 (Product) | product_chef | 1. `.claude/agents/product_chef.md` 2. `~/.claude/agents/product_chef.md` |
+| Step 3 (UX) | ux_chef | 1. `.claude/agents/ux_chef.md` 2. `~/.claude/agents/ux_chef.md` |
+| Step 4 (Plan) | architect_chef, engineer_chef | Load both in order |
+| Step 5 (QA) | qa_chef | 1. `.claude/agents/qa_chef.md` 2. `~/.claude/agents/qa_chef.md` |
+| Step 6 (Security) | security_chef | 1. `.claude/agents/security_chef.md` 2. `~/.claude/agents/security_chef.md` |
+| Step 7 (Docs) | docs_chef | 1. `.claude/agents/docs_chef.md` 2. `~/.claude/agents/docs_chef.md` |
+
+**Resolution algorithm:**
+```
+1. Try: Glob(".claude/agents/<role>_chef.md")
+2. If not found, try: Glob("~/.claude/agents/<role>_chef.md")
+3. If not found, try: Glob(".claude/agents/*<role>*.md") # custom naming
+4. If still not found: proceed without chef (warn in artifact)
+```
 
 **Why this matters:** Chef files contain `non_negotiables`, `rubric`, and `output_contract` that MUST be applied. Without reading them, you're cooking blind.
 
diff --git a/commands/cook.md b/commands/cook.md
index a3f0fa2..2a8365c 100644
--- a/commands/cook.md
+++ b/commands/cook.md
@@ -387,16 +387,24 @@ Only AFTER artifact exists:
 
 #### Chef Loading (MANDATORY)
 
-Before executing each step, **READ the corresponding chef file** to load its rules into context:
-
-| Step | Chef to Load | Command |
-|------|--------------|---------|
-| Step 2 (Product) | product_chef | `Read(.claude/agents/product_chef.md)` |
-| Step 3 (UX) | ux_chef | `Read(.claude/agents/ux_chef.md)` |
-| Step 4 (Plan) | architect_chef + engineer_chef | `Read(.claude/agents/architect_chef.md)` then `Read(.claude/agents/engineer_chef.md)` |
-| Step 5 (QA) | qa_chef | `Read(.claude/agents/qa_chef.md)` |
-| Step 6 (Security) | security_chef | `Read(.claude/agents/security_chef.md)` |
-| Step 7 (Docs) | docs_chef | `Read(.claude/agents/docs_chef.md)` |
+Before executing each step, **load the corresponding chef** following resolution order:
+
+| Step | Chef Role | Resolution Order |
+|------|-----------|------------------|
+| Step 2 (Product) | product_chef | 1. `.claude/agents/product_chef.md` 2. `~/.claude/agents/product_chef.md` |
+| Step 3 (UX) | ux_chef | 1. `.claude/agents/ux_chef.md` 2. `~/.claude/agents/ux_chef.md` |
+| Step 4 (Plan) | architect_chef, engineer_chef | Load both in order |
+| Step 5 (QA) | qa_chef | 1. `.claude/agents/qa_chef.md` 2. `~/.claude/agents/qa_chef.md` |
+| Step 6 (Security) | security_chef | 1. `.claude/agents/security_chef.md` 2. `~/.claude/agents/security_chef.md` |
+| Step 7 (Docs) | docs_chef | 1. `.claude/agents/docs_chef.md` 2. `~/.claude/agents/docs_chef.md` |
+
+**Resolution algorithm:**
+```
+1. Try: Glob(".claude/agents/<role>_chef.md")
+2. If not found, try: Glob("~/.claude/agents/<role>_chef.md")
+3. If not found, try: Glob(".claude/agents/*<role>*.md") # custom naming
+4. If still not found: proceed without chef (warn in artifact)
+```
 
 **Why this matters:** Chef files contain `non_negotiables`, `rubric`, and `output_contract` that MUST be applied. Without reading them, you're cooking blind.
 

From 539ab77acf286e0598dd09a591425738cfada47f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Feb 2026 11:12:08 +0000
Subject: [PATCH 06/14] docs: Explicit two-layer architecture (narrative +
 operational)

Make explicit that cook uses a hybrid approach:
- CLAUDE.md = Narrative Layer (like AGENTS.md) - loaded in Phase 0
- Chefs = Operational Layer (contracts) - loaded per-phase

This addresses Vercel's finding that global context outperforms
local skills, while maintaining the operational rigor of contracts.

Phase 0 now explicitly states it loads the "narrative layer".
Chef Loading section explicitly states it loads "operational contracts".

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/commands/cook.md | 22 ++++++++++++++++------
 CLAUDE.md                | 29 +++++++++++++++++++++++++++++
 commands/cook.md         | 22 ++++++++++++++++------
 3 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 2335f43..11f9e02 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -179,12 +179,20 @@ Step 0.0 - Artifact Created
 
 # Phase 0 - Project Policy & Context
 
+**This phase loads the NARRATIVE LAYER - global project context.**
+
+Read CLAUDE.md FIRST. This is your "AGENTS.md" - it tells you:
+- What the project does
+- How the team works
+- What patterns to follow
+- What to avoid
+
 ## Sources Scanned
-| File | Status | Key Rules |
-|------|--------|-----------|
-| CLAUDE.md | _Pending_ | |
-| README.md | _Pending_ | |
-| .claude/agents/*.md | _Pending_ | |
+| File | Purpose | Status | Key Rules |
+|------|---------|--------|-----------|
+| CLAUDE.md | **Narrative context** (goals, architecture, conventions) | _Pending_ | |
+| README.md | Public documentation | _Pending_ | |
+| .claude/agents/*.md | Chef contracts (loaded per-phase, not here) | _Noted_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
@@ -385,7 +393,9 @@ Only AFTER artifact exists:
 3. Update artifact after EACH phase
 4. Clearly label each cooking phase in output
 
-#### Chef Loading (MANDATORY)
+#### Chef Loading (MANDATORY) - Operational Layer
+
+**Phase 0 loaded the narrative (CLAUDE.md). Now load operational contracts (chefs).**
 
 Before executing each step, **load the corresponding chef** following resolution order:
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 58b5724..4c402b8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,35 @@ This repo contains the **juni** plugin - a Claude Code plugin suite combining:
 - `/juni:cook` - Structured feature development workflows
 - `/juni:guard` - Epistemic safety for JSON data
 
+## Architecture: Two-Layer Context System
+
+Cook uses a **hybrid approach** combining narrative context with operational contracts:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ CLAUDE.md (Narrative Layer)                             │
+│ "What we build, why, how we work"                       │
+│ → Global project context, loaded in Phase 0             │
+└─────────────────────────────────────────────────────────┘
+                         ↓
+              Phase 0: Load project context
+                         ↓
+┌─────────────────────────────────────────────────────────┐
+│ .claude/agents/*_chef.md (Operational Layer)            │
+│ non_negotiables, escalation, rubric, output_contract    │
+│ → Per-phase contracts, loaded before each step          │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Why two layers?**
+
+| Layer | Purpose | When Loaded |
+|-------|---------|-------------|
+| CLAUDE.md | Narrative context - goals, architecture, conventions | Once at start (Phase 0) |
+| Chefs | Operational contracts - rules, escalations, outputs | Per-phase as needed |
+
+This combines the cognitive benefits of global context (like AGENTS.md) with the operational rigor of contractual skills.
+
 ## Quick Start
 
 ```bash
diff --git a/commands/cook.md b/commands/cook.md
index 2a8365c..02704ed 100644
--- a/commands/cook.md
+++ b/commands/cook.md
@@ -179,12 +179,20 @@ Step 0.0 - Artifact Created
 
 # Phase 0 - Project Policy & Context
 
+**This phase loads the NARRATIVE LAYER - global project context.**
+
+Read CLAUDE.md FIRST. This is your "AGENTS.md" - it tells you:
+- What the project does
+- How the team works
+- What patterns to follow
+- What to avoid
+
 ## Sources Scanned
-| File | Status | Key Rules |
-|------|--------|-----------|
-| CLAUDE.md | _Pending_ | |
-| README.md | _Pending_ | |
-| .claude/agents/*.md | _Pending_ | |
+| File | Purpose | Status | Key Rules |
+|------|---------|--------|-----------|
+| CLAUDE.md | **Narrative context** (goals, architecture, conventions) | _Pending_ | |
+| README.md | Public documentation | _Pending_ | |
+| .claude/agents/*.md | Chef contracts (loaded per-phase, not here) | _Noted_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
@@ -385,7 +393,9 @@ Only AFTER artifact exists:
 3. Update artifact after EACH phase
 4. Clearly label each cooking phase in output
 
-#### Chef Loading (MANDATORY)
+#### Chef Loading (MANDATORY) - Operational Layer
+
+**Phase 0 loaded the narrative (CLAUDE.md). Now load operational contracts (chefs).**
 
 Before executing each step, **load the corresponding chef** following resolution order:
 

From 543aaa48b603f742c0e8c036a3473c0732826edd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Feb 2026 11:13:19 +0000
Subject: [PATCH 07/14] feat: Support AGENTS.md as alternative to CLAUDE.md

Phase 0 now checks for narrative context in order:
1. CLAUDE.md - Claude Code native format (preferred)
2. AGENTS.md - Vercel/industry convention (supported)
3. README.md - fallback if neither exists

This allows projects using Vercel's AGENTS.md convention to work
seamlessly with cook without requiring CLAUDE.md.

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/commands/cook.md | 12 +++++++++---
 CLAUDE.md                |  9 +++++++--
 commands/cook.md         | 12 +++++++++---
 3 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 11f9e02..6bea42e 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -181,7 +181,12 @@ Step 0.0 - Artifact Created
 
 **This phase loads the NARRATIVE LAYER - global project context.**
 
-Read CLAUDE.md FIRST. This is your "AGENTS.md" - it tells you:
+Load narrative context in this order (first found wins):
+1. `CLAUDE.md` - Claude Code native format
+2. `AGENTS.md` - Vercel/industry convention
+3. `README.md` - fallback if neither exists
+
+This tells you:
 - What the project does
 - How the team works
 - What patterns to follow
@@ -190,8 +195,9 @@ Read CLAUDE.md FIRST. This is your "AGENTS.md" - it tells you:
 ## Sources Scanned
 | File | Purpose | Status | Key Rules |
 |------|---------|--------|-----------|
-| CLAUDE.md | **Narrative context** (goals, architecture, conventions) | _Pending_ | |
-| README.md | Public documentation | _Pending_ | |
+| CLAUDE.md | **Narrative context** (primary) | _Pending_ | |
+| AGENTS.md | **Narrative context** (alternative) | _Pending_ | |
+| README.md | Public documentation (fallback) | _Pending_ | |
 | .claude/agents/*.md | Chef contracts (loaded per-phase, not here) | _Noted_ | |
 
 ## Hard Rules (must not be violated)
diff --git a/CLAUDE.md b/CLAUDE.md
index 4c402b8..008767d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,7 +12,7 @@ Cook uses a **hybrid approach** combining narrative context with operational con
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│ CLAUDE.md (Narrative Layer)                             │
+│ CLAUDE.md or AGENTS.md (Narrative Layer)                │
 │ "What we build, why, how we work"                       │
 │ → Global project context, loaded in Phase 0             │
 └─────────────────────────────────────────────────────────┘
@@ -26,11 +26,16 @@ Cook uses a **hybrid approach** combining narrative context with operational con
 └─────────────────────────────────────────────────────────┘
 ```
 
+**Narrative file resolution:**
+1. `CLAUDE.md` - Claude Code native format (preferred)
+2. `AGENTS.md` - Vercel/industry convention (supported)
+3. `README.md` - fallback if neither exists
+
 **Why two layers?**
 
 | Layer | Purpose | When Loaded |
 |-------|---------|-------------|
-| CLAUDE.md | Narrative context - goals, architecture, conventions | Once at start (Phase 0) |
+| CLAUDE.md / AGENTS.md | Narrative context - goals, architecture, conventions | Once at start (Phase 0) |
 | Chefs | Operational contracts - rules, escalations, outputs | Per-phase as needed |
 
 This combines the cognitive benefits of global context (like AGENTS.md) with the operational rigor of contractual skills.
diff --git a/commands/cook.md b/commands/cook.md
index 02704ed..cb5ce69 100644
--- a/commands/cook.md
+++ b/commands/cook.md
@@ -181,7 +181,12 @@ Step 0.0 - Artifact Created
 
 **This phase loads the NARRATIVE LAYER - global project context.**
 
-Read CLAUDE.md FIRST. This is your "AGENTS.md" - it tells you:
+Load narrative context in this order (first found wins):
+1. `CLAUDE.md` - Claude Code native format
+2. `AGENTS.md` - Vercel/industry convention
+3. `README.md` - fallback if neither exists
+
+This tells you:
 - What the project does
 - How the team works
 - What patterns to follow
@@ -190,8 +195,9 @@ Read CLAUDE.md FIRST. This is your "AGENTS.md" - it tells you:
 ## Sources Scanned
 | File | Purpose | Status | Key Rules |
 |------|---------|--------|-----------|
-| CLAUDE.md | **Narrative context** (goals, architecture, conventions) | _Pending_ | |
-| README.md | Public documentation | _Pending_ | |
+| CLAUDE.md | **Narrative context** (primary) | _Pending_ | |
+| AGENTS.md | **Narrative context** (alternative) | _Pending_ | |
+| README.md | Public documentation (fallback) | _Pending_ | |
 | .claude/agents/*.md | Chef contracts (loaded per-phase, not here) | _Noted_ | |
 
 ## Hard Rules (must not be violated)

From 792f9afcbef17eb1a29134eb3bef61430ee7fcb0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 1 Feb 2026 11:14:28 +0000
Subject: [PATCH 08/14] fix: Load ALL narrative files, not just first found

Changed from "first found wins" to "load all, priority on conflict":
- CLAUDE.md (priority 1 - highest)
- AGENTS.md (priority 2)
- README.md (priority 3 - lowest)

This allows projects to have complementary information across files
while maintaining clear precedence when instructions conflict.

https://claude.ai/code/session_014Jg9QkT6i4QdczmA2kRx9C
---
 .claude/commands/cook.md | 22 ++++++++++++----------
 CLAUDE.md                |  8 ++++----
 commands/cook.md         | 22 ++++++++++++----------
 3 files changed, 28 insertions(+), 24 deletions(-)

diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 6bea42e..1216383 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -181,10 +181,12 @@ Step 0.0 - Artifact Created
 
 **This phase loads the NARRATIVE LAYER - global project context.**
 
-Load narrative context in this order (first found wins):
-1. `CLAUDE.md` - Claude Code native format
-2. `AGENTS.md` - Vercel/industry convention
-3. `README.md` - fallback if neither exists
+Load ALL narrative files that exist (they complement each other):
+- `CLAUDE.md` - Claude Code native format (highest priority)
+- `AGENTS.md` - Vercel/industry convention
+- `README.md` - general project documentation
+
+**Priority on conflict:** CLAUDE.md > AGENTS.md > README.md
 
 This tells you:
 - What the project does
@@ -193,12 +195,12 @@ This tells you:
 - What to avoid
 
 ## Sources Scanned
-| File | Purpose | Status | Key Rules |
-|------|---------|--------|-----------|
-| CLAUDE.md | **Narrative context** (primary) | _Pending_ | |
-| AGENTS.md | **Narrative context** (alternative) | _Pending_ | |
-| README.md | Public documentation (fallback) | _Pending_ | |
-| .claude/agents/*.md | Chef contracts (loaded per-phase, not here) | _Noted_ | |
+| File | Purpose | Priority | Status | Key Rules |
+|------|---------|----------|--------|-----------|
+| CLAUDE.md | Claude-specific instructions | 1 (highest) | _Pending_ | |
+| AGENTS.md | Agent instructions | 2 | _Pending_ | |
+| README.md | General project docs | 3 (lowest) | _Pending_ | |
+| .claude/agents/*.md | Chef contracts (loaded per-phase) | N/A | _Noted_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._
diff --git a/CLAUDE.md b/CLAUDE.md
index 008767d..1831097 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -26,10 +26,10 @@ Cook uses a **hybrid approach** combining narrative context with operational con
 └─────────────────────────────────────────────────────────┘
 ```
 
-**Narrative file resolution:**
-1. `CLAUDE.md` - Claude Code native format (preferred)
-2. `AGENTS.md` - Vercel/industry convention (supported)
-3. `README.md` - fallback if neither exists
+**Narrative files (all loaded, priority on conflict):**
+1. `CLAUDE.md` - Claude Code native format (highest priority)
+2. `AGENTS.md` - Vercel/industry convention
+3. `README.md` - general project documentation (lowest priority)
 
 **Why two layers?**
 
diff --git a/commands/cook.md b/commands/cook.md
index cb5ce69..066444d 100644
--- a/commands/cook.md
+++ b/commands/cook.md
@@ -181,10 +181,12 @@ Step 0.0 - Artifact Created
 
 **This phase loads the NARRATIVE LAYER - global project context.**
 
-Load narrative context in this order (first found wins):
-1. `CLAUDE.md` - Claude Code native format
-2. `AGENTS.md` - Vercel/industry convention
-3. `README.md` - fallback if neither exists
+Load ALL narrative files that exist (they complement each other):
+- `CLAUDE.md` - Claude Code native format (highest priority)
+- `AGENTS.md` - Vercel/industry convention
+- `README.md` - general project documentation
+
+**Priority on conflict:** CLAUDE.md > AGENTS.md > README.md
 
 This tells you:
 - What the project does
@@ -193,12 +195,12 @@ This tells you:
 - What to avoid
 
 ## Sources Scanned
-| File | Purpose | Status | Key Rules |
-|------|---------|--------|-----------|
-| CLAUDE.md | **Narrative context** (primary) | _Pending_ | |
-| AGENTS.md | **Narrative context** (alternative) | _Pending_ | |
-| README.md | Public documentation (fallback) | _Pending_ | |
-| .claude/agents/*.md | Chef contracts (loaded per-phase, not here) | _Noted_ | |
+| File | Purpose | Priority | Status | Key Rules |
+|------|---------|----------|--------|-----------|
+| CLAUDE.md | Claude-specific instructions | 1 (highest) | _Pending_ | |
+| AGENTS.md | Agent instructions | 2 | _Pending_ | |
+| README.md | General project docs | 3 (lowest) | _Pending_ | |
+| .claude/agents/*.md | Chef contracts (loaded per-phase) | N/A | _Noted_ | |
 
 ## Hard Rules (must not be violated)
 _Pending..._

From 3e34819c3c2eea07d50bd36bf30a47272aad7877 Mon Sep 17 00:00:00 2001
From: Patryk Juniszewski <p.juniszewski@gmail.com>
Date: Sun, 1 Feb 2026 13:35:45 +0100
Subject: [PATCH 09/14] feat: Add router/policy layer for chef orchestration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Create ROUTER_POLICY.md with machine-parseable routing rules
- Add phase → chef mapping and escalation priority
- Define conflict resolution algorithm
- Add escalation routes for all chefs
- Update cook.md with Router Policy section
- Add escalates_to field to all 10 chef definitions

This layer answers "who decides when" with explicit routing logic.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/agents/architect_chef.md            |  10 +
 .claude/agents/docs_chef.md                 |   7 +
 .claude/agents/engineer_chef.md             |  10 +
 .claude/agents/product_chef.md              |   7 +
 .claude/agents/qa_chef.md                   |  10 +
 .claude/agents/release_chef.md              |  10 +
 .claude/agents/sanitation_inspector_chef.md |  10 +
 .claude/agents/security_chef.md             |   7 +
 .claude/agents/sous_chef.md                 |   7 +
 .claude/agents/ux_chef.md                   |   7 +
 .claude/commands/cook.md                    |  27 ++
 ROUTER_POLICY.md                            | 274 ++++++++++++++++++++
 12 files changed, 386 insertions(+)
 create mode 100644 ROUTER_POLICY.md

diff --git a/.claude/agents/architect_chef.md b/.claude/agents/architect_chef.md
index 34d8685..4f72a03 100644
--- a/.claude/agents/architect_chef.md
+++ b/.claude/agents/architect_chef.md
@@ -49,6 +49,16 @@ escalation:
     - No acceptable alternative exists
     - Change fundamentally conflicts with system design
     - Risk assessment shows HIGH with no viable mitigation
+  escalates_to:
+    - condition: trade_offs_affect_ux
+      target: ux_chef
+      reason: "Technical decisions impact user experience"
+    - condition: scope_change_needed
+      target: product_chef
+      reason: "Technical constraints require scope adjustment"
+    - condition: security_implications
+      target: security_chef
+      reason: "Architectural decision has security impact"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/docs_chef.md b/.claude/agents/docs_chef.md
index 2fa0057..4a4fd43 100644
--- a/.claude/agents/docs_chef.md
+++ b/.claude/agents/docs_chef.md
@@ -48,6 +48,13 @@ escalation:
     - Deprecation requires announcement strategy
     - Migration guide complexity unclear
     - Documentation conflicts with implementation
+  escalates_to:
+    - condition: breaking_change_undocumented
+      target: product_chef
+      reason: "Breaking change requires migration strategy"
+    - condition: api_docs_conflict
+      target: architect_chef
+      reason: "Documentation conflicts with API design"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/engineer_chef.md b/.claude/agents/engineer_chef.md
index 908c6a3..14beda2 100644
--- a/.claude/agents/engineer_chef.md
+++ b/.claude/agents/engineer_chef.md
@@ -50,6 +50,16 @@ escalation:
     - No clear implementation path exists
     - Scope remains ambiguous after clarification
     - Technical risk exceeds perceived value
+  escalates_to:
+    - condition: affects_5_plus_modules
+      target: architect_chef
+      reason: "Cross-cutting change requires architectural review"
+    - condition: new_architectural_pattern
+      target: architect_chef
+      reason: "New pattern needs architectural approval"
+    - condition: security_concern
+      target: security_chef
+      reason: "Potential security implications"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/product_chef.md b/.claude/agents/product_chef.md
index c87c490..cd7dec3 100644
--- a/.claude/agents/product_chef.md
+++ b/.claude/agents/product_chef.md
@@ -49,6 +49,13 @@ escalation:
     - Scope conflicts with existing product direction
     - Multiple valid interpretations of requirements exist
     - Feature has unclear success metrics after clarification
+  escalates_to:
+    - condition: technical_constraints_block_scope
+      target: architect_chef
+      reason: "Need technical feasibility assessment"
+    - condition: security_sensitive_feature
+      target: security_chef
+      reason: "Feature requires security review before approval"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/qa_chef.md b/.claude/agents/qa_chef.md
index f2c9db5..06feebc 100644
--- a/.claude/agents/qa_chef.md
+++ b/.claude/agents/qa_chef.md
@@ -51,6 +51,16 @@ escalation:
     - Regression in existing functionality detected
     - Acceptance criteria cannot be verified
     - Test strategy conflicts with timeline constraints
+  escalates_to:
+    - condition: regression_detected
+      target: product_chef
+      reason: "Existing functionality affected - scope decision needed"
+    - condition: acceptance_criteria_unverifiable
+      target: product_chef
+      reason: "Cannot verify success criteria"
+    - condition: security_test_gap
+      target: security_chef
+      reason: "Security testing coverage concern"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/release_chef.md b/.claude/agents/release_chef.md
index a689e32..fee1e7a 100644
--- a/.claude/agents/release_chef.md
+++ b/.claude/agents/release_chef.md
@@ -50,6 +50,16 @@ escalation:
     - Breaking change not explicitly approved
     - Version bump type unclear
     - Release blocked by test failures
+  escalates_to:
+    - condition: version_conflict
+      target: product_chef
+      reason: "Release versioning conflict needs resolution"
+    - condition: breaking_change_not_approved
+      target: product_chef
+      reason: "Breaking change needs explicit approval"
+    - condition: security_release
+      target: security_chef
+      reason: "Security release needs security sign-off"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/sanitation_inspector_chef.md b/.claude/agents/sanitation_inspector_chef.md
index 3ac4fab..a712a54 100644
--- a/.claude/agents/sanitation_inspector_chef.md
+++ b/.claude/agents/sanitation_inspector_chef.md
@@ -51,6 +51,16 @@ escalation:
     - HIGH severity violation found
     - Recipe compliance shows major drift
     - Safety inspection fails
+  escalates_to:
+    - condition: security_violation
+      target: security_chef
+      reason: "Security violation requires security review"
+    - condition: implementation_drift
+      target: engineer_chef
+      reason: "Implementation differs from plan"
+    - condition: scope_drift
+      target: product_chef
+      reason: "Scope creep detected - product decision needed"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/security_chef.md b/.claude/agents/security_chef.md
index bb9f145..4b534cf 100644
--- a/.claude/agents/security_chef.md
+++ b/.claude/agents/security_chef.md
@@ -52,6 +52,13 @@ escalation:
     - Security vulnerability detected
     - High-risk finding cannot be mitigated
     - Trade-off between security and functionality required
+  escalates_to:
+    - condition: security_blocks_feature
+      target: product_chef
+      reason: "Security concern may require scope change"
+    - condition: architectural_security_issue
+      target: architect_chef
+      reason: "Security issue requires architectural remediation"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/sous_chef.md b/.claude/agents/sous_chef.md
index 8220cc4..09dec22 100644
--- a/.claude/agents/sous_chef.md
+++ b/.claude/agents/sous_chef.md
@@ -49,6 +49,13 @@ escalation:
     - Repeated violations in same area
     - Pattern of uncooked changes detected
     - Post-mortem reveals systemic issue
+  escalates_to:
+    - condition: uncooked_sensitive_change
+      target: product_chef
+      reason: "Sensitive change without cook artifact needs review"
+    - condition: repeated_violations
+      target: product_chef
+      reason: "Pattern of violations indicates process issue"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/agents/ux_chef.md b/.claude/agents/ux_chef.md
index 74af84d..3d721eb 100644
--- a/.claude/agents/ux_chef.md
+++ b/.claude/agents/ux_chef.md
@@ -49,6 +49,13 @@ escalation:
     - UI pattern is ambiguous after discussion
     - Accessibility regression cannot be avoided
     - User flow has no clear discovery path
+  escalates_to:
+    - condition: breaking_pattern_change
+      target: product_chef
+      reason: "UX pattern break needs product approval"
+    - condition: accessibility_regression
+      target: product_chef
+      reason: "Accessibility impact requires stakeholder decision"
 
 rubric:
   ready_for_merge:
diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 1216383..af42285 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -69,6 +69,33 @@ Optional flags:
 
 ---
 
+## Router Policy
+
+Before executing any step, consult `ROUTER_POLICY.md` for:
+
+1. **Which chef(s) to invoke** - `phase_routing` maps phases to chefs
+2. **Escalation routes** - When a chef signals escalation, follow defined paths
+3. **Conflict resolution** - If multiple chefs disagree, apply priority rules
+4. **Phase skip rules** - Determine if phase can be skipped (e.g., no UX changes)
+
+### Router Algorithm
+
+```
+For each cooking phase:
+1. Load ROUTER_POLICY.md phase_routing for current phase
+2. For each chef in phase:
+   a. Load chef contract from .claude/agents/
+   b. Execute chef review
+   c. Check for escalation triggers in chef output
+   d. If escalation needed → route to target chef
+3. Collect all verdicts
+4. Apply conflict resolution if multiple verdicts
+5. Record final verdict in artifact
+6. Proceed or block based on verdict
+```
+
+---
+
 ## Cooking Modes
 
 ### --well-done (default)
diff --git a/ROUTER_POLICY.md b/ROUTER_POLICY.md
new file mode 100644
index 0000000..ea45207
--- /dev/null
+++ b/ROUTER_POLICY.md
@@ -0,0 +1,274 @@
+# Router Policy v1.0
+
+Machine-parseable routing and escalation rules for chef orchestration.
+
+**Purpose:** Define "who decides when" - explicit logic for phase routing, escalation paths, and conflict resolution.
+
+---
+
+## Phase → Chef Mapping
+
+```yaml
+phase_routing:
+  scope: [product_chef]
+  ux: [ux_chef]
+  plan: [architect_chef, engineer_chef]  # sequential
+  test: [qa_chef]
+  security: [security_chef]
+  docs: [docs_chef]
+  release: [release_chef]
+  inspect: [sanitation_inspector_chef]
+  monitor: [sous_chef]
+```
+
+### Mapping Rules
+
+| Cook Step | Phase | Primary Chef(s) | Execution |
+|-----------|-------|-----------------|-----------|
+| Step 2 | scope | product_chef | Single |
+| Step 3 | ux | ux_chef | Single (if UI changes) |
+| Step 4 | plan | architect_chef → engineer_chef | Sequential |
+| Step 5 | test | qa_chef | Single |
+| Step 6 | security | security_chef | Single |
+| Step 7 | docs | docs_chef | Single |
+| Post-cook | release | release_chef | Single (on release) |
+| Post-cook | inspect | sanitation_inspector_chef | On-demand |
+| Background | monitor | sous_chef | Continuous |
+
+---
+
+## Escalation Priority
+
+When multiple chefs have opinions, priority determines which chef's verdict takes precedence.
+
+```yaml
+escalation_priority:
+  1: security_chef    # Security always wins
+  2: product_chef     # Scope/value decisions
+  3: architect_chef   # Technical direction
+  4: qa_chef          # Quality gates
+  5: engineer_chef    # Implementation details
+  6: ux_chef          # User experience
+  7: docs_chef        # Documentation
+  8: release_chef     # Release decisions
+```
+
+### Priority Rules
+
+1. **Security overrides all** - A security blocker cannot be overridden by any other chef
+2. **Product defines scope** - Only product_chef can expand/reduce scope
+3. **Architect guides structure** - Technical patterns defer to architect_chef
+4. **Lower priority = advisory** - Can be overridden by higher-priority chef with justification
+
+---
+
+## Conflict Resolution
+
+When verdicts conflict between chefs:
+
+```yaml
+when_verdicts_conflict:
+  block_wins_over: [request-changes, approve, needs-clarification]
+  request-changes_wins_over: [approve, needs-clarification]
+  needs-clarification_wins_over: [approve]
+
+  tie_breaker: escalation_priority
+
+  resolution_actions:
+    both_block:
+      action: combine_must_fix_lists
+      notify: all_blocking_chefs
+
+    block_vs_approve:
+      action: block_wins
+      document: blocking_reason
+
+    multiple_request_changes:
+      action: merge_change_lists
+      deduplicate: true
+```
+
+### Resolution Algorithm
+
+```
+1. Collect all chef verdicts for current phase
+2. If any verdict is "block" → overall verdict is "block"
+3. If any verdict is "request-changes" → overall verdict is "request-changes"
+4. If any verdict is "needs-clarification" → overall verdict is "needs-clarification"
+5. If all verdicts are "approve" → overall verdict is "approve"
+6. On tie → use escalation_priority to determine primary voice
+```
+
+---
+
+## Escalation Routes
+
+Explicit escalation paths when a chef encounters situations beyond their scope.
+
+```yaml
+escalation_routes:
+  engineer_chef:
+    escalates_to:
+      - condition: affects_5_plus_modules
+        target: architect_chef
+        reason: "Cross-cutting change requires architectural review"
+      - condition: new_architectural_pattern
+        target: architect_chef
+        reason: "New pattern needs architectural approval"
+      - condition: security_concern
+        target: security_chef
+        reason: "Potential security implications"
+
+  architect_chef:
+    escalates_to:
+      - condition: trade_offs_affect_ux
+        target: ux_chef
+        reason: "Technical decisions impact user experience"
+      - condition: scope_change_needed
+        target: product_chef
+        reason: "Technical constraints require scope adjustment"
+      - condition: security_implications
+        target: security_chef
+        reason: "Architectural decision has security impact"
+
+  qa_chef:
+    escalates_to:
+      - condition: regression_detected
+        target: product_chef
+        reason: "Existing functionality affected - scope decision needed"
+      - condition: acceptance_criteria_unverifiable
+        target: product_chef
+        reason: "Cannot verify success criteria"
+      - condition: security_test_gap
+        target: security_chef
+        reason: "Security testing coverage concern"
+
+  ux_chef:
+    escalates_to:
+      - condition: breaking_pattern_change
+        target: product_chef
+        reason: "UX pattern break needs product approval"
+      - condition: accessibility_regression
+        target: product_chef
+        reason: "Accessibility impact requires stakeholder decision"
+
+  docs_chef:
+    escalates_to:
+      - condition: breaking_change_undocumented
+        target: product_chef
+        reason: "Breaking change requires migration strategy"
+
+  release_chef:
+    escalates_to:
+      - condition: version_conflict
+        target: product_chef
+        reason: "Release versioning conflict needs resolution"
+      - condition: breaking_change_not_approved
+        target: product_chef
+        reason: "Breaking change needs explicit approval"
+
+  any_chef:
+    escalates_to:
+      - condition: security_vulnerability
+        target: security_chef
+        reason: "Security issue detected"
+      - condition: high_risk_no_mitigation
+        target: security_chef
+        reason: "HIGH risk without viable mitigation"
+      - condition: cannot_decide
+        target: human
+        reason: "Insufficient context for autonomous decision"
+```
+
+---
+
+## Phase Skip Rules
+
+When certain phases can be skipped based on context.
+
+```yaml
+phase_skip_rules:
+  ux:
+    skip_when:
+      - no_ui_changes
+      - backend_only_change
+      - api_internal_change
+    skip_verdict: "N/A - No UX impact"
+
+  security:
+    skip_when: []  # Never skip security
+    note: "Security review is mandatory for all changes"
+
+  docs:
+    skip_when:
+      - internal_refactor_only
+      - no_behavior_change
+      - no_api_change
+    skip_verdict: "N/A - No documentation impact"
+
+  release:
+    skip_when:
+      - not_releasing
+      - draft_only
+    skip_verdict: "N/A - Release phase invoked separately"
+```
+
+---
+
+## Microwave Mode Routing
+
+Simplified routing for `--microwave` mode:
+
+```yaml
+microwave_routing:
+  phases: [scope, plan, test]
+  chefs: [product_chef, engineer_chef, qa_chef]
+
+  auto_escalate_to_wellDone:
+    - auth_topic
+    - payment_topic
+    - pii_topic
+    - schema_change
+    - public_api_change
+
+  reduced_requirements:
+    product_chef:
+      skip: [user_value_statement, non_goals]
+    engineer_chef:
+      skip: [alternatives_analysis]
+    qa_chef:
+      min_test_cases: 1
+```
+
+---
+
+## Strict Mode Triggers
+
+Global triggers that activate strict mode across all chefs:
+
+```yaml
+strict_mode_triggers:
+  global:
+    - authentication_change
+    - authorization_change
+    - payment_processing
+    - pii_handling
+    - cryptography
+    - public_api_change
+    - data_schema_change
+
+  effect:
+    - All phases mandatory (no skips)
+    - Full review depth required
+    - Human approval checkpoint added
+    - Audit logging enhanced
+```
+
+---
+
+## See Also
+
+- [CHEF_CONTRACTS.md](CHEF_CONTRACTS.md) - Handoff contracts between chefs
+- [FALLBACK_POLICY.md](FALLBACK_POLICY.md) - What happens when routing fails
+- [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md) - Standard review format
+- `.claude/agents/` - Individual chef definitions

From 3a35ffc222e8333e0a1f77cd9a5c2098235b4b9d Mon Sep 17 00:00:00 2001
From: Patryk Juniszewski <p.juniszewski@gmail.com>
Date: Sun, 1 Feb 2026 13:37:46 +0100
Subject: [PATCH 10/14] feat: Add chef-to-chef handoff contracts

- Create CHEF_CONTRACTS.md defining handoff requirements between chefs
- Add input_contract and output_contract to all 10 chef definitions
- Define handoff_fields for structured data passing
- Add Handoff Validation section to REVIEW_CONTRACT.md
- Document validation rules and failure handling

This layer answers "what is passed to whom" with explicit contracts.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/agents/architect_chef.md            |  16 +
 .claude/agents/docs_chef.md                 |  12 +
 .claude/agents/engineer_chef.md             |  15 +
 .claude/agents/product_chef.md              |  14 +
 .claude/agents/qa_chef.md                   |  14 +
 .claude/agents/release_chef.md              |  13 +
 .claude/agents/sanitation_inspector_chef.md |  13 +
 .claude/agents/security_chef.md             |  12 +
 .claude/agents/sous_chef.md                 |  13 +
 .claude/agents/ux_chef.md                   |  13 +
 CHEF_CONTRACTS.md                           | 331 ++++++++++++++++++++
 REVIEW_CONTRACT.md                          |  46 +++
 12 files changed, 512 insertions(+)
 create mode 100644 CHEF_CONTRACTS.md

diff --git a/.claude/agents/architect_chef.md b/.claude/agents/architect_chef.md
index 4f72a03..39111ad 100644
--- a/.claude/agents/architect_chef.md
+++ b/.claude/agents/architect_chef.md
@@ -5,6 +5,16 @@ version: 2.0.0
 phase_affinity:
   - plan
 
+input_contract:
+  requires_from: product_chef
+  required_fields:
+    - approved_scope
+    - non_goals
+    - success_metrics
+  optional_fields:
+    - priority
+    - user_value_statement
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +27,12 @@ output_contract:
   optional_addenda:
     - alternatives_considered
     - trade_offs
+  handoff_to: engineer_chef
+  handoff_fields:
+    - chosen_alternative
+    - trade_offs
+    - affected_modules
+    - risk_assessment
 
 traits:
   risk_posture: balanced
diff --git a/.claude/agents/docs_chef.md b/.claude/agents/docs_chef.md
index 4a4fd43..d08dcc0 100644
--- a/.claude/agents/docs_chef.md
+++ b/.claude/agents/docs_chef.md
@@ -5,6 +5,14 @@ version: 2.0.0
 phase_affinity:
   - docs
 
+input_contract:
+  requires_from: security_chef
+  required_fields:
+    - security_status
+  optional_fields:
+    - security_notes
+    - threat_assessment
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +25,10 @@ output_contract:
   optional_addenda:
     - files_to_update
     - migration_guide
+  handoff_to: release_chef
+  handoff_fields:
+    - documentation_status
+    - breaking_changes_documented
 
 traits:
   risk_posture: balanced
diff --git a/.claude/agents/engineer_chef.md b/.claude/agents/engineer_chef.md
index 14beda2..38e8da5 100644
--- a/.claude/agents/engineer_chef.md
+++ b/.claude/agents/engineer_chef.md
@@ -5,6 +5,16 @@ version: 2.0.0
 phase_affinity:
   - plan
 
+input_contract:
+  requires_from: architect_chef
+  required_fields:
+    - chosen_alternative
+    - trade_offs
+    - affected_modules
+  optional_fields:
+    - risk_assessment
+    - alternatives_considered
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +27,11 @@ output_contract:
   optional_addenda:
     - implementation_plan
     - diagram
+  handoff_to: qa_chef
+  handoff_fields:
+    - implementation_plan
+    - files_to_modify
+    - edge_cases_identified
 
 traits:
   risk_posture: balanced
diff --git a/.claude/agents/product_chef.md b/.claude/agents/product_chef.md
index cd7dec3..aaab7d2 100644
--- a/.claude/agents/product_chef.md
+++ b/.claude/agents/product_chef.md
@@ -5,6 +5,14 @@ version: 2.0.0
 phase_affinity:
   - scope
 
+input_contract:
+  requires_from: user_request
+  required_fields:
+    - feature_description
+  optional_fields:
+    - context
+    - constraints
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +25,12 @@ output_contract:
   optional_addenda:
     - scope_definition
     - user_value
+  handoff_to: architect_chef
+  handoff_fields:
+    - approved_scope
+    - non_goals
+    - success_metrics
+    - priority
 
 traits:
   risk_posture: conservative
diff --git a/.claude/agents/qa_chef.md b/.claude/agents/qa_chef.md
index 06feebc..eea82f0 100644
--- a/.claude/agents/qa_chef.md
+++ b/.claude/agents/qa_chef.md
@@ -5,6 +5,15 @@ version: 2.0.0
 phase_affinity:
   - test
 
+input_contract:
+  requires_from: engineer_chef
+  required_fields:
+    - implementation_plan
+    - files_to_modify
+  optional_fields:
+    - edge_cases_identified
+    - high_risk_areas
+
 output_contract:
   format: review_v1
   required_sections:
@@ -18,6 +27,11 @@ output_contract:
     - test_cases
     - edge_cases
     - acceptance_criteria
+  handoff_to: security_chef
+  handoff_fields:
+    - test_cases
+    - coverage_areas
+    - uncovered_risks
 
 traits:
   risk_posture: conservative
diff --git a/.claude/agents/release_chef.md b/.claude/agents/release_chef.md
index fee1e7a..4039083 100644
--- a/.claude/agents/release_chef.md
+++ b/.claude/agents/release_chef.md
@@ -5,6 +5,14 @@ version: 2.0.0
 phase_affinity:
   - release
 
+input_contract:
+  requires_from: docs_chef
+  required_fields:
+    - documentation_status
+  optional_fields:
+    - breaking_changes_documented
+    - migration_guide
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +25,11 @@ output_contract:
   optional_addenda:
     - version_bump
     - changelog_entry
+  handoff_to: null
+  handoff_fields:
+    - version_bump
+    - changelog_entry
+    - release_checklist
 
 traits:
   risk_posture: conservative
diff --git a/.claude/agents/sanitation_inspector_chef.md b/.claude/agents/sanitation_inspector_chef.md
index a712a54..9a653dc 100644
--- a/.claude/agents/sanitation_inspector_chef.md
+++ b/.claude/agents/sanitation_inspector_chef.md
@@ -5,6 +5,14 @@ version: 2.0.0
 phase_affinity:
   - inspect
 
+input_contract:
+  requires_from: any_chef
+  required_fields:
+    - implementation_artifact
+  optional_fields:
+    - implementation_commits
+    - high_risk_files
+
 output_contract:
   format: review_v1
   required_sections:
@@ -18,6 +26,11 @@ output_contract:
     - hygiene_report
     - compliance_report
     - safety_report
+  handoff_to: null
+  handoff_fields:
+    - inspection_result
+    - violations
+    - recommendations
 
 traits:
   risk_posture: conservative
diff --git a/.claude/agents/security_chef.md b/.claude/agents/security_chef.md
index 4b534cf..84acc3e 100644
--- a/.claude/agents/security_chef.md
+++ b/.claude/agents/security_chef.md
@@ -5,6 +5,14 @@ version: 2.0.0
 phase_affinity:
   - security
 
+input_contract:
+  requires_from: qa_chef
+  required_fields:
+    - test_cases
+  optional_fields:
+    - coverage_areas
+    - uncovered_risks
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +25,10 @@ output_contract:
   optional_addenda:
     - threat_assessment
     - owasp_checklist
+  handoff_to: docs_chef
+  handoff_fields:
+    - security_status
+    - security_notes
 
 traits:
   risk_posture: conservative
diff --git a/.claude/agents/sous_chef.md b/.claude/agents/sous_chef.md
index 09dec22..00906a7 100644
--- a/.claude/agents/sous_chef.md
+++ b/.claude/agents/sous_chef.md
@@ -5,6 +5,14 @@ version: 2.0.0
 phase_affinity:
   - monitor
 
+input_contract:
+  requires_from: null
+  required_fields: []
+  optional_fields:
+    - cook_artifact
+    - recent_commits
+    - incident_reports
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +25,11 @@ output_contract:
   optional_addenda:
     - drift_report
     - change_report
+  handoff_to: null
+  handoff_fields:
+    - monitoring_report
+    - drift_analysis
+    - suggestions
 
 traits:
   risk_posture: balanced
diff --git a/.claude/agents/ux_chef.md b/.claude/agents/ux_chef.md
index 3d721eb..22796fe 100644
--- a/.claude/agents/ux_chef.md
+++ b/.claude/agents/ux_chef.md
@@ -5,6 +5,14 @@ version: 2.0.0
 phase_affinity:
   - ux
 
+input_contract:
+  requires_from: product_chef
+  required_fields:
+    - approved_scope
+  optional_fields:
+    - user_value_statement
+    - non_goals
+
 output_contract:
   format: review_v1
   required_sections:
@@ -17,6 +25,11 @@ output_contract:
   optional_addenda:
     - user_flow
     - accessibility_notes
+  handoff_to: architect_chef
+  handoff_fields:
+    - ux_requirements
+    - user_flow
+    - accessibility_concerns
 
 traits:
   risk_posture: balanced
diff --git a/CHEF_CONTRACTS.md b/CHEF_CONTRACTS.md
new file mode 100644
index 0000000..12f238a
--- /dev/null
+++ b/CHEF_CONTRACTS.md
@@ -0,0 +1,331 @@
+# Chef-to-Chef Contracts v1.0
+
+Explicit handoff contracts defining what each chef must deliver to the next chef in the workflow.
+
+**Purpose:** Define "what is passed to whom" - structured outputs that enable downstream chefs to function correctly.
+
+---
+
+## Contract Philosophy
+
+Each chef operates within a bounded context. For the overall workflow to succeed:
+
+1. **Upstream chef** must provide specific outputs (output_contract)
+2. **Downstream chef** must receive specific inputs (input_contract)
+3. **Handoff validation** ensures nothing is lost between phases
+
+Without explicit contracts:
+- Chefs make assumptions about available context
+- Critical information is lost between phases
+- Failures occur late instead of early
+
+---
+
+## Contract: product_chef → architect_chef
+
+```yaml
+handoff_product_to_architect:
+  required_outputs:
+    - approved_scope:
+        description: "List of in-scope items"
+        format: "bullet list"
+        validation: "must not contain TBD"
+    - non_goals:
+        description: "Explicit list of what NOT to build"
+        format: "bullet list"
+        validation: "at least 1 item"
+    - success_metrics:
+        description: "How we measure success"
+        format: "bullet list with measurable criteria"
+        validation: "at least 1 metric defined"
+    - priority:
+        description: "Feature priority level"
+        format: "P0 | P1 | P2"
+        validation: "must be one of allowed values"
+
+  optional_outputs:
+    - user_value_statement:
+        description: "Who/Problem/Solution/Metric"
+    - dependencies:
+        description: "Prerequisites or related features"
+
+  blocking_if_missing: true
+  fallback_action: needs-clarification
+```
+
+---
+
+## Contract: architect_chef → engineer_chef
+
+```yaml
+handoff_architect_to_engineer:
+  required_outputs:
+    - chosen_alternative:
+        description: "Selected approach with rationale"
+        format: "approach name + why selected"
+        validation: "not empty"
+    - trade_offs:
+        description: "Documented trade-offs"
+        format: "sacrificing/gaining/acceptable-because"
+        validation: "trade_offs documented for chosen approach"
+    - affected_modules:
+        description: "List of modules to modify"
+        format: "bullet list of module/component names"
+        validation: "at least 1 module identified"
+    - risk_assessment:
+        description: "Overall risk level with mitigations"
+        format: "HIGH | MEDIUM | LOW + mitigations"
+        validation: "must include mitigation if HIGH"
+
+  optional_outputs:
+    - alternatives_considered:
+        description: "Other approaches evaluated"
+        validation: "at least 2 alternatives if non-trivial change"
+    - integration_points:
+        description: "Where new code integrates with existing"
+    - performance_model:
+        description: "Expected performance characteristics"
+
+  blocking_if_missing: true
+  fallback_action: escalate_to_architect
+```
+
+---
+
+## Contract: engineer_chef → qa_chef
+
+```yaml
+handoff_engineer_to_qa:
+  required_outputs:
+    - implementation_plan:
+        description: "Step-by-step implementation plan"
+        format: "numbered list of steps"
+        validation: "implementation_plan not empty"
+    - files_to_modify:
+        description: "Explicit file list with change descriptions"
+        format: "table: file | change | risk"
+        validation: "at least 1 file identified"
+    - edge_cases_identified:
+        description: "Known edge cases from implementation planning"
+        format: "bullet list"
+        validation: "at least 1 edge case if non-trivial"
+
+  optional_outputs:
+    - commit_sequence:
+        description: "Planned commit order"
+    - high_risk_areas:
+        description: "Areas needing extra attention"
+    - technical_decisions:
+        description: "Implementation-level choices made"
+
+  blocking_if_missing: true
+  fallback_action: request-changes
+```
+
+---
+
+## Contract: qa_chef → security_chef
+
+```yaml
+handoff_qa_to_security:
+  required_outputs:
+    - test_cases:
+        description: "List of test cases defined"
+        format: "table: scenario | given | when | then"
+        validation: "at least 1 test case defined"
+    - coverage_areas:
+        description: "What's covered by tests"
+        format: "bullet list"
+        validation: "not empty"
+    - uncovered_risks:
+        description: "Known gaps in test coverage"
+        format: "bullet list"
+        validation: "explicitly stated even if none"
+
+  optional_outputs:
+    - acceptance_criteria:
+        description: "Verifiable acceptance criteria"
+    - regression_checks:
+        description: "Existing features to verify"
+    - edge_cases:
+        description: "Edge cases to test"
+
+  blocking_if_missing: false  # security can proceed with warning
+  fallback_action: proceed_with_warning
+  warning_message: "QA handoff incomplete - security review may miss test-related concerns"
+```
+
+---
+
+## Contract: security_chef → docs_chef
+
+```yaml
+handoff_security_to_docs:
+  required_outputs:
+    - security_status:
+        description: "Overall security review status"
+        format: "reviewed: yes/no, risk_level: low/medium/high"
+        validation: "must be reviewed"
+    - security_notes:
+        description: "Security considerations for documentation"
+        format: "bullet list"
+        validation: "explicitly stated even if none"
+
+  optional_outputs:
+    - threat_assessment:
+        description: "Detailed threat analysis"
+    - owasp_checklist:
+        description: "OWASP top 10 review results"
+    - security_requirements:
+        description: "Security requirements that affect user behavior"
+
+  blocking_if_missing: false
+  fallback_action: proceed_with_warning
+  warning_message: "Security handoff incomplete - docs may miss security-related guidance"
+```
+
+---
+
+## Contract: docs_chef → release_chef
+
+```yaml
+handoff_docs_to_release:
+  required_outputs:
+    - documentation_status:
+        description: "What documentation was updated"
+        format: "bullet list of files/sections"
+        validation: "explicitly stated even if no changes needed"
+    - breaking_changes_documented:
+        description: "Whether breaking changes have migration guides"
+        format: "yes/no/N/A"
+        validation: "if breaking change, must be yes"
+
+  optional_outputs:
+    - files_to_update:
+        description: "Documentation files that need updates"
+    - migration_guide:
+        description: "User migration instructions"
+    - usage_examples:
+        description: "Code examples for new features"
+
+  blocking_if_missing: false
+  fallback_action: proceed_with_warning
+  warning_message: "Docs handoff incomplete - release notes may miss documentation status"
+```
+
+---
+
+## Contract: any_chef → sanitation_inspector_chef
+
+```yaml
+handoff_to_inspector:
+  required_outputs:
+    - implementation_artifact:
+        description: "Path to cook artifact"
+        format: "file path"
+        validation: "file must exist"
+    - implementation_commits:
+        description: "Commits implementing the feature"
+        format: "list of commit SHAs"
+        validation: "at least 1 commit"
+
+  optional_outputs:
+    - high_risk_files:
+        description: "Files flagged as high-risk"
+    - known_shortcuts:
+        description: "Intentional deviations from plan"
+
+  blocking_if_missing: false
+  fallback_action: inspect_without_context
+```
+
+---
+
+## Validation Rules
+
+### Pre-Phase Validation
+
+Before each phase begins, validate input contract:
+
+```
+1. Load input_contract for current chef
+2. Check required_fields from previous chef output
+3. If missing required field:
+   a. If blocking_if_missing: true → block with needs-clarification
+   b. If blocking_if_missing: false → warn and proceed
+4. Log validation result to audit trail
+```
+
+### Post-Phase Validation
+
+After each phase completes, validate output contract:
+
+```
+1. Load output_contract for current chef
+2. Check all required_outputs are present
+3. Apply format validation rules
+4. If validation fails:
+   a. Return request-changes to current chef
+   b. Log validation failure
+5. If validation passes:
+   a. Package handoff data for next chef
+   b. Log successful handoff
+```
+
+---
+
+## Handoff Data Structure
+
+Standard structure for passing data between chefs:
+
+```yaml
+handoff:
+  from_chef: <chef_id>
+  to_chef: <chef_id>
+  timestamp: <ISO-8601>
+  order_id: <order_id>
+  phase: <phase_name>
+
+  required_data:
+    - field: <field_name>
+      value: <value>
+      validated: true|false
+
+  optional_data:
+    - field: <field_name>
+      value: <value>
+      present: true|false
+
+  validation_result:
+    status: passed|failed|warning
+    missing_fields: [...]
+    invalid_fields: [...]
+    warnings: [...]
+```
+
+---
+
+## Contract Versioning
+
+Contracts are versioned. When updating:
+
+1. Increment version in contract header
+2. Document breaking changes
+3. Maintain backward compatibility for 1 minor version
+4. Update all affected chefs simultaneously
+
+```yaml
+contract_version: 1.0.0
+compatible_with:
+  - 1.0.x
+  - 0.9.x  # deprecated, remove in 2.0
+```
+
+---
+
+## See Also
+
+- [ROUTER_POLICY.md](ROUTER_POLICY.md) - Chef routing and escalation
+- [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md) - Review output format
+- [FALLBACK_POLICY.md](FALLBACK_POLICY.md) - What happens when contracts fail
+- `.claude/agents/` - Individual chef definitions with contracts
diff --git a/REVIEW_CONTRACT.md b/REVIEW_CONTRACT.md
index f3e73fc..355a263 100644
--- a/REVIEW_CONTRACT.md
+++ b/REVIEW_CONTRACT.md
@@ -190,8 +190,54 @@ For tooling and automation:
 
 ---
 
+## Handoff Validation
+
+Before proceeding to the next phase, validate the handoff contract:
+
+### Pre-Phase Check
+
+```
+1. Load CHEF_CONTRACTS.md for current transition
+2. Verify previous chef's output_contract.handoff_fields are present
+3. Verify current chef's input_contract.required_fields are satisfied
+4. If validation fails:
+   a. If blocking_if_missing: true → verdict: needs-clarification
+   b. If blocking_if_missing: false → proceed with warning
+5. Log validation result to audit trail
+```
+
+### Validation Failures
+
+| Failure Type | Action |
+|--------------|--------|
+| Missing required field | Block with `needs-clarification`, request from previous chef |
+| Invalid format | Block with `request-changes`, specify correction needed |
+| Optional field missing | Proceed with warning logged |
+
+### Example Validation
+
+```markdown
+### Handoff Validation: architect_chef → engineer_chef
+
+**Contract:** handoff_architect_to_engineer v1.0
+
+| Required Field | Status | Value |
+|----------------|--------|-------|
+| chosen_alternative | ✅ | "Option B - Module separation" |
+| trade_offs | ✅ | "Sacrificing: simplicity / Gaining: extensibility" |
+| affected_modules | ✅ | [auth, api, models] |
+| risk_assessment | ✅ | "MEDIUM - mitigated by feature flag" |
+
+**Validation Result:** PASSED
+**Handoff Status:** Ready for engineer_chef
+```
+
+---
+
 ## See Also
 
 - [COOK_CONTRACT.md](COOK_CONTRACT.md) - Artifact structure
 - [CHEF_MATRIX.md](CHEF_MATRIX.md) - Phase assignments
+- [CHEF_CONTRACTS.md](CHEF_CONTRACTS.md) - Handoff contracts between chefs
+- [ROUTER_POLICY.md](ROUTER_POLICY.md) - Chef routing and escalation
 - `.claude/agents/` - Individual chef definitions

From 2b62d3fea77f089035523b1a886f64d824ea9af9 Mon Sep 17 00:00:00 2001
From: Patryk Juniszewski <p.juniszewski@gmail.com>
Date: Sun, 1 Feb 2026 13:41:55 +0100
Subject: [PATCH 11/14] feat: Add audit/memory system for cross-order learning

- Create .claude/data/cook-audit.schema.json defining audit event schema
- Add scripts/lib/auditLogger.js for logging cook events
- Add scripts/lib/patternMiner.js for analyzing patterns across orders
- Update cook.md with Audit Logging section
- Add Audit Trail section to order template

This layer answers "what did we learn" with structured audit logging.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/commands/cook.md            |  53 +++++
 .claude/data/cook-audit.schema.json | 141 ++++++++++++
 orders/_TEMPLATE.order.md           |  15 ++
 scripts/lib/auditLogger.js          | 292 ++++++++++++++++++++++++
 scripts/lib/patternMiner.js         | 341 ++++++++++++++++++++++++++++
 5 files changed, 842 insertions(+)
 create mode 100644 .claude/data/cook-audit.schema.json
 create mode 100644 scripts/lib/auditLogger.js
 create mode 100644 scripts/lib/patternMiner.js

diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index af42285..43449ac 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -543,6 +543,59 @@ If Tasks API is unavailable (older Claude Code or `CLAUDE_CODE_ENABLE_TASKS=fals
 
 ---
 
+## Audit Logging
+
+Cook maintains an audit trail for cross-order learning and pattern detection.
+
+### Log Location
+
+Audit logs are stored in `.claude/data/cook-audit.jsonl` (JSON Lines format).
+
+### Events Logged
+
+After each phase completion:
+1. Log event to `.claude/data/cook-audit.jsonl`
+2. Include: order_id, phase, chef_id, verdict, duration
+3. Log any escalations that occurred
+4. Log any blockers identified
+
+### Event Types
+
+| Event | When Logged |
+|-------|-------------|
+| `phase_start` | Chef begins processing |
+| `phase_complete` | Chef finishes with verdict |
+| `escalation` | Chef escalates to another chef |
+| `blocker` | Blocking issue identified |
+| `handoff` | Data passed between chefs |
+| `validation_failure` | Contract validation failed |
+| `human_intervention` | Human input required |
+| `cook_complete` | Entire cook workflow done |
+
+### Pattern Analysis
+
+After cook completion:
+1. If >5 orders exist in audit log, run pattern analysis
+2. Surface recurring blockers in final summary
+3. Track escalation patterns for process improvement
+
+### Example Log Entry
+
+```json
+{
+  "timestamp": "2026-01-31T10:30:00Z",
+  "order_id": "add-auth.2026-01-31",
+  "event_type": "phase_complete",
+  "phase": "security",
+  "chef_id": "security_chef",
+  "verdict": "request-changes",
+  "blockers": [{"type": "missing_validation", "severity": "MEDIUM"}],
+  "duration_seconds": 45
+}
+```
+
+---
+
 ## Failure Modes
 
 Claude Code MUST STOP cooking if:
diff --git a/.claude/data/cook-audit.schema.json b/.claude/data/cook-audit.schema.json
new file mode 100644
index 0000000..6b50a83
--- /dev/null
+++ b/.claude/data/cook-audit.schema.json
@@ -0,0 +1,141 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://juni.dev/cook-audit.schema.json",
+  "title": "Cook Audit Log Entry",
+  "description": "Schema for audit log entries in the cook workflow",
+  "type": "object",
+  "required": ["timestamp", "order_id", "event_type"],
+  "properties": {
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp of the event"
+    },
+    "order_id": {
+      "type": "string",
+      "description": "Unique identifier for the cook order"
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "phase_start",
+        "phase_complete",
+        "escalation",
+        "blocker",
+        "handoff",
+        "validation_failure",
+        "human_intervention",
+        "cook_complete"
+      ],
+      "description": "Type of audit event"
+    },
+    "phase": {
+      "type": "string",
+      "enum": ["scope", "ux", "plan", "test", "security", "docs", "release", "inspect", "monitor"],
+      "description": "Current cook phase"
+    },
+    "chef_id": {
+      "type": "string",
+      "description": "ID of the chef involved in this event"
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["approve", "block", "request-changes", "needs-clarification"],
+      "description": "Chef verdict if applicable"
+    },
+    "escalated": {
+      "type": "boolean",
+      "description": "Whether this event involved escalation"
+    },
+    "escalation": {
+      "type": "object",
+      "properties": {
+        "from_chef": {
+          "type": "string",
+          "description": "Chef that initiated escalation"
+        },
+        "to_chef": {
+          "type": "string",
+          "description": "Chef that received escalation"
+        },
+        "reason": {
+          "type": "string",
+          "description": "Reason for escalation"
+        },
+        "condition": {
+          "type": "string",
+          "description": "Condition that triggered escalation"
+        }
+      }
+    },
+    "blockers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Type of blocker"
+          },
+          "description": {
+            "type": "string",
+            "description": "Blocker description"
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["HIGH", "MEDIUM", "LOW"]
+          }
+        }
+      },
+      "description": "List of blockers identified"
+    },
+    "risks_identified": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["HIGH", "MEDIUM", "LOW"]
+          },
+          "mitigation": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Risks identified during this phase"
+    },
+    "handoff": {
+      "type": "object",
+      "properties": {
+        "from_chef": {
+          "type": "string"
+        },
+        "to_chef": {
+          "type": "string"
+        },
+        "validation_status": {
+          "type": "string",
+          "enum": ["passed", "failed", "warning"]
+        },
+        "missing_fields": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "description": "Handoff validation details"
+    },
+    "duration_seconds": {
+      "type": "number",
+      "description": "Duration of the phase/event in seconds"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Additional event-specific metadata"
+    }
+  }
+}
diff --git a/orders/_TEMPLATE.order.md b/orders/_TEMPLATE.order.md
index 8da0152..12be6e6 100644
--- a/orders/_TEMPLATE.order.md
+++ b/orders/_TEMPLATE.order.md
@@ -58,6 +58,21 @@ tracker:
 -->
 
 
+---
+## Audit Trail
+<!-- Auto-populated during cook execution -->
+
+| Timestamp | Phase | Chef | Verdict | Duration | Notes |
+|-----------|-------|------|---------|----------|-------|
+| | | | | | |
+
+### Escalations
+<!-- Record any escalations that occurred -->
+
+### Blockers Encountered
+<!-- Record blockers and their resolution -->
+
+
 ---
 ## Tracker Snapshot
 <!-- AUTO-GENERATED by cook jira fetch - DO NOT EDIT MANUALLY -->
diff --git a/scripts/lib/auditLogger.js b/scripts/lib/auditLogger.js
new file mode 100644
index 0000000..25c0a1a
--- /dev/null
+++ b/scripts/lib/auditLogger.js
@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+
+/**
+ * Audit Logger for Cook Workflow
+ *
+ * Logs all significant events during cook execution to enable
+ * cross-order learning and pattern detection.
+ *
+ * Log file: .claude/data/cook-audit.jsonl
+ * Schema: .claude/data/cook-audit.schema.json
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const AUDIT_FILE = ".claude/data/cook-audit.jsonl";
+
+/**
+ * Get the audit file path relative to project root
+ */
+function getAuditPath() {
+  // Try to find project root by looking for CLAUDE.md or .claude directory
+  let dir = process.cwd();
+  while (dir !== "/") {
+    if (
+      fs.existsSync(path.join(dir, "CLAUDE.md")) ||
+      fs.existsSync(path.join(dir, ".claude"))
+    ) {
+      return path.join(dir, AUDIT_FILE);
+    }
+    dir = path.dirname(dir);
+  }
+  // Fallback to current directory
+  return path.join(process.cwd(), AUDIT_FILE);
+}
+
+/**
+ * Ensure the audit directory exists
+ */
+function ensureAuditDir() {
+  const auditPath = getAuditPath();
+  const dir = path.dirname(auditPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return auditPath;
+}
+
+/**
+ * Append a log entry to the audit file
+ */
+function appendLog(entry) {
+  const auditPath = ensureAuditDir();
+  const line = JSON.stringify(entry) + "\n";
+  fs.appendFileSync(auditPath, line, "utf8");
+}
+
+/**
+ * Create a base log entry with timestamp
+ */
+function createBaseEntry(orderId, eventType) {
+  return {
+    timestamp: new Date().toISOString(),
+    order_id: orderId,
+    event_type: eventType,
+  };
+}
+
+// ============ Public API ============
+
+/**
+ * Log the start of a phase
+ */
+function logPhaseStart(orderId, phase, chefId) {
+  const entry = {
+    ...createBaseEntry(orderId, "phase_start"),
+    phase,
+    chef_id: chefId,
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Log the completion of a phase
+ */
+function logPhaseCompletion(orderId, phase, chefId, verdict, metadata = {}) {
+  const entry = {
+    ...createBaseEntry(orderId, "phase_complete"),
+    phase,
+    chef_id: chefId,
+    verdict,
+    ...metadata,
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Log an escalation between chefs
+ */
+function logEscalation(orderId, fromChef, toChef, reason, condition = null) {
+  const entry = {
+    ...createBaseEntry(orderId, "escalation"),
+    escalated: true,
+    escalation: {
+      from_chef: fromChef,
+      to_chef: toChef,
+      reason,
+      condition,
+    },
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Log a blocker identified during review
+ */
+function logBlocker(orderId, phase, blockerType, description, severity = "MEDIUM") {
+  const entry = {
+    ...createBaseEntry(orderId, "blocker"),
+    phase,
+    blockers: [
+      {
+        type: blockerType,
+        description,
+        severity,
+      },
+    ],
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Log a handoff between chefs
+ */
+function logHandoff(orderId, fromChef, toChef, validationStatus, missingFields = []) {
+  const entry = {
+    ...createBaseEntry(orderId, "handoff"),
+    handoff: {
+      from_chef: fromChef,
+      to_chef: toChef,
+      validation_status: validationStatus,
+      missing_fields: missingFields,
+    },
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Log a validation failure
+ */
+function logValidationFailure(orderId, phase, chefId, failureDetails) {
+  const entry = {
+    ...createBaseEntry(orderId, "validation_failure"),
+    phase,
+    chef_id: chefId,
+    metadata: failureDetails,
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Log human intervention
+ */
+function logHumanIntervention(orderId, phase, reason, resolution = null) {
+  const entry = {
+    ...createBaseEntry(orderId, "human_intervention"),
+    phase,
+    metadata: {
+      reason,
+      resolution,
+    },
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Log cook completion
+ */
+function logCookComplete(orderId, finalStatus, durationSeconds, summary = {}) {
+  const entry = {
+    ...createBaseEntry(orderId, "cook_complete"),
+    verdict: finalStatus,
+    duration_seconds: durationSeconds,
+    metadata: summary,
+  };
+  appendLog(entry);
+  return entry;
+}
+
+/**
+ * Read all audit entries for a specific order
+ */
+function getOrderAudit(orderId) {
+  const auditPath = getAuditPath();
+  if (!fs.existsSync(auditPath)) {
+    return [];
+  }
+
+  const content = fs.readFileSync(auditPath, "utf8");
+  const lines = content.trim().split("\n").filter(Boolean);
+
+  return lines
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry) => entry && entry.order_id === orderId);
+}
+
+/**
+ * Read all audit entries
+ */
+function getAllAuditEntries() {
+  const auditPath = getAuditPath();
+  if (!fs.existsSync(auditPath)) {
+    return [];
+  }
+
+  const content = fs.readFileSync(auditPath, "utf8");
+  const lines = content.trim().split("\n").filter(Boolean);
+
+  return lines
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Get unique order IDs from audit log
+ */
+function getOrderIds() {
+  const entries = getAllAuditEntries();
+  return [...new Set(entries.map((e) => e.order_id))];
+}
+
+module.exports = {
+  logPhaseStart,
+  logPhaseCompletion,
+  logEscalation,
+  logBlocker,
+  logHandoff,
+  logValidationFailure,
+  logHumanIntervention,
+  logCookComplete,
+  getOrderAudit,
+  getAllAuditEntries,
+  getOrderIds,
+  getAuditPath,
+};
+
+// CLI usage
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case "path":
+      console.log(getAuditPath());
+      break;
+    case "list":
+      console.log(getOrderIds().join("\n"));
+      break;
+    case "show":
+      const orderId = args[1];
+      if (!orderId) {
+        console.error("Usage: auditLogger.js show <order_id>");
+        process.exit(1);
+      }
+      console.log(JSON.stringify(getOrderAudit(orderId), null, 2));
+      break;
+    case "all":
+      console.log(JSON.stringify(getAllAuditEntries(), null, 2));
+      break;
+    default:
+      console.log("Usage: auditLogger.js [path|list|show <order_id>|all]");
+  }
+}
diff --git a/scripts/lib/patternMiner.js b/scripts/lib/patternMiner.js
new file mode 100644
index 0000000..c449e85
--- /dev/null
+++ b/scripts/lib/patternMiner.js
@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+/**
+ * Pattern Miner for Cook Audit Logs
+ *
+ * Analyzes audit history to find patterns, recurring issues,
+ * and opportunities for improvement.
+ */
+
+const auditLogger = require("./auditLogger");
+
+// ============ Analysis Functions ============
+
+/**
+ * Find recurring blockers across orders
+ * Returns blockers that appear in multiple orders
+ */
+function findRecurringBlockers(minOccurrences = 2) {
+  const entries = auditLogger.getAllAuditEntries();
+  const blockerEntries = entries.filter((e) => e.event_type === "blocker");
+
+  // Group by blocker type
+  const blockerCounts = {};
+  for (const entry of blockerEntries) {
+    for (const blocker of entry.blockers || []) {
+      const key = `${blocker.type}:${blocker.severity}`;
+      if (!blockerCounts[key]) {
+        blockerCounts[key] = {
+          type: blocker.type,
+          severity: blocker.severity,
+          count: 0,
+          orders: new Set(),
+          examples: [],
+        };
+      }
+      blockerCounts[key].count++;
+      blockerCounts[key].orders.add(entry.order_id);
+      if (blockerCounts[key].examples.length < 3) {
+        blockerCounts[key].examples.push(blocker.description);
+      }
+    }
+  }
+
+  // Filter to recurring only
+  return Object.values(blockerCounts)
+    .filter((b) => b.orders.size >= minOccurrences)
+    .map((b) => ({
+      ...b,
+      orders: [...b.orders],
+    }))
+    .sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Find escalation patterns
+ * Which chefs escalate most often and to whom
+ */
+function findEscalationPatterns() {
+  const entries = auditLogger.getAllAuditEntries();
+  const escalations = entries.filter((e) => e.event_type === "escalation");
+
+  const patterns = {};
+  for (const entry of escalations) {
+    const esc = entry.escalation;
+    if (!esc) continue;
+
+    const key = `${esc.from_chef} → ${esc.to_chef}`;
+    if (!patterns[key]) {
+      patterns[key] = {
+        from_chef: esc.from_chef,
+        to_chef: esc.to_chef,
+        count: 0,
+        reasons: {},
+        conditions: {},
+      };
+    }
+    patterns[key].count++;
+
+    if (esc.reason) {
+      patterns[key].reasons[esc.reason] =
+        (patterns[key].reasons[esc.reason] || 0) + 1;
+    }
+    if (esc.condition) {
+      patterns[key].conditions[esc.condition] =
+        (patterns[key].conditions[esc.condition] || 0) + 1;
+    }
+  }
+
+  return Object.values(patterns).sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Find phase completion statistics
+ * Which phases take longest, which block most often
+ */
+function findPhaseStatistics() {
+  const entries = auditLogger.getAllAuditEntries();
+
+  const stats = {};
+  const phaseStarts = {};
+
+  for (const entry of entries) {
+    if (entry.event_type === "phase_start") {
+      const key = `${entry.order_id}:${entry.phase}`;
+      phaseStarts[key] = new Date(entry.timestamp);
+    } else if (entry.event_type === "phase_complete") {
+      const phase = entry.phase;
+      if (!stats[phase]) {
+        stats[phase] = {
+          phase,
+          total_count: 0,
+          verdicts: {},
+          durations: [],
+          avg_duration: 0,
+        };
+      }
+
+      stats[phase].total_count++;
+      stats[phase].verdicts[entry.verdict] =
+        (stats[phase].verdicts[entry.verdict] || 0) + 1;
+
+      // Calculate duration if we have start time
+      const key = `${entry.order_id}:${entry.phase}`;
+      if (phaseStarts[key]) {
+        const duration =
+          (new Date(entry.timestamp) - phaseStarts[key]) / 1000;
+        stats[phase].durations.push(duration);
+      } else if (entry.duration_seconds) {
+        stats[phase].durations.push(entry.duration_seconds);
+      }
+    }
+  }
+
+  // Calculate averages
+  for (const stat of Object.values(stats)) {
+    if (stat.durations.length > 0) {
+      stat.avg_duration =
+        stat.durations.reduce((a, b) => a + b, 0) / stat.durations.length;
+    }
+    stat.block_rate =
+      ((stat.verdicts.block || 0) / stat.total_count) * 100;
+  }
+
+  return Object.values(stats);
+}
+
+/**
+ * Analyze pre-mortem prediction accuracy
+ * Compare predicted risks with actual blockers
+ */
+function findPredictionAccuracy() {
+  const entries = auditLogger.getAllAuditEntries();
+  const orderIds = auditLogger.getOrderIds();
+
+  const results = [];
+
+  for (const orderId of orderIds) {
+    const orderEntries = entries.filter((e) => e.order_id === orderId);
+
+    // Find predicted risks (from early phases)
+    const predictedRisks = orderEntries
+      .filter((e) => e.risks_identified && e.risks_identified.length > 0)
+      .flatMap((e) => e.risks_identified);
+
+    // Find actual blockers
+    const actualBlockers = orderEntries
+      .filter((e) => e.event_type === "blocker")
+      .flatMap((e) => e.blockers || []);
+
+    if (predictedRisks.length === 0 && actualBlockers.length === 0) {
+      continue;
+    }
+
+    // Simple matching: check if predicted risks materialized
+    const materialized = actualBlockers.filter((blocker) =>
+      predictedRisks.some(
+        (risk) =>
+          risk.description &&
+          blocker.description &&
+          risk.description.toLowerCase().includes(blocker.type.toLowerCase())
+      )
+    );
+
+    results.push({
+      order_id: orderId,
+      predicted_count: predictedRisks.length,
+      actual_blockers: actualBlockers.length,
+      correctly_predicted: materialized.length,
+      accuracy:
+        predictedRisks.length > 0
+          ? (materialized.length / predictedRisks.length) * 100
+          : null,
+      unpredicted: actualBlockers.length - materialized.length,
+    });
+  }
+
+  // Overall accuracy
+  const totalPredicted = results.reduce((a, r) => a + r.predicted_count, 0);
+  const totalCorrect = results.reduce((a, r) => a + r.correctly_predicted, 0);
+
+  return {
+    orders: results,
+    overall: {
+      total_predictions: totalPredicted,
+      correct_predictions: totalCorrect,
+      accuracy: totalPredicted > 0 ? (totalCorrect / totalPredicted) * 100 : null,
+    },
+  };
+}
+
+/**
+ * Suggest improvements based on patterns
+ */
+function suggestImprovements() {
+  const suggestions = [];
+
+  // Analyze recurring blockers
+  const recurringBlockers = findRecurringBlockers(2);
+  for (const blocker of recurringBlockers.slice(0, 3)) {
+    if (blocker.severity === "HIGH") {
+      suggestions.push({
+        type: "recurring_blocker",
+        priority: "high",
+        message: `HIGH severity blocker "${blocker.type}" occurred ${blocker.count} times across ${blocker.orders.length} orders. Consider adding automated check.`,
+        data: blocker,
+      });
+    }
+  }
+
+  // Analyze escalation patterns
+  const escalations = findEscalationPatterns();
+  for (const pattern of escalations.slice(0, 3)) {
+    if (pattern.count >= 3) {
+      suggestions.push({
+        type: "escalation_pattern",
+        priority: "medium",
+        message: `${pattern.from_chef} frequently escalates to ${pattern.to_chef} (${pattern.count} times). Consider adjusting thresholds or adding guidance.`,
+        data: pattern,
+      });
+    }
+  }
+
+  // Analyze phase statistics
+  const phaseStats = findPhaseStatistics();
+  for (const stat of phaseStats) {
+    if (stat.block_rate > 30) {
+      suggestions.push({
+        type: "high_block_rate",
+        priority: "medium",
+        message: `Phase "${stat.phase}" has ${stat.block_rate.toFixed(1)}% block rate. Consider improving input quality.`,
+        data: stat,
+      });
+    }
+  }
+
+  // Analyze prediction accuracy
+  const accuracy = findPredictionAccuracy();
+  if (accuracy.overall.accuracy !== null && accuracy.overall.accuracy < 30) {
+    suggestions.push({
+      type: "low_prediction_accuracy",
+      priority: "low",
+      message: `Pre-mortem prediction accuracy is ${accuracy.overall.accuracy.toFixed(1)}%. Consider improving risk identification.`,
+      data: accuracy.overall,
+    });
+  }
+
+  return suggestions.sort((a, b) => {
+    const priority = { high: 0, medium: 1, low: 2 };
+    return priority[a.priority] - priority[b.priority];
+  });
+}
+
+/**
+ * Generate a summary report
+ */
+function generateReport() {
+  const orderIds = auditLogger.getOrderIds();
+  const allEntries = auditLogger.getAllAuditEntries();
+
+  return {
+    summary: {
+      total_orders: orderIds.length,
+      total_events: allEntries.length,
+      date_range: {
+        first:
+          allEntries.length > 0
+            ? allEntries[0].timestamp
+            : null,
+        last:
+          allEntries.length > 0
+            ? allEntries[allEntries.length - 1].timestamp
+            : null,
+      },
+    },
+    recurring_blockers: findRecurringBlockers(2),
+    escalation_patterns: findEscalationPatterns(),
+    phase_statistics: findPhaseStatistics(),
+    prediction_accuracy: findPredictionAccuracy(),
+    suggestions: suggestImprovements(),
+  };
+}
+
+module.exports = {
+  findRecurringBlockers,
+  findEscalationPatterns,
+  findPhaseStatistics,
+  findPredictionAccuracy,
+  suggestImprovements,
+  generateReport,
+};
+
+// CLI usage
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case "blockers":
+      console.log(JSON.stringify(findRecurringBlockers(), null, 2));
+      break;
+    case "escalations":
+      console.log(JSON.stringify(findEscalationPatterns(), null, 2));
+      break;
+    case "phases":
+      console.log(JSON.stringify(findPhaseStatistics(), null, 2));
+      break;
+    case "accuracy":
+      console.log(JSON.stringify(findPredictionAccuracy(), null, 2));
+      break;
+    case "suggest":
+      console.log(JSON.stringify(suggestImprovements(), null, 2));
+      break;
+    case "report":
+      console.log(JSON.stringify(generateReport(), null, 2));
+      break;
+    default:
+      console.log(
+        "Usage: patternMiner.js [blockers|escalations|phases|accuracy|suggest|report]"
+      );
+  }
+}

From 0f1e1c373db8d396762ce0fc60f137d9a09ddefa Mon Sep 17 00:00:00 2001
From: Patryk Juniszewski <p.juniszewski@gmail.com>
Date: Sun, 1 Feb 2026 13:43:47 +0100
Subject: [PATCH 12/14] feat: Add explicit fallback policies

- Create FALLBACK_POLICY.md with recovery paths for all failure modes
- Define chef loading fallback with resolution order
- Add verdict fallback with clarification loop
- Add escalation and contract validation fallbacks
- Update cook.md with Fallback Handling section
- Add fallback_behavior to all 10 chef definitions

This layer answers "what happens when we can't decide" with explicit policies.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/agents/architect_chef.md            |   6 +
 .claude/agents/docs_chef.md                 |   6 +
 .claude/agents/engineer_chef.md             |   6 +
 .claude/agents/product_chef.md              |   6 +
 .claude/agents/qa_chef.md                   |   6 +
 .claude/agents/release_chef.md              |   6 +
 .claude/agents/sanitation_inspector_chef.md |   6 +
 .claude/agents/security_chef.md             |   6 +
 .claude/agents/sous_chef.md                 |   6 +
 .claude/agents/ux_chef.md                   |   6 +
 .claude/commands/cook.md                    |  36 +++
 CLAUDE.md                                   |  61 ++++-
 FALLBACK_POLICY.md                          | 271 ++++++++++++++++++++
 13 files changed, 418 insertions(+), 10 deletions(-)
 create mode 100644 FALLBACK_POLICY.md

diff --git a/.claude/agents/architect_chef.md b/.claude/agents/architect_chef.md
index 39111ad..848b06a 100644
--- a/.claude/agents/architect_chef.md
+++ b/.claude/agents/architect_chef.md
@@ -103,6 +103,12 @@ tool_policy:
     - module_boundaries
     - performance_models
     - integration_planning
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: needs-clarification
+  max_clarification_rounds: 2
 ---
 
 # Chef: Architect Chef
diff --git a/.claude/agents/docs_chef.md b/.claude/agents/docs_chef.md
index d08dcc0..572498b 100644
--- a/.claude/agents/docs_chef.md
+++ b/.claude/agents/docs_chef.md
@@ -92,6 +92,12 @@ tool_policy:
     - documentation_planning
     - example_writing
     - changelog_updates
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: proceed_with_warning
+  max_clarification_rounds: 2
 ---
 
 # Chef: Docs Chef
diff --git a/.claude/agents/engineer_chef.md b/.claude/agents/engineer_chef.md
index 38e8da5..55468ae 100644
--- a/.claude/agents/engineer_chef.md
+++ b/.claude/agents/engineer_chef.md
@@ -102,6 +102,12 @@ tool_policy:
     - implementation_design
     - test_planning
     - diagram_generation
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_architect
+  on_timeout: proceed_with_warning
+  max_clarification_rounds: 2
 ---
 
 # Chef: Engineer Chef
diff --git a/.claude/agents/product_chef.md b/.claude/agents/product_chef.md
index aaab7d2..e89cd71 100644
--- a/.claude/agents/product_chef.md
+++ b/.claude/agents/product_chef.md
@@ -94,6 +94,12 @@ tool_policy:
     - scope_analysis
     - prioritization
     - user_value_assessment
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: needs-clarification
+  max_clarification_rounds: 2
 ---
 
 # Chef: Product Chef
diff --git a/.claude/agents/qa_chef.md b/.claude/agents/qa_chef.md
index eea82f0..2d95da8 100644
--- a/.claude/agents/qa_chef.md
+++ b/.claude/agents/qa_chef.md
@@ -101,6 +101,12 @@ tool_policy:
     - test_planning
     - coverage_analysis
     - edge_case_identification
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: proceed_with_warning
+  max_clarification_rounds: 2
 ---
 
 # Chef: QA Chef
diff --git a/.claude/agents/release_chef.md b/.claude/agents/release_chef.md
index 4039083..7e08069 100644
--- a/.claude/agents/release_chef.md
+++ b/.claude/agents/release_chef.md
@@ -99,6 +99,12 @@ tool_policy:
     - version_analysis
     - changelog_writing
     - tag_creation
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: block
+  max_clarification_rounds: 1
 ---
 
 # Chef: Release Chef
diff --git a/.claude/agents/sanitation_inspector_chef.md b/.claude/agents/sanitation_inspector_chef.md
index 9a653dc..49701de 100644
--- a/.claude/agents/sanitation_inspector_chef.md
+++ b/.claude/agents/sanitation_inspector_chef.md
@@ -104,6 +104,12 @@ tool_policy:
     - inspection
     - violation_reporting
     - compliance_verification
+
+fallback_behavior:
+  on_insufficient_context: inspect_without_context
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: report_partial
+  max_clarification_rounds: 1
 ---
 
 # Chef: Sanitation Inspector Chef
diff --git a/.claude/agents/security_chef.md b/.claude/agents/security_chef.md
index 84acc3e..71ed59a 100644
--- a/.claude/agents/security_chef.md
+++ b/.claude/agents/security_chef.md
@@ -99,6 +99,12 @@ tool_policy:
     - vulnerability_analysis
     - threat_modeling
     - security_audit
+
+fallback_behavior:
+  on_insufficient_context: block
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: block
+  max_clarification_rounds: 1
 ---
 
 # Chef: Security Chef
diff --git a/.claude/agents/sous_chef.md b/.claude/agents/sous_chef.md
index 00906a7..18a0cb7 100644
--- a/.claude/agents/sous_chef.md
+++ b/.claude/agents/sous_chef.md
@@ -95,6 +95,12 @@ tool_policy:
     - monitoring
     - reporting
     - analysis
+
+fallback_behavior:
+  on_insufficient_context: report_limited
+  on_conflicting_requirements: report_conflict
+  on_timeout: skip_analysis
+  max_clarification_rounds: 0
 ---
 
 # Chef: Sous Chef
diff --git a/.claude/agents/ux_chef.md b/.claude/agents/ux_chef.md
index 22796fe..9add339 100644
--- a/.claude/agents/ux_chef.md
+++ b/.claude/agents/ux_chef.md
@@ -94,6 +94,12 @@ tool_policy:
     - flow_diagrams
     - ui_review
     - accessibility_audit
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_product
+  on_timeout: proceed_with_warning
+  max_clarification_rounds: 2
 ---
 
 # Chef: UX Chef
diff --git a/.claude/commands/cook.md b/.claude/commands/cook.md
index 43449ac..c8c0a78 100644
--- a/.claude/commands/cook.md
+++ b/.claude/commands/cook.md
@@ -543,6 +543,42 @@ If Tasks API is unavailable (older Claude Code or `CLAUDE_CODE_ENABLE_TASKS=fals
 
 ---
 
+## Fallback Handling
+
+When things go wrong, consult `FALLBACK_POLICY.md` for recovery paths.
+
+### Chef Loading Fallback
+
+If chef loading fails:
+1. Try resolution order: `.claude/agents/` → `~/.claude/agents/` → fuzzy match
+2. If no chef found → use default contract (no blocking verdicts allowed)
+3. Always escalate to human if in doubt
+
+### Verdict Fallback
+
+If verdict is `needs-clarification`:
+1. Allow max 2 clarification rounds
+2. Request additional context between attempts
+3. If still unclear after 2 attempts → escalate to human
+4. Log all attempts to audit trail
+
+### Escalation Fallback
+
+If escalation target unavailable:
+1. Check alternative routing in FALLBACK_POLICY.md
+2. Security escalations → always to human (never skip)
+3. Other unavailable → try alternative or human
+
+### Contract Validation Fallback
+
+If handoff validation fails:
+1. Missing required field → return to previous chef (max 2 retries)
+2. Invalid format → request correction (max 1 retry)
+3. Optional field missing → proceed with warning
+4. Repeated failures → suggest contract review
+
+---
+
 ## Audit Logging
 
 Cook maintains an audit trail for cross-order learning and pattern detection.
diff --git a/CLAUDE.md b/CLAUDE.md
index 1831097..d182da5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,23 +6,45 @@ This repo contains the **juni** plugin - a Claude Code plugin suite combining:
 - `/juni:cook` - Structured feature development workflows
 - `/juni:guard` - Epistemic safety for JSON data
 
-## Architecture: Two-Layer Context System
+## Architecture: Multi-Layer Context System
 
-Cook uses a **hybrid approach** combining narrative context with operational contracts:
+Cook uses a **layered approach** combining narrative context with operational contracts and explicit policies:
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│ CLAUDE.md or AGENTS.md (Narrative Layer)                │
+│ CLAUDE.md / AGENTS.md (Narrative Layer)                 │
 │ "What we build, why, how we work"                       │
 │ → Global project context, loaded in Phase 0             │
 └─────────────────────────────────────────────────────────┘
                          ↓
-              Phase 0: Load project context
+┌─────────────────────────────────────────────────────────┐
+│ ROUTER_POLICY.md (Router/Policy Layer)                  │
+│ "Who decides when"                                      │
+│ → Phase routing, escalation paths, conflict resolution  │
+└─────────────────────────────────────────────────────────┘
                          ↓
 ┌─────────────────────────────────────────────────────────┐
 │ .claude/agents/*_chef.md (Operational Layer)            │
 │ non_negotiables, escalation, rubric, output_contract    │
 │ → Per-phase contracts, loaded before each step          │
+└─────────────────────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────┐
+│ CHEF_CONTRACTS.md (Handoff Layer)                       │
+│ "What is passed to whom"                                │
+│ → Input/output contracts, handoff validation            │
+└─────────────────────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────┐
+│ FALLBACK_POLICY.md (Fallback Layer)                     │
+│ "What when we can't decide"                             │
+│ → Recovery paths, timeouts, degradation modes           │
+└─────────────────────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────┐
+│ .claude/data/cook-audit.jsonl (Audit/Memory Layer)      │
+│ "What did we learn"                                     │
+│ → Event logging, pattern analysis, improvements         │
 └─────────────────────────────────────────────────────────┘
 ```
 
@@ -31,14 +53,18 @@ Cook uses a **hybrid approach** combining narrative context with operational con
 2. `AGENTS.md` - Vercel/industry convention
 3. `README.md` - general project documentation (lowest priority)
 
-**Why two layers?**
+**Architecture layers:**
 
-| Layer | Purpose | When Loaded |
-|-------|---------|-------------|
-| CLAUDE.md / AGENTS.md | Narrative context - goals, architecture, conventions | Once at start (Phase 0) |
-| Chefs | Operational contracts - rules, escalations, outputs | Per-phase as needed |
+| Layer | File | Purpose |
+|-------|------|---------|
+| Narrative | CLAUDE.md | Goals, conventions, context |
+| Router | ROUTER_POLICY.md | Phase→chef mapping, escalation |
+| Operational | .claude/agents/*.md | Per-chef rules and contracts |
+| Handoff | CHEF_CONTRACTS.md | What data passes between chefs |
+| Fallback | FALLBACK_POLICY.md | Recovery when things go wrong |
+| Audit | .claude/data/*.jsonl | Learning from past cooks |
 
-This combines the cognitive benefits of global context (like AGENTS.md) with the operational rigor of contractual skills.
+This combines global context with operational rigor and explicit failure handling.
 
 ## Quick Start
 
@@ -102,6 +128,7 @@ See [COOK_CONTRACT.md](COOK_CONTRACT.md) for full contract.
 
 All chefs output reviews using `review_v1` format. See [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md).
 See [CHEF_MATRIX.md](CHEF_MATRIX.md) for inputs/outputs.
+See [CHEF_CONTRACTS.md](CHEF_CONTRACTS.md) for handoff contracts between chefs.
 
 ## Anti-patterns
 
@@ -130,3 +157,17 @@ Since Claude Code v2.1.16, `/juni:cook` uses the Tasks API for progress tracking
 | Chef not activating | Check `.claude/agents/` has the file |
 | Stuck in Phase 0 | Provide more project context |
 | Order not created | Check `orders/` directory exists |
+| Chef can't decide | Check `FALLBACK_POLICY.md` for recovery |
+| Handoff validation fails | Check `CHEF_CONTRACTS.md` for requirements |
+| Escalation unclear | Check `ROUTER_POLICY.md` for routing |
+
+## Key Contract Files
+
+| File | Purpose |
+|------|---------|
+| [ROUTER_POLICY.md](ROUTER_POLICY.md) | Phase→chef routing, escalation priority |
+| [CHEF_CONTRACTS.md](CHEF_CONTRACTS.md) | Chef-to-chef handoff contracts |
+| [FALLBACK_POLICY.md](FALLBACK_POLICY.md) | Recovery paths for failures |
+| [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md) | Standard review output format |
+| [COOK_CONTRACT.md](COOK_CONTRACT.md) | Artifact structure |
+| [CHEF_MATRIX.md](CHEF_MATRIX.md) | Chef responsibilities matrix |
diff --git a/FALLBACK_POLICY.md b/FALLBACK_POLICY.md
new file mode 100644
index 0000000..370133c
--- /dev/null
+++ b/FALLBACK_POLICY.md
@@ -0,0 +1,271 @@
+# Fallback Policy v1.0
+
+Explicit fallback chains for when things go wrong. No more "proceed with warning" ambiguity.
+
+**Purpose:** Define "what happens when we can't decide" - clear recovery paths for all failure modes.
+
+---
+
+## Chef Loading Fallback
+
+When attempting to load a chef definition:
+
+```yaml
+chef_resolution:
+  order:
+    1: .claude/agents/<role>_chef.md
+    2: ~/.claude/agents/<role>_chef.md
+    3: .claude/agents/*<role>*.md  # fuzzy match
+
+  on_not_found:
+    action: use_default_contract
+    default_contract:
+      verdict_options: [approve, needs-clarification]  # no block without chef
+      escalation: always_to_human
+      strict_mode: true
+      warning: "Chef not found - using default contract"
+
+  on_parse_error:
+    action: escalate_to_human
+    message: "Chef definition has syntax errors"
+    provide_context: [file_path, error_message]
+```
+
+### Resolution Algorithm
+
+```
+1. Try: Glob(".claude/agents/<role>_chef.md")
+2. If found → parse and validate
+3. If not found:
+   a. Try: Glob("~/.claude/agents/<role>_chef.md")
+   b. If not found: Try fuzzy Glob(".claude/agents/*<role>*.md")
+4. If still not found → apply default_contract
+5. If parse error → escalate_to_human
+6. Log resolution result to audit trail
+```
+
+---
+
+## Verdict Fallback
+
+When a chef cannot reach a clear verdict:
+
+```yaml
+when_chef_cannot_decide:
+  needs-clarification:
+    max_attempts: 2
+    on_max_attempts: escalate_to_human
+    timeout_seconds: 300
+    between_attempts:
+      action: request_additional_context
+      prompt: "What additional information would help you reach a verdict?"
+
+  no_clear_verdict:
+    action: request_human_tiebreaker
+    provide_context:
+      - all_chef_outputs
+      - identified_risks
+      - decision_factors
+    timeout_seconds: 86400  # 24 hours
+
+  conflicting_signals:
+    action: apply_escalation_priority
+    if_still_unclear: escalate_to_human
+```
+
+### Clarification Loop
+
+```
+attempt = 0
+while attempt < max_attempts:
+  verdict = chef.review()
+  if verdict != needs-clarification:
+    return verdict
+  attempt += 1
+  context = request_additional_context()
+
+if attempt >= max_attempts:
+  return escalate_to_human()
+```
+
+---
+
+## Escalation Fallback
+
+When the escalation target is unavailable:
+
+```yaml
+when_escalation_target_unavailable:
+  action: escalate_to_human
+  provide_context:
+    - original_escalation_reason
+    - attempted_target
+    - escalation_chain
+
+  alternative_routing:
+    security_chef_unavailable: always_to_human  # never skip security
+    architect_chef_unavailable: try_engineer_chef
+    product_chef_unavailable: always_to_human
+    other_chef_unavailable: proceed_with_warning
+```
+
+### Escalation Chain
+
+```
+1. Try target chef
+2. If unavailable:
+   a. Check alternative_routing
+   b. If alternative exists → try alternative
+   c. If no alternative → escalate_to_human
+3. Log escalation attempt to audit trail
+```
+
+---
+
+## Human Fallback
+
+When human intervention is requested:
+
+```yaml
+when_human_unavailable:
+  timeout_seconds: 86400  # 24 hours
+
+  on_timeout:
+    if_blocking: keep_blocked
+    if_non_blocking: proceed_with_warning
+    log: true
+    notify: true
+
+  notification:
+    message: "Cook workflow waiting for human input"
+    include: [order_id, phase, question, timeout_remaining]
+
+  reminder_intervals: [3600, 14400, 43200]  # 1h, 4h, 12h
+```
+
+### Human Request Format
+
+```yaml
+human_request:
+  order_id: <order_id>
+  phase: <phase>
+  chef_id: <chef_id>
+  question: <specific question>
+  context:
+    - <relevant background>
+  options:
+    - <option A with pros/cons>
+    - <option B with pros/cons>
+  recommendation: <chef's recommendation if any>
+  blocking: true|false
+  timeout: <timestamp>
+```
+
+---
+
+## Contract Validation Fallback
+
+When handoff contract validation fails:
+
+```yaml
+when_contract_fails:
+  missing_required_field:
+    blocking: true
+    action: return_to_previous_chef
+    message: "Missing required field: {field_name}"
+    max_retries: 2
+
+  invalid_format:
+    blocking: true
+    action: request_correction
+    message: "Invalid format for {field_name}: expected {expected}, got {actual}"
+    max_retries: 1
+
+  optional_field_missing:
+    blocking: false
+    action: proceed_with_warning
+    warning: "Optional field missing: {field_name}"
+    log: true
+
+  validation_timeout:
+    action: escalate_to_human
+    message: "Contract validation timed out"
+```
+
+---
+
+## Recovery Actions
+
+Automated recovery for repeated failures:
+
+```yaml
+on_repeated_failures:
+  same_phase_blocked_3x:
+    action: suggest_scope_reduction
+    notify: product_chef
+    message: "Phase {phase} has blocked 3 times. Consider reducing scope."
+    log_pattern: true
+
+  same_chef_escalates_3x:
+    action: review_chef_thresholds
+    notify: product_chef
+    message: "Chef {chef_id} has escalated 3 times. Consider threshold adjustment."
+    log_pattern: true
+
+  contract_fails_repeatedly:
+    action: audit_contract_definition
+    message: "Contract between {from_chef} and {to_chef} failing repeatedly."
+    suggest: "Review CHEF_CONTRACTS.md for this transition"
+
+  human_timeout_repeated:
+    action: escalate_to_project_owner
+    message: "Multiple human timeouts. Process may need restructuring."
+```
+
+---
+
+## Timeout Configuration
+
+Default timeouts for various operations:
+
+```yaml
+timeouts:
+  chef_review: 300         # 5 minutes
+  clarification_round: 120 # 2 minutes
+  human_response: 86400    # 24 hours
+  contract_validation: 30  # 30 seconds
+  pattern_analysis: 60     # 1 minute
+
+  grace_period: 60         # 1 minute buffer before timeout
+```
+
+---
+
+## Graceful Degradation
+
+When systems are partially available:
+
+```yaml
+degradation_modes:
+  audit_unavailable:
+    action: continue_without_audit
+    warning: "Audit logging unavailable - proceeding without logging"
+    retry_interval: 300
+
+  pattern_analysis_unavailable:
+    action: skip_analysis
+    warning: "Pattern analysis unavailable - suggestions disabled"
+
+  tasks_api_unavailable:
+    action: use_artifact_only
+    warning: "Tasks API unavailable - using artifact for tracking"
+```
+
+---
+
+## See Also
+
+- [ROUTER_POLICY.md](ROUTER_POLICY.md) - Normal routing behavior
+- [CHEF_CONTRACTS.md](CHEF_CONTRACTS.md) - Contract definitions
+- [REVIEW_CONTRACT.md](REVIEW_CONTRACT.md) - Review format
+- `.claude/agents/` - Individual chef fallback_behavior

From 116816f8a110b69ddf7faebddca82d9309bcf778 Mon Sep 17 00:00:00 2001
From: Patryk Juniszewski <p.juniszewski@gmail.com>
Date: Sun, 1 Feb 2026 14:20:30 +0100
Subject: [PATCH 13/14] chore: Bump version to 3.1.0

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json |  2 +-
 .claude-plugin/plugin.json      |  2 +-
 CHANGELOG.md                    | 40 ++++++++++++++++++++++++++++++++-
 3 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 56c82c7..41c38cf 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
       "name": "juni",
       "source": "./",
       "description": "Juni Skills Suite - /juni:cook, /juni:guard, and more.",
-      "version": "3.0.0",
+      "version": "3.1.0",
       "category": "development",
       "author": {
         "name": "Patryk Juniszewski"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 3e62112..8987032 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "juni",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Juni Skills Suite - Feature development workflows and context safety tools.",
   "author": {
     "name": "Patryk Juniszewski",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ecfc931..6c0edca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,45 @@ All notable changes to claude-cook will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-<<<<<<< HEAD
+## [3.1.0] - 2026-02-01
+
+### Added
+- **Router/Policy Layer** (`ROUTER_POLICY.md`): Machine-parseable routing rules
+  - Phase → chef mapping with explicit execution order
+  - Escalation priority (security > product > architect > ...)
+  - Conflict resolution algorithm
+  - Phase skip rules (e.g., skip UX for CLI-only changes)
+  - Microwave mode routing with auto-escalation triggers
+- **Chef-to-Chef Contracts** (`CHEF_CONTRACTS.md`): Explicit handoff requirements
+  - Input/output contracts for all 10 chefs
+  - Handoff validation between phases
+  - Blocking vs non-blocking field requirements
+- **Audit/Memory System**: Cross-order learning
+  - `.claude/data/cook-audit.schema.json` - event schema
+  - `scripts/lib/auditLogger.js` - event logging utilities
+  - `scripts/lib/patternMiner.js` - pattern analysis (blockers, escalations, suggestions)
+  - Audit Trail section in order template
+- **Fallback Policies** (`FALLBACK_POLICY.md`): Recovery paths for failures
+  - Chef loading fallback with resolution order
+  - Verdict fallback with clarification loops
+  - Escalation fallback (security always to human)
+  - Contract validation fallback
+  - Graceful degradation modes
+
+### Changed
+- All 10 chefs now have `escalates_to`, `input_contract`, `output_contract`, `fallback_behavior`
+- CLAUDE.md updated with 6-layer architecture diagram
+- cook.md updated with Router Policy, Fallback Handling, and Audit Logging sections
+- REVIEW_CONTRACT.md extended with Handoff Validation section
+
+## [3.0.0] - 2026-01-31
+
+### Changed
+- **Unified chef/order contracts** with review_v1 format
+- Two-layer architecture (narrative + operational)
+- Support for AGENTS.md as alternative to CLAUDE.md
+- Dynamic chef resolution for custom project locations
+
 ## [2.2.0] - 2026-01-29
 
 ### Added

From 624f33a4d82886d7e895513246db908a7eec2234 Mon Sep 17 00:00:00 2001
From: Patryk Juniszewski <p.juniszewski@gmail.com>
Date: Sun, 1 Feb 2026 14:32:22 +0100
Subject: [PATCH 14/14] docs: Add comprehensive architecture diagrams

- High-level 6-layer architecture overview
- Context loading flow (CLAUDE.md/AGENTS.md)
- Router & phase flow with skip rules
- Chef contract structure diagram
- Handoff validation flow
- Escalation flow with priority
- Fallback chains (chef loading, verdict, human)
- Audit & pattern mining system
- Complete cooking flow example
- File reference table

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md | 757 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 757 insertions(+)
 create mode 100644 docs/ARCHITECTURE.md

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..3c22784
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,757 @@
+# Cook Architecture Overview
+
+This document provides a holistic view of how the cook system works - from context loading through chef orchestration to final artifact generation.
+
+---
+
+## 1. High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           /juni:cook "Feature X"                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        LAYER 1: NARRATIVE CONTEXT                           │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                         │
+│  │  CLAUDE.md  │  │  AGENTS.md  │  │  README.md  │   "What we build, why"  │
+│  │  (priority) │  │             │  │  (lowest)   │                         │
+│  └─────────────┘  └─────────────┘  └─────────────┘                         │
+│         │                │                │                                 │
+│         └────────────────┼────────────────┘                                 │
+│                          ▼                                                  │
+│              Merged Project Context                                         │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      LAYER 2: ROUTER / POLICY                               │
+│                       (ROUTER_POLICY.md)                                    │
+│                                                                             │
+│   phase_routing:         escalation_priority:      conflict_resolution:    │
+│   ├─ scope → product     1. security_chef          block > request-changes │
+│   ├─ ux → ux             2. product_chef           request-changes > approve│
+│   ├─ plan → architect    3. architect_chef         tie → escalation_priority│
+│   │         → engineer   4. engineer_chef                                   │
+│   ├─ test → qa                                                              │
+│   ├─ security → security                                                    │
+│   └─ docs → docs                                                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    LAYER 3: OPERATIONAL CONTRACTS                           │
+│                      (.claude/agents/*_chef.md)                             │
+│                                                                             │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
+│  │ product_chef │ │architect_chef│ │engineer_chef │ │   qa_chef    │       │
+│  ├──────────────┤ ├──────────────┤ ├──────────────┤ ├──────────────┤       │
+│  │input_contract│ │input_contract│ │input_contract│ │input_contract│       │
+│  │output_contract││output_contract││output_contract││output_contract│       │
+│  │escalates_to  │ │escalates_to  │ │escalates_to  │ │escalates_to  │       │
+│  │fallback      │ │fallback      │ │fallback      │ │fallback      │       │
+│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘       │
+│                                                                             │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
+│  │security_chef │ │   ux_chef    │ │  docs_chef   │ │ release_chef │       │
+│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘       │
+│                                                                             │
+│  ┌──────────────┐ ┌──────────────┐                                         │
+│  │  sous_chef   │ │sanitation_   │  (monitoring & inspection)              │
+│  │              │ │inspector_chef│                                         │
+│  └──────────────┘ └──────────────┘                                         │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                   LAYER 4: CHEF-TO-CHEF CONTRACTS                           │
+│                       (CHEF_CONTRACTS.md)                                   │
+│                                                                             │
+│   product ──────────────────────────────────────────────────► architect    │
+│            approved_scope, non_goals, success_metrics, priority            │
+│                                                                             │
+│   architect ────────────────────────────────────────────────► engineer     │
+│              chosen_alternative, trade_offs, affected_modules              │
+│                                                                             │
+│   engineer ─────────────────────────────────────────────────► qa           │
+│             implementation_plan, files_to_modify, edge_cases               │
+│                                                                             │
+│   qa ───────────────────────────────────────────────────────► security     │
+│       test_cases, coverage_areas, uncovered_risks                          │
+│                                                                             │
+│   security ─────────────────────────────────────────────────► docs         │
+│             security_status, security_notes                                │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      LAYER 5: FALLBACK POLICY                               │
+│                       (FALLBACK_POLICY.md)                                  │
+│                                                                             │
+│   chef_loading:          verdict_fallback:        escalation_fallback:     │
+│   1. .claude/agents/     needs-clarification:     target unavailable:      │
+│   2. ~/.claude/agents/     max 2 attempts           → escalate to human    │
+│   3. *<role>*.md           → escalate to human                             │
+│   4. default_contract                                                      │
+│                          no_clear_verdict:        human_unavailable:       │
+│                            → human tiebreaker       24h timeout            │
+│                                                     → keep blocked         │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      LAYER 6: AUDIT / MEMORY                                │
+│                  (.claude/data/cook-audit.jsonl)                            │
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐  │
+│   │ {"event_type":"phase_complete","chef_id":"product_chef",...}        │  │
+│   │ {"event_type":"handoff","from":"product_chef","to":"architect",...} │  │
+│   │ {"event_type":"escalation","from":"engineer","to":"architect",...}  │  │
+│   └─────────────────────────────────────────────────────────────────────┘  │
+│                                      │                                      │
+│                                      ▼                                      │
+│                          ┌───────────────────┐                             │
+│                          │   patternMiner    │                             │
+│                          ├───────────────────┤                             │
+│                          │ recurringBlockers │                             │
+│                          │ escalationPatterns│                             │
+│                          │ phaseStatistics   │                             │
+│                          │ suggestions       │                             │
+│                          └───────────────────┘                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          OUTPUT: COOK ARTIFACT                              │
+│                    (cook/<feature>.<date>.cook.md)                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Context Loading Flow
+
+```
+                    ┌──────────────────────────────────────┐
+                    │         /juni:cook invoked           │
+                    └──────────────────────────────────────┘
+                                       │
+                                       ▼
+              ┌────────────────────────────────────────────────┐
+              │            PHASE 0: Load Context               │
+              └────────────────────────────────────────────────┘
+                                       │
+          ┌────────────────────────────┼────────────────────────────┐
+          ▼                            ▼                            ▼
+   ┌─────────────┐              ┌─────────────┐              ┌─────────────┐
+   │  CLAUDE.md  │              │  AGENTS.md  │              │  README.md  │
+   │  Priority 1 │              │  Priority 2 │              │  Priority 3 │
+   └─────────────┘              └─────────────┘              └─────────────┘
+          │                            │                            │
+          │   ┌────────────────────────┘                            │
+          │   │   ┌─────────────────────────────────────────────────┘
+          ▼   ▼   ▼
+   ┌─────────────────────────────────────────────────────────────────┐
+   │                    MERGED PROJECT CONTEXT                       │
+   │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
+   │  │   Hard Rules    │  │Preferred Patterns│  │   Non-Goals    │ │
+   │  │ (MUST/MUST NOT) │  │  (conventions)   │  │  (forbidden)   │ │
+   │  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
+   │                                                                 │
+   │  On conflict: CLAUDE.md > AGENTS.md > README.md                │
+   └─────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼
+                    ┌──────────────────────────────────────┐
+                    │   Write to artifact: Phase 0 section │
+                    └──────────────────────────────────────┘
+```
+
+---
+
+## 3. Router & Phase Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          ROUTER_POLICY.md                                   │
+│                                                                             │
+│  Determines: WHO reviews WHAT and WHEN                                      │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                           COOKING FLOW
+                               │
+     ┌─────────────────────────┼─────────────────────────┐
+     │                         │                         │
+     ▼                         ▼                         ▼
+┌─────────┐              ┌───────────┐            ┌───────────┐
+│ Step 1  │              │  Step 2   │            │  Step 3   │
+│  Read   │──────────────│   Scope   │────────────│    UX     │
+│  Order  │              │ (product) │            │   (ux)    │
+└─────────┘              └───────────┘            └───────────┘
+                               │                       │
+                               │              ┌────────┘
+                               │              │ skip if no_ui_changes
+                               ▼              ▼
+                         ┌───────────────────────┐
+                         │       Step 4          │
+                         │    Plan (sequential)  │
+                         │  ┌─────────────────┐  │
+                         │  │  architect_chef │  │
+                         │  └────────┬────────┘  │
+                         │           │           │
+                         │           ▼           │
+                         │  ┌─────────────────┐  │
+                         │  │  engineer_chef  │  │
+                         │  └─────────────────┘  │
+                         └───────────────────────┘
+                                    │
+                                    ▼
+                         ┌───────────────────────┐
+                         │       Step 5          │
+                         │    Test (qa_chef)     │
+                         └───────────────────────┘
+                                    │
+                                    ▼
+                         ┌───────────────────────┐
+                         │       Step 6          │
+                         │ Security (mandatory)  │
+                         │   NEVER SKIPPED       │
+                         └───────────────────────┘
+                                    │
+                                    ▼
+                         ┌───────────────────────┐
+                         │       Step 7          │
+                         │   Docs (docs_chef)    │
+                         └───────────────────────┘
+                                    │
+                                    ▼
+                         ┌───────────────────────┐
+                         │   COOKING COMPLETE    │
+                         └───────────────────────┘
+
+
+                      PHASE SKIP RULES
+    ┌─────────────────────────────────────────────────┐
+    │  Condition          │  Skip Phase   │ Reason   │
+    ├─────────────────────┼───────────────┼──────────┤
+    │  no_ui_changes      │  ux           │ CLI only │
+    │  docs_only          │  security,test│ Low risk │
+    │  microwave_mode     │  scope, ux    │ Speed    │
+    └─────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Chef Contract Structure
+
+Each chef has a standardized contract structure:
+
+```yaml
+# .claude/agents/<role>_chef.md
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           CHEF CONTRACT                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      INPUT CONTRACT                                  │   │
+│  │  requires_from: <previous_chef>                                      │   │
+│  │  required_fields:                                                    │   │
+│  │    - field_1                                                         │   │
+│  │    - field_2                                                         │   │
+│  │  optional_fields:                                                    │   │
+│  │    - optional_1                                                      │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      CHEF PROCESSING                                 │   │
+│  │                                                                      │   │
+│  │  traits:                    non_negotiables:                         │   │
+│  │    risk_posture: balanced     - rule_1                               │   │
+│  │    quality_bar: standard      - rule_2                               │   │
+│  │    verbosity: minimal                                                │   │
+│  │                                                                      │   │
+│  │  allowed_scope:             rubric:                                  │   │
+│  │    can: [...]                 ready_for_merge:                       │   │
+│  │    cannot_without_human:        - criterion_1                        │   │
+│  │      [...]                      - criterion_2                        │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      OUTPUT CONTRACT                                 │   │
+│  │  format: review_v1                                                   │   │
+│  │  required_sections:                                                  │   │
+│  │    - verdict        # approve | block | request-changes              │   │
+│  │    - must_fix       # blocking issues                                │   │
+│  │    - should_fix     # non-blocking suggestions                       │   │
+│  │    - questions      # clarification needed                           │   │
+│  │    - risks          # identified risks                               │   │
+│  │    - next_step      # what happens next                              │   │
+│  │                                                                      │   │
+│  │  handoff_to: <next_chef>                                             │   │
+│  │  handoff_fields:                                                     │   │
+│  │    - output_1                                                        │   │
+│  │    - output_2                                                        │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      ESCALATION                                      │   │
+│  │  escalates_to:                                                       │   │
+│  │    - condition: <trigger>                                            │   │
+│  │      target: <other_chef>                                            │   │
+│  │      reason: "why escalate"                                          │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      FALLBACK BEHAVIOR                               │   │
+│  │  on_insufficient_context: needs-clarification                        │   │
+│  │  on_conflicting_requirements: escalate_to_human                      │   │
+│  │  on_timeout: proceed_with_warning                                    │   │
+│  │  max_clarification_rounds: 2                                         │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. Handoff Validation Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         HANDOFF VALIDATION                                  │
+│                        (Before each phase)                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+   ┌──────────────────┐                           ┌──────────────────┐
+   │   product_chef   │                           │  architect_chef  │
+   │                  │                           │                  │
+   │  output_contract │                           │  input_contract  │
+   │  ────────────────│                           │  ────────────────│
+   │  handoff_to:     │                           │  requires_from:  │
+   │    architect     │────────────────────────── │    product       │
+   │                  │                           │                  │
+   │  handoff_fields: │         MUST MATCH        │  required_fields:│
+   │  - approved_scope│─────────────────────────► │  - approved_scope│
+   │  - non_goals     │─────────────────────────► │  - non_goals     │
+   │  - success_metric│─────────────────────────► │  - success_metric│
+   │  - priority      │─────────────────────────► │  - priority      │
+   └──────────────────┘                           └──────────────────┘
+           │                                               │
+           │                                               │
+           ▼                                               ▼
+   ┌──────────────────────────────────────────────────────────────────┐
+   │                    VALIDATION CHECK                              │
+   │                                                                  │
+   │  for each field in next_chef.input_contract.required_fields:    │
+   │    if field NOT in previous_chef_output:                        │
+   │      if blocking_if_missing:                                     │
+   │        → BLOCK with "missing handoff field"                      │
+   │      else:                                                       │
+   │        → WARN and proceed                                        │
+   │                                                                  │
+   │  RESULT: PASSED | FAILED (with missing fields)                  │
+   └──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Escalation Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          ESCALATION FLOW                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                    Normal Flow
+                        │
+                        ▼
+            ┌───────────────────────┐
+            │    engineer_chef      │
+            │    processing...      │
+            └───────────────────────┘
+                        │
+                        │ Detects: affects_5_plus_modules
+                        ▼
+            ┌───────────────────────┐
+            │   ESCALATION TRIGGER  │
+            │                       │
+            │  condition matched:   │
+            │  affects_5_plus_modules│
+            └───────────────────────┘
+                        │
+                        │ Look up in ROUTER_POLICY.md
+                        ▼
+            ┌───────────────────────┐
+            │  escalation_routes:   │
+            │  engineer_chef:       │
+            │    on: affects_5_plus │
+            │    escalate_to:       │
+            │      architect_chef   │
+            └───────────────────────┘
+                        │
+                        ▼
+            ┌───────────────────────┐
+            │   architect_chef      │
+            │   (escalation target) │
+            └───────────────────────┘
+                        │
+                        │ Resolves concern OR
+                        │ escalates further
+                        ▼
+            ┌───────────────────────┐
+            │  ESCALATION PRIORITY  │
+            │  (conflict resolver)  │
+            │                       │
+            │  1. security_chef     │◄── Security always wins
+            │  2. product_chef      │
+            │  3. architect_chef    │
+            │  4. engineer_chef     │
+            └───────────────────────┘
+
+
+                 SPECIAL CASE: Security Escalation
+
+            ┌───────────────────────┐
+            │     ANY chef          │
+            │     processing...     │
+            └───────────────────────┘
+                        │
+                        │ Detects: security_vulnerability
+                        ▼
+            ┌───────────────────────┐
+            │   IMMEDIATE ESCALATE  │
+            │   to security_chef    │
+            │   (overrides all)     │
+            └───────────────────────┘
+                        │
+                        ▼
+            ┌───────────────────────┐
+            │   security_chef       │
+            │   verdict: block      │──────► COOKING STOPS
+            │   (if high risk)      │
+            └───────────────────────┘
+```
+
+---
+
+## 7. Fallback Chain
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          FALLBACK CHAINS                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+
+    CHEF LOADING FALLBACK
+    ──────────────────────
+
+    Need: product_chef
+           │
+           ▼
+    ┌─────────────────────────────┐
+    │ 1. .claude/agents/          │
+    │    product_chef.md          │───── Found? ──► USE IT
+    └─────────────────────────────┘
+           │ Not found
+           ▼
+    ┌─────────────────────────────┐
+    │ 2. ~/.claude/agents/        │
+    │    product_chef.md          │───── Found? ──► USE IT
+    └─────────────────────────────┘
+           │ Not found
+           ▼
+    ┌─────────────────────────────┐
+    │ 3. .claude/agents/          │
+    │    *product*.md (glob)      │───── Found? ──► USE IT
+    └─────────────────────────────┘
+           │ Not found
+           ▼
+    ┌─────────────────────────────┐
+    │ 4. DEFAULT CONTRACT         │
+    │    - verdict: [approve,     │
+    │      needs-clarification]   │
+    │    - escalation: to human   │
+    │    - strict_mode: true      │
+    └─────────────────────────────┘
+
+
+
+    VERDICT FALLBACK
+    ─────────────────
+
+    Chef returns: needs-clarification
+           │
+           ▼
+    ┌─────────────────────────────┐
+    │  Clarification Round 1      │
+    │  Ask for more context       │
+    └─────────────────────────────┘
+           │
+           │ Still unclear?
+           ▼
+    ┌─────────────────────────────┐
+    │  Clarification Round 2      │
+    │  (max_clarification_rounds) │
+    └─────────────────────────────┘
+           │
+           │ Still unclear?
+           ▼
+    ┌─────────────────────────────┐
+    │  ESCALATE TO HUMAN          │
+    │  Provide:                   │
+    │  - all chef outputs         │
+    │  - identified risks         │
+    │  - what's unclear           │
+    └─────────────────────────────┘
+
+
+
+    HUMAN FALLBACK
+    ───────────────
+
+    Escalated to human
+           │
+           ▼
+    ┌─────────────────────────────┐
+    │  Wait for human response    │
+    │  timeout: 24 hours          │
+    └─────────────────────────────┘
+           │
+           │ Timeout reached?
+           ▼
+    ┌────────────────┬────────────────┐
+    │  IF BLOCKING   │ IF NON-BLOCKING│
+    │                │                │
+    │  Keep blocked  │ Proceed with   │
+    │  Log: true     │ warning        │
+    │                │ Log: true      │
+    └────────────────┴────────────────┘
+```
+
+---
+
+## 8. Audit & Pattern Mining
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          AUDIT SYSTEM                                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+    During Cooking:
+    ───────────────
+
+    ┌────────────────────┐     ┌────────────────────┐
+    │   Phase Start      │     │   Phase Complete   │
+    │   logPhaseStart()  │     │ logPhaseCompletion│
+    └────────────────────┘     └────────────────────┘
+              │                          │
+              │                          │
+              ▼                          ▼
+    ┌─────────────────────────────────────────────────────────────────────┐
+    │                  .claude/data/cook-audit.jsonl                      │
+    │                                                                     │
+    │  {"event_type":"phase_start","order_id":"feat-123",...}            │
+    │  {"event_type":"phase_complete","verdict":"approve",...}           │
+    │  {"event_type":"escalation","from":"engineer","to":"architect",...}│
+    │  {"event_type":"handoff","validation":"passed",...}                │
+    │  {"event_type":"blocker","blocker_type":"security",...}            │
+    └─────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    │ After multiple orders
+                                    ▼
+    ┌─────────────────────────────────────────────────────────────────────┐
+    │                      PATTERN MINING                                 │
+    │                    (patternMiner.js)                                │
+    │                                                                     │
+    │  ┌─────────────────────────────────────────────────────────────┐   │
+    │  │  findRecurringBlockers()                                    │   │
+    │  │  → "security_chef blocks 40% of orders"                     │   │
+    │  │  → "input_validation is top blocker (5 occurrences)"        │   │
+    │  └─────────────────────────────────────────────────────────────┘   │
+    │                                                                     │
+    │  ┌─────────────────────────────────────────────────────────────┐   │
+    │  │  findEscalationPatterns()                                   │   │
+    │  │  → "engineer_chef escalates to architect 30% of time"       │   │
+    │  │  → "Most escalations happen in plan phase"                  │   │
+    │  └─────────────────────────────────────────────────────────────┘   │
+    │                                                                     │
+    │  ┌─────────────────────────────────────────────────────────────┐   │
+    │  │  findPhaseStatistics()                                      │   │
+    │  │  → "security phase has 15% block rate"                      │   │
+    │  │  → "Average phases per order: 7.2"                          │   │
+    │  └─────────────────────────────────────────────────────────────┘   │
+    │                                                                     │
+    │  ┌─────────────────────────────────────────────────────────────┐   │
+    │  │  suggestImprovements()                                      │   │
+    │  │  → "Add security checklist earlier in process"              │   │
+    │  │  → "Consider pre-review for high-escalation areas"          │   │
+    │  └─────────────────────────────────────────────────────────────┘   │
+    └─────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │   cook-stats patterns         │
+                    │   (CLI dashboard)             │
+                    └───────────────────────────────┘
+```
+
+---
+
+## 9. Complete Cooking Flow Example
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│              /juni:cook "Add user authentication" --well-done               │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 0.0 ──────────────────────────────────────────────────────────────────┐
+│  CREATE ARTIFACT                                                            │
+│  → cook/add-user-authentication.2026-02-01.cook.md                         │
+│  → Status: raw                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Phase 0 ───────────────────────────────────────────────────────────────────┐
+│  LOAD CONTEXT                                                               │
+│  → Read CLAUDE.md, AGENTS.md, README.md                                    │
+│  → Extract hard rules, patterns, non-goals                                 │
+│  → Audit: logPhaseStart("phase_0")                                         │
+│  → Status: cooking                                                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 0.5 ──────────────────────────────────────────────────────────────────┐
+│  KITCHEN RECON (well-done only)                                            │
+│  → Launch Explore agents in parallel                                        │
+│  → Find similar implementations                                             │
+│  → Map integration points                                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 1 ────────────────────────────────────────────────────────────────────┐
+│  READ THE ORDER                                                             │
+│  → Parse feature description                                                │
+│  → Identify affected modules                                                │
+│  → Check microwave blockers (auth = BLOCKED → stay well-done)              │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 2 ────────────────────────────────────────────────────────────────────┐
+│  INGREDIENT APPROVAL                                                        │
+│  → Router: phase=scope → product_chef                                      │
+│  → Load: .claude/agents/product_chef.md                                    │
+│  → Input validation: (none required, first chef)                           │
+│  → Review: verdict=approve                                                  │
+│  → Handoff validation: approved_scope, non_goals, metrics ✓                │
+│  → Audit: logPhaseCompletion("scope", "product_chef", "approve")           │
+│  → Audit: logHandoff("product_chef", "architect_chef", "passed")           │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 3 ────────────────────────────────────────────────────────────────────┐
+│  PRESENTATION PLANNING                                                      │
+│  → Router: phase=ux → ux_chef                                              │
+│  → Check skip rule: has UI changes? YES → continue                         │
+│  → Load: .claude/agents/ux_chef.md                                         │
+│  → Review: verdict=approve                                                  │
+│  → Audit: logPhaseCompletion("ux", "ux_chef", "approve")                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 4 ────────────────────────────────────────────────────────────────────┐
+│  IMPLEMENTATION PLAN (sequential)                                           │
+│                                                                             │
+│  4a. ARCHITECT                                                              │
+│  → Router: phase=plan → [architect_chef, engineer_chef]                    │
+│  → Load: .claude/agents/architect_chef.md                                  │
+│  → Input validation: approved_scope ✓, non_goals ✓                         │
+│  → Review: verdict=approve                                                  │
+│  → Detects: affects 6 modules → NO escalation (within threshold)           │
+│  → Handoff: chosen_alternative, trade_offs, affected_modules               │
+│                                                                             │
+│  4b. ENGINEER                                                               │
+│  → Load: .claude/agents/engineer_chef.md                                   │
+│  → Input validation: chosen_alternative ✓, trade_offs ✓                    │
+│  → Review: verdict=approve                                                  │
+│  → Handoff: implementation_plan, files_to_modify, edge_cases               │
+│  → Audit: logPhaseCompletion("plan", "engineer_chef", "approve")           │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 5 ────────────────────────────────────────────────────────────────────┐
+│  TASTE TESTING                                                              │
+│  → Router: phase=test → qa_chef                                            │
+│  → Load: .claude/agents/qa_chef.md                                         │
+│  → Input validation: implementation_plan ✓, files_to_modify ✓              │
+│  → Review: verdict=approve                                                  │
+│  → Handoff: test_cases, coverage_areas, uncovered_risks                    │
+│  → Audit: logPhaseCompletion("test", "qa_chef", "approve")                 │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 6 ────────────────────────────────────────────────────────────────────┐
+│  SECURITY REVIEW (NEVER SKIPPED)                                           │
+│  → Router: phase=security → security_chef                                  │
+│  → Load: .claude/agents/security_chef.md                                   │
+│  → Input validation: test_cases ✓                                          │
+│  → Review: verdict=approve (auth implementation secure)                    │
+│  → Handoff: security_status, security_notes                                │
+│  → Audit: logPhaseCompletion("security", "security_chef", "approve")       │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─ Step 7 ────────────────────────────────────────────────────────────────────┐
+│  RECIPE NOTES                                                               │
+│  → Router: phase=docs → docs_chef                                          │
+│  → Load: .claude/agents/docs_chef.md                                       │
+│  → Review: verdict=approve                                                  │
+│  → Audit: logPhaseCompletion("docs", "docs_chef", "approve")               │
+│  → Audit: logCookComplete("add-user-auth", "well-done")                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  COOKING COMPLETE                                                           │
+│  → Status: well-done ✅                                                     │
+│  → Artifact: cook/add-user-authentication.2026-02-01.cook.md               │
+│  → All handoffs validated                                                   │
+│  → No escalations triggered                                                 │
+│  → Audit log updated                                                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 10. File Reference
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` / `AGENTS.md` | Narrative context (project goals, conventions) |
+| `ROUTER_POLICY.md` | Phase→chef routing, escalation rules |
+| `CHEF_CONTRACTS.md` | Handoff requirements between chefs |
+| `FALLBACK_POLICY.md` | Recovery paths for failures |
+| `REVIEW_CONTRACT.md` | Output format (review_v1) |
+| `.claude/agents/*_chef.md` | Individual chef contracts |
+| `.claude/data/cook-audit.jsonl` | Audit log (JSON Lines) |
+| `scripts/lib/auditLogger.js` | Audit logging functions |
+| `scripts/lib/patternMiner.js` | Pattern analysis functions |
+| `cook/*.cook.md` | Generated artifacts |
+
+---
+
+## 11. Key Principles
+
+1. **Narrative + Operational**: Global context (CLAUDE.md) + per-phase contracts (chefs)
+2. **Explicit Routing**: ROUTER_POLICY determines who reviews what
+3. **Validated Handoffs**: Each chef validates inputs before processing
+4. **Escalation Priority**: Security > Product > Architect > Engineer
+5. **Fallback Chains**: Every failure mode has a recovery path
+6. **Audit Everything**: Learn from patterns across orders
+7. **Security Never Skipped**: Always mandatory review