iosm-cli 0.1.3 → 0.2.1

package/docs/cli-reference.md

@@ -112,7 +112,35 @@ iosm semantic query "<text>" [--top-k N]
 
 Notes:
 - If semantic config is missing, the command prints actionable paths and suggests `/semantic setup`.
-- `query` auto-refreshes stale indexes incrementally; provider/chunk/filter changes require `rebuild`.
+- `query` auto-refreshes stale indexes only when `semanticSearch.autoIndex=true` (default is `true`).
+- When auto-index is off, run `iosm semantic index` (or `rebuild` for provider/chunk/filter changes).
+
+### Interactive feasibility/contract commands
+
+These commands run inside interactive mode (`iosm`), not as top-level CLI subcommands:
+
+- `/contract` — interactive engineering contract manager:
+  - edit fields one-by-one
+  - autosave on `Enter`
+  - auto-build `.iosm/contract.json` for project scope
+- `/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`, 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`
+- `/shadow` removed
 
 ---
 

package/docs/configuration.md

@@ -135,6 +135,7 @@ Schema (`semanticSearch` object):
 {
   "semanticSearch": {
     "enabled": true,
+    "autoIndex": true,
     "provider": {
       "type": "openrouter",
       "model": "openai/text-embedding-3-small",
@@ -166,6 +167,10 @@ Schema (`semanticSearch` object):
 }
 ```
 
+`autoIndex` controls query-time automatic refresh:
+- `true` (default): `query` automatically refreshes stale index (and rebuilds when required)
+- `false`: stale/missing index must be updated manually via `iosm semantic index` / `rebuild`
+
 Index storage (global cache):
 
 ```

package/docs/interactive-mode.md

@@ -53,7 +53,10 @@ iosm --continue
 | `/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` |
-| `/semantic` | Open semantic search manager (`setup/status/index/rebuild/query`) | `/semantic` |
+| `/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` |
@@ -74,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` |
@@ -99,9 +103,174 @@ iosm --continue
 
 `/mcp add` without flags starts a guided wizard in the terminal UI.
 `/semantic` opens an interactive setup/status/index/query manager for embeddings search.
+Manager includes `Automatic indexing` toggle (default `on`) to control query-time auto-refresh.
 `/semantic setup` now auto-loads model catalogs for OpenRouter (`/api/v1/embeddings/models`) and Ollama (`/api/tags`) with manual fallback.
 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, 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
+
+`/contract` is a layered contract editor with two sources and one merged output:
+
+| Layer | Scope | Persistence | Storage |
+|------|-------|-------------|---------|
+| `project` | Project-wide baseline | Persistent | `.iosm/contract.json` |
+| `session` | Current session override | Temporary | In-memory session overlay |
+| `effective` | `project + session` merged result | Derived | Computed at runtime |
+
+Important merge rule:
+- `session` overrides `project` for the same keys.
+- `effective` is what the runtime actually uses.
+
+#### Quick Difference: Effective vs Session vs Project
+
+- `Open effective contract` is read-only and shows what runtime is enforcing right now.
+- `Edit session contract` changes only this session (temporary overlay, not persisted to disk).
+- `Edit project contract` changes `.iosm/contract.json` (persistent baseline for future sessions).
+
+#### Manager Actions
+
+| Action | What it does | When to use |
+|------|---------------|-------------|
+| `Open effective contract` | Shows the merged JSON currently enforced by runtime | Verify final active constraints |
+| `Edit session contract` | Edits temporary overrides for current session | Experiments, one-off constraints |
+| `Edit project contract` | Edits persistent project contract file | Team-wide stable defaults |
+| `Copy effective -> session` | Saves merged state into session layer | Freeze current merged state for this run |
+| `Copy effective -> project` | Saves merged state into project file | Promote temporary decisions to baseline |
+| `Delete session contract` | Clears temporary overlay | Reset session overrides |
+| `Delete project contract` | Removes `.iosm/contract.json` | Full baseline reset |
+
+#### Field Editor Behavior
+
+- Select a field and press `Enter`.
+- Input text (single-line or multi-line list depending on field type).
+- Press `Enter` to submit.
+- Change is saved immediately to selected scope (`session` or `project`).
+- Empty input clears that field.
+
+There is no separate "Save" step in field editor mode.
+
+#### Common Workflows
+
+1. Temporary tightening for one run:
+   - Open `/contract`
+   - `Edit session contract`
+   - Set `constraints` and `quality_gates`
+   - Confirm via `Open effective contract`
+
+2. Promote temporary policy to project baseline:
+   - Open `/contract`
+   - `Copy effective -> project`
+   - Review `.iosm/contract.json` in VCS
+
+3. Recover from aggressive temporary overrides:
+   - Open `/contract`
+   - `Delete session contract`
+   - Re-open `effective` and verify fallback to `project`
+
+### `/singular` Detailed Guide
+
+`/singular` is a command-first feasibility mode (no pre-menu).  
+Pattern: `/singular <feature request>`
+
+Examples:
+- `/singular add account dashboard`
+- `/singular introduce RBAC for API`
+- `/singular redesign billing reconciliation flow`
+
+#### What Happens Internally
+
+1. Baseline repository pass:
+   - Scans project files and estimates baseline complexity/blast radius.
+   - Collects likely impacted files and contract signals.
+
+2. Standard agent feasibility pass:
+   - Launches an isolated standard agent run (`plan` profile) with repository tools.
+   - Agent inspects real files and returns structured feasibility JSON.
+   - Produces recommendation, impact analysis, and implementation variants.
+
+3. Merge + persistence:
+   - Agent insights are merged with baseline data.
+   - Analysis is saved to `.iosm/singular/<run-id>/analysis.json` (+ `meta.json`).
+
+#### Output Shape
+
+Each run includes:
+- `recommendation`: `implement_now | implement_incrementally | defer`
+- `reason`: why this recommendation is best for current stage
+- `complexity` and `blast_radius`
+- `stage_fit`: `needed_now | optional_now | later`
+- `impact_analysis`: codebase, delivery, risks, operations
+- `implementation_options` (exactly 3 variants):
+  - Option 1: practical/recommended path
+  - Option 2: alternative approach
+  - Option 3: defer / do not implement now
+
+Each option includes:
+- summary and trade-offs (`pros`/`cons`)
+- concrete file targets (`suggested_files`)
+- step-by-step plan (`plan`)
+- `when_to_choose` guidance
+
+#### Decision Flow
+
+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 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
+
+If no model is selected (or agent pass fails), `/singular` still returns a heuristic baseline analysis.  
+Use `/model` to enable full agent feasibility pass.
+
+#### Command Migration
+
+- `/singular` is the feasibility command to use.
+- `/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.
 
 ---
 

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.1.3",
+	"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"