iosm-cli 0.2.0 → 0.2.1

package/docs/cli-reference.md

@@ -126,7 +126,17 @@ These commands run inside interactive mode (`iosm`), not as top-level CLI subcom
 - `/singular <feature request>` — command-first feasibility analyzer:
   - baseline repository scan + standard agent pass
   - outputs exactly 3 implementation options with recommendation
-  - lets user choose option `1/2/3` before implementation
+  - lets user choose option `1/2/3`, then `Start with Swarm` or `Continue without Swarm`
+- `/swarm` — canonical gated execution runtime:
+  - `/swarm run <task> [--max-parallel N] [--budget-usd X]`
+  - `/swarm from-singular <run-id> --option <1|2|3> [--max-parallel N] [--budget-usd X]`
+  - `/swarm watch [run-id]`
+  - `/swarm retry <run-id> <task-id> [--reset-brief]`
+  - `/swarm resume <run-id>`
+  - limits: `--max-parallel` supports `1..20`; delegated intra-task fan-out supports up to `10`
+  - consistency model: `Scopes -> Touches -> Locks -> Gates -> Done`
+  - built-in scheduler guards: progress heuristic + conflict density guard
+  - high-risk spawn candidates are confirmation-gated
 
 Migration notes:
 - `/blast` removed in favor of `/singular`

package/docs/interactive-mode.md

@@ -56,6 +56,7 @@ iosm --continue
 | `/semantic` | Open semantic search manager (`setup/auto-index/status/index/rebuild/query`) | `/semantic` |
 | `/contract` | Interactive engineering contract editor (field-by-field, auto JSON build) | `/contract` |
 | `/singular` | Feature feasibility analyzer with implementation options and recommendation | `/singular add account dashboard` |
+| `/swarm` | Recommended multi-agent orchestration runtime for complex/risky tasks (`run`, `from-singular`, `watch`, `retry`, `resume`) | `/swarm run refactor auth module --max-parallel 3` |
 | `/memory` | Interactive memory manager (`add/edit/remove/scope/path`) | `/memory` |
 | `/settings` | View/modify settings | `/settings` |
 | `/hotkeys` | View keyboard shortcuts | `/hotkeys` |
@@ -76,7 +77,8 @@ iosm --continue
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| `/orchestrate` | Launch subagent orchestration | See below |
+| `/swarm` | Swarm-first multi-agent orchestration runtime for complex/risky work | `/swarm run refactor auth and token flow` |
+| `/orchestrate` | Manual legacy multi-agent orchestration (explicit agent splitting) | 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` |
@@ -106,7 +108,8 @@ Manager includes `Automatic indexing` toggle (default `on`) to control query-tim
 In `/semantic setup`, the headers step is optional: press `Enter` on empty input to skip.
 `/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.
 `/contract` edits contract fields interactively (`goal`, scope, constraints, quality gates, DoD, risks, etc.), then writes JSON automatically.
-`/singular <request>` runs a two-pass feasibility analysis (baseline scan + standard agent pass), builds concrete implementation options, and asks user to choose one.
+`/singular <request>` runs a two-pass feasibility analysis (baseline scan + standard agent pass), builds concrete implementation options, then prompts `Start with Swarm` / `Continue without Swarm` / `Cancel`.
+`/swarm` enforces `Scopes -> Touches -> Locks -> Gates -> Done`. If effective contract is missing, it blocks execution and opens a bootstrap menu (auto-draft, guided Q&A, or manual `/contract` editor).
 `/blast` and `/shadow` are removed from active interactive workflow.
 
 ### `/contract` Detailed Guide
@@ -219,7 +222,11 @@ After analysis, selector opens with variants:
 - choose Option 1 / Option 2 / Option 3
 - or close without decision
 
-If Option 1 or 2 is selected, execution draft is inserted into editor (ready to run).  
+If Option 1 or 2 is selected, execution mode prompt opens:
+- `Start with Swarm (Recommended)` -> runs `/swarm from-singular <run-id> --option <n>`
+- `Continue without Swarm` -> inserts execution draft into editor (ready to run)
+- `Cancel` -> exits without changes
+
 If Option 3 is selected, run is explicitly marked as postponed.
 
 #### Fallback Behavior
@@ -233,6 +240,38 @@ Use `/model` to enable full agent feasibility pass.
 - `/blast` is deprecated/removed.
 - `/shadow` is removed.
 
