simplicio-loop 3.43.10__tar.gz → 3.43.12__tar.gz

{simplicio_loop-3.43.10/simplicio_loop.egg-info → simplicio_loop-3.43.12}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: simplicio-loop
-Version: 3.43.10
-Summary: The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (7 skills) that drains any queue of work end-to-end on any LLM/runtime.
+Version: 3.43.12
+Summary: Standalone orchestrator for mapper, fast, and simplicio-dev-cli. No Runtime.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/wesleysimplicio/simplicio-loop
@@ -22,9 +22,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: simplicio-cli<0.19,>=0.18.12
-Requires-Dist: simplicio-mapper<0.27,>=0.26.29
-Requires-Dist: simplicio-fast<3,>=2.0.31
-Requires-Dist: simplicio-prompt<1.15,>=1.14.4
+Requires-Dist: simplicio-mapper<0.27,>=0.26.31
+Requires-Dist: simplicio-fast<3,>=2.0.32
 Requires-Dist: tiktoken<1,>=0.12.0
 Provides-Extra: dev
 Requires-Dist: setuptools>=77; extra == "dev"

{simplicio_loop-3.43.10 → simplicio_loop-3.43.12}/README.md

@@ -812,6 +812,173 @@ exit 0) when `gh`/network is unavailable, so an offline dev environment never lo
 `update.sh` stashes local edits, fast-forwards `main`, reinstalls from the fresh source, restarts the
 launchd/systemd services so they run the new code, and prints the live stack + savings.
 
