@haposoft/cafekit 0.15.3 → 0.16.0-rc.2

package/src/claude/skills/mobile-development/SKILL.md

@@ -31,8 +31,8 @@ Production-ready mobile development with modern frameworks, best practices, and
 ## Technology Selection Guide
 
 **Cross-Platform Frameworks:**
-- **React Native**: JavaScript expertise, web code sharing, mature ecosystem (121K stars, 67% familiarity)
-- **Flutter**: Performance-critical apps, complex animations, fastest-growing (170K stars, 46% adoption)
+- **React Native**: JavaScript expertise, web code sharing, mature ecosystem
+- **Flutter**: Performance-critical apps, complex animations, fastest-growing
 
 **Native Development:**
 - **iOS (Swift/SwiftUI)**: Maximum iOS performance, latest features, Apple ecosystem integration
@@ -44,7 +44,7 @@ See: `references/mobile-frameworks.md` for detailed framework comparisons
 
 **The 10 Commandments of Mobile Development:**
 
-1. **Performance is Foundation, Not Feature** - 70% abandon apps >3s load time
+1. **Performance is Foundation, Not Feature** - Slow load times can drive users away
 2. **Every Kilobyte, Every Millisecond Matters** - Mobile constraints are real
 3. **Offline-First by Default** - Network is unreliable, design for it
 4. **User Context > Developer Environment** - Think real-world usage scenarios
@@ -72,7 +72,7 @@ See: `references/mobile-mindset.md` for thinking patterns and decision framework
 ## Key Best Practices (2024-2025)
 
 **Performance Targets:**
-- App launch: <2 seconds (70% abandon if >3s)
+- App launch: <2 seconds; slow launches risk abandonment
 - Memory usage: <100MB for typical screens
 - Network requests: Batch and cache aggressively
 - Battery impact: Respect Doze Mode and background restrictions
@@ -92,7 +92,7 @@ See: `references/mobile-mindset.md` for thinking patterns and decision framework
 - Implement proper session management
 
 **Testing Strategy:**
-- Unit tests: 70%+ coverage for business logic
+- Unit tests: meaningful coverage for business logic
 - Integration tests: Critical user flows
 - E2E tests: Detox (React Native), Appium (cross-platform), XCUITest (iOS), Espresso (Android)
 - Real device testing mandatory before release
@@ -101,7 +101,7 @@ See: `references/mobile-mindset.md` for thinking patterns and decision framework
 - Fastlane for automation across platforms
 - Staged rollouts: Internal → Closed → Open → Production
 - Mandatory: iOS 17 SDK (2024), Android 15 API 35 (Aug 2025)
-- CI/CD saves 20% development time
+- CI/CD saves development time
 
 ## Quick Decision Matrix
 
@@ -121,9 +121,9 @@ See: `references/mobile-mindset.md` for thinking patterns and decision framework
 
 | Criterion | React Native | Flutter | Swift/SwiftUI | Kotlin/Compose |
 |-----------|--------------|---------|---------------|----------------|
-| **Stars** | 121K | 170K | N/A | N/A |
-| **Adoption** | 35% | 46% | iOS only | Android only |
-| **Performance** | 80-90% native | 85-95% native | 100% native | 100% native |
+| **Community footprint** | Large | Large | Apple ecosystem | Android ecosystem |
+| **Adoption** | Established | Established | iOS only | Android only |
+| **Performance** | Near-native when profiled | Near-native when profiled | Native baseline | Native baseline |
 | **Dev Speed** | Fast (hot reload) | Very fast (hot reload) | Fast (Xcode Previews) | Fast (Live Edit) |
 | **Learning Curve** | Easy (JavaScript) | Medium (Dart) | Medium (Swift) | Medium (Kotlin) |
 | **UI Paradigm** | Component-based | Widget-based | Declarative | Declarative |
@@ -148,7 +148,7 @@ See: `references/mobile-mindset.md` for thinking patterns and decision framework
 - Image optimization → Lazy loading → Memory profiling → Network optimization → Battery testing → Launch time optimization
 
 **Quality:**
-- Unit tests (70%+) → Integration tests → E2E tests → Accessibility testing → Performance testing → Security audit
+- Unit tests → Integration tests → E2E tests → Accessibility testing → Performance testing → Security audit
 
 **Security:**
 - Secure storage → Authentication flow → Network security → Input validation → Session management → Encryption