+### `/swarm` Detailed Guide
+
+Canonical commands:
+- `/swarm run <task> [--max-parallel N] [--budget-usd X]`
+- `/swarm from-singular <run-id> --option <1|2|3> [--max-parallel N] [--budget-usd X]`
+- `/swarm watch [run-id]`
+- `/swarm retry <run-id> <task-id> [--reset-brief]`
+- `/swarm resume <run-id>`
+
+Execution note:
+- Run-level `--max-parallel` supports `1..20`.
+- A single swarm task can use delegated intra-task subagents in parallel (up to 10) when decomposition is beneficial.
+- Shared memory tools (`shared_memory_write` / `shared_memory_read`) are available to tasks/delegates that share a `run_id`.
+- Standalone `task` calls auto-generate internal `run_id/task_id`, so shared-memory collaboration still works for root + delegates.
+
+Runtime artifacts:
+- `.iosm/orchestrate/<run-id>/run.json`
+- `.iosm/orchestrate/<run-id>/dag.json`
+- `.iosm/orchestrate/<run-id>/state.json`
+- `.iosm/orchestrate/<run-id>/events.jsonl`
+- `.iosm/orchestrate/<run-id>/checkpoints/latest.json`
+- `.iosm/orchestrate/<run-id>/reports/*`
+
+`/swarm watch` includes:
+- current state and task breakdown
+- budget and warning state
+- ETA ticks and throughput
+- critical path and theoretical speedup
+- lock snapshot and bottleneck tasks
+
+`/orchestrate --swarm` was removed. Use `/swarm ...` directly.
+
 ---
 
 ## Keyboard Shortcuts

package/docs/orchestration-and-subagents.md

@@ -1,184 +1,152 @@
 # Orchestration & Subagents
 
-`iosm-cli` supports delegated execution through subagents — specialized AI agents that handle task delegation, parallel execution, and multi-agent workflows.
+`iosm-cli` now uses a **swarm-first** execution model for complex/risky changes.
 
-## Overview
+Canonical path:
+- `/singular` -> choose option
+- effective `/contract` applied (or bootstrap required)
+- `/swarm` execution runtime
+- optional `/iosm` optimization loop
 
-Subagents allow you to:
-- **Delegate tasks** to specialized agents with isolated context windows
-- **Run agents in parallel** for independent analyses or implementations
-- **Orchestrate teams** with dependency ordering and lock-based coordination
-- **Track runs** with full transcripts and result aggregation
+Core consistency model:
+- **Scopes -> Touches -> Locks -> Gates -> Done**
 
 ---
 
 ## User-Level Entry Points
 
-### 1. Natural Language Delegation
+### 1. Decision-first flow (recommended)
 
-Simply describe what you want delegated, and the agent handles orchestration:
-
-```
-You: Launch 3 agents to analyze security, performance, and code quality separately
-
-Agent: I'll create 3 parallel subagents for each analysis area...
+```bash
+/singular "Refactor auth and split session handling from token validation"
+# choose Option 1/2/3
+# choose Start with Swarm (Recommended)
 ```
 
-### 2. Slash Command Orchestration
-
-Use `/orchestrate` for explicit control:
+### 2. Direct swarm execution
 
 ```bash
-/orchestrate --parallel --agents 3 \
-  --profiles explore,full,iosm_verifier \
-  --cwd .,src,.iosm \
-  Analyze security, optimize performance, verify IOSM compliance
+/swarm run "Refactor auth and reduce integration risk" --max-parallel 3 --budget-usd 12
 ```
 
-### 3. Agent Mention
+### 3. Agent mention / delegated tasks
 
-Reference a specific agent by name:
-
-```
+```text
 @security-auditor Review the authentication module for vulnerabilities
 ```
 
 ---
 
