iosm-cli 0.1.0

package/docs/interactive-mode.md

@@ -0,0 +1,272 @@
+# Interactive Mode
+
+Interactive mode is the default experience when running `iosm` without `-p` or `--mode` flags. It provides a rich multi-turn terminal session with persistent history, model switching, and keyboard-driven controls.
+
+## Starting Interactive Mode
+
+```bash
+# Default
+iosm
+
+# With specific model
+iosm --model sonnet:high
+
+# With profile
+iosm --profile plan
+
+# Continue previous session
+iosm --continue
+```
+
+## Core UX
+
+- Multi-turn conversation with persistent session history
+- Keyboard-driven controls for model, profile, and queue management
+- Live tool execution rendering with expandable output
+- Pending message queue for follow-up prompts
+- Task plan visualization and progress tracking
+- Streaming responses with interrupt/steer capability
+
+---
+
+## Slash Commands
+
+### Session Lifecycle
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/new` | Start a new session | `/new` |
+| `/clear` | Alias for `/new` | `/clear` |
+| `/resume` | Open session picker | `/resume` |
+| `/fork` | Branch from a previous message | `/fork` |
+| `/tree` | Navigate the session tree | `/tree` |
+| `/checkpoint` | Save a rollback checkpoint (`/checkpoint list`) | `/checkpoint before-refactor` |
+| `/rollback` | Roll back to latest/named/indexed checkpoint | `/rollback 2` |
+| `/name` | Set session display name | `/name refactoring-auth` |
+| `/session` | Session info | `/session` |
+| `/quit` | Exit the application | `/quit` |
+
+### Model & Runtime
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/model` | Open provider-first model selector (`provider -> model`) | `/model` |
+| `/scoped-models` | Manage model rotation | `/scoped-models` |
+| `/mcp` | Open MCP manager UI and run MCP subcommands | `/mcp` |
+| `/memory` | Interactive memory manager (`add/edit/remove/scope/path`) | `/memory` |
+| `/settings` | View/modify settings | `/settings` |
+| `/hotkeys` | View keyboard shortcuts | `/hotkeys` |
+| `/changelog` | View recent changes | `/changelog` |
+
+### IOSM & Planning
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/init` | Bootstrap IOSM workspace | `/init` |
+| `/iosm` | Run full IOSM cycle | `/iosm 0.95 --max-iterations 5` |
+| `/cycle-plan` | Plan a new cycle | `/cycle-plan reduce latency` |
+| `/cycle-status` | Check cycle progress | `/cycle-status` |
+| `/cycle-report` | View cycle report | `/cycle-report` |
+| `/cycle-list` | List all cycles | `/cycle-list` |
+
+### Orchestration & Agents
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/orchestrate` | Launch subagent orchestration | See below |
+| `/agents` | Inspect custom/system agents | `/agents` |
+| `/subagent-runs` | List subagent run history | `/subagent-runs` |
+| `/subagent-resume` | Resume a subagent run | `/subagent-resume run-123` |
+| `/team-runs` | List team orchestration runs | `/team-runs` |
+| `/team-status` | Check team run status | `/team-status team-456` |
+
+### System Actions
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/export` | Export session to HTML | `/export` |
+| `/share` | Share via GitHub Gist | `/share` |
+| `/copy` | Copy last response to clipboard | `/copy` |
+| `/doctor` | Run diagnostics for model/auth/MCP/hooks/resources | `/doctor` |
+| `/compact` | Compact conversation context | `/compact` |
+| `/reload` | Reload extensions and resources | `/reload` |
+| `/permissions` | View/set tool permissions | `/permissions` |
+| `/yolo` | Toggle auto-approve mode | `/yolo on` |
+| `/login` | Authenticate with provider (OAuth incl. Qwen + OpenRouter API key) | `/login` |
+| `/auth` | Alias for `/login` | `/auth` |
+| `/logout` | Clear saved provider credentials | `/logout` |
+
+`/mcp add` without flags starts a guided wizard in the terminal UI.
+`/memory` opens an interactive manager. `/memory <text>` saves a note to `memory.md` and reloads session context. Use `/memory edit <index> <text>` for direct updates.
+
+---
+
+## Keyboard Shortcuts
+
+### Application Controls
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Interrupt current agent run |
+| `Ctrl+C` | Clear input or app-level clear |
+| `Ctrl+D` | Exit the application |
+| `Ctrl+Z` | Suspend process |
+
+### Model & Profile
+
+| Key | Action |
+|-----|--------|
+| `Shift+Tab` | Cycle profile (full → plan → iosm) |
+| `Shift+Ctrl+T` | Cycle thinking level |
+| `Ctrl+P` | Next model in rotation |
+| `Shift+Ctrl+P` | Previous model in rotation |
+| `Ctrl+L` | Open model selector |
+
+### UI Controls
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+O` | Expand/collapse tool output details |
+| `Ctrl+T` | Toggle thinking panel |
+| `Ctrl+G` | Open external editor for input |
+
+### Input & Queue
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+Enter` | Steer while streaming (macOS: `Ctrl+\\`) |
+| `Alt+Enter` | Queue follow-up message |
+| `Alt+Up` | Dequeue/edit queued draft |
+| `Ctrl+V` | Paste image (Windows: `Alt+V`) |
+
+### Customization
+
+Override keybindings by creating `~/.iosm/agent/keybindings.json`:
+
+```json
+{
+  "Ctrl+P": "nextModel",
+  "Ctrl+Shift+P": "previousModel",
+  "Ctrl+L": "openModelSelector"
+}
+```
+
+---
+
+## Profiles
+
+Profiles change the agent's behavior, available tools, and system prompt:
+
+### Main Profiles (switchable via `Shift+Tab`)
+
+| Profile | Tools | Use Case |
+|---------|-------|----------|
+| `full` | All (read, bash, edit, write, grep, find, ls) | Default development work |
+| `plan` | Read-only (read, grep, find, ls) | Architecture planning, code review |
+| `iosm` | All + IOSM context | IOSM cycle execution with artifact sync |
+
+### Advanced Profiles (via `--profile` or orchestration)
+
+| Profile | Use Case |
+|---------|----------|
+| `explore` | Exploratory codebase analysis |
+| `iosm_analyst` | Deep metric analysis and reporting |
+| `iosm_verifier` | Verify cycle results and quality gates |
+| `cycle_planner` | Plan and structure IOSM cycles |
+
+### Example: Planning Workflow
+
+```bash
+# Start in plan mode for analysis
+iosm --profile plan
+
+# In the session:
+# "Analyze the authentication module and propose a migration plan to OAuth 2.0"
+
+# Switch to full mode for implementation (Shift+Tab)
+# "Implement phase 1 of the OAuth migration"
+```
+
+---
+
+## Streaming Input Modes
+
+While a response is streaming, you can interact with it:
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| **Steer** | `Ctrl+Enter` | Interrupt and redirect immediately |
+| **Follow-up** | `Alt+Enter` | Queue message for after completion |
+| **Meta** | Adaptive | Soft update at boundary checkpoints |
+
+### Example: Steering
+
+```
+Agent: [streaming a long analysis of the codebase...]
+
+You: (Ctrl+Enter) Focus specifically on the database layer
+# Agent immediately redirects to database analysis
+```
+
+### Example: Follow-up Queue
+
+```
+Agent: [streaming response...]
+
+You: (Alt+Enter) Also check for N+1 query issues
+You: (Alt+Enter) And suggest indexing improvements
+# Both messages will be processed after the current response
+```
+
+---
+
+## Workflow Examples
+
+### Code Review Session
+
+```bash
+iosm --profile plan --tools read,grep,find,ls
+
+# "Review src/core/ for code quality issues, focusing on error handling"
+# "Check for any security vulnerabilities in the auth module"
+# "Generate a summary of findings sorted by severity"
+```
+
+### Debugging Session
+
+```bash
+iosm --model sonnet:high
+
+# "The checkout API returns 500 errors intermittently. Help me debug."
+# Agent will use bash, read, grep to investigate
+# "Run the failing test with verbose output"
+# "Apply the fix and verify all tests pass"
+```
+
+### IOSM Improvement Cycle
+
+```bash
+iosm --profile iosm
+
+# "/init" (first time)
+# "/cycle-plan reduce API response time"
+# "Analyze the current baseline and create hypothesis cards"
+# "Execute the Improve phase focusing on query optimization"
+# "/cycle-status"
+```
+
+### Multi-Agent Orchestration
+
+```bash
+iosm
+
+# "Launch 3 parallel agents to:
+#  1. Audit auth module security
+#  2. Review database query performance  
+#  3. Check API contract compliance"
+
+# Or via slash command:
+/orchestrate --parallel --agents 3 \
+  --profiles explore,explore,iosm_verifier \
+  Audit security, performance, and contracts
+```

package/docs/iosm-init-and-cycles.md

@@ -0,0 +1,355 @@
+# IOSM Init & Cycles
+
+IOSM (**Improve → Optimize → Shrink → Modularize**) is an algorithmic methodology for systematic engineering improvement. This document covers workspace bootstrapping and cycle operations.
+
+## Overview
+
+Each IOSM cycle follows a fixed execution order:
+
+```
+PLAN → HYPOTHESIZE → IMPROVE → GATE_I → OPTIMIZE → GATE_O → SHRINK → GATE_S → MODULARIZE → GATE_M → SCORE → LEARN → DECIDE
+```
+
+Every phase is evaluated against a Quality Gate. The methodology tracks six canonical metrics, computes an IOSM-Index, and determines whether to continue, stop, or fail.
+
+---
+
+## `iosm init`
+
+Bootstrap IOSM artifacts for a project:
+
+```bash
+iosm init [path] [--force] [--agent-verify|--no-agent-verify]
+```
+
+| Flag | Description |
+|------|-------------|
+| `path` | Target directory (default: current directory) |
+| `--force` | Recreate artifacts even if they exist |
+| `--agent-verify` | Run post-init agent verification (default) |
+| `--no-agent-verify` | Skip the verification step |
+
+### What It Creates
+
+```bash
+# Initialize current project
+iosm init
+```
+
+This generates:
+
+```
+project/
+├── iosm.yaml                         # ← Method configuration
+├── IOSM.md                           # ← Operator/agent playbook
+└── .iosm/
+    ├── metrics-history.jsonl          # Longitudinal cycle metrics
+    ├── decision-log.md                # Historical decisions and rationale
+    ├── pattern-library.md             # Reusable implementation patterns
+    ├── waivers.yaml                   # Governance exceptions
+    ├── invariants.yaml                # Logic baseline (invariant catalog)
+    ├── contracts.yaml                 # Boundary control (contract catalog)
+    └── cycles/                        # Per-cycle artifact storage
+```
+
+### Example: Initialize with Verification
+
+```bash
+# Full init with agent-powered analysis
+iosm init
+
+# This will:
+# 1. Analyze your codebase
+# 2. Generate a tailored iosm.yaml with appropriate thresholds
+# 3. Create an IOSM.md playbook with project-specific guidance
+# 4. Verify the configuration is valid
+```
+
+### Example: Quick Init without Analysis
+
+```bash
+# Skip the agent verification
+iosm init --no-agent-verify
+
+# Force re-init for an existing workspace
+iosm init --force
+```
+
+---
+
+## Configuration: `iosm.yaml`
+
+The `iosm.yaml` file controls all methodology parameters. Here's a fully annotated example:
+
+```yaml
+iosm:
+  metadata:
+    system_name: billing-api           # System under improvement
+    scope: service                     # Scope level
+    criticality_profile: standard      # standard | critical | exploratory
+    delivery_boundary: billing-api     # Unit for delivery flow measurement
+
+  planning:
+    use_economic_decision: true        # Use WSJF-based prioritization
+    prioritization_formula: wsjf_confidence
+    min_confidence: 0.70               # Minimum confidence to select a goal
+    hypothesis_required: true          # Require hypothesis cards
+    cycle_scope_required: true         # Require explicit scope declaration
+
+  cycle_capacity:
+    max_goals: 3                       # Max goals per cycle
+    max_scope_items: 5                 # Max scope elements
+    max_expected_change_surface: 3     # Max coordinated changes
+
+  cycle_policy:
+    max_iterations_per_phase: 3        # Retry limit per phase
+    stabilization:
+      target_index: 0.98              # Target IOSM-Index for stabilization
+      consecutive_cycles: 3           # Consecutive stable cycles needed
+      global_metric_floor: 0.60       # Minimum for any metric
+      max_consecutive_unexplained_declines: 2
+
+  quality_gates:
+    gate_I:                            # Improve gate
+      semantic_min: 0.95
+      logical_consistency_min: 1.00
+      duplication_max: 0.05
+    gate_O:                            # Optimize gate
+      latency_ms:
+        p50_max: 60
+        p95_max: 150
+        p99_max: 250
+      error_budget_respected: true
+    gate_S:                            # Shrink gate
+      at_least_one_dimension: true
+      api_surface_reduction_min: 0.20
+      dependency_hygiene_min: 0.95
+    gate_M:                            # Modularize gate
+      change_surface_max: 3
+      coupling_max: 0.20
+      cohesion_min: 0.80
+      contracts_pass: true
+
+  guardrails:
+    max_negative_delta:                # Maximum allowed regression per metric
+      semantic: 0.02
+      logic: 0.00                     # Zero tolerance for logic regression
+      performance: 0.03
+      simplicity: 0.03
+      modularity: 0.02
+      flow: 0.02
+
+  index:
+    weights:                           # Must sum to 1.0
+      semantic: 0.15
+      logic: 0.20
+      performance: 0.25
+      simplicity: 0.15
+      modularity: 0.15
+      flow: 0.10
+
+  evidence:
+    min_decision_confidence: 0.80
+    freshness_sla_hours:
+      tier_a: 24                      # Production evidence freshness
+      tier_b: 168                     # Staging evidence freshness
+
+  automation:
+    allow_agents: true
+    human_approval_required_for:
+      - waivers
+      - public_contract_changes
+      - threshold_relaxation
+      - destructive_data_changes
+```
+
+---
+
+## Cycle Commands
+
+### List Cycles
+
+```bash
+iosm cycle list
+```
+
+Shows all known cycles with their status, scope, and last decision.
+
+### Plan a New Cycle
+
+```bash
+iosm cycle plan [--id <cycle-id>] [--force] <goal...>
+```
+
+**Examples:**
+
+```bash
+# Plan with auto-generated ID
+iosm cycle plan "reduce checkout latency" "simplify auth flow"
+
+# Plan with a specific cycle ID
+iosm cycle plan --id cycle-2026-q1 "modernize API contracts"
+
+# Force re-plan an existing cycle
+iosm cycle plan --force "optimize database queries"
+```
+
+Planning creates:
+- Cycle scope declaration
+- Hypothesis cards with expected metric impacts
+- Baseline report
+- Empty phase report scaffolds
+
+### View Cycle Report
+
+```bash
+iosm cycle report [cycle-id]
+```
+
+Outputs a full JSON cycle report including:
+- Goals and scope
+- All phase results
+- Metric values (before/after)
+- Quality gate pass/fail status
+- IOSM-Index and decision confidence
+- Guardrail violations (if any)
+
+### Check Cycle Status
+
+```bash
+iosm cycle status [cycle-id]
+```
+
+Human-readable summary showing:
+- Phase completion progress
+- Gate pass/fail indicators
+- Current metric values
+- Blocking issues or waivers
+
+---
+
+## Six Canonical Metrics
+
+Every cycle measures these normalized metrics (0.0–1.0):
+
+| Metric | What It Measures | Example Indicators |
+|--------|-----------------|-------------------|
+| `semantic` | Terminology and naming coherence | Glossary coverage, naming consistency, ambiguity ratio |
+| `logic` | Invariant correctness | Invariant pass rate, logical consistency |
+| `performance` | Latency, reliability, resilience | p50/p95/p99 latency, error budget, chaos pass rate |
+| `simplicity` | Cognitive load and interface size | Onboarding time, API surface area, dependency count |
+| `modularity` | Decoupling and contract discipline | Change surface, coupling, cohesion, contract compliance |
+| `flow` | Delivery throughput and safety | Lead time, deploy frequency, change failure rate |
+
+### IOSM-Index
+
+The aggregate health score is computed as a weighted sum:
+
+```
+IOSM-Index = Σ (weight[metric] × value[metric])
+```
+
+Default weights sum to 1.0 and can be customized in `iosm.yaml`.
+
+---
+
+## Cycle Lifecycle Example
+
+### Step-by-Step Walkthrough
+
+```bash
+# 1. Initialize the workspace
+iosm init
+# → Creates iosm.yaml, IOSM.md, and .iosm/ workspace
+
+# 2. Plan a cycle
+iosm cycle plan "reduce API response time by 30%"
+# → Creates baseline report, hypothesis cards, empty phase reports
+
+# 3. Enter IOSM mode
+iosm --profile iosm
+# → Agent has full IOSM context and artifact awareness
+
+# 4. Execute the cycle (within interactive mode)
+# The agent will work through:
+#   IMPROVE  → Focus on semantic clarity and correctness
+#   OPTIMIZE → Target performance improvements
+#   SHRINK   → Reduce complexity and surface area
+#   MODULARIZE → Improve boundaries and contracts
+
+# 5. Check progress
+iosm cycle status
+# → Shows which phases are complete and gate results
+
+# 6. View final report
+iosm cycle report
+# → Full metrics, hypotheses evaluation, IOSM-Index, decision
+```
+
+---
+
+## Hypothesis Cards
+
+Each goal requires a formal hypothesis card:
+
+```yaml
+hypothesis:
+  id: hyp-latency-001
+  goal_id: reduce-checkout-latency
+  owner: payments-team
+  statement: >
+    If cache miss paths are removed, p95 latency
+    will decrease without harming API clarity.
+  expected_positive_delta:
+    performance: 0.05
+  allowed_negative_delta:
+    semantic: 0.00
+    logic: 0.00
+    simplicity: 0.02
+    modularity: 0.01
+    flow: 0.01
+  expected_business_signal:
+    metric: checkout_conversion
+    direction: up
+  validation:
+    method: production_observation
+    window: 7d
+  rollback_trigger:
+    - contracts_break
+    - change_failure_rate_up_10_percent
+  confidence: 0.80
+```
+
+---
+
+## Post-Change Synchronization
+
+When working through a cycle, keep IOSM artifacts in sync:
+
+- **Update metrics** — Refresh cycle metrics and confidence fields after changes
+- **Track hypotheses** — Record whether expected deltas were achieved
+- **Phase reports** — Fill in phase reports with actual outcomes
+- **Decision log** — Document decisions in `.iosm/decision-log.md`
+- **Pattern library** — Record successful patterns in `.iosm/pattern-library.md`
+
+The `iosm` profile automatically guides the agent to maintain this synchronization.
+
+---
+
+## Operating Profiles
+
+| Profile | Use Case | Evidence Strictness |
+|---------|----------|-------------------|
+| `standard` | Most production systems | Normal |
+| `critical` | Safety/revenue-critical systems | Strict — shorter waivers, higher confidence |
+| `exploratory` | Prototyping and discovery | Relaxed — cannot claim stabilization |
+
+Set in `iosm.yaml` under `metadata.criticality_profile`.
+
+---
+
+## Further Reading
+
+- [IOSM Specification](../iosm-spec.md) — Full 1600-line methodology specification
+- [Configuration](./configuration.md) — Complete config reference
+- [Interactive Mode](./interactive-mode.md) — IOSM slash commands