@@ -179,7 +179,7 @@ See: `references/mobile-mindset.md` for thinking patterns and decision framework
 3. **No offline handling** - Network failures will happen
 4. **Poor memory management** - Leads to crashes and poor UX
 5. **Hardcoded credentials** - Security vulnerability
-6. **No accessibility** - Excludes 15%+ of users
+6. **No accessibility** - Can exclude users
 7. **Premature optimization** - Optimize based on metrics, not assumptions
 8. **Over-engineering** - Start simple, scale as needed
 9. **Skipping real device testing** - Simulators don't show battery/network issues
@@ -193,7 +193,7 @@ See: `references/mobile-mindset.md` for thinking patterns and decision framework
 - **Screen load**: <1 second for cached data
 - **Network request**: <3 seconds for API calls
 - **Memory**: <100MB for typical screens, <200MB peak
-- **Battery**: <5% drain per hour of active use
+- **Battery**: Minimize drain during active use
 - **Frame rate**: 60 FPS (16.67ms per frame)
 
 ## Resources

package/src/claude/skills/mobile-development/references/mobile-android.md

@@ -74,8 +74,8 @@ when (uiState) {
 
 ### Why Compose?
 - **Declarative**: Describe UI state, not imperative commands
-- **60% adoption**: In top 1,000 apps (2024)
-- **Less code**: 40% reduction vs Views
+- **Adoption**: Used in many top 1,000 apps
+- **Less code**: Reduction vs Views
 - **Modern**: Built for Kotlin and coroutines
 - **Material 3**: First-class support
 
@@ -310,7 +310,7 @@ class UserViewModel(
 
 **Hilt vs Koin:**
 - **Hilt**: Compile-time, type-safe, Google-backed, complex setup
-- **Koin**: Runtime, simple DSL, 50% faster setup, reflection-based
+- **Koin**: Runtime, simple DSL, faster setup, reflection-based
 
 ## Performance Optimization
 
@@ -335,14 +335,14 @@ android {
 ```
 
 **Impact:**
-- 10-20% app size reduction
-- 20% faster startup
+- Smaller app size
+- Faster startup
 - Harder to reverse engineer
 
 ### Baseline Profiles
 
 **Performance boost:**
-- 10-20% faster startup
+- Faster startup
 - Reduced jank in critical paths
 - AOT compilation of hot code
 
@@ -572,7 +572,7 @@ android {
 ```
 
 **Benefits:**
-- 15-30% smaller downloads
+- Smaller downloads
 - Dynamic feature modules
 - Instant apps support
 

package/src/claude/skills/mobile-development/references/mobile-best-practices.md

@@ -86,8 +86,8 @@ User opens screen
 - Background App Refresh (iOS)
 
 **Targets:**
-- Active use: <5% per hour
-- Background: <1% per hour
+- Active use: minimize foreground energy use
+- Background: minimize background energy use
 
 ## Offline-First Architecture
 
@@ -315,8 +315,8 @@ messaging().onNotificationOpenedApp(remoteMessage => {
 ```
 
 **Impact:**
-- 25% revenue increase with proper personalization
-- 88% opt-in rate with pre-permission modal (vs 40% without)
+- Personalization can increase revenue
+- Pre-permission modal can improve opt-in rate
 
 ## Authentication & Authorization
 
@@ -443,10 +443,10 @@ const token = credentials.password;
 - Expedited: 1-2 hours (emergencies only)
 
 **Rejection Reasons:**
-- Crashes (50%)
-- Privacy violations (25%)
-- Incomplete information (15%)
-- Guideline violations (10%)
+- Crashes
+- Privacy violations
+- Incomplete information
+- Guideline violations
 
 ### Google Play (Android)
 
@@ -460,7 +460,7 @@ const token = credentials.password;
 1. Build signed AAB (Android App Bundle)
 2. Upload to Play Console
 3. Submit to production track
-4. Staged rollout (10% → 50% → 100%)
+4. Staged rollout (pilot → partial → full)
 
 **Review Time:**
 - Average: 1-3 days
@@ -468,22 +468,21 @@ const token = credentials.password;
 
 ### Staged Rollout Strategy
 
-**Week 1:**
-- 10% of users
+**Pilot:**
+- Release to a small audience
 - Monitor crash-free rate
 - Watch for critical bugs
 
-**Week 2:**
-- 50% of users
+**Partial rollout:**
+- Expand audience after pilot
 - Validate performance metrics
 - Check user feedback
 
-**Week 3:**
-- 100% of users
-- Full release if metrics healthy
+**Full rollout:**
+- Release to all users when metrics are healthy
 
 **Rollback Triggers:**
-- Crash-free rate drops >5%
+- Crash-free rate shows a material drop
 - Critical bug discovered
 - Major user complaints
 
@@ -493,12 +492,12 @@ const token = credentials.password;
 
 | Metric | React Native | Flutter |
 |--------|--------------|---------|
-| **Adoption** | 35% | 46% |
-| **Performance** | 80-90% | 85-95% |
-| **App Size** | 40-50MB | 15-20MB |
-| **Dev Speed** | Fast | Very Fast |
-| **Commercial** | 12.57% | 5.24% |
-| **Developers** | 20:1 ratio | 1 ratio |
+| **Adoption** | Established | Established |
+| **Performance** | Near-native when profiled | Near-native when profiled |
+| **App Size** | Moderate | Moderate |
+| **Dev Speed** | Fast | Very fast |
+| **Commercial footprint** | Established | Established |
+| **Developers** | Broad ecosystem | Broad ecosystem |
 | **Best For** | JS teams | Performance |
 
 ### Architecture Comparison

package/src/claude/skills/mobile-development/references/mobile-frameworks.md

@@ -7,8 +7,8 @@ Comprehensive guide to mobile development frameworks: React Native, Flutter, and
 ### React Native
 - **Language**: JavaScript/TypeScript
 - **Stars**: 121,000+ on GitHub
-- **Adoption**: 35% of mobile developers, 67% familiarity
-- **Performance**: 80-90% native performance
+- **Adoption**: Broad adoption and familiarity among mobile developers
+- **Performance**: Near-native performance
 - **Architecture**: Bridge-based (legacy) → New Architecture (JSI, Fabric, Codegen)
 - **Rendering**: Native components
 - **Hot Reload**: Yes
@@ -17,8 +17,8 @@ Comprehensive guide to mobile development frameworks: React Native, Flutter, and
 ### Flutter
 - **Language**: Dart
 - **Stars**: 170,000+ on GitHub (fastest-growing)
-- **Adoption**: 46% of mobile developers
-- **Performance**: 85-95% native performance
+- **Adoption**: Broad adoption among mobile developers
+- **Performance**: Near-native performance
 - **Architecture**: "Everything is a widget"
 - **Rendering**: Custom Impeller rendering engine (eliminates jank)
 - **Hot Reload**: Yes (fastest in industry)
@@ -26,7 +26,7 @@ Comprehensive guide to mobile development frameworks: React Native, Flutter, and
 
 ### Native iOS (Swift/SwiftUI)
 - **Language**: Swift
-- **Performance**: 100% native
+- **Performance**: Native performance
 - **UI Framework**: SwiftUI (declarative) or UIKit (imperative)
 - **Latest**: Swift 6 with compile-time data race detection
 - **Tooling**: Xcode 16, Swift Package Manager
@@ -34,7 +34,7 @@ Comprehensive guide to mobile development frameworks: React Native, Flutter, and
 
 ### Native Android (Kotlin/Jetpack Compose)
 - **Language**: Kotlin
-- **Performance**: 100% native
+- **Performance**: Native performance
 - **UI Framework**: Jetpack Compose (declarative) or Views (imperative)
 - **Latest**: Kotlin 2.1, Compose 1.7
 - **Tooling**: Android Studio Hedgehog+
@@ -51,7 +51,7 @@ Comprehensive guide to mobile development frameworks: React Native, Flutter, and
 - **Turbo Modules**: Lazy-loaded native modules
 
 **Performance Optimizations**
-- **Hermes Engine**: 30-40% faster startup, reduced memory
+- **Hermes Engine**: Faster startup, reduced memory
 - **Native Driver Animations**: Offloaded to UI thread (60 FPS)
 - **FlatList Virtualization**: Renders only visible items
 - **Image Optimization**: FastImage library, progressive loading
@@ -81,14 +81,14 @@ src/
 4. **Context API**: Simple apps, avoid prop drilling
 
 **Navigation**
-- **React Navigation**: Industry standard, 80%+ adoption
+- **React Navigation**: Industry standard
 - Type-safe navigation with TypeScript
 - Deep linking configuration
 - Tab, stack, drawer navigators
 
 **TypeScript Adoption**
-- 85%+ of new React Native projects use TypeScript
-- Type safety prevents 15% of runtime errors
+- TypeScript is common in new React Native projects
+- Type safety helps prevent runtime errors
 - Better IDE support and autocomplete
 
 ### Testing Strategy
@@ -130,7 +130,7 @@ test('login button should be enabled when form is valid', async () => {
 - Rapid prototyping and MVPs
 - Strong community support needed
 - npm ecosystem integration
-- Commercial apps (12.57% market share)
+- Commercial apps
 
 **❌ Not Ideal For:**
 - Heavy graphics/gaming (use native or Unity)
@@ -254,7 +254,7 @@ testWidgets('Counter increments', (WidgetTester test-runner) async {
 - Move semantics for performance
 
 **SwiftUI vs UIKit**
-- **SwiftUI**: Declarative, 40% less code, iOS 13+, modern approach
+- **SwiftUI**: Declarative, less code, iOS 13+, modern approach
 - **UIKit**: Imperative, fine-grained control, legacy support, complex customizations
 - Both work together in same project
 
@@ -318,7 +318,7 @@ struct LoginView: View {
 
 **Jetpack Compose**
 - Declarative UI (like SwiftUI/React)
-- 60% adoption in top 1,000 apps
+- Widely adopted in top 1,000 apps
 - Material Design 3 integration
 - Compose compiler with Kotlin 2.0+
 

package/src/claude/skills/mobile-development/references/mobile-ios.md

@@ -53,7 +53,7 @@ actor UserCache {
 ✅ Declarative UI preferred
 ✅ Fast iteration needed
 ✅ Cross-platform (macOS, watchOS, tvOS)
-✅ 40% less code vs UIKit
+✅ Less code vs UIKit
 
 ### When to Use UIKit
 ✅ Legacy app maintenance

package/src/claude/skills/mobile-development/references/mobile-mindset.md

@@ -5,7 +5,7 @@ Essential thinking patterns and decision-making frameworks for successful mobile
 ## The 10 Commandments of Mobile Development
 
 ### 1. Performance is Foundation, Not Feature
-- **Reality**: 70% users abandon apps >3s load time
+- **Reality**: Users may abandon apps when load time exceeds 3s
 - **Mindset**: Optimize from day one, not "later"
 - **Action**: Set performance budgets before writing code
 
@@ -50,7 +50,7 @@ Essential thinking patterns and decision-making frameworks for successful mobile
 - **Action**: MVVM for small apps, Clean Architecture when complexity demands
 
 ### 10. Continuous Learning is Survival
-- **Reality**: 85% developers use AI tools (2024), frameworks evolve constantly
+- **Reality**: AI tools are widely used by developers (2024), frameworks evolve constantly
 - **Mindset**: Embrace change, allocate learning time
 - **Action**: 1+ hour weekly for new tech/patterns
 
@@ -131,7 +131,7 @@ Essential thinking patterns and decision-making frameworks for successful mobile
 - "It just works" expectation = zero tolerance for crashes
 
 **Fragmentation**: LOW
-- 90%+ on iOS 16+ (2024)
+- Most users on iOS 16+ (2024)
 - Only ~50 device models to test
 - Predictable hardware specs
 
@@ -165,7 +165,7 @@ Essential thinking patterns and decision-making frameworks for successful mobile
 - Handle back button properly
 
 **When to Go Native Android:**
-- Global market focus (72% market share)
+- Global market focus (Android dominates)
 - Emerging markets (Android dominates)
 - Enterprise/B2B (customization needs)
 
@@ -177,7 +177,7 @@ Essential thinking patterns and decision-making frameworks for successful mobile
 |--------|-----------|-----------------|
 | **Launch time** | <2s | Acceptable |
 | **Launch time** | 2-3s | Noticeable delay |
-| **Launch time** | >3s | 70% abandon |
+| **Launch time** | >3s | Users may abandon |
 | **Screen load** | <1s | Instant (cached) |
 | **Screen load** | 1-3s | Acceptable (network) |
 | **Screen load** | >3s | Frustrating |
@@ -259,46 +259,44 @@ Week 2: Polish + Ship
 8. Merge to develop
 
 **CI/CD Impact:**
-- 20% reduction in development time
-- 50% fewer production bugs
-- 3x faster deployment
+- Faster development and deployment with fewer production bugs
 
 ### Common Pitfalls & Avoidance
 
 #### 1. Testing Only on Simulators
 **Problem**: Simulators don't show real performance (battery, memory, network)
 **Solution**: Real device testing mandatory before every release
-**Impact**: 40% of bugs only appear on real devices
+**Impact**: Some bugs only appear on real devices
 
 #### 2. Ignoring Platform Conventions
 **Problem**: Custom navigation confuses users
 **Solution**: Follow iOS HIG and Material Design
-**Impact**: 30% lower engagement with non-standard UIs
+**Impact**: Non-standard UIs can lower engagement
 
 #### 3. No Offline Handling
 **Problem**: Network failures = blank screens, errors
 **Solution**: Offline-first architecture, cached data
-**Impact**: 50% of users experience network issues daily
+**Impact**: Users can experience network issues daily
 
 #### 4. Poor Memory Management
 **Problem**: Memory leaks → crashes, poor performance
 **Solution**: ARC/GC understanding, profile regularly
-**Impact**: Memory issues = #1 crash cause (35%)
+**Impact**: Memory issues are a leading crash cause
 
 #### 5. Hardcoded Credentials
 **Problem**: Security vulnerability, API key exposure
 **Solution**: Environment variables, secure storage
-**Impact**: 23% of apps leak sensitive data (OWASP)
+**Impact**: Apps can leak sensitive data; follow OWASP guidance.
 
 #### 6. No Accessibility
-**Problem**: Excludes 15%+ of users (disability, situational)
+**Problem**: Excludes users with disabilities or situational needs
 **Solution**: VoiceOver/TalkBack testing, semantic labels
 **Impact**: Accessibility = 1.3B global market
 
 #### 7. Premature Optimization
 **Problem**: Wasted time optimizing non-bottlenecks
 **Solution**: Measure first, optimize biggest impact
-**Impact**: 80% of performance issues = 20% of code
+**Impact**: Many performance issues come from a small part of the code
 
 #### 8. Over-Engineering
 **Problem**: Complex architecture for simple apps
@@ -308,7 +306,7 @@ Week 2: Polish + Ship
 #### 9. Skipping Real Device Testing
 **Problem**: Missed battery drain, thermal issues
 **Solution**: Device farm in CI/CD, manual testing
-**Impact**: 25% of performance issues device-specific
+**Impact**: Some performance issues are device-specific
 
 #### 10. Not Respecting Battery
 **Problem**: Background processing drains battery
@@ -460,12 +458,12 @@ if (isLowEndDevice) {
 
 **Example Architecture:**
 ```
-React Native / Flutter (90%)
+React Native / Flutter
 ├─ UI and business logic
 ├─ Standard features
 └─ API integration
 
-Native Modules (10%)
+Native Modules
 ├─ Performance-critical (video processing)
 ├─ Platform-specific (HealthKit, Android Auto)
 └─ Third-party SDKs (payment, analytics)
@@ -535,7 +533,7 @@ v4.0: Extract microservices if justified
 - Discord (React Native, Flutter official)
 - Twitter: Follow framework creators and contributors
 
-**AI Tools (85% adoption in 2024):**
+**AI Tools (widely adopted in 2024):**
 - GitHub Copilot: Code completion, boilerplate
 - ChatGPT/Claude: Architecture questions, debugging
 - Tabnine: Context-aware suggestions

package/src/claude/skills/question/SKILL.md

@@ -30,14 +30,14 @@ The output is an answer, evidence, confidence, and a follow-up only when needed.
 ## When To Use
 
 Use `hapo:question` when the user asks:
-- "Trong hệ thống này X làm gì?"
-- "Luồng này đang xử lý ở đâu?"
-- "Config/version/package hiện tại là gì?"
-- "Có dùng thư viện/công nghệ/cách làm nào không?"
-- "Requirement/spec này có khớp code không?"
-- "Tool/library/framework này nên dùng thế nào?"
-- "Theo best practice/current docs thì sao?"
-- "Tôi nên hiểu phần này như thế nào?"
+- "What does X do in this system?"
+- "Where is this flow handled?"
+- "What is the current config/version/package?"
+- "Does it use a particular library/technology/approach?"
+- "Does this requirement/spec match the code?"
+- "How should I use this tool/library/framework?"
+- "What does best practice or the current docs say?"
+- "How should I understand this part?"
 
 Do not use it when:
 - The user asks to implement, fix, debug, test, commit, or publish.
@@ -131,14 +131,14 @@ Use `templates/question.md` when the user asks to save or document the answer.
 - Separate "confirmed by source" from "inferred".
 - Keep the answer proportional: concise for simple questions, structured for complex ones.
 - If external sources were used, include source links or names.
-- If no evidence exists, say "không thấy bằng chứng trong source hiện tại" and explain what was checked.
+- If no evidence exists, say "no evidence found in the current source" and explain what was checked.
 
 ## Examples
 
 ### Source Question
 
 ```text
-/hapo:question "Trong hệ thống này cafekit dùng file nào để bật/tắt skill routing?"
+/hapo:question "In this system, which file does cafekit use to toggle skill routing?"
 ```
 
 Expected behavior:
@@ -149,7 +149,7 @@ Expected behavior:
 ### Mixed Source + Web Question
 
 ```text
-/hapo:question "Dự án này đang dùng React version nào, và version đó có còn phù hợp theo best practice hiện tại không?" --both
+/hapo:question "Which React version does this project use, and does that version still match current best practice?" --both
 ```
 
 Expected behavior:
@@ -160,8 +160,8 @@ Expected behavior:
 ### Ask Back
 
 ```text
-/hapo:question "Hệ thống này có ổn không?"
+/hapo:question "Is this system stable?"
 ```
 
 Expected behavior:
-- ask one narrowing question because "ổn" could mean architecture, security, performance, UX, tests, or deploy readiness.
+- ask one narrowing question because "stable" could mean architecture, security, performance, UX, tests, or deploy readiness.

package/src/claude/skills/research/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 ---
 # Research (Delegation Facade)
 
-**Mantra:** YAGNI, KISS, DRY. Be brutal, straight to the point, and strictly authoritative.
+**Mantra:** Return ranked recommendations with sources; never an unsorted list of options.
 
 This skill acts as a **Command Facade**. When invoked, the main Orchestrator MUST NOT attempt to run WebSearch itself. Instead, it must instantly delegate the operation to the Specialized Subagent.
 
@@ -40,7 +40,7 @@ Output Format: Must strictly follow the 'Standard Research Report' layout.
 The subagent MUST return the findings formatted EXACTLY according to the built-in specification template.
 
 Instruct the Researcher Subagent with this strict requirement:
-> "Sử dụng nguyên bản template tại `packages/spec/src/claude/skills/specs/templates/research.md`. Tuyệt đối không tự ý đẻ thêm các đề mục ngoài phạm vi file template này."
+> "Use the template at .claude/skills/specs/templates/research.md verbatim. Do not add sections beyond it."
 
 ## Post-Execution
 Once the `researcher` completes the Task and returns the Markdown output, save it based on context:

package/src/claude/skills/specs/SKILL.md

@@ -88,6 +88,22 @@ Forbidden generated artifacts:
 - Concise, prefer bullet lists; no fluff
 - Unresolved questions → list at the end of each document
 
+## Lane selection before spec gate
+
+Classify task risk at the runtime boundary before starting spec state or approval flow. Use the executable policy, not keyword count or prose alone:
+
+```bash
+node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
+# Downgrade from Critical requires explicit user authorization — model-supplied lane cannot bypass risk signals
+node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '{"riskSignals":{"auth":true},"override":"Direct","userAuthorized":true}' --json
+```
+
+- **Direct** — clear, isolated, reversible, low-risk work. May skip spec files, registry/state, and subagents. Still run targeted verification, diff self-check, and evidence proportional to blast radius. No spec/state/registry ceremony required.
+- **Standard** — default lane. Create one bounded spec artifact (`requirements.md` + `design.md` in the current layout), keep one canonical receipt, and run exactly one combined `code-auditor` review at feature ship point (not per-task).
+- **Critical** — destructive/irreversible, auth/payment/privacy/data, schema/migration, public contract, cross-runtime coupling, outcome-changing ambiguity, or difficult rollback. Require strict spec/state/evidence; delegation is risk-driven (inspector/test-runner/code-auditor enabled only when risk lens requires), not a fixed four-agent chain.
+
+Explicit `override` is allowed in either direction but is enforced at the runtime boundary. A model-supplied lane or downgrade must not bypass risk signals. Downgrading from Critical requires explicit user-originated authorization (`userAuthorized:true` or `origin:user`) and must surface the trade-off (reduced review/evidence coverage). Agent validation or --auto never fabricates `user_approved`; `generated`, `agent_validated`, and `user_approved` are independent booleans per `schema_version: "2.0"`.
+
 ## Default Behavior
 
 > **This section is the entry/dispatch layer ONLY.** It decides *which part of the pipeline to run and where to stop*. It does NOT change any pipeline step, the validator, templates, or rules.
@@ -112,15 +128,15 @@ Forbidden generated artifacts:
 
 ### Creation Mode Gate
 
-Shown once on the no-flag create path. Selects the **stop point only**.
+Shown once on the no-flag create path. Selects the **stop point only**. Approval schema is versioned (`schema_version: "2.0"`): each phase has `generated`, `agent_validated`, `user_approved` as independent booleans. `ready` requires all three true. Legacy `approved` field is rejected — `--auto` or agent validation never fabricates `user_approved`.
 
-| Option | Runs | Stops after | Approvals |
+| Option | Runs | Stops after | Approvals (v2) |
 |---|---|---|---|
-| **Auto (→ Tasks)** | Step 1→10 end-to-end | full (ready gate) | each phase `generated=true` + `approved=true` |
-| **Stop after Design** | Step 1→6 | `design` (before Step 7) | requirements + design `approved=true`; `ready_for_implementation=false` |
-| **Step by step** | one phase at a time | after each phase | per phase `generated=true`, `approved=false` until user approves |
+| **Auto (→ Tasks)** | Step 1→10 end-to-end | full (ready gate) | each phase `generated=true` + `agent_validated=true`; `user_approved` stays false until explicit user approval (`--auto` does NOT auto-set `user_approved`). Ready requires `generated && agent_validated && user_approved`. |
+| **Stop after Design** | Step 1→6 | `design` (before Step 7) | requirements + design `generated=true` + `agent_validated=true`; `user_approved=true` only after explicit user approval; later phases ungenerated; `ready_for_implementation=false` |
+| **Step by step** | one phase at a time | after each phase | per phase `generated=true`, `agent_validated` per agent check, `user_approved=false` until user explicitly approves |
 
-`--auto` = Auto without the gate. Early stops leave `ready_for_implementation=false` and emit Step 9b. Resume via `/hapo:specs` Interactive State Discovery.
+`--auto` = Auto without the gate. Early stops leave `ready_for_implementation=false` and emit Step 9b. Resume via `/hapo:specs` Interactive State Discovery. If legacy `approved` field is present, fail closed with migration guidance: replace `approved` with `agent_validated` + `user_approved` per `spec-state.json` template.
 
 ### Translation Mirror (optional reference copy)
 
@@ -210,16 +226,16 @@ Load: `references/scope-inquiry.md` (+ `references/ask-user-question-gates.md` f
 - Smell: >8 files / >2 new classes / >12 tasks → challenge; **>15 tasks → sibling specs**
 - User: Expand / Hold / Reduce. Skip if trivial (< 20 words, 1 file, "just do it")
 
-#### Execution Tier (auto-scale — after 5-Dimension assessment)
-Record in `spec.json.design_context.execution_tier`.
+#### Execution Tier (auto-scale — after 5-Dimension assessment) — legacy metadata
+Record in `spec.json.design_context.execution_tier` for backward compatibility. Tier is metadata only; **lane controls ceremony and delegation** (Direct/Standard/Critical). Light/Standard/Deep mappings are preserved for compatibility but lane policy is authoritative.
 
-| Tier | Trigger | Research | Discovery | Red-Team | Always runs |
+| Tier (legacy) | Trigger | Research | Discovery | Red-Team | Always runs |
 |---|---|---|---|---|---|
 | **Light** | Clear + Isolated + ≤2 tasks | skip (rationale) | minimal | Validate-only | scope_lock, EARS, **Layer 1+2** |
 | **Standard** | default / 3-4 tasks | targeted | light | per Step 8 | all of the above |
 | **Deep** | Complex/Critical / security-migration / 5+ tasks | full | full | Red-Team → Validate | all of the above |
 
-Grounding + validator + scope_lock never skip. Auth/payment/migration/schema/privacy force Deep. Tier never changes Hard Output Contract or DoCT.
+Grounding + validator + scope_lock never skip. Auth/payment/migration/schema/privacy force Deep (legacy) and Critical (lane). Tier remains backward-compatible execution metadata; lane controls ceremony and delegation.
 
 ### Step 4: Init
 - Check duplicate slugs; create `specs/<feature-name>/`
@@ -355,17 +371,18 @@ Early stop (**Stop after Design** / **Step by step**): no completion block, no v
 
 | Field | Rule |
 |---|---|
+| `schema_version` | Must be `"2.0"`; approvals use `generated` + `agent_validated` + `user_approved` per phase. Legacy `approved` field is rejected — fail closed with migration guidance. |
 | Status | `in_progress` / `blocked` / `done` / `archived` only (never emit `in-progress`) |
 | Timestamps | Each `timestamps.*_done` = actual ISO 8601 time at that phase; never reuse init |
-| Approvals (Auto / full pipeline) | `generated=true` + `approved=true` per completed phase |
-| Approvals (Stop after Design) | phases that ran: both true; later phases ungenerated; `ready_for_implementation=false` |
-| Approvals (Step by step) | `generated=true`, `approved=false` until user approves |
+| Approvals (Auto / full pipeline) | `generated=true` + `agent_validated=true`; `user_approved` stays false until explicit user approval (`--auto` never fabricates `user_approved`). Ready requires all three true per phase. |
+| Approvals (Stop after Design) | phases that ran: `generated=true` + `agent_validated=true`; `user_approved=true` only after explicit user approval; later phases ungenerated; `ready_for_implementation=false` |
+| Approvals (Step by step) | `generated=true`, `agent_validated` per agent check, `user_approved=false` until user explicitly approves |
 | `task_files` / `task_registry` | Exact match to disk after Step 7; registry keys = relative paths with full registry fields |
 | `validation_recommended` | `true` for auth/privacy/delete/migration/schema/extension/provider or 5+ tasks |
 | `translation` | optional mirror metadata; never affects ready gate |
-| `ready_for_implementation` | `true` only when requirements+design+tasks approved, `progress.tasks=done`, inventories match disk, and validation completed when recommended |
+| `ready_for_implementation` | `true` only when requirements+design+tasks each have `generated && agent_validated && user_approved`, `progress.tasks=done`, inventories match disk, and validation completed when recommended |
 
-If any approval is `false`, keep `ready_for_implementation = false`. Specs with 5+ tasks stay not-ready until `--validate` writes `validation.status = "completed"`.
+If any approval (`generated`, `agent_validated`, or `user_approved`) is `false`, keep `ready_for_implementation = false`. Specs with 5+ tasks stay not-ready until `--validate` writes `validation.status = "completed"`. Legacy `approved` fails closed — do not infer `user_approved` from `generated` or `agent_validated`.
 
 ## Subcommands
 

package/src/claude/skills/specs/references/review.md

@@ -99,7 +99,7 @@ These rules override any self-reasoning or optimization the system may attempt:
 Each reviewer receives:
 - Their specific lens and persona
 - Spec file paths to read directly
-- Instructions: find 5-10 flaws, findings only, NO praise
+- Instructions: report findings only when backed by concrete citations
 
 **Reviewer instructions:**
 ```
@@ -111,8 +111,8 @@ Rules:
 - Be concrete: describe failure scenario, not just "could be a problem"
 - Rate severity: Critical (blocks success) | High (significant risk) | Medium (notable concern)
 - Skip trivial observations (style, naming, formatting)
-- No praise. No "overall looks good". Only findings.
-- 5-10 findings. Quality over quantity.
+- No praise. No "overall looks good". Only evidence-backed findings.
+- Quality over quantity; do not pad to a count.
 ```
 
 #### Step 5: Collect → Deduplicate → Cap