-## `/orchestrate` Command
+## `/swarm` Command Surface
 
 ### Syntax
 
 ```bash
-/orchestrate [flags] <task description>
-```
-
-### Execution Flags
+/swarm run <task> [--max-parallel N] [--budget-usd X]
+/swarm from-singular <run-id> --option <1|2|3> [--max-parallel N] [--budget-usd X]
+/swarm watch [run-id]
+/swarm retry <run-id> <task-id> [--reset-brief]
+/swarm resume <run-id>
+/swarm help
+```
+
+### Notes
+
+- `/swarm` will not execute without an effective `/contract`.
+- Run-level `--max-parallel` supports `1..20`.
+- Within a single swarm task, the execution agent can fan out delegated subagents in parallel (up to 10) when the subtask is decomposable.
+- Tasks/delegates with the same `run_id` can exchange intermediate state via `shared_memory_write` / `shared_memory_read`.
+- Standalone `task` calls without explicit `run_id` use an internal run/task id, so shared memory still works inside that task execution (root + delegates).
+- If contract is missing, bootstrap menu is blocking:
+  - `Auto-draft from task (Recommended)`
+  - `Guided Q&A`
+  - `Open manual /contract editor`
+- Medium/large repositories use Project Index planning by default.
+- Semantic index is optional enrichment; when stale/missing, swarm continues with guided recommendations.
+- Scheduler guards are enabled by default:
+  - `progress heuristic` (prioritizes high-impact tasks when progress stalls)
+  - `conflict density guard` (reduces parallelism under heavy touch overlap)
+- High-risk spawn candidates require confirmation (approve/reject/abort run).
 
-| Flag | Description | Example |
-|------|-------------|---------|
-| `--parallel` | Run agents concurrently | `--parallel` |
-| `--sequential` | Run agents one after another | `--sequential` |
-| `--agents <N>` | Number of agents to spawn | `--agents 3` |
-| `--max-parallel <N>` | Concurrency limit for parallel runs | `--max-parallel 2` |
-
-### Profile & Context Flags
-
-| Flag | Description | Example |
-|------|-------------|---------|
-| `--profile <name>` | Single profile for all agents | `--profile explore` |
-| `--profiles p1,p2,...` | Per-agent profile assignment | `--profiles explore,full,iosm_verifier` |
-| `--cwd path1,path2,...` | Per-agent working directories | `--cwd .,src,test` |
+---
 
-### Coordination Flags
+## Command Separation
 
-| Flag | Description | Example |
-|------|-------------|---------|
-| `--locks lock1,lock2,...` | Write serialization domains | `--locks db,config` |
-| `--depends 2>1,3>2` | Dependency ordering | `--depends 2>1` (agent 2 waits for 1) |
-| `--worktree` | Git worktree isolation | `--worktree` |
+- Use direct prompt to the main agent for simple tasks.
+- Use legacy `/orchestrate ...` when you explicitly want manual multi-agent splitting with old team-run semantics.
+- Use canonical `/swarm ...` as multi-agent orchestration runtime for complex/risky work.
+- `/orchestrate --swarm` was removed to avoid command ambiguity.
 
 ---
 
-## Usage Examples
-
-### Parallel Independent Analysis
+## Runtime Artifacts
 
-Three agents analyze different aspects simultaneously:
+Swarm run artifacts are written to:
 
-```bash
-/orchestrate --parallel --agents 3 \
-  --profiles explore,explore,explore \
-  --cwd src/auth,src/api,src/data \
-  Analyze code quality and suggest improvements
+```text
+.iosm/orchestrate/<run-id>/
+├── run.json
+├── dag.json
+├── state.json
+├── events.jsonl
+├── checkpoints/
+│   └── latest.json
+└── reports/
+    ├── integration_report.md
+    ├── gates.json
+    └── shared_context.md
 ```
 
-### Sequential Pipeline
+Swarm run history is native to `/swarm` commands (`watch`, `retry`, `resume`), not mirrored into legacy team-run storage.
 
-Agent 2 depends on Agent 1's output:
-
-```bash
-/orchestrate --sequential --agents 2 \
-  --depends 2>1 \
-  First: analyze the codebase architecture. \
-  Second: propose a refactoring plan based on the analysis.
-```
+---
 
-### Parallel with Write Isolation
+## Visibility & Recovery
 
-For concurrent changes that might conflict:
+### Watch
 
 ```bash
-/orchestrate --parallel --worktree --agents 2 \
-  Agent 1: refactor auth module \
-  Agent 2: refactor payment module
+/swarm watch [run-id]
 ```
 
-### Locked Write Coordination
-
-Serialize writes to shared resources:
-
-```bash
-/orchestrate --parallel --agents 3 \
-  --locks database-schema \
-  All agents: optimize your assigned module's database queries
-```
+Shows live snapshot fields:
+- run status
+- ready/running/blocked/done/error counts
+- budget usage and 80% warning state
+- locks and current touches map
+- ETA ticks, throughput per tick, critical path estimate, theoretical speedup, and top bottleneck tasks
 
-### Full Team Orchestration
+### Retry
 
 ```bash
-/orchestrate --parallel --agents 4 \
-  --profiles iosm_analyst,explore,iosm_verifier,full \
-  --max-parallel 2 \
-  1: Collect baseline metrics \
-  2: Identify optimization opportunities \
-  3: Verify current quality gate compliance \
-  4: Implement the top-priority fix
+/swarm retry <run-id> <task-id> [--reset-brief]
 ```
 
