codecruise 0.1.0

package/config/schemas.md

@@ -0,0 +1,767 @@
+# Schemas — Contract Definitions
+
+**CRITICAL**: These schemas are contracts. Commands write → other commands read.
+Changing field names or structures breaks the workflow chain.
+
+## ID Patterns
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Phase | `phase-NN` | `phase-01`, `phase-02` |
+| Feature | `feature-N.N` | `feature-1.2`, `feature-2.5` |
+| Subfeature | `subfeature-N.Na` | `subfeature-1.1a`, `subfeature-2.3b` |
+| TODO | `todo-N.Na-NNN` | `todo-1.1a-001`, `todo-2.3b-015` |
+| Conflict | `conflict-NNN` | `conflict-001` |
+| Open Question | `oq-NNN` | `oq-012` |
+| Assumption | `assumption-NNN` | `assumption-003` |
+| Decision | `D-NNN` | `D-005` |
+| ADR | `ADR-NNN` | `ADR-001` |
+| RFC | `RFC-NNN` | `RFC-001` |
+| Requirement (FR) | `FR-NNN` | `FR-001` |
+| Requirement (NFR) | `NFR-NNN` | `NFR-010` |
+| Workflow | `WF-NNN` | `WF-001` |
+| Use Case | `UC-NNN` | `UC-003` |
+
+---
+
+## Project Structure
+
+```
+{project}/
+├── CLAUDE.md                      # Claude Code requirement (root, <100 lines)
+│
+├── .claude/
+│   └── settings.json              # Claude Code project settings
+│
+└── .codecruise/                   # ALL CodeCruise artifacts
+    ├── .codecruise/progress.yaml              # Execution state
+    ├── steering/                  # Context docs
+    │   ├── product.md             # What: purpose, users, scope
+    │   ├── tech.md                # How: stack, tools, constraints
+    │   └── structure.md           # Where: architecture, patterns
+    ├── canon/                     # Canonical spec (from /spec-forge)
+    │   ├── spec.md                # FR/NFR requirements
+    │   ├── issues.md              # Conflicts, OQs, assumptions
+    │   ├── decisions.md           # ADRs (immutable)
+    │   └── changelog.md           # Spec version history
+    ├── context/                   # Per-feature context
+    │   └── {feature}.yaml         # Sources, decisions, constraints
+    ├── roadmap/                   # Phase/feature/TODO definitions
+    │   └── phase-NN.yaml
+    ├── metrics/
+    │   ├── events.jsonl           # OODA event stream
+    │   └── scorecards/            # Per-TODO quality scores
+    ├── insights.yaml              # Companion state
+    └── cache/                     # Temp files (gitignored)
+```
+
+## Steering Docs Structure
+
+Minimal, focused context files. CLAUDE.md < 100 lines, details in steering docs.
+
+### CLAUDE.md (Required Sections)
+
+```markdown
+# {Project}
+
+## What
+{one-liner}
+
+## Stack
+{language, runtime, framework, package manager}
+
+## Quality Command
+{single command, <10s}
+
+## Key Commands
+{install, dev, build, test}
+
+## Project Structure
+{key directories}
+
+## Steering Docs
+{links to product.md, tech.md, structure.md}
+
+## Rules
+{max 10, universally applicable}
+
+## Domain Context
+{1-2 sentences of domain expertise}
+```
+
+### Steering Doc Required Sections
+
+**product.md**:
+- One-Liner
+- Problem Statement
+- Target Users
+- Key Features (v1)
+- Out of Scope (v1)
+
+**tech.md**:
+- Core Stack (table)
+- Package Manager
+- Quality Command
+- Constraints
+
+**structure.md**:
+- System Context (C4 Level 1)
+- Directory Structure
+- Naming Conventions
+- Module Boundaries
+
+---
+
+## .codecruise/progress.yaml (v2 — Current)
+
+Simplified schema. Stats and patterns are computed from `.codecruise/metrics/events.jsonl`.
+
+```yaml
+# .codecruise/progress.yaml v2 — Minimal State (~40 lines)
+schema_version: 2
+project: {name}
+generated: {ISO timestamp}
+
+# Current position
+current_todo: todo-1.1b-004
+
+# Execution state
+execution_state:
+  status: running|paused|stopped|completed|error
+  tempo: ship-fast|balanced|careful
+  on_error: ask|skip|abort|replan
+  started_at: {ISO timestamp}
+  paused_at: {ISO timestamp|null}
+
+# OODA state (confidence computed in ORIENT, stored for display)
+ooda:
+  confidence: high|medium|low|{0.0-1.0}
+  last_observation: {ISO timestamp|null}
+
+# Guardrails
+guardrails:
+  max_retries_per_todo: 3
+  max_replans_per_module: 2
+  on_limit_hit: escalate|abort|skip_module
+
+# Queue (simple arrays)
+queue:
+  completed: [todo-1.1a-001, todo-1.1a-002]
+  pending: [todo-1.1b-004, todo-1.1b-005]
+  failed: []
+  skipped: []
+
+# Human-managed
+blockers: []
+notes: []
+
+last_updated: {ISO timestamp}
+```
+
+### Computed Values (ORIENT Phase)
+
+These are computed from `events.jsonl`, not stored:
+
+| Field | Source | Calculation |
+|-------|--------|-------------|
+| `stats.todos_completed` | `queue.completed` | Length |
+| `stats.todos_remaining` | `queue.pending` | Length |
+| `stats.total_retries` | `events.jsonl` | Sum retry events |
+| `consecutive_failures` | `events.jsonl` | Count since last success |
+| `patterns_detected` | `events.jsonl` | Analyze last N events |
+| `module_replans` | `events.jsonl` | Group replan events by module |
+| `confidence_factors` | OODA rules | Computed during ORIENT |
+
+### Migration from v1
+
+Run `/init --upgrade-schema` or `/doctor --fix` to migrate.
+
+---
+
+## .codecruise/progress.yaml (v1 — Deprecated)
+
+> **Deprecated**: Use v2 schema above. v1 support will be removed in future releases.
+
+```yaml
+project: {name}
+generated: {ISO timestamp}
+
+# Current position
+current_phase: phase-01
+current_feature: feature-1.1
+current_subfeature: subfeature-1.1b
+current_todo: todo-1.1b-004
+
+# Execution state (managed by /run)
+execution_state:
+  status: running|paused|stopped|completed|error
+  started_at: {ISO timestamp}
+  paused_at: {ISO timestamp|null}
+  completed_at: {ISO timestamp|null}
+
+  # Scope being executed
+  scope: feature-1.1
+  scope_type: phase|feature|subfeature|todo
+
+  # Settings
+  tempo: ship-fast|balanced|careful
+  checkpoint_mode: subfeature|feature|none
+  on_error: ask|skip|abort|replan
+  max_iterations: 3
+
+  # Autonomous mode
+  mode: interactive|autonomous
+  max_turns: 100
+  current_turn: 0
+  notify_channel: slack|webhook|null
+
+  # OODA Loop State
+  ooda:
+    last_observation: {ISO timestamp|null}
+    confidence: high|medium|low|{0.0-1.0}
+    confidence_factors:
+      base: 0.8
+      retry_penalty: 0.0
+      module_penalty: 0.0
+      dep_penalty: 0.0
+    consecutive_failures: 0
+    patterns_detected: []  # [retry_spike, module_failing, error_cluster, external_dep_down]
+    skip_count: 0
+    replan_count: 0
+
+  # Guardrails (prevent infinite loops)
+  guardrails:
+    max_retries_per_todo: 3
+    max_replans_per_module: 2
+    max_replans_per_feature: 3
+    on_limit_hit: escalate|abort|skip_module
+    cost_limit: {number|null}  # USD, optional
+    cost_current: 0.0
+
+  # Per-module replan tracking
+  module_replans:
+    auth: 0
+    api: 0
+    database: 0
+
+  # Pause state (for /resume)
+  pause_phase: observe|orient|decide|act|null
+  pause_reason: {string|null}
+
+  # Promise verification
+  promise:
+    text: {string|null}
+    verified: false
+    checks: []
+
+  # Blockers (autonomous)
+  blockers:
+    - todo: todo-1.2a-005
+      reason: "Redis not running"
+      pattern: external_dep_down
+      timestamp: {ISO timestamp}
+      notified: true
+      resolved: false
+
+  # Queue
+  queue:
+    total: 14
+    completed: [todo-1.1a-001, todo-1.1a-002]
+    pending: [todo-1.1b-004, todo-1.1b-005]
+    failed: []
+    skipped:
+      - id: todo-1.1b-003
+        reason: "External API not ready"
+        skip_source: user_override|ooda_routing|blocker_detected
+        skipped_at: {ISO timestamp}
+        had_dependents: false
+    replanned: []
+
+  # Stats
+  stats:
+    todos_completed: 10
+    todos_remaining: 4
+    todos_failed: 0
+    todos_skipped: 0
+    total_retries: 2
+    total_commits: 5
+    total_replans: 0
+    avg_confidence: 0.85
+    duration_minutes: 45
+
+  # Last checkpoint
+  last_checkpoint:
+    type: subfeature
+    id: subfeature-1.1a
+    timestamp: {ISO timestamp}
+    todos_completed: 7
+    ooda_summary:
+      avg_confidence: 0.87
+      patterns: []
+      replans: 0
+
+  # Error tracking
+  last_error:
+    todo: todo-1.2a-005
+    message: "Connection refused"
+    error_type: connection|test_failure|lint_error|type_error
+    attempts: 3
+    timestamp: {ISO timestamp}
+    output: "Error: connect ECONNREFUSED..."
+
+# Human notes (managed by user)
+blockers:
+  - id: blocker-001
+    description: "Redis connection failing"
+    affects: feature-2.3
+    since: {ISO date}
+
+notes:
+  - "API rate limits hit - added retry"
+  - "Need design review before Phase 3"
+
+# Session tracking (for /dashboard)
+session:
+  started: {ISO timestamp}
+  tokens:
+    input: 45000
+    output: 12000
+  estimated_cost: 0.42
+
+# Overall stats
+stats:
+  total_phases: 2
+  completed_phases: 0
+  total_features: 10
+  completed_features: 1
+  total_todos: 164
+  completed_todos: 14
+  percent_complete: 8
+
+last_updated: {ISO timestamp}
+```
+
+---
+
+## .codecruise/metrics/events.jsonl
+
+Append-only event stream. Used by ORIENT phase to compute stats and patterns.
+
+```jsonl
+{"ts":"2026-02-20T10:30:00Z","event":"session_start","data":{}}
+{"ts":"2026-02-20T10:30:15Z","event":"todo_start","data":{"todo":"todo-1.1b-004"}}
+{"ts":"2026-02-20T10:30:16Z","event":"ooda_observe","data":{"todo":"todo-1.1b-004","git":"clean","deps":"ok"}}
+{"ts":"2026-02-20T10:30:17Z","event":"ooda_orient","data":{"todo":"todo-1.1b-004","confidence":0.85,"patterns":[]}}
+{"ts":"2026-02-20T10:30:18Z","event":"ooda_decide","data":{"todo":"todo-1.1b-004","decision":"execute"}}
+{"ts":"2026-02-20T10:30:20Z","event":"ooda_act","data":{"todo":"todo-1.1b-004","phase":"red"}}
+{"ts":"2026-02-20T10:33:45Z","event":"verify","data":{"lint":0,"tsc":0,"test":0}}
+{"ts":"2026-02-20T10:33:50Z","event":"todo_complete","data":{"todo":"todo-1.1b-004","duration_s":210,"commit":"abc123"}}
+{"ts":"2026-02-20T10:35:20Z","event":"todo_fail","data":{"todo":"todo-1.1b-005","error":"connection refused","attempt":1}}
+{"ts":"2026-02-20T10:35:21Z","event":"retry","data":{"todo":"todo-1.1b-005","attempt":2}}
+{"ts":"2026-02-20T10:36:46Z","event":"skip","data":{"todo":"todo-1.1b-005","reason":"external dep","source":"ooda_routing"}}
+{"ts":"2026-02-20T10:36:50Z","event":"replan","data":{"module":"auth","count":1}}
+{"ts":"2026-02-20T11:15:00Z","event":"session_pause","data":{"reason":"user"}}
+```
+
+### Event Types
+
+| Event | Description | Data Fields |
+|-------|-------------|-------------|
+| `session_start` | New execution session | — |
+| `session_pause` | Session paused | `reason` |
+| `todo_start` | TODO execution began | `todo` |
+| `todo_complete` | TODO finished successfully | `todo`, `duration_s`, `commit` |
+| `todo_fail` | TODO attempt failed | `todo`, `error`, `attempt` |
+| `ooda_observe` | OBSERVE phase completed | `todo`, `git`, `deps`, `branch` |
+| `ooda_orient` | ORIENT phase completed | `todo`, `confidence`, `patterns` |
+| `ooda_decide` | DECIDE phase completed | `todo`, `decision` |
+| `ooda_act` | ACT phase update | `todo`, `phase` (red/green/refactor) |
+| `verify` | Quality verification | `lint`, `tsc`, `test` (exit codes) |
+| `retry` | Retry attempt | `todo`, `attempt` |
+| `skip` | TODO skipped | `todo`, `reason`, `source` |
+| `replan` | Module replanned | `module`, `count` |
+
+---
+
+## .codecruise/activity.log
+
+Human-readable log for `tail -f`. Plain text with timestamps and emoji.
+
+```
+[2026-02-20 10:30:15] ━━━ SESSION START ━━━
+[2026-02-20 10:30:16] 👁 OBSERVE todo-1.1b-004
+[2026-02-20 10:30:17]    ├─ git: clean
+[2026-02-20 10:30:17]    └─ branch: feature/auth
+[2026-02-20 10:30:18] 🧭 ORIENT confidence=0.85
+[2026-02-20 10:30:19] ⚡ DECIDE execute
+[2026-02-20 10:30:20] ▶ ACT todo-1.1b-004 "Implement validation"
+[2026-02-20 10:33:45]    └─ VERIFY: lint ✓ | tsc ✓ | test ✓
+[2026-02-20 10:33:50] ✓ COMPLETE todo-1.1b-004 (3m 30s) commit:abc123
+[2026-02-20 10:33:51] → NEXT todo-1.1b-005
+[2026-02-20 10:35:20]    └─ ✗ TEST FAIL: connection refused
+[2026-02-20 10:35:21] ⚠ RETRY (attempt 2/3)
+[2026-02-20 10:36:46] ⏭ SKIP todo-1.1b-005 (blocker: external dep)
+[2026-02-20 11:15:00] ⏸ PAUSE
+[2026-02-20 11:15:01] ━━━ SESSION PAUSE ━━━
+```
+
+---
+
+## .codecruise/roadmap/phase-NN.yaml
+
+```yaml
+phase:
+  id: phase-01
+  name: Alpha Bootstrap
+  status: pending|in_progress|completed
+  started: {ISO timestamp|null}
+  completed: {ISO timestamp|null}
+  branch: feature/alpha-bootstrap
+
+  goals:
+    - "Set up monorepo structure"
+    - "Implement core infrastructure"
+
+  success_criteria:
+    - "All packages build"
+    - "Tests pass"
+
+features:
+  - id: feature-1.1
+    name: Monorepo Foundation
+    branch: feature/alpha/monorepo-foundation
+    status: pending|in_progress|completed
+
+    subfeatures:
+      - id: subfeature-1.1a
+        name: Root Configuration
+        status: pending|in_progress|completed
+
+        todos:
+          - id: todo-1.1a-001
+            description: Create root package.json
+            owner: dev
+            status: pending|in_progress|done|blocked|skipped
+            files:
+              - package.json
+              - pnpm-workspace.yaml
+            criteria:
+              - "package.json has workspace config"
+              - "pnpm-workspace.yaml lists all packages"
+            tests:
+              - "pnpm install succeeds"
+            constraints:
+              - "Use pnpm 8+"
+            depends_on: []
+
+          - id: todo-1.1a-002
+            description: Configure TypeScript
+            depends_on: [todo-1.1a-001]
+            # ... same structure
+```
+
+---
+
+## .codecruise/canon/spec.md
+
+```markdown
+---
+version: 0.1.0
+generated: {ISO timestamp}
+generated_hash: sha256:abc123
+sources_hash: sha256:def456
+sources_count: 12
+last_reviewed: {ISO timestamp|null}
+---
+
+# {Project Name} — Product Specification
+
+## 1. Overview
+### 1.1 One-Line Pitch
+### 1.2 Problem Statement
+### 1.3 Goals
+### 1.4 Non-Goals (v1)
+### 1.5 Key Terms
+
+## 2. Users
+### 2.1 Personas
+### 2.2 Key Use Cases
+
+## 3. Scope
+### 3.1 v1 In-Scope
+### 3.2 Out-of-Scope (v1)
+
+## 4. Requirements
+### 4.1 Functional Requirements
+
+#### FR-001: {Feature Name}
+- **Description**: {what it does}
+- **User Story**: As a {role}, I want {goal}, so that {benefit}
+- **Acceptance Criteria**:
+  - [ ] {testable criterion}
+- **Source**: {document}
+
+### 4.2 Non-Functional Requirements
+
+#### NFR-001: {Requirement}
+- **Category**: Performance|Security|Reliability|Observability
+- **Requirement**: {specific, measurable}
+- **Threshold**: {number/metric}
+- **Source**: {document}
+
+## 5. Workflows
+
+### WF-001: {Workflow Name}
+- **Trigger**: {what initiates this flow}
+- **Actors**: {user roles involved}
+- **Related**: FR-001, FR-002
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant A as API
+    participant D as Database
+    participant E as External Service
+
+    U->>A: Request
+    A->>D: Query
+    D-->>A: Result
+    A-->>U: Response
+```
+
+**Steps:**
+1. {Step description}
+2. {Step description}
+
+**Error Handling:**
+- {error condition} → {behavior}
+
+**Edge Cases:**
+- {edge case} → {handling}
+
+## 6. Data & Integrations
+### 6.1 Key Entities
+### 6.2 Integrations
+### 6.3 Auth Model
+
+## 7. Risks
+## 8. Links
+```
+
+---
+
+## .codecruise/canon/issues.md
+
+```yaml
+# Conflicts
+conflicts:
+  - id: conflict-001
+    description: "Auth timeout: 30min vs 1hr"
+    side_a:
+      position: "30 minutes for security"
+      sources: [security-review.md]
+    side_b:
+      position: "1 hour for UX"
+      sources: [ux-research.pdf]
+    severity: P0|P1|P2
+    suggested_resolution: "..."
+    status: open|resolved
+    # User adds for resolution:
+    resolution: "Use 1hr with re-auth for sensitive actions"
+    rationale: "Balances UX with security"
+    apply_to:
+      - section: "6.3 Auth Model"
+      - requirement: FR-003
+    # Added by /spec-resolve:
+    resolved_date: {ISO date}
+    resolved_by: /spec-resolve
+    decision_id: D-005
+
+# Open Questions
+open_questions:
+  - id: oq-001
+    question: "What happens when rate limit exceeded?"
+    context: "Behavior undefined"
+    impact: "Cannot implement error handling"
+    owner: PM|Eng|Security|Legal
+    priority: P0|P1|P2
+    related_conflicts: []
+    status: open|resolved
+    # User adds:
+    resolution: "Return 429 with Retry-After header"
+    apply_to:
+      - new_requirement: NFR-010
+
+# Assumptions
+assumptions:
+  - id: assumption-001
+    assumption: "Free tier = no premium API"
+    rationale: "Inferred from pricing doc"
+    sources: [pricing-draft.md]
+    needs_validation: true
+    related: [oq-003]
+    status: open|resolved
+    # User adds:
+    resolution: confirmed|"revised: {new assumption}"
+    validated_by: "PM confirmed 2024-01-20"
+```
+
+---
+
+## .codecruise/canon/decisions.md
+
+```markdown
+# Decision Log
+
+## D-001: {Decision Title}
+- **Date**: {ISO date}
+- **Decision**: {what was decided}
+- **Rationale**: {why}
+- **Alternatives Considered**: {options rejected}
+- **Sources**: {documents that informed}
+- **Related**: conflict-001, oq-003
+- **Resolved by**: /spec-resolve|manual
+```
+
+---
+
+## .codecruise/context/{feature}.yaml
+
+```yaml
+feature: auth
+created: {ISO date}
+updated: {ISO date}
+
+sources:
+  - file: "Auth Guide.pdf"
+    pages: [2, 5-7]
+    note: "Session management"
+  - file: "Security Review.md"
+    sections: ["Authentication"]
+
+decisions:
+  - id: D-001
+    summary: "JWT with refresh tokens"
+    source: "Security Review.md"
+
+constraints:
+  - "httpOnly cookies for web"
+  - "Biometric auth optional mobile"
+
+open_questions:
+  - id: oq-001
+    question: "MFA for v1?"
+```
+
+---
+
+## .codecruise/scorecards/{todo-id}.json
+
+```json
+{
+  "todo_id": "todo-1.1b-004",
+  "timestamp": "{ISO timestamp}",
+  "ooda": {
+    "confidence": 0.85,
+    "patterns": [],
+    "observation_time_ms": 45
+  },
+  "verification": {
+    "lint": { "exit_code": 0, "errors": 0 },
+    "typecheck": { "exit_code": 0, "errors": 0 },
+    "tests": { "exit_code": 0, "passed": 47, "failed": 0 }
+  },
+  "scores": {
+    "quality": 0.95,
+    "alignment": 0.88,
+    "overall": 0.91
+  },
+  "decision": "proceed|proceed_with_comment|retry|replan|flag_for_human"
+}
+```
+
+---
+
+## .codecruise/insights.yaml (Companion State)
+
+```yaml
+generated: {ISO timestamp}
+
+# Real-time pattern state (used by ORIENT phase)
+pattern_state:
+  retry_window: [2, 3, 1, 0, 2]  # Last 5 TODO retry counts
+  error_types:
+    auth_error: 3
+    type_error: 1
+    connection_error: 0
+  module_failures:
+    auth: 2
+    api: 0
+    database: 1
+  external_deps:
+    docker: up|down|unknown
+    redis: up|down|unknown
+
+# Active insights (for /companion standalone)
+active_insights:
+  - id: insight-001
+    type: blocker|friction|opportunity|win
+    pattern: retry_spike|module_failing|error_cluster|external_dep_down|context_bloat
+    category: {module or skill name}
+    message: "Auth module averaging 0.52 confidence"
+    severity: critical|warning|info
+    first_seen: {ISO timestamp}
+    occurrences: 4
+    status: active|resolved|dismissed
+    resolved_at: {ISO timestamp|null}
+
+# Dismissed insights (don't re-surface)
+dismissed_insights:
+  - id: insight-003
+    reason: "User dismissed"
+    dismissed_at: {ISO timestamp}
+```
+
+---
+
+## OODA Values
+
+| Field | Valid Values |
+|-------|--------------|
+| `tempo` | `ship-fast`, `balanced`, `careful` |
+| `confidence` | `high`, `medium`, `low` or `0.0` - `1.0` |
+| `pause_phase` | `observe`, `orient`, `decide`, `act`, `null` |
+| `patterns_detected` | `retry_spike`, `module_failing`, `error_cluster`, `external_dep_down`, `context_bloat` |
+| `skip_source` | `user_override`, `ooda_routing`, `blocker_detected` |
+| `on_error` | `ask`, `skip`, `abort`, `replan` |
+| `decision` | `proceed`, `proceed_cautious`, `skip`, `replan`, `escalate` |
+| `on_limit_hit` | `escalate`, `abort`, `skip_module` |
+
+## Guardrail Defaults
+
+| Guardrail | Default | Range |
+|-----------|---------|-------|
+| `max_retries_per_todo` | 3 | 1-10 |
+| `max_replans_per_module` | 2 | 1-5 |
+| `max_replans_per_feature` | 3 | 1-10 |
+| `cost_limit` | null | 0.00+ USD |
+
+---
+
+## Status Values
+
+| Context | Valid Values |
+|---------|--------------|
+| Phase/Feature/Subfeature | `pending`, `in_progress`, `completed` |
+| TODO | `pending`, `in_progress`, `done`, `blocked`, `skipped` |
+| execution_state.status | `running`, `paused`, `stopped`, `completed`, `error` |
+| Issue status | `open`, `resolved` |
+| Severity | `P0`, `P1`, `P2` |
+
+---
+
+## Timestamps
+
+All timestamps use ISO 8601 format: `2026-02-20T14:30:00Z`
+
+Dates use: `2026-02-20`