izanagi-ai 2.0.0

package/core/planning-engine.md

@@ -0,0 +1,201 @@
+# Core: Planning Engine
+
+> Version 1.0.0
+> Priority: Critical
+> Dependencies: Context Engine, Decision Engine
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The Planning Engine is activated before any code is written. It breaks down tasks into ordered steps, estimates effort, identifies dependencies, and produces a clear implementation plan. It ensures the agent never writes code without knowing exactly what needs to be built and in what order.
+
+---
+
+## Goals
+
+- Break any task into steps no larger than 1 file or 50 lines.
+- Estimate effort per step (minutes or complexity points).
+- Identify hidden dependencies between steps.
+- Produce a plan that another agent or human can follow.
+- Never start coding without a plan.
+
+---
+
+## Triggers
+
+| Condition | Action |
+|-----------|--------|
+| `task == "new_project"` | Full project plan with phases |
+| `task == "new_feature"` | Feature breakdown into tasks |
+| `task == "refactor"` | Migration plan with safe steps |
+| `task == "bug"` | Investigation → Fix → Verify plan |
+| Any complex task | Decompose into sub-tasks |
+
+---
+
+## Workflow
+
+```
+1. Analyze requirements
+    ↓
+2. Decompose into atomic steps
+    ↓
+3. Identify dependencies between steps
+    ↓
+4. Estimate effort per step
+    ↓
+5. Order steps (topological sort)
+    ↓
+6. Identify risks per step
+    ↓
+7. Generate implementation plan
+    ↓
+8. Validate plan against requirements
+    ↓
+9. Pass to next skill in chain
+```
+
+---
+
+## Plan Format
+
+```yaml
+plan:
+  title: "Create Login API"
+  total_effort: "45 min"
+  
+  steps:
+    - id: 1
+      name: "Create users table migration"
+      file: "database/migrations/xxxx_create_users_table.php"
+      effort: "5 min"
+      depends_on: []
+      risks: []
+      
+    - id: 2
+      name: "Create User model"
+      file: "app/Models/User.php"
+      effort: "5 min"
+      depends_on: [1]
+      risks: []
+      
+    - id: 3
+      name: "Create AuthController"
+      file: "app/Http/Controllers/AuthController.php"
+      effort: "10 min"
+      depends_on: [2]
+      risks: []
+      
+    - id: 4
+      name: "Create LoginRequest"
+      file: "app/Http/Requests/LoginRequest.php"
+      effort: "5 min"
+      depends_on: []
+      risks: []
+      
+    - id: 5
+      name: "Create AuthService"
+      file: "app/Services/AuthService.php"
+      effort: "10 min"
+      depends_on: [2, 4]
+      risks: ["Token storage strategy needed"]
+      
+    - id: 6
+      name: "Write authentication tests"
+      file: "tests/Feature/AuthTest.php"
+      effort: "10 min"
+      depends_on: [3, 5]
+      risks: []
+```
+
+---
+
+## Effort Estimation
+
+```
+complexity = estimate_complexity(task)
+
+effort = base_time * complexity * uncertainty_factor
+
+base_time:
+  - new file: 5 min
+  - edit file: 3 min
+  - config: 2 min
+  - test: 5 min
+
+complexity:
+  - simple (CRUD, no logic): 1x
+  - medium (business logic): 2x
+  - complex (algorithms, integrations): 3x
+
+uncertainty_factor:
+  - known tech: 1x
+  - unfamiliar tech: 2x
+  - new pattern: 1.5x
+```
+
+---
+
+## Dependency Resolution
+
+Steps are ordered using topological sort:
+
+```
+function order_steps(steps):
+    graph = build_dependency_graph(steps)
+    ordered = topological_sort(graph)
+    return ordered
+```
+
+If a circular dependency is detected:
+
+```
+→ flag for user review
+→ ask for clarification
+→ suggest breaking the cycle
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Plan before coding. Always.
+- ✅ Break down into atomic steps (1 file or 50 lines max).
+- ✅ Identify dependencies between steps.
+- ✅ Estimate effort per step.
+- ✅ Validate plan against all requirements.
+
+### Never
+
+- ❌ Start coding with "let me just write the code".
+- ❌ Combine multiple concerns in one step.
+- ❌ Skip effort estimation.
+- ❌ Ignore step dependencies.
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Plans generated | 100% of complex tasks | Plans / tasks requiring plans |
+| Step atomicity | ≤ 50 lines per step | Average lines per step |
+| Dependency accuracy | ≥ 90% | Dependencies correct / total |
+| Plan adherence | ≥ 80% | Steps followed in order |
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- Topological sort for dependency resolution
+- Effort estimation with complexity factors
+- Atomic step decomposition (max 1 file / 50 lines)
+- Circular dependency detection
+- YAML plan format for machine readability

package/core/quality-gates.md

@@ -0,0 +1,233 @@
+# Core: Quality Gates
+
+> Version 1.0.0
+> Priority: Critical
+> Dependencies: Token Manager, Security Scanner
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Quality Gates are the final validation layer before any output is delivered to the user. Every response passes through 5 gates: Security, Style, Clarity, Conciseness, and Completeness. If any gate fails, the output is rejected and reworked.
+
+---
+
+## Gates Overview
+
+```
+┌─────────────────────────────────────────────────┐
+│                 QUALITY GATES                   │
+│                                                 │
+│  Input → Gate 1 → Gate 2 → Gate 3 → Gate 4 →   │
+│          → Gate 5 → ✅ Pass → Output           │
+│                    → ❌ Fail → Rework          │
+│                                                 │
+│  Gate 1: Security (fatal if fail)               │
+│  Gate 2: Style                                  │
+│  Gate 3: Clarity                                │
+│  Gate 4: Conciseness                            │
+│  Gate 5: Completeness                           │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Gate 1: Security
+
+**Fatal gate** — if this fails, output is blocked immediately.
+
+### Checks
+
+- [ ] No hardcoded credentials, API keys, tokens, or secrets
+- [ ] No SQL injection vectors (raw queries without parameterization)
+- [ ] No XSS vectors (untrusted output without escaping)
+- [ ] No CSRF vulnerabilities
+- [ ] No SSRF vulnerabilities
+- [ ] No insecure deserialization
+- [ ] No hardcoded IPs or internal paths
+- [ ] No commented-out security code
+- [ ] Passwords are hashed (bcrypt/argon2), not encrypted
+- [ ] HTTPS is enforced (not HTTP)
+- [ ] File uploads are validated (type, size, path traversal)
+
+### Failure Action
+
+```yaml
+fail:
+  action: "Block output"
+  message: "❌ SECURITY GATE FAILED: [specific issue]"
+  notify: "Reflection Engine"
+  log: true
+```
+
+---
+
+## Gate 2: Style
+
+**Non-fatal** — can pass with warnings.
+
+### Checks
+
+- [ ] Follows project naming conventions
+- [ ] Consistent indentation (spaces vs tabs)
+- [ ] No commented-out code blocks
+- [ ] No debug statements (dd(), var_dump, console.log)
+- [ ] No trailing whitespace
+- [ ] Imports are organized
+- [ ] Line length ≤ 120 characters
+- [ ] PHP: follows PSR-12
+- [ ] JS/TS: follows project ESLint config
+- [ ] Python: follows PEP 8
+
+### Failure Action
+
+```yaml
+warn:
+  action: "Pass with warnings"
+  message: "⚠️ STYLE GATE: [specific issues] — fixed automatically"
+  fix: true
+```
+
+---
+
+## Gate 3: Clarity
+
+**Non-fatal** — subjective, uses heuristics.
+
+### Checks
+
+- [ ] Response directly answers the user's question
+- [ ] No undefined acronyms or jargon
+- [ ] Code examples have context (filename, purpose)
+- [ ] Steps are in logical order
+- [ ] Error messages are human-readable
+- [ ] Variable names are meaningful
+- [ ] Complex logic has brief explanation
+
+### Heuristics
+
+```
+clarity_score = 0
+if answer_directly_matches_question:
+    clarity_score += 3
+if jargon_defined:
+    clarity_score += 1
+if code_has_context:
+    clarity_score += 1
+if steps_are_ordered:
+    clarity_score += 1
+if no_undefined_acronyms:
+    clarity_score += 1
+
+if clarity_score < 5:
+    fail("Response lacks clarity — rewrite")
+```
+
+---
+
+## Gate 4: Conciseness
+
+**Non-fatal** — measured against token budget.
+
+### Checks
+
+- [ ] No repetition of the same information
+- [ ] No filler phrases ("I would recommend", "It is important to note")
+- [ ] No verbose markdown (excessive headers, dividers)
+- [ ] Token count ≤ budget for the skill chain
+- [ ] No redundant code examples (same pattern twice)
+
+### Heuristics
+
+```
+repetition_penalty = count_repeated_phrases(output)
+filler_penalty = count_filler_phrases(output)
+total_penalty = repetition_penalty + filler_penalty
+
+if total_penalty > 5:
+    fail("Response too verbose — compress")
+```
+
+---
+
+## Gate 5: Completeness
+
+**Non-fatal** — checks that nothing is missing.
+
+### Checks
+
+- [ ] All user questions are answered
+- [ ] All requirements from the task are addressed
+- [ ] No "TODO" or "FIXME" left in code
+- [ ] Error handling is included
+- [ ] Edge cases are mentioned
+- [ ] Dependencies are declared
+- [ ] Installation/setup instructions are provided (if applicable)
+
+### Heuristics
+
+```
+answered = count_user_questions_answered(output)
+expected = count_user_questions(input)
+completeness_ratio = answered / expected
+
+if completeness_ratio < 1.0:
+    fail("Missing answers to [n] question(s)")
+```
+
+---
+
+## Combined Result
+
+```yaml
+quality_result:
+  security: "✅ PASS"
+  style: "⚠️ PASS (warnings: trailing whitespace)"
+  clarity: "✅ PASS"
+  conciseness: "✅ PASS (3% under budget)"
+  completeness: "✅ PASS"
+  overall: "✅ PASS"
+  token_usage: "1,234 / 2,048"
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Run all 5 gates on every output.
+- ✅ Block output on security gate failure.
+- ✅ Log gate results for Reflection Engine.
+- ✅ Fix style issues automatically when possible.
+
+### Never
+
+- ❌ Skip gates for speed.
+- ❌ Deliver output that fails any gate.
+- ❌ Modify security gate rules without user approval.
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Security pass rate | 100% | Outputs passing / total outputs |
+| Overall pass rate | ≥ 95% | Outputs passing all gates |
+| Auto-fix rate | ≥ 80% | Issues auto-fixed / total issues |
+| Gate latency | < 50ms | Time to run all gates |
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- 5 quality gates with distinct checklists
+- Security gate is fatal — blocks output on failure
+- Style gate auto-fixes common issues
+- Clarity, conciseness, completeness use heuristic scoring
+- Full logging for Reflection Engine integration

package/core/reflection-engine.md

@@ -0,0 +1,182 @@
+# Core: Reflection Engine
+
+> Version 1.0.0
+> Priority: High
+> Dependencies: Memory Manager, Evolution Engine
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The Reflection Engine activates after every task execution. It reviews what was done, identifies what went well and what can improve, logs patterns and mistakes, and feeds data into the Evolution Engine to update skills over time.
+
+---
+
+## Goals
+
+- Review every task after delivery.
+- Identify at least 1 improvement opportunity per task.
+- Log all mistakes to prevent recurrence.
+- Feed structured data to the Evolution Engine.
+- Build a personal improvement history for the agent.
+
+---
+
+## Workflow
+
+```
+1. Task completes
+    ↓
+2. Gather execution data
+    - Input, classification, chain used
+    - Token usage per skill
+    - Quality gate results
+    ↓
+3. Run self-review questions
+    - What went well?
+    - What could be better?
+    - Was the classification correct?
+    - Was context sufficient?
+    - Were quality gates passed?
+    ↓
+4. Check for patterns
+    - Recurring mistakes
+    - Recurring clarifications
+    - Token waste patterns
+    ↓
+5. Generate reflection output
+    ↓
+6. Pass to Memory Manager (log)
+    ↓
+7. Pass to Evolution Engine (if pattern found)
+```
+
+---
+
+## Self-Review Questions
+
+### Quality
+
+- Was the output complete?
+- Did it answer all user questions?
+- Was it concise?
+- Was it correct?
+
+### Process
+
+- Was the classification accurate?
+- Was the skill chain optimal?
+- Was context sufficient?
+- Was budget respected?
+
+### Security
+
+- Were any secrets exposed?
+- Were any vulnerabilities introduced?
+- Was security validated?
+
+### Teaching
+
+- Did the user learn something?
+- Did I explain the reasoning?
+- Was the explanation appropriate for the user level?
+
+---
+
+## Reflection Log Format
+
+```yaml
+reflection:
+  task_id: "task-20260717-001"
+  timestamp: "2026-07-17T11:30:00Z"
+  classification: "new_feature"
+  chain: ["architect", "security", "backend", "testing"]
+  
+  scores:
+    completeness: 4.5 / 5
+    conciseness: 4.0 / 5
+    correctness: 5.0 / 5
+    teaching: 3.5 / 5
+    
+  wins:
+    - "Architecture was clean and well-explained"
+    - "Security considerations included early"
+    
+  improvements:
+    - "Could have included more testing examples"
+    - "Token budget exceeded by 12%"
+    
+  patterns:
+    - type: "token_waste"
+      detail: "Verbose code examples in security section"
+      frequency: 3
+    
+  evolution_triggers:
+    - skill: "backend-engineer"
+      suggestion: "Add token budget optimization for code examples"
+```
+
+---
+
+## Pattern Detection
+
+The engine maintains a rolling window of the last 50 reflections to detect:
+
+| Pattern | Detection | Action |
+|---------|-----------|--------|
+| Token waste | >5 compressions in 10 tasks | Update Token Manager budget |
+| Misclassification | >3 clarifications for same category | Update Decision Engine keywords |
+| Repeated mistakes | >2 same improvement items | Flag for Evolution Engine |
+| User confusion | >2 follow-up clarifications | Add teaching moment to output |
+| Security gaps | Any security item missed | Immediate skill update |
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Tasks reflected | 100% | Reflections / total tasks |
+| Improvements per task | ≥ 1 | Count improvement items |
+| Pattern detection rate | ≥ 80% | Patterns found / patterns present |
+| Evolution triggers | ≥ 1 per 10 tasks | Count triggers generated |
+
+---
+
+## Reflection Quality Gates
+
+1. ✅ Reflection is generated for every task.
+2. ✅ At least 1 improvement identified.
+3. ✅ Scores are honest (not all 5/5).
+4. ✅ Patterns are detected (if present).
+
+---
+
+## Memory Hooks
+
+```yaml
+on_reflect:
+  - save: reflection_log
+  - save: pattern_window (rolling 50)
+
+on_pattern_detected:
+  - notify: Evolution Engine
+  - save: pattern_alert
+
+on_complete:
+  - compress: reflection_log if > budget
+```
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- Post-task self-review with scoring
+- Pattern detection over rolling 50-task window
+- Structured reflection log in YAML format
+- Integration with Evolution Engine
+- 5 dimensions of review: quality, process, security, teaching, efficiency