finitemonkey 0.0.0-stage → 0.1.0-next.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/NOTICE

@@ -0,0 +1,4 @@
+Finite Monkey
+Copyright 2026 Gabriel Vieira
+
+This product includes software developed by Gabriel Vieira (https://github.com/gabrielvieiraf/finitemonkey).

package/README.es.md

@@ -0,0 +1,105 @@
+# Finite Monkey
+
+<p align="center">
+  <img src="assets/finitemonkey.gif" width="720" alt="Animación: un mono con sudadera aporrea el teclado de una portátil mientras una terminal ejecuta finitemonkey gate. Las verificaciones que fallan se vuelven verdes y quedan fijadas una a una hasta que aparece actually done, y el mono celebra con un plátano.">
+</p>
+
+**No hacen falta infinitos monos. Basta con uno: tú.**
+
+[English](README.md) | [Português (Brasil)](README.pt-BR.md) | Español
+
+> **Estado: prelanzamiento.** Nada de esto funciona todavía. El nombre `finitemonkey` en npm está reservado y el código se construye en público. Todo lo que sigue describe lo que Finite Monkey está planeado para hacer, no lo que hace hoy.
+
+## La idea
+
+Ya conoces la rutina. Aporreas el teclado, pegas algo sacado de quién sabe dónde, compila, a producción. Después resulta que no hay pruebas, que un `.env` se coló en el diff y que "listo" era "casi listo". No es un defecto de carácter. Es el ritmo del trabajo, con o sin un agente de código tecleando por ti.
+
+Finite Monkey está diseñado para ser la compuerta entre ese mono y `main`. Teclea como quieras. Cada verificación que pasa queda fijada, el resto sigue fallando a la vista, y nada se da por listo hasta que cada verificación tenga prueba. Un mono, tiempo finito, trabajo que de verdad sale.
+
+### Por qué funciona
+
+El teorema del mono infinito dice que suficientes monos, tecleando durante suficiente tiempo, terminan escribiendo Hamlet. En *El relojero ciego* (1986), Richard Dawkins mostró un atajo con su "programa de la comadreja": conserva cada letra que ya es correcta, vuelve a sortear solo el resto, y `METHINKS IT IS LIKE A WEASEL` aparece en decenas de generaciones en lugar de una eternidad. La selección acumulativa conserva lo que pasó. Finite Monkey aplica el mismo truco a tu trabajo y al de tu agente: lo verificado sigue verificado, y solo lo que todavía falla vuelve a intentarse.
+
+## El problema
+
+Los agentes de código ya son lo bastante capaces para construir sistemas grandes en horas. Lo que falla es el entorno:
+
+- El agente dice "listo" y no está listo.
+- Las pruebas pasan porque se debilitaron o se saltaron.
+- Las reglas escritas en `CLAUDE.md` o `AGENTS.md` se olvidan, sobre todo después de la compactación del contexto, porque la prosa es contexto, no imposición.
+- Se pierde trabajo con un `git reset --hard`, un push forzado o un worktree borrado.
+- Un secreto termina en un commit, un log o un pull request.
+
+Son fallas de verificación y de control, no de inteligencia. Más Markdown, más fases y más personas no las resuelven. El mecanismo sí.
+
+## Lo que va a hacer (planeado)
+
+### Tú tecleas; la compuerta lleva la cuenta
+
+Finite Monkey está diseñado para que **no haya ningún comando que recordar**. Ejecutas `npx finitemonkey init` una vez. Después actúa por su cuenta, según el contexto, dentro de Claude Code:
+
+- **Hooks** hacen la imposición: `SessionStart` restaura el estado de la tarea, `UserPromptSubmit` detecta lo que pediste, `PreToolUse` bloquea acciones peligrosas antes de que ocurran, `Stop` se niega a cerrar la sesión mientras la definición de listo falle, y `SubagentStop` revisa lo que reportan los subagentes.
+- **Skills** que Claude invoca automáticamente, según su descripción, cuando la situación lo pide.
+- **Slash commands** existen solo como atajos opcionales. Ningún flujo depende de ellos.
+
+### Una definición de listo verificada por máquina
+
+Cada tarea recibe un contrato de lo que significa "listo": comandos que deben tener éxito, pruebas que deben existir y pasar, un diff que se mantiene dentro del alcance, y más. El hook `Stop` ejecuta la compuerta y bloquea el fin de la sesión con la lista de lo que aún falta. La evidencia se registra solo a partir de comandos que el propio Finite Monkey ejecutó, atada al hash del árbol de trabajo, así que "corrí las pruebas antes de la última edición" no cuenta. El informe final se genera a partir de esa evidencia, no de lo que dice el agente.
+
+### Los cuatro daños que previene primero
+
+La primera etapa de la hoja de ruta cubre solo lo que es irreversible o corrompe la prueba:
+
+1. **Filtrar secretos.** Una regla de detección aplicada al escribir archivos, en el prompt, al hacer commit, en el historial y en CI. Un secreto encontrado es un incidente que hay que rotar, no un aviso para ignorar. Los secretos se citan por archivo y línea, nunca por su valor.
+2. **Editar producción a mano.** Se bloquean los comandos con efecto en un host de producción. Producción solo cambia por el camino de despliegue declarado.
+3. **Perder trabajo en git.** Una instantánea antes de cada operación git riesgosa, un `undo` que la restaura, nunca `--force`, worktrees sucios archivados en lugar de borrados, y una verificación de "no se perdió nada" en cada merge.
+4. **Un "listo" falso.** La compuerta de arriba, más protecciones contra pruebas eliminadas, `skip` u `only` nuevos, aserciones eliminadas y ediciones a la configuración de la propia compuerta.
+
+### Principios
+
+- **Ceremonia proporcional.** Una tarea pequeña no tiene fases, solo la compuerta. Las tareas grandes reciben un plan corto y una revisión independiente.
+- **Las reglas se vuelven mecanismo.** Una regla que debe cumplirse siempre se convierte en hook, permiso, git hook o paso de CI, no en un párrafo. Finite Monkey muestra, por regla, dónde sigue siendo solo texto.
+- **Cada regla demuestra su valor o se va.** Un banco de pruebas compara Claude Code solo, con Finite Monkey y con Finite Monkey menos una pieza a la vez. Una regla sin efecto medido sale del núcleo.
+- **Nunca romper lo que existe.** Instalación con respaldo, fusión estructural, archivo de lock, reejecución idempotente, `doctor`, `update` y un `uninstall` limpio.
+- **Nada sale de tu máquina por defecto.** Sin telemetría.
+- **La salida para agentes es un contrato.** Todo comando aceptará `--json` y devolverá `schemaVersion`; los campos solo se agregan.
+- **Tres idiomas.** Inglés, portugués de Brasil y español.
+
+## Hoja de ruta
+
+Ordenada por dependencia, no por fecha. Cada etapa termina en una compuerta de salida medida.
+
+| Etapa | Contenido | Estado |
+|---|---|---|
+| 0. Fundación | Ejecutable con `init`, `doctor`, `update`, `uninstall`; contratos JSON; i18n; versiones automáticas | En construcción |
+| 1. Los cuatro daños | Secretos, producción, git, "listo" falso; la compuerta en `Stop` | Planeado |
+| 2. Decidir bien y no perderse | Inventario antes de cambiar, registros de decisión, controles de costo y de paridad, frentes de trabajo en paralelo, protocolo completo de merge, reglas compiladas por superficie | Planeado |
+| 3. Generadores | Generadores de lint, arquitectura, CI y despliegue para proyectos nuevos y existentes | Planeado |
+| 4. Demostrar valor | Banco de pruebas con ablación; se recortan las piezas sin efecto medido | Planeado |
+
+La versión 1.0 es el conjunto de las etapas 0 a 4.
+
+## Instalación (planeada)
+
+Todavía no está disponible. Cuando salga la primera versión, el camino principal será:
+
+```sh
+npx finitemonkey@latest init
+```
+
+Es el único comando que deberías necesitar. Los requisitos serán Node.js 20 o superior, en Linux, macOS, Windows o WSL. Se planean ejecutables independientes para quien no tenga Node. También podrás pedirle a Claude Code que lo instale por ti; el agente sigue [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md).
+
+## Cómo salen las versiones
+
+- La versión la deciden los mensajes de commit. El repositorio usa [Conventional Commits](https://www.conventionalcommits.org/es/), verificados por commitlint en cada commit.
+- En cada push a `main`, CI ejecuta los controles y [semantic-release](https://semantic-release.gitbook.io/) calcula la versión, escribe el changelog, publica en npm y crea la release en GitHub. Nadie edita la versión a mano.
+- Los paquetes se publican solo desde CI, con [procedencia de npm](https://docs.npmjs.com/generating-provenance-statements), para que puedas verificar que una versión se construyó desde este repositorio.
+- Se planean dos canales: `latest` para versiones estables y `next` para prelanzamientos. El estable es el predeterminado; `next` es opcional.
+
+## Contribuir
+
+Consulta [CONTRIBUTING.md](CONTRIBUTING.md) (en inglés). Los agentes y las personas que cambian este repositorio siguen [AGENTS.md](AGENTS.md). Los reportes de seguridad van por [SECURITY.md](SECURITY.md).
+
+## Licencia
+
+[Apache-2.0](LICENSE), por Gabriel Vieira. La licencia no otorga derechos sobre el nombre ni el logo "Finite Monkey".

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# Finite Monkey
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <img src="assets/finitemonkey.gif" width="720" alt="Animation: a monkey in a hoodie mashes the keyboard of a laptop while a terminal runs finitemonkey gate. Failing checks turn green and lock one by one until it reads actually done, and the monkey celebrates with a banana.">
+</p>
+
+**Infinite monkeys not required. One is enough: you.**
+
+English | [Português (Brasil)](README.pt-BR.md) | [Español](README.es.md)
+
+> **Status: pre-release.** Nothing here works yet. The npm name `finitemonkey` is reserved and the code is being built in the open. Everything below describes what Finite Monkey is planned to do, not what it does today.
+
+## The idea
+
+You know the routine. You mash keys, paste something from somewhere, it compiles, ship it. Then it turns out the tests are missing, a `.env` slipped into the diff and "done" meant "done-ish". That is not a character flaw. It is the pace of the work, with or without a coding agent typing for you.
+
+Finite Monkey is designed to be the gate between that monkey and `main`. Type however you like. Every check that passes gets locked in, the rest keeps failing out loud, and nothing is called done until every check has proof. One monkey, finite time, work that actually ships.
+
+### Why it works
+
+The infinite monkey theorem says that enough monkeys typing for long enough will eventually produce Hamlet. In *The Blind Watchmaker* (1986), Richard Dawkins showed a shortcut with his "weasel program": keep every letter that is already right, re-roll only the rest, and `METHINKS IT IS LIKE A WEASEL` shows up in dozens of generations instead of an eternity. Cumulative selection keeps what passed. Finite Monkey applies the same trick to your work and to your agent's: what was verified stays verified, and only what still fails goes back for another try.
+
+## The problem
+
+Coding agents are strong enough to build large systems in hours. What fails is everything around them:
+
+- The agent says "done" and it is not done.
+- Tests pass because they were weakened or skipped.
+- Rules written in `CLAUDE.md` or `AGENTS.md` are forgotten, especially after context compaction, because prose is context, not enforcement.
+- Work is lost to `git reset --hard`, a forced push or a deleted worktree.
+- A secret ends up in a commit, a log or a pull request.
+
+These are failures of verification and control, not of intelligence. More Markdown, more phases and more personas do not fix them. Mechanism does.
+
+## What it will do (planned)
+
+### You keep typing; the gate keeps score
+
+Finite Monkey is designed to need **zero commands to remember**. You run `npx finitemonkey init` once. After that it acts on its own, from context, inside Claude Code:
+
+- **Hooks** do the enforcing: `SessionStart` restores the task state, `UserPromptSubmit` notices what you asked for, `PreToolUse` blocks dangerous actions before they happen, `Stop` refuses to end the session while the definition of done fails, and `SubagentStop` checks what subagents report.
+- **Skills** are invoked by Claude automatically, based on their description, when the situation calls for them.
+- **Slash commands** exist only as optional shortcuts. No workflow requires them.
+
+### A definition of done verified by machine
+
+Each task gets a contract of what "done" means: commands that must succeed, tests that must exist and pass, a diff that stays in scope, and more. The `Stop` hook runs the gate and blocks the end of the session with the list of what is still missing. Evidence is recorded only from commands Finite Monkey ran itself, tied to the hash of the working tree, so "I ran the tests before my last edit" does not count. The final report is generated from that evidence, not from what the agent says.
+
+### The four damages it prevents first
+
+The first stage of the roadmap covers only what is irreversible or corrupts the proof:
+
+1. **Leaking secrets.** One detection rule applied when files are written, in prompts, at commit time, in history and in CI. A secret found is an incident to rotate, not a warning to ignore. Secrets are cited by file and line, never by value.
+2. **Editing production by hand.** Commands with effects on a production host are blocked. Production changes only through the declared deploy path.
+3. **Losing work in git.** A snapshot before every risky git operation, an `undo` that restores it, no `--force` ever, dirty worktrees archived instead of deleted, and a "nothing was lost" check on every merge.
+4. **False "done".** The gate above, plus guards against removed tests, new `skip` or `only`, removed assertions and edits to the gate's own configuration.
+
+### Principles
+
+- **Proportional ceremony.** A small task has no phases, only the gate. Larger tasks get a short plan and an independent review.
+- **Rules become mechanism.** A rule that must always hold becomes a hook, a permission, a git hook or a CI step, not a paragraph. Finite Monkey shows, per rule, where it is only text.
+- **Every rule proves its value or goes.** A benchmark compares Claude Code alone, with Finite Monkey and with Finite Monkey minus one piece at a time. A rule with no measured effect leaves the core.
+- **Never break what exists.** Install with backup, structural merge, a lock file, idempotent re-runs, `doctor`, `update` and a clean `uninstall`.
+- **Nothing leaves your machine by default.** No telemetry.
+- **Output for agents is a contract.** Every command will accept `--json` and return a `schemaVersion`; fields are only ever added.
+- **Three languages.** English, Brazilian Portuguese and Spanish.
+
+## Roadmap
+
+Ordered by dependency, not by date. Each stage ends at a measured exit gate.
+
+| Stage | Content | Status |
+|---|---|---|
+| 0. Foundation | Executable with `init`, `doctor`, `update`, `uninstall`; JSON contracts; i18n; automated releases | In progress |
+| 1. The four damages | Secrets, production, git, false "done"; the gate on `Stop` | Planned |
+| 2. Deciding well and not getting lost | Inventory before change, decision records, cost and parity checks, parallel work fronts, full merge protocol, rules compiled per surface | Planned |
+| 3. Generators | Lint, architecture, CI and deploy generators for new and existing projects | Planned |
+| 4. Proving value | Benchmark with ablation; pieces without measured effect are cut | Planned |
+
+Version 1.0 is the whole of stages 0 to 4.
+
+## Install (planned)
+
+Not available yet. When the first release is out, the main path will be:
+
+```sh
+npx finitemonkey@latest init
+```
+
+That is the only command you are meant to need. Requirements will be Node.js 20 or later, on Linux, macOS, Windows or WSL. Standalone executables for people without Node are planned. You will also be able to ask Claude Code to install it for you; the agent follows [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md).
+
+## How releases work
+
+- Versions are decided by commit messages. The repository uses [Conventional Commits](https://www.conventionalcommits.org/), checked by commitlint on every commit.
+- On every push to `main`, CI runs the checks and [semantic-release](https://semantic-release.gitbook.io/) computes the version, writes the changelog, publishes to npm and creates the GitHub release. Nobody edits the version by hand.
+- Packages are published only from CI, with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), so you can verify that a version was built from this repository.
+- Two channels are planned: `latest` for stable releases and `next` for pre-releases. Stable is the default; `next` is opt-in.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Agents and humans changing this repository must follow [AGENTS.md](AGENTS.md). Security reports go through [SECURITY.md](SECURITY.md).
+
+## License
+
+[Apache-2.0](LICENSE), by Gabriel Vieira. The license does not grant rights to the "Finite Monkey" name or logo.

package/README.pt-BR.md

@@ -0,0 +1,105 @@
+# Finite Monkey
+
+<p align="center">
+  <img src="assets/finitemonkey.gif" width="720" alt="Animação: um macaco de moletom bate no teclado de um notebook enquanto um terminal roda finitemonkey gate. As verificações que falham ficam verdes e travam uma a uma até aparecer actually done, e o macaco comemora com uma banana.">
+</p>
+
+**Não precisa de infinitos macacos. Um basta: você.**
+
+[English](README.md) | Português (Brasil) | [Español](README.es.md)
+
+> **Status: pré-lançamento.** Nada aqui funciona ainda. O nome `finitemonkey` no npm está reservado e o código está sendo construído em público. Tudo abaixo descreve o que o Finite Monkey está planejado para fazer, não o que ele faz hoje.
+
+## A ideia
+
+Você conhece o roteiro. Bate no teclado, cola alguma coisa de algum lugar, compilou, manda. Depois descobre que os testes não existem, que um `.env` entrou no diff e que "pronto" era "mais ou menos pronto". Não é defeito de caráter. É o ritmo do trabalho, com ou sem um agente de código digitando por você.
+
+O Finite Monkey foi desenhado para ser o portão entre esse macaco e a `main`. Digite do jeito que quiser. Cada verificação que passa fica travada, o resto continua falhando em voz alta, e nada é chamado de pronto até cada verificação ter prova. Um macaco, tempo finito, trabalho que sai de verdade.
+
+### Por que funciona
+
+O teorema do macaco infinito diz que macacos suficientes, batendo à máquina por tempo suficiente, acabam escrevendo Hamlet. Em *O Relojoeiro Cego* (1986), Richard Dawkins mostrou um atalho com o "programa da doninha": guarde cada letra que já está certa, sorteie de novo só o resto, e `METHINKS IT IS LIKE A WEASEL` aparece em dezenas de gerações em vez de uma eternidade. A seleção cumulativa guarda o que passou. O Finite Monkey usa o mesmo truque no seu trabalho e no do seu agente: o que foi verificado continua verificado, e só o que ainda falha volta para outra tentativa.
+
+## O problema
+
+Agentes de código já são fortes o bastante para construir sistemas grandes em horas. O que falha é o entorno:
+
+- O agente diz "pronto" e não está pronto.
+- Os testes passam porque foram afrouxados ou pulados.
+- Regras escritas no `CLAUDE.md` ou no `AGENTS.md` são esquecidas, principalmente depois da compactação do contexto, porque prosa é contexto, não imposição.
+- Trabalho se perde num `git reset --hard`, num push forçado ou num worktree apagado.
+- Um segredo vai parar num commit, num log ou num pull request.
+
+São falhas de verificação e de controle, não de inteligência. Mais Markdown, mais fases e mais personas não resolvem. Mecanismo resolve.
+
+## O que ele vai fazer (planejado)
+
+### Você só digita; o portão confere
+
+O Finite Monkey foi desenhado para **não ter nenhum comando para decorar**. Você roda `npx finitemonkey init` uma vez. Depois disso ele age sozinho, pelo contexto, dentro do Claude Code:
+
+- **Hooks** fazem a imposição: `SessionStart` restaura o estado da tarefa, `UserPromptSubmit` percebe o que você pediu, `PreToolUse` barra ações perigosas antes que aconteçam, `Stop` se recusa a encerrar a sessão enquanto a definição de pronto falha, e `SubagentStop` confere o que os subagentes relatam.
+- **Skills** são acionadas pelo Claude automaticamente, pela descrição, quando a situação pede.
+- **Slash commands** existem só como atalhos opcionais. Nenhum fluxo depende deles.
+
+### Uma definição de pronto verificada por máquina
+
+Cada tarefa ganha um contrato do que "pronto" significa: comandos que precisam dar certo, testes que precisam existir e passar, um diff que fica dentro do escopo, e mais. O hook `Stop` roda o portão e bloqueia o fim da sessão com a lista do que ainda falta. A evidência é registrada só a partir de comandos que o próprio Finite Monkey executou, presa ao hash da árvore de trabalho, então "rodei os testes antes da última edição" não conta. O relatório final é gerado dessa evidência, não do que o agente diz.
+
+### Os quatro danos que ele impede primeiro
+
+A primeira etapa do roteiro cobre só o que é irreversível ou corrompe a prova:
+
+1. **Vazar segredo.** Uma regra de detecção aplicada na escrita de arquivos, no prompt, no commit, no histórico e na CI. Segredo encontrado é incidente para rotacionar, não aviso para ignorar. Segredos são citados por arquivo e linha, nunca pelo valor.
+2. **Editar produção na mão.** Comandos com efeito num host de produção são barrados. Produção só muda pelo caminho de deploy declarado.
+3. **Perder trabalho no git.** Uma fotografia antes de toda operação git de risco, um `undo` que a devolve, `--force` nunca, worktree sujo arquivado em vez de apagado, e uma verificação de "nada se perdeu" em toda mescla.
+4. **"Pronto" falso.** O portão acima, mais travas contra teste removido, `skip` ou `only` novo, asserção removida e edição da configuração do próprio portão.
+
+### Princípios
+
+- **Cerimônia proporcional.** Tarefa pequena não tem fase, só o portão. Tarefa maior ganha um plano curto e uma revisão independente.
+- **Regra vira mecanismo.** Regra que precisa valer sempre vira hook, permissão, git hook ou passo de CI, não um parágrafo. O Finite Monkey mostra, por regra, onde ela ainda é só texto.
+- **Toda regra prova valor ou sai.** Uma bancada compara o Claude Code puro, com o Finite Monkey e com o Finite Monkey menos uma peça de cada vez. Regra sem efeito medido sai do núcleo.
+- **Nunca quebrar o que existe.** Instalação com backup, mescla estrutural, arquivo de lock, reexecução idempotente, `doctor`, `update` e `uninstall` limpo.
+- **Nada sai da sua máquina por padrão.** Sem telemetria.
+- **Saída para agente é contrato.** Todo comando vai aceitar `--json` e devolver `schemaVersion`; campos só são acrescentados.
+- **Três idiomas.** Inglês, português do Brasil e espanhol.
+
+## Roteiro
+
+Ordenado por dependência, não por data. Cada etapa termina num portão de saída medido.
+
+| Etapa | Conteúdo | Status |
+|---|---|---|
+| 0. Fundação | Executável com `init`, `doctor`, `update`, `uninstall`; contratos JSON; i18n; releases automáticas | Em construção |
+| 1. Os quatro danos | Segredo, produção, git, "pronto" falso; o portão no `Stop` | Planejado |
+| 2. Decidir bem e não se perder | Inventário antes de mudar, registro de decisão, checagens de custo e de paridade, frentes de trabalho em paralelo, protocolo completo de mescla, regras compiladas por superfície | Planejado |
+| 3. Geradores | Geradores de lint, arquitetura, CI e deploy para projetos novos e existentes | Planejado |
+| 4. Provar valor | Bancada com ablação; peças sem efeito medido são cortadas | Planejado |
+
+A versão 1.0 é o conjunto das etapas 0 a 4.
+
+## Instalação (planejada)
+
+Ainda não disponível. Quando a primeira versão sair, o caminho principal será:
+
+```sh
+npx finitemonkey@latest init
+```
+
+É o único comando que você deve precisar. Os requisitos serão Node.js 20 ou mais novo, em Linux, macOS, Windows ou WSL. Executáveis avulsos para quem não tem Node estão planejados. Você também vai poder pedir ao Claude Code que instale por você; o agente segue o [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md).
+
+## Como saem as versões
+
+- A versão é decidida pelas mensagens de commit. O repositório usa [Conventional Commits](https://www.conventionalcommits.org/pt-br/), conferidos pelo commitlint em todo commit.
+- A cada push na `main`, a CI roda as checagens e o [semantic-release](https://semantic-release.gitbook.io/) calcula a versão, escreve o changelog, publica no npm e cria a release no GitHub. Ninguém edita a versão na mão.
+- Os pacotes são publicados só pela CI, com [proveniência do npm](https://docs.npmjs.com/generating-provenance-statements), para você conferir que uma versão foi construída a partir deste repositório.
+- Dois canais estão planejados: `latest` para versões estáveis e `next` para pré-lançamentos. O estável é o padrão; o `next` é opcional.
+
+## Contribuir
+
+Veja o [CONTRIBUTING.md](CONTRIBUTING.md) (em inglês). Agentes e pessoas que mexem neste repositório seguem o [AGENTS.md](AGENTS.md). Relatos de segurança vão pelo [SECURITY.md](SECURITY.md).
+
+## Licença
+
+[Apache-2.0](LICENSE), por Gabriel Vieira. A licença não dá direito de usar o nome nem o logo "Finite Monkey".