autoworkflow 1.2.0 → 2.0.1

package/system/gates.md

@@ -0,0 +1,390 @@
+# System Gates
+
+> Blocking checkpoints that MUST pass before proceeding.
+> Gates enforce hard rules that cannot be bypassed.
+
+---
+
+## Gate Philosophy
+
+Gates are **BLOCKING**. If a gate fails:
+1. Claude MUST stop
+2. Claude MUST report the failure
+3. Claude MUST NOT proceed until resolved
+4. User CANNOT override blocking gates (only fix the issue)
+
+---
+
+## Gate Definitions
+
+### `analyze_gate`
+
+**Phase:** Before ANALYZE → PLAN transition
+**Purpose:** Ensure adequate analysis was performed
+
+```
+GATE: analyze_gate
+├── REQUIRES:
+│   ✓ Read relevant source files
+│   ✓ Understood existing code patterns
+│   ✓ Identified affected files
+│   ✓ Checked BLUEPRINT.md for requirements
+│   ✓ Checked AI_RULES.md for standards
+│
+├── ON_PASS:
+│   └── Proceed to: PLAN phase
+│
+└── ON_FAIL:
+    └── BLOCK: "Insufficient analysis"
+    └── Report: what's missing
+    └── Return to: ANALYZE phase
+```
+
+---
+
+### `plan_approval_gate`
+
+**Phase:** Before PLAN → IMPLEMENT transition
+**Purpose:** User must approve the plan before implementation
+
+```
+GATE: plan_approval_gate
+├── REQUIRES:
+│   ✓ Plan has been presented to user
+│   ✓ Suggestions (if applicable) have been shown
+│   ✓ User has explicitly approved
+│       - "yes", "proceed", "go ahead", "approved", etc.
+│       - OR selected which suggestions to include
+│
+├── ON_PASS:
+│   └── Record: approved suggestions
+│   └── Proceed to: IMPLEMENT phase
+│
+├── ON_FAIL (no approval):
+│   └── BLOCK: "Awaiting user approval"
+│   └── State: "Should I proceed with this plan?"
+│   └── Wait for: user response
+│
+└── ON_REJECT (user says no):
+    └── Ask: "What should I change?"
+    └── Return to: PLAN phase
+    └── Revise: based on feedback
+```
+
+**Approval Detection:**
+```
+APPROVED if user says:
+- "yes" / "y" / "yeah" / "yep"
+- "proceed" / "go ahead" / "do it"
+- "approved" / "lgtm" / "looks good"
+- "all" / "include all" (for suggestions)
+- "required" / "required only"
+- Specific numbers: "1, 3, 5" (for suggestions)
+
+NOT APPROVED if user says:
+- "no" / "n" / "nope"
+- "wait" / "hold on"
+- "change" / "modify"
+- Question asking for clarification
+```
+
+---
+
+### `verify_gate`
+
+**Phase:** After IMPLEMENT, before AUDIT/COMMIT
+**Purpose:** Code must pass TypeScript and ESLint checks
+
+```
+GATE: verify_gate
+├── REQUIRES:
+│   ✓ npm run typecheck → exit code 0
+│   ✓ npm run lint → exit code 0 (0 warnings)
+│   ✓ No TypeScript errors in any file
+│   ✓ No ESLint errors or warnings
+│
+├── COMMANDS:
+│   npm run verify
+│   (which runs: npm run typecheck && npm run lint)
+│
+├── ON_PASS:
+│   └── Report: "✅ Verification passed"
+│   └── Proceed to: AUDIT phase (if feature) or COMMIT gate
+│
+└── ON_FAIL:
+    └── BLOCK: "⛔ Verification failed"
+    └── Report: all errors with file:line
+    └── Enter: fix_loop (from system/loops.md)
+    └── After fix: re-check gate
+```
+
+**Output Format:**
+```
+## Verify Gate Check
+
+| Check | Status | Details |
+|-------|--------|---------|
+| TypeScript | ✅/⛔ | X errors found |
+| ESLint | ✅/⛔ | X warnings found |
+
+Gate Status: ✅ PASSED / ⛔ BLOCKED
+```
+
+---
+
+### `audit_gate`
+
+**Phase:** After VERIFY, before COMMIT (for features)
+**Purpose:** No orphan features, no circular dependencies
+
+```
+GATE: audit_gate
+├── REQUIRES:
+│   ✓ npm run audit:ui → no orphan features
+│   ✓ npm run audit:cycles → no circular dependencies
+│
+├── CHECKS:
+│   1. UI Enforcement:
+│      - Every API endpoint has a UI that calls it
+│      - Every hook is used by a component
+│      - Every utility is imported somewhere
+│      - User can access every feature
+│
+│   2. Circular Dependencies:
+│      - No A → B → A import cycles
+│      - No longer chains (A → B → C → A)
+│
+├── ON_PASS:
+│   └── Report: "✅ All audits passed"
+│   └── Proceed to: pre_commit_gate
+│
+├── ON_UI_FAIL:
+│   └── BLOCK: "⛔ Orphan feature detected"
+│   └── Report: features missing UI
+│   └── Enter: ui_fix_loop
+│   └── After fix: re-check gate
+│
+└── ON_CYCLE_FAIL:
+    └── BLOCK: "⛔ Circular dependency detected"
+    └── Report: cycle paths
+    └── Enter: cycle_fix_loop
+    └── After fix: re-check gate
+```
+
+---
+
+### `pre_commit_gate`
+
+**Phase:** Before COMMIT
+**Purpose:** Final check before committing - ALL rules enforced
+
+```
+GATE: pre_commit_gate
+├── REQUIRES:
+│   ✓ verify_gate passed (TypeScript + ESLint clean)
+│   ✓ audit_gate passed (no orphans, no cycles)
+│   ✓ No TODO comments in changed files
+│   ✓ No FIXME comments in changed files
+│   ✓ No console.log in changed files
+│   ✓ No console.debug in changed files
+│   ✓ No console.info in changed files
+│   ✓ Commit message follows conventional format
+│
+├── CHECKS:
+│   1. Re-verify: npm run verify
+│   2. Check diff: grep -E "TODO|FIXME"
+│   3. Check diff: grep "console\.(log|debug|info)"
+│   4. Validate: commit message format
+│
+├── COMMIT_MESSAGE_FORMAT:
+│   type(scope): description
+│
+│   Valid types: feat, fix, docs, style, refactor,
+│                perf, test, build, ci, chore, revert
+│
+│   Examples:
+│   - feat(auth): add login page
+│   - fix(api): handle null response
+│   - refactor(utils): extract date helpers
+│
+├── ON_PASS:
+│   └── Report: "✅ All pre-commit checks passed"
+│   └── Show: commit preview (files + message)
+│   └── Ask: "Should I commit?"
+│   └── Wait for: user confirmation
+│
+└── ON_FAIL:
+    └── BLOCK: "⛔ Cannot commit"
+    └── Report: ALL blocking issues
+    └── Route to: appropriate fix action
+    └── After fix: re-check gate
+```
+
+**Output Format:**
+```
+## Pre-Commit Gate Check
+
+| Check | Status | Details |
+|-------|--------|---------|
+| TypeScript | ✅ | No errors |
+| ESLint | ✅ | No warnings |
+| UI Enforcement | ✅ | All features have UI |
+| Circular Deps | ✅ | No cycles |
+| TODO/FIXME | ✅ | None in diff |
+| console.log | ✅ | None in diff |
+| Commit Message | ✅ | Valid format |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ ALL GATES PASSED
+
+Ready to commit:
+- 3 files changed
+- Message: "feat(auth): add login page"
+
+Should I proceed with this commit?
+```
+
+---
+
+### `destructive_action_gate`
+
+**Phase:** Before any destructive action
+**Purpose:** User must confirm dangerous operations
+
+```
+GATE: destructive_action_gate
+├── TRIGGERS_ON:
+│   - Deleting files
+│   - Removing significant code (>50 lines)
+│   - Changing database schema
+│   - Modifying authentication logic
+│   - Changing API contracts
+│   - Force operations (git push --force, etc.)
+│
+├── REQUIRES:
+│   ✓ User explicitly confirms the action
+│   ✓ Impact has been clearly explained
+│
+├── FORMAT:
+│   ⚠️ **Warning:** This will [describe impact].
+│
+│   Files affected:
+│   - [file1]
+│   - [file2]
+│
+│   This action [is/is not] reversible.
+│
+│   **Should I proceed?**
+│
+└── ON_CONFIRM:
+    └── Proceed with: action
+    └── On reject: cancel action
+```
+
+---
+
+## Gate Hierarchy
+
+Gates are checked in order. Later gates assume earlier gates passed.
+
+```
+1. analyze_gate
+      │
+      ▼
+2. plan_approval_gate
+      │
+      ▼
+3. [IMPLEMENT]
+      │
+      ▼
+4. verify_gate
+      │
+      ▼
+5. audit_gate (if feature/component)
+      │
+      ▼
+6. pre_commit_gate
+      │
+      ▼
+7. [COMMIT]
+```
+
+---
+
+## Gate Override Policy
+
+**CANNOT be overridden by user:**
+- `verify_gate` - TypeScript/ESLint errors
+- `audit_gate` - Orphan features
+- `pre_commit_gate` - Blocking rule violations
+
+**CAN be acknowledged by user:**
+- `destructive_action_gate` - With explicit "yes, delete it"
+
+**User controls:**
+- `plan_approval_gate` - User decides when to proceed
+
+---
+
+## Reporting Gate Status
+
+Claude MUST show gate status at phase transitions:
+
+```
+## Gate: pre_commit_gate
+
+Checking requirements...
+
+[1/7] TypeScript errors: ✅ PASS (0 errors)
+[2/7] ESLint warnings: ✅ PASS (0 warnings)
+[3/7] UI Enforcement: ✅ PASS (no orphans)
+[4/7] Circular deps: ✅ PASS (no cycles)
+[5/7] TODO/FIXME: ✅ PASS (none found)
+[6/7] console.log: ✅ PASS (none found)
+[7/7] Commit format: ✅ PASS (valid)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ GATE PASSED - Ready to proceed
+```
+
+Or on failure:
+
+```
+## Gate: pre_commit_gate
+
+Checking requirements...
+
+[1/7] TypeScript errors: ✅ PASS
+[2/7] ESLint warnings: ✅ PASS
+[3/7] UI Enforcement: ⛔ FAIL
+      └── Missing UI for: /api/users endpoint
+[4/7] Circular deps: ✅ PASS
+[5/7] TODO/FIXME: ⛔ FAIL
+      └── Found: src/utils.ts:42 "TODO: implement"
+[6/7] console.log: ✅ PASS
+[7/7] Commit format: ✅ PASS
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔ GATE BLOCKED - Cannot proceed
+
+Issues to resolve:
+1. Add UI component for /api/users
+2. Remove TODO comment at src/utils.ts:42
+
+Fixing now...
+```
+
+---
+
+## Quick Reference
+
+| Gate | When | Blocking Rule |
+|------|------|---------------|
+| `analyze_gate` | Before planning | Must read relevant files |
+| `plan_approval_gate` | Before implementing | User must approve |
+| `verify_gate` | After implementing | Zero TS/ESLint errors |
+| `audit_gate` | Before committing features | No orphans, no cycles |
+| `pre_commit_gate` | Before any commit | All rules enforced |
+| `destructive_action_gate` | Before dangerous ops | User must confirm |
+
+**Gates are non-negotiable. Fix issues, don't bypass gates.**