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

{simplicio_loop-3.43.11/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.11
-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
@@ -21,10 +21,9 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: simplicio-cli<0.19,>=0.18.13
+Requires-Dist: simplicio-cli<0.19,>=0.18.12
 Requires-Dist: simplicio-mapper<0.27,>=0.26.31
-Requires-Dist: simplicio-fast<3,>=2.0.33
-Requires-Dist: simplicio-prompt<1.15,>=1.14.4
+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.11 → simplicio_loop-3.43.12}/README.md

@@ -839,33 +839,62 @@ The main `simplicio-loop` entry point is the user-facing control surface for pla
 
 ### Zero-config execution
 
-The normal start path requires only the task and repository scope:
+The standard entry point uses the governed `wave` flow (with automatic reconciliation barriers):
 
 ```bash
-simplicio-loop run --task task.md --repo .
+# 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
 ```
 
-Loop initializes the Mapper-owned operations store when needed, runs the required
-Mapper handoff, reconciles one normal cold-start inspection internally when the index is
-still warming, derives worker demand from the task set, and lets physical CPU/RAM/disk
-admission choose the safe concurrency. For an existing run, `simplicio-loop batch RUN_ID`
-applies the same defaults; `--serial` is reserved for explicit dependency or conflict
-cases. Missing Mapper receipts, stale plans, invalid targets, failed workers, or unsafe
-machine pressure remain visible stop conditions and are never silently bypassed.
+> **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.
 
-> **At a glance:** `plan` creates a frozen task contract → `run` executes it with bounded iterations → `verify` checks the evidence independently → `deliver` reconciles the result with the source of record.
+> **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 | `run`, `tick`, `batch`, `wave`, `prism`, `single-task-fast` | Arm and execute a task with evidence; execute one planned task through Dev CLI; dispatch ready tasks through bounded isolated workers and reconciled Prism waves; select the local-first route for one task. |
+| 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.
@@ -932,7 +961,8 @@ Typical single-task commands:
 simplicio-loop preflight --repo . --json
 simplicio-loop orient --task "understand this repository" --repo .
 simplicio-loop plan --task task.md --out contract.json
-simplicio-loop run --task task.md --repo . --max-iterations 5
+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
@@ -941,7 +971,7 @@ 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 `run`, `batch`, `batch --serial`, `tasks run`,
+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

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

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.43.11"
-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.13,<0.19",
+  "simplicio-cli>=0.18.12,<0.19",
   "simplicio-mapper>=0.26.31,<0.27",
-  "simplicio-fast>=2.0.33,<3",
-  "simplicio-prompt>=1.14.4,<1.15",
+  "simplicio-fast>=2.0.32,<3",
   "tiktoken>=0.12.0,<1",
 ]
 
@@ -53,7 +49,6 @@ Repository = "https://github.com/wesleysimplicio/simplicio-loop"
 Issues = "https://github.com/wesleysimplicio/simplicio-loop/issues"
 
 [project.scripts]
-simplicio = "simplicio_loop.savings_cli:main"
 simplicio-loop = "simplicio_loop.cli:main"
 issue-factory = "simplicio_loop.issue_factory_cli:main"
 simplicio-ecosystem-doctor = "simplicio_loop.ecosystem_doctor:main"

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

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

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.11 → 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`),