----
-
-## Visibility & Tracking
+- retries one failed/blocked task under retry taxonomy
+- optional `--reset-brief` lets you edit task brief before retry
 
-### View Subagent Runs
+### Resume
 
 ```bash
-/subagent-runs
+/swarm resume <run-id>
 ```
 
-Lists all subagent runs with:
-- Run ID, status (running/complete/failed)
-- Agent profile and task description
-- Timestamps and duration
-
-### Resume a Subagent Run
-
-```bash
-/subagent-resume <run-id> [extra instructions]
-```
+Resumes from checkpoint + snapshot state.
 
-Continue or refine a previous subagent's work:
+---
 
-```bash
-/subagent-resume run-abc123 "Focus more on error handling"
-```
+## Legacy `/orchestrate` (non-swarm)
 
-### Team Run Status
+Legacy orchestration remains available for existing workflows:
 
 ```bash
-/team-runs                     # List team orchestration runs
-/team-status <team-run-id>     # Detailed status of a specific team run
+/orchestrate --parallel --agents 3 \
+  --profiles explore,full,iosm_verifier \
+  --cwd .,src,.iosm \
+  Analyze security, optimize performance, verify IOSM compliance
 ```
 
-### Artifacts
-
-Subagent transcripts and team records are stored in:
-
-```
-.iosm/subagents/
-├── runs/     # Individual subagent transcripts
-└── teams/    # Team orchestration records
-```
+Use legacy mode when you explicitly need old team-run semantics.
 
 ---
 
@@ -217,57 +185,16 @@ Always provide:
 
 # View all available agents
 /agents
-
-# Use in orchestration
-/orchestrate --agents 1 --profile security-auditor \
-  Audit the authentication module
 ```
 
-### System Agents
-
-Built-in system agents available by default include auditor, verifier, and executor roles. View them with `/agents`.
-
----
-
-## Parallel Safety Model
-
-### When to Use Locks
-
-Use `lock_key` domains when multiple agents might write to the same files:
-
-```bash
-/orchestrate --parallel --agents 2 \
-  --locks "config-files" \
-  Both modify shared configuration
-```
-
-### When to Use Worktrees
-
-Use `--worktree` for large-scale concurrent edits:
-
-```bash
-/orchestrate --parallel --worktree --agents 3 \
-  Each refactor a major module independently
-```
-
-### When No Coordination Is Needed
-
-Keep independent analyses lock-free:
-
-```bash
-/orchestrate --parallel --agents 3 \
-  --profiles explore,explore,explore \
-  Each analyze a different module (read-only)
-```
+Built-in system agents remain available; inspect via `/agents`.
 
 ---
 
-## Best Practices
+## Safety Guidance
 
-1. **Keep tasks independent** — Each agent works best with a well-defined, independent scope
-2. **Narrow responsibilities** — One agent, one clear task
-3. **Use appropriate profiles** — Read-only tasks don't need `full` profile
-4. **Aggregate results** — The orchestrating agent synthesizes all subagent outputs
-5. **Clarify constraints** — Specify boundaries and expected output format
-6. **Monitor progress** — Use `/subagent-runs` and `/team-status` to track execution
-7. **Start small** — Begin with 2-3 agents and scale up as needed
+- Use `/contract` to lock execution scope before running swarm.
+- Prefer `/singular` when scope/impact is unclear.
+- Use `/swarm watch` frequently on medium/high-risk runs.
+- Use `/checkpoint`/`/rollback` before broad refactors.
+- Follow up with `/iosm` for measurable post-change quality improvements.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "iosm-cli",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Standalone IOSM CLI with agent tooling, session management, and IOSM artifact orchestration",
 	"type": "module",
 	"iosmConfig": {
@@ -53,7 +53,7 @@
 		"cli-highlight": "^2.1.11",
 		"diff": "^8.0.2",
 		"extract-zip": "^2.0.1",
-		"file-type": "^21.1.1",
+		"file-type": "^21.3.1",
 		"glob": "^13.0.1",
 		"hosted-git-info": "^9.0.2",
 		"ignore": "^7.0.5",
@@ -68,7 +68,8 @@
 		"rimraf": "6.1.2",
 		"gaxios": {
 			"rimraf": "6.1.2"
-		}
+		},
+		"hono": "4.12.7"
 	},
 	"optionalDependencies": {
 		"@mariozechner/clipboard": "^0.3.2"