+## 🧭 CLI command map — what each command does
+
+### Required Mapper context and automatic machine capacity
+
+Every Loop execution workflow requires **Simplicio Mapper**, including standalone,
+sequential, Prism/wave and Fast-assisted execution. Prepare context centrally and
+bind workers to its current generation and digest. Fast is an optional accelerator;
+Runtime remains optional for ordinary orchestration. Missing or stale Mapper
+context blocks work until central preparation succeeds.
+
+The intended worker default is automatic physical admission from available machine
+capacity, preserving foreground responsiveness. The source changes remove fixed
+defaults in batch/tasks/fan-out entrypoints; validation is still in progress and
+these edits are not part of the installed 3.43.10 release yet.
+
+Mapper context reuse does not itself prove a provider cache hit. Report token and
+cost savings only from attributable provider usage and passing quality gates.
+The fastest/cheapest production route is **not yet established**. See the
+[ten-task benchmark protocol, command sequence and evidence status](docs/QUEUE_BENCHMARK_PROTOCOL.md)
+before using historical synthetic scheduler measurements as a recommendation.
+
+The main `simplicio-loop` entry point is the user-facing control surface for planning, executing, verifying, and delivering work. Use the most specific `--help` for the exact options available in the installed version.
+
+**Standalone by design.** Runtime is optional: without it, Loop uses its own scheduler/hooks plus the Mapper, Fast, and Dev CLI operators. When Runtime is available, it adds governed activation, physical admission, gates, receipts, and reconciliation; it does not replace the Loop.
+
+### Zero-config execution
+
+The standard entry point uses the governed `wave` flow (with automatic reconciliation barriers):
+
+```bash
+# Preparar / Armar run a partir de especificação markdown:
+simplicio-loop prepare --task task.md --repo .
+
+# Executar via fluxo wave padrão (recomendado):
+simplicio-loop wave <run_id>
+
+# Ou para tarefa única ultrarrápida (local-first, sem latência externa):
+simplicio-loop single-task-fast --task-file task.json
+```
+
+> **Aviso de Descontinuação do `run`**: O comando `simplicio-loop run` foi descontinuado e excluído da interface pública. Caso seja invocado (`simplicio-loop run --task task.md` ou `simplicio-loop run <run_id>`), o comando é automaticamente interceptado e redirecionado para o fluxo padrão `simplicio-loop wave`, garantindo execução com barreira de integridade e a máxima velocidade.
+
+> **Operadores Obrigatórios**: O ecossistema agora opera com `simplicio-mapper` e `simplicio-fast` estritamente obrigatórios. O `simplicio-fast` acelera a indexação e o planejamento sintático, enquanto o `simplicio-mapper` garante a integridade estrutural do repositório e o prefix caching determinístico da LLM.
+
+| Area | Commands | What they do |
+|---|---|---|
+| Install and utilities | `install`, `dashboard`, `learn` | Install the bundled skills/hooks; open or stop the token-monitor dashboard; derive and persist a retrospective from completed runs. |
+| Intake and planning | `task`, `prototype`, `plan`, `orient` | Validate/preview task contracts; route prototype planning; compile Markdown into a frozen contract; build bounded Mapper/Fast context and an orientation receipt. |
+| Execution | `wave`, `prism`, `single-task-fast`, `batch`, `tick` | Dispatch ready tasks through governed wave barriers (`wave`, default flow); execute through isolated worktrees (`prism`); execute bounded tasks locally (`single-task-fast`); continuous background dispatch (`batch`); step-by-step single-task execution (`tick`). *(Nota: `run` foi descontinuado e redireciona para `wave`)*. |
+| Run lifecycle | `status`, `progress`, `resume`, `cancel`, `verify`, `oracle`, `checkpoint` | Inspect a run; render progress as text/JSON/Markdown/ANSI; resume or cancel non-terminal work; run independent watcher/delivery gates; evaluate completion/parity; manage Fast V3 checkpoints. |
+| Repository and operators | `preflight`, `map`, `inspect`, `doctor`, `stack`, `extensions`, `retrieve` | Check Mapper/Dev CLI/Runtime/Fast readiness; inspect map-service receipts; inspect MapperStore capabilities; diagnose stack/source/resource/storage; lock or verify installed components; verify extension handshakes; retrieve tee-cache results. |
+| Queues and coordination | `queue`, `drain`, `agent-slots`, `generation-broker`, `ledger`, `hub-drain-plan`, `hub-drain-admit` | Operate the durable queue; evaluate or persist queue-drain receipts; inspect/reclaim Loop capacity; reconcile generation bindings; replay/validate the operational ledger; plan or admit GitHub drain work. |
+| Delivery and source control | `deliver`, `decide`, `sync-source`, `findings`, `maintenance-deferred`, `defer-maintenance` | Reconcile delivery with source evidence; apply a human decision and invalidate dependent artifacts; requery external source state; list/report/reconcile/diagnose/import findings; record deferred maintenance. `defer-maintenance` is the alias form. |
+| Economy, safety, and deployment | `economy`, `ecc`, `deploy`, `release-train` | Inspect/print/apply the economy-parallel environment; verify ECC provenance and safety policy; plan a gated deployment (`--apply` is explicit); validate release manifests and ecosystem drift. |
+
+### Guia de Decisão para a LLM / Agentes: Qual fluxo escolher?
+
+Para garantir os melhores resultados de velocidade, economia e confiabilidade:
+
+| Cenário / Demanda | Fluxo Recomendado | Comando | Por que escolher? |
+|---|---|---|---|
+| **1 Tarefa Simples / Local** | `single-task-fast` | `simplicio-loop single-task-fast --task-file task.json` | **Mais Rápido e Barato**: Execução local-first imediata via Fast + Dev CLI. 0 chamadas de rede, custo zero de tokens. |
+| **Multi-tarefas Padrão (2 a 30+ tarefas)** | `wave` *(Padrão)* | `simplicio-loop wave <run_id>` | **Máxima Velocidade e Confiabilidade**: Despacha ondas concorrentes com barreiras de reconciliação de estado entre cada onda. Evita race conditions em arquivos compartilhados e aproveita 96%+ de cache hit. |
+| **Alta Concorrência em Árvores Isoladas** | `prism` | `simplicio-loop prism <run_id> --batch-size 10` | **Isolamento Total**: Worktrees Git isoladas para tarefas independentes que alteram partes distintas do código sem colisão. |
+| **Fila Contínua de Tarefas** | `batch` | `simplicio-loop batch <run_id>` | **Processamento em Massa**: Mantém workers ocupados continuamente processando tarefas prontas da fila até o esgotamento. |
+| **Depuração Passo a Passo / Inspeção** | `tick` | `simplicio-loop tick <run_id> --task-index N` | **Controle Fino**: Executa exatamente uma tarefa por vez com controle cirúrgico de inspeção e validação pré/pós. |
+
+### Dinâmica de Prompt Caching da LLM: Por que o cache aumenta em lotes maiores (10 vs 20 vs 30 tarefas)?
+
+Em tarefas orquestradas pelo `simplicio-loop` com `simplicio-mapper` obrigatório, o prefixo de contexto (árvore do projeto, AST, regras e instruções do sistema) é fixo e canônico. Os provedores de LLM (como DeepSeek v4.1 Flash via OpenRouter ou Claude/Anthropic) aplicam **KV Cache Prefix Matching**:
+
+1. **Amortização do Cold-Start**:
+   - **Na 1ª tarefa (Cold-Start)**: O prefixo é enviado e processado pela primeira vez. A LLM grava o KV-cache (`cache_creation` ou cache miss).
+   - **Da 2ª à 30ª tarefa (Cache Hit)**: O prefixo idêntico é encontrado no cache do provedor (dentro da janela de TTL de 5 a 10 minutos). Apenas o delta da tarefa é processado como novos tokens de entrada.
+2. **Evolução do Hit Rate Conforme o Volume de Tarefas**:
+   - **10 tarefas**: 1 cold-start + 9 cache hits = **90.0% de reaproveitamento de cache**.
+   - **20 tarefas**: 1 cold-start + 19 cache hits = **95.0% de reaproveitamento de cache**.
+   - **30 tarefas**: 1 cold-start + 29 cache hits = **96.7% de reaproveitamento de cache**.
+3. **Impacto no Custo e na Latência**:
+   - O custo de tokens de entrada em cache hit cai em até **90%** (de \$0.14/M para \$0.014/M de tokens no DeepSeek v4.1 Flash).
+   - A latência por tarefa (Time to First Token - TTFT) despenca drasticamente, pois a LLM não recalcula os embeddings nem a atenção de todo o repositório a cada iteração.
+   - Portanto, a percepção de que *"o cache vai aumentando a cada rodada de 30 tarefas"* é matematicamente real e um benefício direto da arquitetura do `simplicio-mapper` + `simplicio-fast`.
+
+### Candidate governed flow for 10 tasks — not yet a measured winner
+
+Ten tasks are above the three-task direct-parallel threshold, so the Loop routes them through a Prism wave: isolated worktrees, leases, a wave barrier, and serialized writes. This wave works in standalone mode; when Runtime is available, Runtime governs activation and physical admission while Prism coordinates the wave.
+
+```bash
+# 1. If using Runtime, ask its activation authority (optional integration)
+simplicio loop decide --task "complete these 10 tasks" --repo . --json
+
+# 2. Inspect the profile before applying environment changes
+# 3.43.11 recommends MCP-required flags; do not apply it blindly in CLI-only mode.
+simplicio-loop economy status --json
+
+# 3. Block until the required operators and strict mutation policy are ready
+simplicio-loop preflight --strict --json
+
+# 4. Survey and enrich context through the bound operators
+simplicio-mapper scan . --sync --json
+simplicio-mapper inspect . --json
+simplicio-mapper handoff . --task-file task.md --execution-context --json
+simplicio-fast understand --repo .
+
+# 5. Arm the drain scratchpad; this does NOT start workers
+# The CLI resolves slots=0 via its machine-capacity recommendation.
+python3 scripts/arm_drain_prism.py --repo . --slots 0 --batch-size 10 --json
+
+# 6. Each task follows claim → implement → focused gate → evidence → PR/merge
+#    The next wave starts only after reconcile-before-next.
+```
+
+Do not interpret ten logical tasks as ten unrestricted processes: physical CPU/RAM/backpressure limits are still enforced, and writes are serialized by path. For only one to three tasks, use direct parallelism instead of Prism.
+
+### Where Prism fits
+
+The public `simplicio-loop prism` and `simplicio-loop wave` commands dispatch through the same governed batch implementation, with typed receipts and a reconcile-before-next barrier. The `simplicio-prism` skill/layer classifies the work and composes Mapper, Fast, Loop, Dev CLI, and Runtime. The concrete drain-wave operator is `scripts/arm_drain_prism.py`; Runtime's `simplicio loop decide` remains the authority for Loop activation.
+
+A wave ends with lease/result reconciliation before the next group is admitted.
+Arming is preparation, not execution. In standalone operation Runtime/MCP is
+optional; Mapper remains mandatory. See the [Prism/wave interface details](docs/CLI_COMMANDS.md#prism-and-wave).
+
+**Measured benchmark status (2026-09-11):** ten simulated tasks pass the independent
+verifier after real OpenRouter proposals and native edits. This is a diagnostic
+composed route, not a completed serial/Prism/Fast comparison. No fastest or
+cheapest standard is proven. The [detailed report](docs/QUEUE_BENCHMARK_PROTOCOL.md)
+records failures, retries, commands, receipts and the remaining qualification gates.
+Open the [charts and measured command tables](.lavish/queue-benchmark-20260911/report.html)
+or the [raw metrics and receipt hashes](.lavish/queue-benchmark-20260911/summary.json).
+
+The [release qualification results](docs/BENCHMARK_RELEASE_QUALIFICATION.md)
+separately record the restarted native CLI probes, exact commands, CPU/RAM,
+and blockers. Failed admission, dry-run, and time-to-failure never qualify as
+completed tasks or a performance winner.
+
+Important nested command surfaces:
+
+- `queue`: `status`, `top`, `drain`, `resume`, `doctor`, `reclaim`, `migrate`, `gc`, `inspect`, `cancel`.
+- `findings`: `list`, `report`, `reconcile`, `doctor`, `import`.
+- `economy`: `status`, `print`, `apply`.
+- `stack`: `lock`, `verify`; `extensions` and `ecc` each expose `doctor`.
+- `release-train`: `check` validates component/ecosystem release schemas and local drift.
+
+Typical single-task commands:
+
+```bash
+simplicio-loop preflight --repo . --json
+simplicio-loop orient --task "understand this repository" --repo .
+simplicio-loop plan --task task.md --out contract.json
+simplicio-loop prepare --task task.md --repo . --max-iterations 5
+simplicio-loop wave <run_id>
+simplicio-loop status --repo . --text
+simplicio-loop progress --repo . --format markdown --once
+simplicio-loop queue status
+simplicio-loop verify <run_id>
+```
+
+The complete command reference is [`docs/CLI_COMMANDS.md`](docs/CLI_COMMANDS.md). The command surface can vary by installed package version, so check `simplicio-loop --version` and `simplicio-loop --help`; the current repository source is `3.43.11`.
+
+The restarted comparison includes `wave`, `batch`, `batch --serial`, `tasks run`,
+Prism, wave-policy variations and a limited semaphore control. See the
+[flow matrix and mandatory Mapper/cache contract](docs/BENCHMARK_FLOW_MATRIX.md).
+The limited control is not a public legacy command; `tasks run` currently has
+a PR/merge delivery boundary and cannot be ranked against local edits alone.
+
+---
+
 ### Doctor — verify + repair
 
 ```bash

{simplicio_loop-3.43.10 → simplicio_loop-3.43.12}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.43.10"
-description = "The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (7 skills) that drains any queue of work end-to-end on any LLM/runtime."
+version = "3.43.12"
+description = "Standalone orchestrator for mapper, fast, and simplicio-dev-cli. No Runtime."
 readme = "PYPI.md"
 requires-python = ">=3.11"
 license = "MIT"
@@ -23,18 +23,14 @@ classifiers = [
   "Topic :: Utilities",
   "Operating System :: OS Independent",
 ]
-# The loop ships with its two bound operators and the Prompt contract runtime as
-# direct dependencies. `simplicio-cli` is the distribution that exports the
-# `simplicio-dev-cli` entrypoint. Do not rely on transitive installs: partial /
-# no-deps installations must be diagnosed explicitly and normal
-# `pip install simplicio-loop` must request the complete route -> enrichment
-# closure.
+# Loop is the aggregate of mapper + fast + simplicio-dev-cli. `simplicio-cli`
+# exports the `simplicio-dev-cli` entrypoint. There is no Runtime and no
+# simplicio-prompt on this train. Train target for simplicio-cli is 0.18.13;
+# the floor stays 0.18.12 while that is the locally installed wheel.
 dependencies = [
-  # Loop is the aggregate distribution. Keep one tested component train.
   "simplicio-cli>=0.18.12,<0.19",
-  "simplicio-mapper>=0.26.29,<0.27",
-  "simplicio-fast>=2.0.31,<3",
-  "simplicio-prompt>=1.14.4,<1.15",
+  "simplicio-mapper>=0.26.31,<0.27",
+  "simplicio-fast>=2.0.32,<3",
   "tiktoken>=0.12.0,<1",
 ]
 

{simplicio_loop-3.43.10 → simplicio_loop-3.43.12}/simplicio_loop/__init__.py

@@ -13,6 +13,6 @@ try:
     try:
         __version__ = _v("simplicio-loop")
     except PackageNotFoundError:
-        __version__ = "3.43.10"
+        __version__ = "3.43.12"
 except Exception:  # pragma: no cover
-    __version__ = "3.43.10"
+    __version__ = "3.43.12"

{simplicio_loop-3.43.10 → simplicio_loop-3.43.12}/simplicio_loop/_bundle/hooks/hooks.claude.json

@@ -15,6 +15,13 @@
           { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/orient_rewrite.py\"" }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/user_prompt_submit.py\"" }
+        ]
+      }
     ]
   }
 }

simplicio_loop-3.43.12/simplicio_loop/_bundle/hooks/user_prompt_submit.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Run the canonical Claude adapter for UserPromptSubmit."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    current = Path(__file__).resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / "adapters" / "claude" / "adapter.py").is_file():
+            return candidate
+    return current.parents[1]
+
+
+ROOT = _repo_root()
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from adapters.claude.adapter import decide  # noqa: E402
+
+
+def main() -> int:
+    try:
+        event = json.loads(sys.stdin.read() or "{}")
+    except json.JSONDecodeError:
+        event = {}
+    event.setdefault("hook_event_name", "UserPromptSubmit")
+    decision = decide(event)
+    print(json.dumps(decision, ensure_ascii=False))
+    return 0 if decision.get("decision") != "block" else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simplicio_loop-3.43.12/simplicio_loop/_bundle/skills/simplicio-loop/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: simplicio-loop
+description: "Ralph loop for mapper + fast + simplicio-dev-cli. Same goal every turn; exit only on an evidence-gated promise or max_iterations. GitHub is SoT for issues/PRs. Host writes the edit plan."
+---
+
+# /simplicio-loop
+
+Self-referential iteration: the SAME goal is re-fed each turn. Exit ONLY when the
+typed `<promise>…</promise>` is true **and** in-turn evidence exists, or when
+`max_iterations` fires. Credit: Ralph Wiggum / cursor `ralph-loop`.
+
+Public stack: `simplicio-mapper`, `simplicio-fast`, `simplicio-dev-cli`,
+`simplicio-loop`. **No Runtime. No MCP force. No `SIMPLICIO_LOOP_REQUIRE_RUNTIME`.**
+The host LLM writes `simplicio.dev-cli.edit-plan/v1`. Loop never calls a provider
+to generate diffs.
+
+## GitHub source of truth
+
+When the remote is GitHub, GitHub is the coordination SoT: Issues, PR comments,
+checks, merge path. Re-query live state before closing. Do not substitute another
+tracker unless the user asks.
+
+## Contract
+
+1. Evidence-gated exit. No in-turn evidence → no promise.
+2. Exact sentinel `<promise>EXACT TEXT</promise>` matching `completion_promise`.
+3. `max_iterations` is mandatory before iteration 1.
+4. Scratchpad `.simplicio/orchestrator/loop/scratchpad.md` is the agent SoT.
+5. Review: **1 implement + 1 verify**. No 3–4 reviewer panels on ordinary diffs.
+
+## Hot path (mutate recipe)
+
+```bash
+simplicio-mapper scan . --json
+simplicio-mapper inspect . --json --await
+simplicio-mapper handoff . --goal "..." --token-budget 4000 --for-llm toon
+simplicio-fast ingest .   # skip if inspect says snapshot fresh
+simplicio-dev-cli edit --plan plan.json --apply --json
+simplicio-dev-cli test --json
+python3 scripts/watcher_verify.py verify
+```
+
+- Host writes `plan.json` (`simplicio.dev-cli.edit-plan/v1`).
+- **Never** `simplicio-dev-cli task "prose"`. Missing plan → `plan_required`.
+- Fast is cache. Skip ingest when inspect reports a fresh snapshot.
+- Promise only after watcher + test MEASURED in the same turn.
+
+## State
+
+`.simplicio/orchestrator/loop/scratchpad.md`:
+
+```markdown
+---
+iteration: 1
+max_iterations: <N>
+completion_promise: "<EXACT TEXT>"
+evidence_required: true
+mode: converge
+started_at: "<ISO-8601>"
+---
+
+<goal, verbatim>
+```
+
+Journal: `.simplicio/orchestrator/loop/journal.jsonl`. Watcher:
+`python3 scripts/watcher_verify.py verify` writes `watcher_state.json` — never
+hand-write it.
+
+## Drive
+
+Hook hosts (Claude/Cursor): capture + stop hooks re-feed the goal.
+Self-paced hosts: re-read the scratchpad every turn; triage → decide → operate
+→ verify → journal.
+
+End every message: `DONE | NEXT | BLOCKED`.
+
+<!-- SIMPLICIO-LLM-ORIENTATION:BEGIN -->
+Loop orientation:
+- Stack: mapper + fast + simplicio-dev-cli + loop. No Runtime. No MCP force.
+- GitHub is SoT for issues/PRs when the remote is GitHub.
+- Survey: mapper scan → inspect → handoff(--token-budget 4000). Context = handoff.
+- Fast ingest only if inspect says snapshot is stale; skip if fresh.
+- Host writes simplicio.dev-cli.edit-plan/v1. Apply: simplicio-dev-cli edit --plan --apply.
+- Never simplicio-dev-cli task "prose". No plan → plan_required (do not call OpenRouter).
+- Review: 1 implement + 1 verify. Promise only with watcher + test MEASURED.
+- End: DONE | NEXT | BLOCKED.
+<!-- SIMPLICIO-LLM-ORIENTATION:END -->
+
+## Bounded delivery
+
+One implementation issue and one delivery PR per worker. Freeze ACs before
+mutation. Findings: `AC_BLOCKER` / `REGRESSION_BLOCKER` / `FOLLOW_UP`. Only
+blockers hold the current delivery.
+
+## Guardrails
+
+- Do not invent MEASURED numbers.
+- Do not close issues without a live GitHub re-query.
+- Do not hand-edit source as the primary mutation path; apply the host plan.
+- Parallelism: 1–3 tasks direct; >3 Prism. Writes serialized.

{simplicio_loop-3.43.10 → simplicio_loop-3.43.12}/simplicio_loop/_bundle/skills/simplicio-loop/references/bound-operators.md

@@ -10,8 +10,9 @@ Two installed CLIs are the operators; the model only DECIDES, the operators do.
 
 | Operator | CLI (binary) | Binds | Role in the loop |
 |---|---|---|---|
-| **simplicio-mapper** | `simplicio-mapper` | `orient` / `recall` | **Survey** — maps the repo(s) into `.simplicio/*.json` (project-map, precedent-index, symbol-index, call-graph, docs). Two-tier (v0.9+): `macro` is an instant shallow skeleton (no content reads), `scan` returns that skeleton now and runs the deep index in the background, `status` reports the deep-pass phase. v0.13+ adds `inspect` (machine-readable evidence that the artifacts actually exist — the survey's own evidence gate) and `handoff` (a compact context-pack — files, symbols, deps, `pack_hash` — that feeds the goal instead of re-reading the tree). v0.14+ adds the flow-docs engine: `ask` (low-token structured queries over the artifacts), `sync --check`/`drift --check` (docs-staleness + spec-drift gates), `flows`/`survey`/`business`/`history`/`diff` (flow inventory, onboarding report, business rules, architecture history). This survey, not an ad-hoc LLM read, is what feeds the goal each turn. |
-| **simplicio-dev-cli** | `simplicio-dev-cli` | `execute` / `deterministic_edit` / `validate` / `diagnostics` | **Operate** — applies a DECIDED change through its 6-layer contract (mapper context → precedent → prompt → diff → test → verify, ≤3 retries). The CLI edits and verifies; the AI does not hand-write the diff. |
+| **simplicio-mapper** | `simplicio-mapper` | `orient` / `recall` | **Survey** — maps the repo(s) into `.simplicio/*.json` (project-map, precedent-index, symbol-index, call-graph, docs). Two-tier (v0.9+): `macro` is an instant shallow skeleton (no content reads), `scan` returns that skeleton now and runs the deep index in the background, `status` reports the deep-pass phase. Mandatory operator. |
+| **simplicio-fast** | `simplicio-fast` | `understand` / `plan` | **Accelerate & Plan** — syntactic AST indexation, high-speed project snapshot and deterministic edit planning. Mandatory operator. |
+| **simplicio-dev-cli** | `simplicio-dev-cli` | `execute` / `deterministic_edit` / `validate` / `diagnostics` | **Operate** — applies a DECIDED change through its 6-layer contract (mapper context → precedent → prompt → diff → test → verify, ≤3 retries). The CLI edits and verifies; the AI does not hand-write the diff. Mandatory operator. |
 
 **Preflight (MANDATORY, BLOCKING).** Before iteration 1, auto-update the operator package to its
 latest release (so every run uses the newest `simplicio-cli`-shipped `simplicio-mapper`/`simplicio-dev-cli`),