wogiflow 2.15.0 → 2.16.0

package/.claude/docs/knowledge-base/06-safety-guardrails/mechanical-gates.md

@@ -0,0 +1,150 @@
+# Mechanical Enforcement Gates
+
+WogiFlow enforces workflow rules through PreToolUse hook gates — real JavaScript code that intercepts every tool call and blocks violations before they happen. These are not prompt suggestions; they are physical blocks that the AI cannot bypass.
+
+---
+
+## How It Works
+
+Every time Claude Code calls a tool (Edit, Write, Bash, Read, Grep, etc.), the PreToolUse hook fires first. It runs through a chain of gates. If any gate returns `blocked: true`, the tool call is rejected with an error message telling the AI what to do instead.
+
+```
+Claude Code → tool call → PreToolUse hook → [Gate chain] → allowed / blocked
+```
+
+Gates are fail-open by default (errors don't block work) unless noted. The routing gate is fail-closed (errors block everything until routing completes).
+
+---
+
+## Gate Reference
+
+### Routing Gate
+**Enforces**: Every user message must go through `/wogi-start` before any tool can run.
+**Blocks**: Read, Glob, Grep, Edit, Write, Bash, Agent, WebSearch, WebFetch, EnterPlanMode
+**Fail mode**: Fail-CLOSED (if the gate errors, tools are blocked)
+**Config**: `hooks.rules.routingGate.enabled`
+**Exceptions**: Read-only git commands (`git status`, `git log`, `git diff`), subagents with an active parent task
+
+### Phase Gate
+**Enforces**: Tools are restricted based on the current workflow phase.
+**Rules**:
+- `routing` phase: Edit, Write, Bash blocked
+- `exploring` phase: Edit, Write blocked (research is read-only)
+- `spec_review` phase: Edit, Write, Bash blocked (reviewing, not coding)
+- `coding` phase: All tools allowed
+- `validating` phase: Edit, Write blocked (verifying, not changing)
+- `completing` phase: All tools allowed (for logs, maps, commits)
+**Config**: `hooks.rules.phaseGate.enabled`
+
+### Phase-Read Gate
+**Enforces**: Must read the phase instruction file before using mutation tools.
+**Blocks**: Edit, Write, Bash — until the current phase's file in `.claude/docs/phases/` is read
+**Purpose**: Enables on-demand loading of pipeline instructions (79% token savings for conversations)
+**State file**: `.workflow/state/phase-reads.json`
+**Config**: Respects `hooks.rules.phaseGate.enabled` (same toggle)
+
+### Scope Gate
+**Enforces**: Edits must be within the task's declared file scope.
+**Blocks**: Edit, Write on files not listed in the task spec
+**Config**: `hooks.rules.scopeGating.enabled`
+
+### Bugfix Scope Gate
+**Enforces**: L3 bugfix tasks are limited in how many files they can touch.
+**Behavior**: Warns after 3 unique file edits, blocks at configurable threshold
+**Purpose**: Prevents scope creep — a "quick fix" that touches 15 files should be an L2 task
+**Config**: `enforcement.bugfixScope.enabled`
+
+### Scope Mutation Gate
+**Enforces**: Fix tasks cannot create new files; tasks cannot delete pre-existing files via Bash.
+**Blocks**: Write (new file creation in fix tasks), Bash (rm commands on tracked files)
+**Config**: `enforcement.scopeMutation.enabled`
+
+### Strike Gate
+**Enforces**: After repeated verification failures, blocks further edits.
+**Behavior**: Tracks consecutive failures per task. After 3 strikes, blocks Edit/Write/Bash.
+**Purpose**: Prevents infinite retry loops where the AI tries the same broken approach repeatedly
+**State file**: `.workflow/state/strike-tracker.json`
+**Config**: `enforcement.strikeEscalation.enabled`
+
+### Deploy Gate
+**Enforces**: Cannot deploy without a verification artifact. Cannot write/edit verification artifacts directly (anti-forgery).
+**Blocks**: Bash (deploy commands without artifact), Write/Edit (on verification artifact files)
+**Config**: `enforcement.deployGate.enabled`
+
+### Git Safety Gate
+**Enforces**: Creates automatic backup before destructive git operations.
+**Triggers on**: `git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -f`
+**Behavior**: Creates a backup branch before allowing the destructive operation
+**Config**: `enforcement.gitSafety.enabled`
+
+### Commit-Log Gate
+**Enforces**: Commits must have corresponding request-log entries.
+**Blocks**: Bash (git commit) when request-log.md wasn't updated for the current task
+**Config**: `hooks.rules.commitLogGate.enabled`
+
+### Manager Boundary Gate
+**Enforces**: Manager repos cannot modify worker repo source code (workspace mode).
+**Blocks**: Edit/Write on any file inside member repos; Bash except allowlisted read-only commands
+**Allows**: Read of metadata files (api-map, app-map, config, state files)
+**Active when**: `WOGI_REPO_NAME === 'manager'`
+
+### Component Reuse Gate
+**Enforces**: Must check existing components before creating new ones.
+**Behavior**: When Write creates a new component file, checks app-map for similar existing components
+**Output**: Warning with reuse candidates (name, path, similarity score)
+**Config**: `componentReuse.enabled`
+
+### Standards Compliance Gate
+**Enforces**: Naming conventions, security patterns, decisions.md rules.
+**Runs at**: Task completion (part of quality gates)
+**Checks scoped by task type**: component → naming/components/security, API → naming/api/security, feature → all
+**Config**: Part of `qualityGates.<taskType>.require` array
+
+### Damage Control
+**Enforces**: Configurable blocklist for dangerous commands and protected files.
+**Behavior**: Block or ask-before-execute based on pattern matching
+**Config**: `damageControl.enabled` with custom patterns in `.workflow/damage-control.yaml`
+
+---
+
+## Configuration
+
+All gates can be toggled independently:
+
+```json
+{
+  "hooks": {
+    "rules": {
+      "routingGate": { "enabled": true },
+      "phaseGate": { "enabled": true },
+      "scopeGating": { "enabled": true },
+      "commitLogGate": { "enabled": true }
+    }
+  },
+  "enforcement": {
+    "strictMode": true,
+    "bugfixScope": { "enabled": true },
+    "scopeMutation": { "enabled": true },
+    "strikeEscalation": { "enabled": true },
+    "deployGate": { "enabled": true },
+    "gitSafety": { "enabled": true }
+  },
+  "componentReuse": { "enabled": true },
+  "damageControl": { "enabled": false }
+}
+```
+
+---
+
+## Fast-Path Optimization
+
+The hook checks pre-computed status from `.workflow/state/hook-status.json`. If all gates are disabled, the entire hook exits in <1ms. Individual gates are skipped via the status cache without loading their modules.
+
+---
+
+## Related
+
+- [Damage Control](./damage-control.md) — Configurable pattern-based protection
+- [Commit Gates](./commit-gates.md) — Approval workflow for commits
+- [Task Execution](../02-task-execution/) — Where gates enforce workflow phases
+- [Verification](../02-task-execution/03-verification.md) — Quality gates at completion

package/.claude/docs/knowledge-base/wogiflow-enterprise-showcase.md

@@ -0,0 +1,423 @@
+# WogiFlow: Enterprise AI Development Workflow
+
+**The only AI coding workflow with mechanical enforcement.**
+
+Every other tool in the Claude Code ecosystem gives the AI _suggestions_. WogiFlow gives it _rules it physically cannot break_. This is the difference between a coding assistant that sometimes follows best practices and one that is architecturally incapable of skipping them.
+
+---
+
+## The Core Problem WogiFlow Solves
+
+AI coding agents are powerful but undisciplined. Without structure, they:
+
+- Skip verification and claim "done" based on "the code looks correct"
+- Make untracked changes that nobody can audit
+- Forget project conventions between sessions
+- Hallucinate completion — static checks pass, but the feature doesn't actually work
+- Make autonomous decisions about things the team should decide
+- Lose context mid-task and produce inconsistent output
+
+These problems multiply with team size. One developer with a loose AI assistant creates tech debt. Ten developers with loose AI assistants create chaos.
+
+**WogiFlow eliminates these failure modes through mechanical enforcement** — hook-based gates that physically intercept every tool call and block violations before they happen. Not prompts asking nicely. Real code that runs before every file edit, every bash command, every tool invocation.
+
+---
+
+## How It Works: The /wogi-start Pipeline
+
+Everything in WogiFlow begins with `/wogi-start`. This is the universal entry point — every user message, every task, every question must pass through it. The routing gate mechanically blocks all tools (Edit, Write, Bash, Read, Grep) until routing completes.
+
+### What Happens When You Say "Add dark mode toggle"
+
+```
+User message
+    │
+    ▼
+┌─────────────────────────────┐
+│  ROUTING GATE (mechanical)  │  ← All tools blocked until /wogi-start runs
+│  PreToolUse hook intercepts │
+│  every tool call            │
+└─────────────┬───────────────┘
+              │
+              ▼
+┌─────────────────────────────┐
+│  /wogi-start TRIAGE         │  ← Classifies: story, bug, review, conversation?
+│  Determines task level:     │     Routes to appropriate pipeline
+│  L0 Epic (15+ files)        │
+│  L1 Story (5-15 files)      │
+│  L2 Task (1-5 files)        │
+│  L3 Subtask (1 file)        │
+└─────────────┬───────────────┘
+              │
+              ▼
+```
+
+### The Pipeline: What Runs Depends on Task Size
+
+| Phase | L3 Subtask | L2 Task | L1 Story | L0 Epic |
+|-------|-----------|---------|----------|---------|
+| **Routing + Context** | Yes | Yes | Yes | Yes |
+| **Multi-Agent Research** (6 parallel agents) | Skip | Yes | Yes | Yes |
+| **Reuse Gate** (check existing components) | Skip | Yes | Yes | Yes |
+| **Scope-Confidence Audit** | Skip | Skip | Yes | Yes |
+| **Architect Pass** (IGR) | Skip | Skip | Yes | Yes |
+| **Logic Adversary** (different model critiques plan) | Skip | Skip | Yes | Yes |
+| **Spec Generation + Approval** | Skip | Conditional | Yes (blocks for approval) | Yes (blocks for approval) |
+| **Implementation Loop** | Yes | Yes | Yes | Yes |
+| **Skeptical Evaluator** (separate agent grades work) | Skip | Yes | Yes | Yes |
+| **Runtime Verification** (auto-generated tests) | Yes | Yes | Yes | Yes |
+| **Wiring Validation** | Yes | Yes | Yes | Yes |
+| **Standards Compliance** | Yes | Yes | Yes | Yes |
+| **Quality Gates** | Yes | Yes | Yes | Yes |
+
+A trivial L3 fix takes seconds. An L1 story goes through the full pipeline — research, planning, adversarial review, implementation, independent verification, quality gates. The AI doesn't choose what to skip; the pipeline enforces it based on task classification.
+
+### Phase-Loaded Architecture
+
+The pipeline instructions are split into 5 phase files loaded on-demand. A conversation that never reaches the coding phase never loads coding instructions — saving ~79% of prompt tokens. The PreToolUse hook blocks Edit/Write/Bash until the current phase's instruction file is read, ensuring the AI always has the right instructions loaded.
+
+---
+
+## Mechanical Enforcement: 12+ Gates That Cannot Be Bypassed
+
+Every tool call in WogiFlow passes through the PreToolUse hook. This is real JavaScript code that executes before Claude Code processes any Edit, Write, Bash, Read, or Grep command. The gates are not suggestions — they are physical blocks.
+
+| Gate | What It Enforces | Fail Mode |
+|------|-----------------|-----------|
+| **Routing Gate** | Every message must go through /wogi-start first | Block all tools |
+| **Phase Gate** | Tools restricted per workflow phase (no editing during research) | Block Edit/Write |
+| **Phase-Read Gate** | Must read phase instructions before working | Block Edit/Write/Bash |
+| **Scope Gate** | Edits must be within the task's declared file scope | Block Edit/Write |
+| **Bugfix Scope Gate** | L3 bugfixes limited to 3 files before escalation | Warn then block |
+| **Scope Mutation Gate** | Fix tasks can't create new files; can't delete pre-existing files | Block Write/Bash |
+| **Strike Gate** | After 3 failed verification attempts, blocks further edits | Block Edit/Write/Bash |
+| **Deploy Gate** | Can't deploy without verification artifact | Block Bash |
+| **Git Safety Gate** | Auto-backup before destructive git operations | Block or backup |
+| **Commit-Log Gate** | Commits must have request-log entries | Block Bash (git commit) |
+| **Manager Boundary Gate** | Manager repos can't modify worker repo source code | Block Edit/Write |
+| **Component Reuse Gate** | Must check existing components before creating new ones | Warn on Write |
+| **Standards Compliance** | Naming, security, decisions.md rules enforced | Block task completion |
+| **Damage Control** | Configurable blocklist for dangerous commands/files | Block or ask |
+
+**Example**: A developer asks Claude to "quickly fix the login bug." Without WogiFlow, Claude edits 8 files, skips tests, and says "done." With WogiFlow:
+
+1. Routing gate forces `/wogi-start` classification → L3 bugfix
+2. Bugfix scope gate warns after 3 files, blocks after threshold
+3. Phase gate prevents editing during the research phase
+4. Strike gate blocks further changes after 3 failed lint checks
+5. Standards gate verifies the fix follows project conventions
+6. Commit-log gate ensures the change is logged before commit
+
+---
+
+## Intent-Grounded Reasoning (IGR)
+
+For L1+ tasks, WogiFlow adds a reasoning layer that catches logic failures _before_ code is written.
+
+### The Architect + Adversary Pattern
+
+1. **Intent Framing**: The AI explicitly interprets the task — resolving ambiguous terms, identifying affected user journeys, surfacing assumptions
+2. **Architect Pass**: A read-only sub-agent produces an 8-section plan (approach, data model, risks, alternatives, dependencies)
+3. **Logic Adversary**: A _different model_ critiques the plan against a 10-principle Logic Constitution. Same-model self-critique is a known rubber-stamp failure mode — WogiFlow uses Sonnet to critique Opus plans (or vice versa)
+4. **Iteration Loop**: If the Adversary finds issues, the plan goes back to the Architect. Max 3 rounds. If it still fails → task is blocked and surfaced to the user
+
+This catches architectural mistakes, missing edge cases, and flawed assumptions before a single line of code is written.
+
+### Completion Truth Gate
+
+When the AI claims a task is "done," the Truth Gate audits every acceptance criterion against evidence tiers:
+
+| Tier | Name | Counts as Done? |
+|------|------|----------------|
+| 0 | STATIC (compiles, lints) | Never |
+| 1 | STRUCTURAL (file exists, imported) | Never |
+| 2 | OBSERVATIONAL (page loads, renders) | Display-only criteria |
+| 3 | INTERACTIVE (click → result persists) | Yes |
+| 4 | AUTOMATED (test passes) | Yes (strongest) |
+
+If the AI claims "done" with only Tier 0 evidence (it compiles), the gate downgrades the claim to "implemented (unverified)" and blocks task completion.
+
+---
+
+## Verification: The Skeptical Evaluator
+
+After implementation, WogiFlow spawns a separate sub-agent specifically tuned for skepticism:
+
+- **Different model** than the implementer (prevents self-congratulation bias)
+- **Prompted to find problems**, not praise
+- **Grades each criterion**: PASS / PARTIAL / FAIL with file:line evidence
+- **Iteration loop**: If issues found → fix → re-evaluate (max 3 rounds)
+
+This is based on Anthropic's own harness design research: _"Separating the agent doing the work from the agent judging it is a strong lever"_ and _"tuning standalone evaluators toward skepticism is far more tractable than making a generator critical of its own work."_
+
+---
+
+## Enforced Testing: Auto-Generated Verification Tests
+
+WogiFlow doesn't trust "it compiles" as proof that a feature works. For every task that changes code, the Runtime Verification Gate automatically generates and runs tests — frontend and backend — as part of the execution loop. This is ON by default, not opt-in.
+
+### How It Works
+
+For each acceptance criterion in the task spec:
+1. **Classify**: Is this a UI behavior, API behavior, or internal logic?
+2. **Generate**: Write a test that exercises the specific criterion
+3. **Implement**: Write the actual code
+4. **Run**: Execute the test — it must pass
+5. **If fail** → debug, fix, re-run (max 5 retries)
+6. **Persist**: Test stays in `tests/verification/` as a permanent regression guard
+
+Over time, this builds an automated test suite from the actual use cases that were implemented — not hypothetical test cases, but tests that directly verify the features your team shipped.
+
+### Frontend: Browser Verification
+
+When changed files include UI code (`.tsx`, `.jsx`, `.vue`, `.svelte`, `.css`), WogiFlow generates browser-level tests:
+
+**Method 1 — WebMCP (preferred)**: If a browser MCP server is connected, WogiFlow drives the actual browser:
+1. Navigate to the affected page
+2. Screenshot BEFORE the change
+3. Perform the user action (click, type, submit)
+4. Wait for async updates
+5. Screenshot AFTER
+6. Assert DOM state matches expected behavior
+7. For state mutations: reload the page and verify changes persisted
+
+**Method 2 — Playwright**: Auto-generates a Playwright test to `tests/verification/verify-{taskId}.spec.ts`. Persists as a CI-ready regression guard.
+
+**Method 3 — User Checklist (fallback)**: When no browser automation is available, generates a specific checklist and blocks task completion until the user replies "verified."
+
+**High-risk mutation detection**: When code contains `useMutation`, `invalidateQueries`, or `onMutate`, WogiFlow adds extra verification — wait 3 seconds after all criteria pass, reload the page, and confirm state survived the refetch cycle. This catches the #1 frontend false-completion: "it looked right but the server didn't persist it."
+
+### Backend: API Integration Tests
+
+When changed files include API code (`.controller.*`, `.service.*`, `.resolver.*`, `/routes/`, `/api/`, `.dto.*`, `.guard.*`, `.middleware.*`), WogiFlow generates integration tests:
+
+- Makes actual HTTP requests to the running dev server
+- Asserts status codes, response shapes, and field values
+- For mutations (POST/PUT/PATCH/DELETE): re-fetches the resource to verify persistence
+- Auth-protected endpoints get the auth token included automatically
+- Tests persist in `tests/verification/api-verify-{taskId}.test.js`
+
+### Fullstack: Boundary Verification
+
+When both UI and API files change, WogiFlow generates BOTH browser and API tests and validates the boundary:
+- The API test verifies the server accepts the payload shape the frontend sends
+- The browser test verifies the UI correctly displays the response shape the server returns
+- If either side fails → the frontend/backend contract is broken
+
+### Banned Verification Methods
+
+WogiFlow explicitly bans methods that give false confidence for UI tasks:
+
+| Banned Method | Why It's Insufficient |
+|---|---|
+| `tsc --noEmit` passes | Type-correct code can have wrong runtime behavior |
+| `vite build` succeeds | Build success says nothing about UX |
+| `grep` deployed bundle | Function may exist but never execute |
+| "I read the code and it's correct" | Author is the worst judge of own work |
+
+### The Repeat Failure Protocol
+
+When the same issue appears in 2+ consecutive attempts:
+
+| Strike | What Happens |
+|--------|-------------|
+| 1 | Normal fix + evidence log |
+| 2 | Mandatory root cause analysis BEFORE coding. Must change approach. Tier 3+ evidence required. |
+| 3 | Hard block: Cannot mark done without screenshot/console evidence. Must explain what's different this time. |
+| 4+ | Escalation: Acknowledge inability, suggest pair debugging with the developer. |
+
+This prevents the AI from trying the same broken approach in a loop — a pattern that wastes hours on real projects.
+
+---
+
+## Hybrid Mode: Smart Model Routing
+
+Not every task needs the most expensive model. WogiFlow's hybrid mode lets Opus plan while cheaper models execute:
+
+| Task Complexity | Executor | Token Savings |
+|----------------|----------|---------------|
+| Typo fix, config edit | Haiku / GPT-4o-mini | ~75% |
+| New function, component | Sonnet / GPT-4o | ~60% |
+| Documentation | Haiku | ~80% |
+| Complex refactoring | Opus only | 0% (not delegated) |
+
+**How it works:**
+1. Opus analyzes the task and creates a detailed execution plan
+2. You review and approve (or edit via `/wogi-hybrid-edit`)
+3. The executor model (Haiku, Sonnet, Ollama, etc.) runs each step
+4. Opus validates results — lint, typecheck, standards checks
+5. Opus handles failures with escalation back to itself if needed
+
+**Supports cloud and local models**: Haiku, Sonnet, GPT-4o, GPT-4o-mini, Gemini Flash/Pro, Ollama (Qwen3-Coder, DeepSeek Coder, Nemotron). Local models = free execution.
+
+---
+
+## Code Review: /wogi-review
+
+WogiFlow's review is not "look at the code and give suggestions." It's a 5-phase verification pipeline:
+
+1. **Verification Gates**: Spec verification, lint, typecheck, test execution
+2. **AI Analysis**: Multi-pass or parallel code/logic/security/architecture review with adversarial minimum findings (the reviewer must find at least N issues — prevents rubber-stamping)
+3. **Git-Verified Claim Checking**: Cross-references spec claims against actual git diff. If the spec promises a file that isn't in the diff → BLOCKED
+4. **Standards Compliance [STRICT]**: Every finding checked against decisions.md, app-map.md, naming conventions. MUST_FIX violations block sign-off
+5. **Post-Review Workflow**: Fix loop with automatic task creation for findings
+
+The review produces a structured report with findings classified by severity (critical, high, medium, low) and type (MUST_FIX, SHOULD_FIX, SUGGESTION). Critical/high findings block the next release.
+
+---
+
+## Morning Briefing: /wogi-morning
+
+Start every day with instant situational awareness:
+
+- **Where you left off**: Current task, status, files touched
+- **What happened since**: New commits, issues, changes by teammates
+- **Rule violations**: Auto-promoted patterns awaiting enforcement decisions
+- **Stale skills**: Documentation older than 90 days flagged for refresh
+- **Recommended next tasks**: Top 3 by priority from the backlog
+- **Ready-to-use prompt**: Copy-paste continuation prompt to resume immediately
+
+This eliminates the 10-15 minute "where was I?" ramp-up that costs teams hours per week.
+
+---
+
+## Session End: /wogi-session-end
+
+When you stop working, WogiFlow preserves everything:
+
+- **Structured handoff notes**: What's completed, what's in progress, what's next
+- **Cross-session pattern detection**: Identifies requests repeated 3+ times across sessions and suggests promoting them to permanent rules
+- **State persistence**: All workflow state committed to git — survives restarts, crashes, and machine changes
+- **Request log verification**: Ensures all changes are logged before closing
+- **Component registry check**: Verifies new components are registered in app-map
+
+The next session (or the next developer on the same repo) picks up exactly where you left off.
+
+---
+
+## Workspace Mode: Multi-Repo Orchestration
+
+This is the game changer for enterprise teams. WogiFlow can manage multiple repositories from a single orchestrator.
+
+### The Manager-Worker Architecture
+
+```
+Manager (workspace root — orchestrates, never codes)
+   │
+   ├── Backend repo (provider — APIs, database)
+   ├── Frontend repo (consumer — UI, pages)
+   ├── Shared repo (library — types, utils)
+   └── Mobile repo (consumer — native app)
+```
+
+**How it works:**
+1. You tell the manager: "Add user profile editing"
+2. Manager reads metadata from all repos (API maps, component registries, schemas — never source code)
+3. Manager analyzes which repos are affected and in what order
+4. Manager creates phased execution plan: library → provider → consumer
+5. Each worker repo gets a task dispatched via HTTP channel
+6. Workers execute independently in their own Claude Code sessions
+7. Workers communicate via message bus: contract changes, questions, completion signals
+8. Manager validates cross-repo integration
+
+### Mechanical Boundary Enforcement
+
+The manager physically cannot modify worker repo source code. The Manager Boundary Gate blocks all Edit/Write operations on files inside member repos. The manager can only:
+- Read metadata (api-map, app-map, schema-map, config)
+- Dispatch tasks to workers
+- Read messages from the message bus
+- Validate cross-repo contracts
+
+This prevents the orchestrator from becoming a bottleneck or making unauthorized changes.
+
+### Cross-Repo Quality Gates
+
+When workspace mode is active, additional gates enforce integration quality:
+- **Contract Compliance**: Changes must comply with declared API contracts
+- **Peer Notification**: Affected repos are automatically notified of changes
+- **Cascade Verification**: Library changes trigger verification in all consumer repos
+- **Impact Query**: Before implementing, workers can ask peers "will my change break you?"
+
+### Agent-to-Agent Communication
+
+Workers communicate through 11 message types:
+- `contract-change` — "I changed an API endpoint"
+- `question` — "Does your side handle X?"
+- `impact-query` / `impact-response` — Pre-implementation impact assessment
+- `lock-acquired` / `lock-released` — Shared interface edit coordination
+- `verification-request` — "Please verify your integrations"
+
+---
+
+## Self-Improving Workflow
+
+WogiFlow learns from corrections and promotes patterns to permanent rules:
+
+1. **Feedback Patterns**: When you correct the AI, it records the pattern in `feedback-patterns.md`
+2. **Promotion Threshold**: When a pattern occurs 3+ times, it's promoted to `decisions.md` (permanent project rules)
+3. **Gate Telemetry**: Every gate tracks pass/catch/miss rates. A gate that consistently passes work that later needs correction has a high "miss rate" — revealing rubber-stamping
+4. **Correction Memory**: The IGR system cross-references corrections back to gates that previously approved the flawed work
+5. **Decision Authority**: The AI learns which decisions it can make autonomously vs which need human approval, calibrated per category
+
+This means the more you use WogiFlow, the better it gets. Week 1 catches 60% of issues. Week 8 catches 90% — because the rules that caught the other 30% were learned from your corrections.
+
+---
+
+## Memory System
+
+WogiFlow maintains persistent memory across sessions using SQLite with semantic search:
+
+- **SQLite database** with HuggingFace Transformers embeddings (all-MiniLM-L6-v2)
+- **Cosine similarity search**: "Find decisions related to authentication" works without exact keywords
+- **Relevance decay**: Facts accessed frequently stay hot; unused facts decay over 30 days
+- **Cold retention**: Facts not accessed in 90 days are archived
+- **Auto-promotion**: Facts accessed 3+ times with high relevance are promoted to permanent knowledge
+- **Structured registries**: app-map, function-map, api-map, schema-map, service-map — deterministic lookup for components, functions, endpoints, schemas
+
+---
+
+## Why This Matters for Enterprise
+
+### The Cost of Undisciplined AI Coding
+
+| Problem | Without WogiFlow | With WogiFlow |
+|---------|-----------------|---------------|
+| Untracked changes | AI edits files without logging | Every change logged, tagged, auditable |
+| Skipped verification | "It compiles" = "it works" | 5-tier evidence system, skeptical evaluator |
+| Convention drift | Each session forgets project rules | Rules mechanically enforced, self-improving |
+| Scope creep | Fix one bug, touch 15 files | Bugfix scope gate limits blast radius |
+| Knowledge loss | Context lost between sessions | SQLite memory + structured handoffs |
+| Unsafe deployments | Deploy without testing | Deploy gate blocks without verification |
+| Team inconsistency | 10 developers, 10 styles | Standards gate enforces unified conventions |
+| Wasted tokens | Full pipeline for typo fixes | Phase-loaded router: 79% savings for small tasks |
+| Multi-repo chaos | Manual coordination across repos | Workspace orchestration with boundary enforcement |
+
+### What Companies Get
+
+1. **Auditability**: Every task is tracked from request through implementation to verification. The request log, git history, and verification artifacts create a complete audit trail.
+
+2. **Consistency**: Mechanical enforcement means the AI follows the same process whether it's Monday morning or Friday 5pm, whether the developer is senior or junior.
+
+3. **Scalability**: Hybrid mode reduces token costs by 60-75%. Workspace mode enables multi-repo orchestration. Phase loading optimizes prompt costs.
+
+4. **Safety**: 12+ mechanical gates prevent unauthorized changes, scope creep, unsafe deployments, and convention violations. The AI literally cannot bypass them.
+
+5. **Continuous improvement**: The self-learning system means the workflow gets better over time without manual rule maintenance. Corrections become permanent rules automatically.
+
+6. **Knowledge retention**: Project knowledge persists in structured state files, semantic memory, and cross-session handoffs. New team members inherit the full learning history.
+
+---
+
+## Quick Start
+
+```bash
+npm install -D wogiflow
+npx flow onboard
+```
+
+Onboarding analyzes the existing project, detects the tech stack, indexes components, and configures the workflow. First task can start in under 5 minutes.
+
+---
+
+*WogiFlow v2.15.0 — AGPL-3.0 Licensed*
+*Teams/enterprise features available via @wogiflow/teams*

package/.claude/docs/phases/02-spec.md

@@ -6,7 +6,7 @@ Instructions for the spec/approval phase. Loaded on-demand when phase transition
 
 **Conditional** — runs for L1+ tasks when IGR on. L3 skip. L2 runs only on ultrathink auto-bump.
 
-Spawn a **read-only sub-agent** (Explore subagent_type, with Read/Grep/Glob only — no Edit/Write/Bash) on a model chosen per `config.intentGroundedReasoning.architectPass.modelOverride`. Input: Framing Artifact from Step 1.15 + explore findings from Step 1.3 + scope-confidence audit from Step 1.45 + the Logic Constitution v1 rubric (so the Architect anticipates the Adversary's checks).
+Spawn a **read-only sub-agent** (Explore subagent_type, with Read/Grep/Glob only — no Edit/Write/Bash) on a model chosen per `config.intentGroundedReasoning.architectPass.modelOverride`. Input: Framing Artifact from Step 1.15 + explore findings from Step 1.3 + scope-confidence audit from Step 1.45 + the Logic Constitution v2 rubric (so the Architect anticipates the Adversary's checks, including Principle 11 — Platform Capability Grounding, which demands citation + enforcement-preservation + alternative-ruled-out + fallback for every platform-capability claim).
 
 Build the prompt via `node scripts/flow-architect-pass.js prompt <task>`. Invoke via Agent tool. Output: an 8-section plan at `.workflow/plans/{taskId}.md` (PINs: approach, data-model, journey-impact, net-new, alternatives, risks, reversibility, dependencies). Parse via `parsePlanArtifact()`; if structural FAIL, re-prompt.
 
@@ -20,7 +20,7 @@ When IGR flag is OFF: SKIPPED. Pipeline proceeds from Step 1.45 directly to Step
 
 Spawn a **separate sub-agent on a different model** than the Architect (Sonnet when Architect is Opus; Opus when Architect is Sonnet — per `modelSeparation: different-from-architect`). Per Anthropic harness research, same-model self-critique is a known rubber-stamp failure mode.
 
-Build the prompt via `node scripts/flow-logic-adversary.js prompt .workflow/plans/{taskId}.md`. The Adversary critiques the plan against the 10-principle Logic Constitution v1 with few-shot calibration examples from `.workflow/state/adversary-calibration.json`.
+Build the prompt via `node scripts/flow-logic-adversary.js prompt .workflow/plans/{taskId}.md`. The Adversary critiques the plan against the 11-principle Logic Constitution v2 with few-shot calibration examples from `.workflow/state/adversary-calibration.json`. Principle 11 (Platform Capability Grounding) always runs — every claim about hook/tool/API/platform behavior must be cited, enforcement must be preserved, an alternative must be named, and a fallback must be specified.
 
 Iteration loop (max 3 rounds by default):
 - `overallVerdict: PASS` or `PASS_WITH_CONCERNS` → proceed to Step 1.5. Concerns surface at approval gate (Step 1.6).

package/.claude/docs/phases/04-verify.md

@@ -473,7 +473,7 @@ Run `node node_modules/wogiflow/scripts/flow-standards-gate.js wf-XXXXXXXX [chan
 
 Checks scoped by task type: component → naming/components/security. Utility → naming/functions/security. API → naming/api/security. Bugfix → naming/security. Feature → all. Refactor/migration → all + consumer-impact verification.
 
-**Consumer impact check** (ALL L1+ tasks): For each BREAKING consumer from explore phase (blast-radius analysis), verify it was updated. If any NOT migrated → BLOCK task completion. Results are persisted in `.workflow/state/blast-radius-{taskId}.json`.
+**Consumer impact check** (ALL L1+ tasks): The blast-radius analysis ran in the explore phase (Agent 6: Consumer Impact) and wrote results to `.workflow/state/blast-radius-{taskId}.json`. That file contains an array of consumer entries, each classified as BREAKING (must update), NEEDS-UPDATE (review), or SAFE (no change needed). Read the file and, for each entry with `classification: "BREAKING"`, verify the file listed in `path` was actually modified in this task's changeset (check `git diff --name-only`). If any BREAKING consumer is NOT in the diff → BLOCK task completion and surface to user.
 
 **Reuse candidate check** (AI-as-Judge): Standards gate returns similar items from all registries. AI reasons about PURPOSE overlap (not just name). If purpose overlaps → ask user (use existing / extend / create new). If purpose clearly differs → proceed silently.
 

package/.workflow/agents/logic-adversary.md

@@ -11,9 +11,9 @@
 
 You are the **Logic Adversary** for WogiFlow's Intent-Grounded Reasoning layer.
 
-Your job is to find logic problems in a plan BEFORE any code is written. You are not critiquing code. You are not checking style, library choice, or syntax — other gates handle those. You are reasoning about whether this plan is **logically right** for the project it's proposed for.
+Your job is to find logic problems in a plan BEFORE any code is written. You are not critiquing code. You are not checking style, library choice, or syntax — other gates handle those. You are reasoning about whether this plan is **logically right** for the project it's proposed for AND whether its claims about the target platform (hooks, tool APIs, subagent model, MCP, etc.) are actually true.
 
-You have a specific rubric: the Logic Constitution (currently v1). You will receive it as input. For each of the 10 principles, you produce a verdict: PASS, CONCERN, FAIL, or SKIP. You cite specific evidence for every verdict. Verdicts without evidence are themselves failures of your job.
+You have a specific rubric: the Logic Constitution (currently v2). You will receive it as input. For each of the 11 principles, you produce a verdict: PASS, CONCERN, FAIL, or SKIP. You cite specific evidence for every verdict. Verdicts without evidence are themselves failures of your job.
 
 ### What you are looking for
 
@@ -29,6 +29,11 @@ Patterns that produce logic failures in practice — seen in real agent session
 8. **Implicit-requirement blindness** — happy path only, no edge cases.
 9. **User-journey orphans** — dead-end screens, unreachable features.
 10. **Undocumented irreversibility** — destructive ops without confirmation.
+11. **Ungrounded platform-capability claims** — plans that rely on a hook, tool API, subagent behavior, MCP feature, or slash command working a certain way WITHOUT citation, WITHOUT enforcement-preservation evidence, WITHOUT a ruled-out alternative, or WITHOUT a capability-unavailable fallback. For every platform-capability claim, demand all four: citation, enforcement walk-through, alternative, fallback. Missing any of the four = FAIL. **Additionally, for runtime-behavior claims (hooks firing, tools returning specific shapes, signals being handled, events being emitted), hearsay-level citations — code comments or docs claiming "X does Y" — are NOT sufficient. Demand either O1 (a captured observation: log, telemetry, trace, test result) OR O2 (a named live-test plan that produces O1 before downstream code is built). See P11.1 in the rubric. A comment saying "the hook fires" is not evidence the hook fires; a log line showing it firing is.**
+
+**P11.2 — The same discipline applies to the PROJECT'S OWN RULES**, not just platform capabilities. For every artifact a plan produces (task IDs, file names, config values, state-file entries, spec structures, commit messages), demand: (E1) which rule from `decisions.md`, `feedback-patterns.md`, `.claude/rules/`, a schema, or a validator function applies? (E2) show the artifact satisfying the rule — run the validator, show the format side-by-side with the rule, paste the passing check — *not* "I followed it." (E3) what's the failure mode when violated? Examples of P11.2 violations: (a) "task ID `wf-test0001` follows WogiFlow convention" — no, the convention requires hex, this fails `validateTaskId()`; (b) "config key `taskBoundaryReset` is valid" without being in `flow-constants.js`'s known-keys list; (c) "file name `flowFoo.js` follows kebab-case" — it doesn't. Reflex: *what's the artifact? what rule governs it? is satisfaction SHOWN, not just claimed?*
+
+**P11.3 — Also check for EXISTING WOGIFLOW FEATURES that touch the same domain.** Before shipping any new mechanism (hook, wrapper, CLI entry, state file, config key, skill), enumerate the sibling surface: (S1) `grep -r "execSync\|spawn.*claude" lib/ scripts/`, check `.claude/commands/`, check `scripts/flow-constants.js`, check `lib/workspace.js` — does an existing feature already touch this domain? (S2) Show how the new mechanism composes, conflicts, or integrates with each sibling. "Orthogonal" is OK but must be asserted. (S3) If integration work is needed (e.g., the new wrapper needs to be injected into workspace's `execSync('claude')` call), include it in scope OR explicitly file a follow-up story. Silent omission of sibling integration = FAIL. Example violation caught live: `wogi-claude` wrapper initially missed that `lib/workspace.js:1612` spawns claude directly, so workspace-mode workers weren't restart-capable.
 
 ### What you are NOT looking for