logsayer 0.6.0__tar.gz

logsayer-0.6.0/.gitignore

@@ -0,0 +1,15 @@
+feelback_agente.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+coverage.xml
+htmlcov/

logsayer-0.6.0/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md — logsayer
+
+CLI open source en Python que scaffoldea y coordina un sistema de 5 capas documentales para proyectos con agentes IA (Especificación, Estado, Bitácora, Verificación y Proceso). Stack: Python 3.11+, Typer, Jinja2, TOML (`logsayer.toml`), empaquetado con `pyproject.toml` + hatchling, distribución vía PyPI (`uv tool install` / `pipx`).
+
+## Idioma y tono
+- Responder siempre en español rioplatense, informal ("vos"). Nunca en inglés, aunque el código, logs o skills estén en inglés.
+- La superficie pública del framework (rutas `docs/`, comandos, README) va en inglés; el contenido generado puede ir en español.
+
+## Comandos del proyecto
+- Instalar: `uv tool install .`
+- Tests: `python -m pytest -q` (entorno: `.venv`)
+- Lint/formato: `ruff check src tests`
+- Tipado: `mypy src` (strict)
+
+## Setup / gotchas
+- Fuente de verdad absoluta: `logsayer_especificacion_maestra.md`. Reemplaza y consolida toda decisión previa (capas, roadmap, tema Dune, bot vs subagente, umbrales, estrategia multi-agente).
+- `prompts_bootstrap_framework.md` es el flujo de prompts de bootstrap: define la constitución y las features del propio CLI.
+- No inventar comandos, config ni estructura que no estén en la especificación maestra: verificar ahí antes de asumir.
+- `__version__` vive en `src/logsayer/__init__.py` y debe seguir el `version` de `pyproject.toml`.
+
+## Arquitectura del proyecto
+- El CLI genera para proyectos usuarios: `docs/01_global/`, `docs/02_technical/`, `docs/03_process/`, `docs/04_user_stories/HU-XX/`, `docs/05_agile_methodology/`, `docs/06_audits/`; más `docs/project_state.md` (Capa 2) y `docs/logbooks/logbook_<fase>_NN.md` con `00_index.md` (Capa 3) — ver `src/logsayer/scaffold.py`.
+- Motor único `logsayer/core/` + adaptadores por agente (`logsayer/adapters/<agente>/`) que solo traducen la convención de archivos nativa de cada herramienta e invocan comandos del CLI.
+- Comandos con alias plano: `logsayer truthsayer audit run` ≡ `logsayer audit run`.
+
+## Fuente de verdad
+- `logsayer_especificacion_maestra.md` es la única fuente de verdad (nombre, 5 capas, estructura, umbrales, comandos, roadmap, stack, riesgos conocidos, disclaimer).
+- Si el código real contradice la especificación, avisar antes de asumir.
+
+## Reglas globales (no duplicar, ya cargadas vía config global)
+- Git/git flow, anti-alucinación, APA y SOLID viven en `~/.config/opencode/rules/`. No copiarlas acá: si este repo necesita algo distinto, documentarlo JUSTIFICANDO la diferencia.
+
+## Reglas del proyecto
+- No duplicar lógica del framework dentro de los templates/adaptadores que genera el CLI: todo juicio vive en `logsayer/core/`, los archivos generados son wrappers finos (spec §6).
+
+## Coordinación con docs/ (dogfooding)
+Este repo usa logsayer sobre sí mismo (marco de sesiones, spec §7). Los umbrales viven en `logsayer.toml`; esto tiene que reflejarlos (lo verifica `logsayer fremen verify`).
+
+### Al iniciar sesión
+1. Leer `docs/project_state.md` (Capa 2, obligatorio, siempre).
+2. Si el contador de HUs cerradas desde la última auditoría es >= 3 HUs, proponer auditoría (Decidora de Verdad) antes de tomar tarea nueva.
+3. NO leer `docs/logbooks/` completa — solo `docs/logbooks/00_index.md` bajo demanda.
+
+### Durante la sesión
+- Si el uso de contexto supera el 70%, proponer cierre de sesión antes de tomar más tareas.
+- Trabajar cada HU leyendo solo su carpeta en `docs/04_user_stories/`.
+- Decisión de arquitectura nueva → candidata a entrada de logbook y a `docs/02_technical/decisions.md`; nunca se escribe directo en el estado.
+
+### Al cerrar sesión o commit (requiere aprobación previa)
+- Sobrescribir `docs/project_state.md` (snapshot, no acumulativo).
+- Append en el logbook activo `docs/logbooks/logbook_dogfooding_NN.md`.
+- Si el logbook activo supera las 400 líneas, crear `NN+1` y actualizar `00_index.md`.
+- Si se cerró una HU, incrementar el contador de auditoría.
+
+### Auditoría (Decidora de Verdad)
+- Disparador: contador >= 3 HUs. Ejecutar `logsayer audit run`.
+- Compara `docs/04_user_stories/` contra el código real; resultado en `docs/06_audits/audit_<fecha>.md`.
+- Resetear el contador tras la aprobación.
+
+## Estado actual
+- Dogfooding del marco activo: logsayer se gobierna a sí mismo (docs/ bootstrappeado con `init --here` en modo adopt, HUs reales HU-01..05 en `docs/04_user_stories/`, logbooks por fase, auditoría 2026-09-24 aprobada y contador reseteado).
+- Versión actual: `0.6.0` (sync entre `pyproject.toml` y `src/logsayer/__init__.py`). El modo adopt de `init --here` (spec §5) cerró la deuda de repositorios existentes, verificado con tests + check + fremen.
+- Fases 0-5 del roadmap cerradas. Pendientes: publicar en PyPI (token de `3m1l10j4v13r4qu1n0`), fase 3 restante (copilot/cursor/gemini/hermes por demanda), fase 6 (comunidad: presets, más agentes).
+- `main` tiene solo el bootstrap; feature branches convergen en `develop`; releases con tag semver (`v0.1.0`..`v0.6.0`).
+
+## Memoria del proyecto
+- [x] Dogfooding del propio repo: `docs/` bootstrappeado sobre sí mismo; `docs/project_state.md` (Capa 2), logbooks por fase (Capa 3) y auditoría (Capa 4) mantenidos en el marco de sesiones.

logsayer-0.6.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+Todos los cambios notables de logsayer quedan documentados acá, por versión, en orden cronológico inverso. Formato [Keep a Changelog](https://keepachangelog.com/es/1.1.0/), versionado [semver](https://semver.org/lang/es/).
+
+## [Unreleased]
+
+## [0.6.0] — 2026-09-24
+
+### Added
+- **Modo adopt en `logsayer init --here`** (spec §5): scaffoldea sobre un repositorio existente — crea lo que falta (capa de `docs/`, `logsayer.toml`) y **no sobrescribe** archivos ya presentes (`AGENTS.md`, estado, índice). Cierra la deuda entre la especificación y el código.
+- **Dogfooding activo**: el propio repo ahora se gobierna con logsayer (Capa 1-5 en `docs/`), con HUs reales HU-01..05, logbooks por fase y auditoría 2026-09-24 aprobada.
+
+### Changed
+- `scaffold()` acepta `adopt` y devuelve los paths escritos; el CLI reporta qué se preservó y qué se generó.
+
+## [0.5.0] — 2026-09-24
+
+### Added
+- `README.md` público (inglés) con el disclaimer Dune obligatorio (spec §12).
+- `LICENSE` MIT.
+- `examples/hello-logsayer/` — sesión real documentada con salidas del CLI.
+- Empaquetado listo para PyPI: `readme`, `authors`, `keywords`, clasificadores y URLs en `pyproject.toml`.
+
+## [0.4.0] — 2026-09-24
+
+### Added
+- **Suk Doctor** (`logsayer suk doctor` / alias `logsayer check`): verificación mecánica determinística — marcadores de raíz, estructura de capas, estado, índice de bitácora, ubicación de HUs y detección de capas mezcladas. Exit code 1 ante fallas.
+- **Fremen** (`logsayer fremen verify` / alias `logsayer process check`): estado documentado, proceso desplegado, acuerdo de coordinación y Definition of Ready.
+
+## [0.3.0] — 2026-09-24
+
+### Added
+- **`logsayer agent add <opencode|claude>`**: genera subagentes por rol (mentat, navigator, reverend-mother, truthsayer) como wrappers finos que invocan al CLI (motor único, spec §6).
+
+## [0.2.0] — 2026-09-24
+
+### Added
+- **Comandos core** con alias plano (spec §13): `spec new` (template mínimo de HU), `state show`, `log add` con partición automática, `log index`, `audit run` y `audit status`.
+
+### Changed
+- Registro de comandos bajo grupo de rol **y** con alias plano en la raíz.
+
+## [0.1.0] — 2026-09-24
+
+### Added
+- **`logsayer init <project-name>`** y `--here`: scaffoldea `docs/` con las 7 carpetas de capas, `AGENTS.md`, `project_state.md` e índice de bitácora.
+- **`logsayer.toml`** con los umbrales (spec §4): `session_close_context_threshold = 0.70`, `bitacora_max_lines = 400`, `audit_threshold_hus = 3`.
+- Valida slug y destino vacío; empaquetado hatchling (`pyproject.toml`).
+
+[Unreleased]: https://github.com/3m1l10j4v13r4qu1n0/logsayer/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/3m1l10j4v13r4qu1n0/logsayer/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/3m1l10j4v13r4qu1n0/logsayer/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/3m1l10j4v13r4qu1n0/logsayer/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/3m1l10j4v13r4qu1n0/logsayer/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/3m1l10j4v13r4qu1n0/logsayer/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/3m1l10j4v13r4qu1n0/logsayer/releases/tag/v0.1.0

logsayer-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emilio Javier Aquino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logsayer-0.6.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: logsayer
+Version: 0.6.0
+Summary: CLI que extiende el patron spec-driven con estado, bitacora y verificacion continua de que lo construido sigue siendo lo especificado.
+Project-URL: Homepage, https://github.com/3m1l10j4v13r4qu1n0/logsayer
+Project-URL: Repository, https://github.com/3m1l10j4v13r4qu1n0/logsayer
+Project-URL: Issues, https://github.com/3m1l10j4v13r4qu1n0/logsayer/issues
+Author-email: Emilio Javier Aquino <aquinoemiliojavier@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,cli,documentation,logbook,scaffolding,spec-driven,state,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# logsayer
+
+> **Spec-kit tells you what to build. logsayer tells you where you stand, how you got there, and whether what you built is still what you said you would build.**
+
+A Python CLI that scaffolds and coordinates a 5-layer documentary system for AI-agent projects: Specification, State, Logbook, Verification (mechanical + semantic), and Process.
+
+Everything the agent needs to know about a project is written down by the same system that uses it — each layer answers one question, each document lives in exactly one layer, and every judgment lives in the CLI, not in the generated files.
+
+## Disclaimer (Dune homage)
+
+> This project uses names and concepts from Frank Herbert's *Dune* saga exclusively as a thematic reference and role metaphor. It is not affiliated with, sponsored by, or officially associated with Herbert Properties LLC, Legendary Entertainment, or any rights holders of the franchise. No art, logos, or protected material is reproduced — only concept/role names as a design analogy.
+
+## Why logsayer
+
+The spec-driven pattern (as popularized by GitHub Spec Kit) governs the *first* generation of code. After that, its authority over the code is by convention, not verification. logsayer closes the loop that pattern leaves open:
+
+- **State continuity** between sessions — an anchor snapshot the agent reads (and only that) at session start.
+- **A partitioned, append-only logbook** for the *"why"* of past decisions.
+- **A mechanical + semantic verification loop** that checks whether the code still matches the spec — both structurally and in meaning.
+- **Multi-agent coordination** through the standard `AGENTS.md` convention, with thin native adapters per tool (opencode and Claude Code today).
+
+## The 5 layers
+
+| # | Layer | Question it answers | Dune role |
+|---|-------|--------------------|-----------|
+| 1 | Specification (normative) | What must be built? | Mentat |
+| 2 | State (anchor) | Where is the project right now? | Guild Navigator |
+| 3 | Logbook (historical) | How did we get here, and why? | Reverend Mother |
+| 4 | Verification | Does what was built still match the spec? | Suk Doctor (mechanical) + Truthsayer (semantic) |
+| 5 | Process (operational) | How do we work here? | Fremen |
+
+Every layer has a plain-English alias, so you can use logsayer without knowing any of the lore.
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+uv tool install logsayer
+# or
+pipx install logsayer
+```
+
+## Quick start
+
+```bash
+# 1. Scaffold a new project
+logsayer init my-project
+cd my-project
+
+# 2. Write the spec for a user story
+logsayer spec new HU-01
+
+# 3. Add an agent adapter (opencode, claude)
+logsayer agent add opencode
+
+# 4. Start a session: check state, work the story
+logsayer state show
+# ... implement HU-01 ...
+
+# 5. Close the session: log it, audit when threshold is hit
+logsayer log add "HU-01 done: API + tests"
+logsayer check          # mechanical: structure, no mixed layers
+logsayer audit run      # semantic: spec vs real code report
+```
+
+For an existing project:
+
+```bash
+logsayer init --here
+```
+
+## Commands
+
+| Command | Dune alias | Layer | Purpose |
+|---------|-----------|-------|---------|
+| `logsayer init [name]` | — | scaffold | Creates `docs/` + `AGENTS.md` + `logsayer.toml` |
+| `logsayer init --here` | — | scaffold | Scaffolds into the current directory |
+| `logsayer agent add <opencode\|claude>` | — | coordination | Generates per-role subagents for a tool |
+| `logsayer spec new <hu>` | `logsayer mentat spec new` | 1 | Creates a minimal HU template |
+| `logsayer state show` | `logsayer navigator state show` | 2 | Prints the project snapshot |
+| `logsayer log add "…"` | `logsayer reverend-mother log add` | 3 | Appends a logbook entry (auto-partition) |
+| `logsayer log index` | `logsayer reverend-mother log index` | 3 | Rebuilds `00_index.md` from real files |
+| `logsayer check` | `logsayer suk doctor` | 4 | Mechanical checks: structure, no layer mixing |
+| `logsayer audit run` | `logsayer truthsayer audit run` | 4 | Generates the audit report + semantic prompt |
+| `logsayer audit status` | `logsayer truthsayer audit status` | 4 | Shows HU counter vs threshold, last report |
+| `logsayer process check` | `logsayer fremen verify` | 5 | Process checks: Dor, coordination agreement |
+
+## Configuration (`logsayer.toml`)
+
+Generated by `logsayer init`, tuned in a single file:
+
+```toml
+[logsayer]
+session_close_context_threshold = 0.70   # % context used → propose session close
+bitacora_max_lines = 400                 # lines/logbook file before partitioning
+audit_threshold_hus = 3                  # HUs closed since last audit → trigger audit
+```
+
+## How a session flows
+
+1. **Session start** — the agent reads *only* the state layer (`docs/project_state.md`). Cheap in tokens, enough to orient.
+2. **Audit check** — if the closed-HUs counter meets the threshold, the agent proactively proposes an audit (semantic verification).
+3. **Work** — the agent works a HU reading only its folder under `docs/04_user_stories/`, and only opens a logbook entry when it needs the *"why"* of a past decision.
+4. **Close / commit** — with your prior approval, the agent overwrites the state snapshot and appends to the active logbook.
+5. **Auto-partition** — when the active logbook exceeds the line limit, the next file is created and the master index updated.
+
+## Example session
+
+A full, real transcript — run against a freshly scaffolded project — lives in [`examples/hello-logsayer/`](examples/hello-logsayer/README.md). It walks through scaffold, story creation, logbook entries, verification, and agent adapters, with the actual output of every command.
+
+## Multi-agent design
+
+A single engine (`logsayer/core/`) plus one thin adapter per agent (`logsayer/adapters/<agent>/`) that only translates each tool's native file convention and calls the CLI. Adding a new agent means a new adapter, not new logic. See [`docs/` of this repo](logsayer_especificacion_maestra.md) (master spec) for the full architecture.
+
+## Roadmap
+
+- **0–4 (done):** naming & manifest, `init`, core commands (`spec`, `state`, `log`, `audit`), opencode/Claude adapters, mechanical validation (`check`, `process check`).
+- **5 (current):** documentation & publishing — README, PyPI, MIT, examples. You are here.
+- **6:** community presets, more agents on demand (copilot, cursor, gemini, hermes).
+
+## Acknowledgment & license
+
+- MIT — see [LICENSE](LICENSE).
+- Built around the 5-layer documentary system described in the master spec.
+- Names and concepts from *Dune* are used as a thematic role metaphor only (full disclaimer at the top of this document).

logsayer-0.6.0/README.md

@@ -0,0 +1,126 @@
+# logsayer
+
+> **Spec-kit tells you what to build. logsayer tells you where you stand, how you got there, and whether what you built is still what you said you would build.**
+
+A Python CLI that scaffolds and coordinates a 5-layer documentary system for AI-agent projects: Specification, State, Logbook, Verification (mechanical + semantic), and Process.
+
+Everything the agent needs to know about a project is written down by the same system that uses it — each layer answers one question, each document lives in exactly one layer, and every judgment lives in the CLI, not in the generated files.
+
+## Disclaimer (Dune homage)
+
+> This project uses names and concepts from Frank Herbert's *Dune* saga exclusively as a thematic reference and role metaphor. It is not affiliated with, sponsored by, or officially associated with Herbert Properties LLC, Legendary Entertainment, or any rights holders of the franchise. No art, logos, or protected material is reproduced — only concept/role names as a design analogy.
+
+## Why logsayer
+
+The spec-driven pattern (as popularized by GitHub Spec Kit) governs the *first* generation of code. After that, its authority over the code is by convention, not verification. logsayer closes the loop that pattern leaves open:
+
+- **State continuity** between sessions — an anchor snapshot the agent reads (and only that) at session start.
+- **A partitioned, append-only logbook** for the *"why"* of past decisions.
+- **A mechanical + semantic verification loop** that checks whether the code still matches the spec — both structurally and in meaning.
+- **Multi-agent coordination** through the standard `AGENTS.md` convention, with thin native adapters per tool (opencode and Claude Code today).
+
+## The 5 layers
+
+| # | Layer | Question it answers | Dune role |
+|---|-------|--------------------|-----------|
+| 1 | Specification (normative) | What must be built? | Mentat |
+| 2 | State (anchor) | Where is the project right now? | Guild Navigator |
+| 3 | Logbook (historical) | How did we get here, and why? | Reverend Mother |
+| 4 | Verification | Does what was built still match the spec? | Suk Doctor (mechanical) + Truthsayer (semantic) |
+| 5 | Process (operational) | How do we work here? | Fremen |
+
+Every layer has a plain-English alias, so you can use logsayer without knowing any of the lore.
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+uv tool install logsayer
+# or
+pipx install logsayer
+```
+
+## Quick start
+
+```bash
+# 1. Scaffold a new project
+logsayer init my-project
+cd my-project
+
+# 2. Write the spec for a user story
+logsayer spec new HU-01
+
+# 3. Add an agent adapter (opencode, claude)
+logsayer agent add opencode
+
+# 4. Start a session: check state, work the story
+logsayer state show
+# ... implement HU-01 ...
+
+# 5. Close the session: log it, audit when threshold is hit
+logsayer log add "HU-01 done: API + tests"
+logsayer check          # mechanical: structure, no mixed layers
+logsayer audit run      # semantic: spec vs real code report
+```
+
+For an existing project:
+
+```bash
+logsayer init --here
+```
+
+## Commands
+
+| Command | Dune alias | Layer | Purpose |
+|---------|-----------|-------|---------|
+| `logsayer init [name]` | — | scaffold | Creates `docs/` + `AGENTS.md` + `logsayer.toml` |
+| `logsayer init --here` | — | scaffold | Scaffolds into the current directory |
+| `logsayer agent add <opencode\|claude>` | — | coordination | Generates per-role subagents for a tool |
+| `logsayer spec new <hu>` | `logsayer mentat spec new` | 1 | Creates a minimal HU template |
+| `logsayer state show` | `logsayer navigator state show` | 2 | Prints the project snapshot |
+| `logsayer log add "…"` | `logsayer reverend-mother log add` | 3 | Appends a logbook entry (auto-partition) |
+| `logsayer log index` | `logsayer reverend-mother log index` | 3 | Rebuilds `00_index.md` from real files |
+| `logsayer check` | `logsayer suk doctor` | 4 | Mechanical checks: structure, no layer mixing |
+| `logsayer audit run` | `logsayer truthsayer audit run` | 4 | Generates the audit report + semantic prompt |
+| `logsayer audit status` | `logsayer truthsayer audit status` | 4 | Shows HU counter vs threshold, last report |
+| `logsayer process check` | `logsayer fremen verify` | 5 | Process checks: Dor, coordination agreement |
+
+## Configuration (`logsayer.toml`)
+
+Generated by `logsayer init`, tuned in a single file:
+
+```toml
+[logsayer]
+session_close_context_threshold = 0.70   # % context used → propose session close
+bitacora_max_lines = 400                 # lines/logbook file before partitioning
+audit_threshold_hus = 3                  # HUs closed since last audit → trigger audit
+```
+
+## How a session flows
+
+1. **Session start** — the agent reads *only* the state layer (`docs/project_state.md`). Cheap in tokens, enough to orient.
+2. **Audit check** — if the closed-HUs counter meets the threshold, the agent proactively proposes an audit (semantic verification).
+3. **Work** — the agent works a HU reading only its folder under `docs/04_user_stories/`, and only opens a logbook entry when it needs the *"why"* of a past decision.
+4. **Close / commit** — with your prior approval, the agent overwrites the state snapshot and appends to the active logbook.
+5. **Auto-partition** — when the active logbook exceeds the line limit, the next file is created and the master index updated.
+
+## Example session
+
+A full, real transcript — run against a freshly scaffolded project — lives in [`examples/hello-logsayer/`](examples/hello-logsayer/README.md). It walks through scaffold, story creation, logbook entries, verification, and agent adapters, with the actual output of every command.
+
+## Multi-agent design
+
+A single engine (`logsayer/core/`) plus one thin adapter per agent (`logsayer/adapters/<agent>/`) that only translates each tool's native file convention and calls the CLI. Adding a new agent means a new adapter, not new logic. See [`docs/` of this repo](logsayer_especificacion_maestra.md) (master spec) for the full architecture.
+
+## Roadmap
+
+- **0–4 (done):** naming & manifest, `init`, core commands (`spec`, `state`, `log`, `audit`), opencode/Claude adapters, mechanical validation (`check`, `process check`).
+- **5 (current):** documentation & publishing — README, PyPI, MIT, examples. You are here.
+- **6:** community presets, more agents on demand (copilot, cursor, gemini, hermes).
+
+## Acknowledgment & license
+
+- MIT — see [LICENSE](LICENSE).
+- Built around the 5-layer documentary system described in the master spec.
+- Names and concepts from *Dune* are used as a thematic role metaphor only (full disclaimer at the top of this document).

logsayer-0.6.0/docs/01_global/mission.md

@@ -0,0 +1,19 @@
+# Misión y alcance — logsayer
+
+**Mensaje de una línea:** *Spec Kit te dice qué construir. logsayer te dice dónde estás parado, cómo llegaste, y si lo que construiste sigue siendo lo que dijiste que ibas a construir.*
+
+## Problema
+
+Spec Kit y el patrón spec-driven gobiernan la primera generación de código; después, su autoridad sobre el código es por convención, no por verificación. Además, los agentes de IA no tienen memoria persistente entre sesiones: cada sesión arranca sin saber dónde está parado el proyecto ni por qué se tomaron decisiones pasadas.
+
+## Qué resuelve logsayer
+
+1. **Continuidad de estado entre sesiones** — snapshot ancla (`project_state.md`) que el agente lee al arrancar y que se sobrescribe al cerrar, con aprobación previa.
+2. **Bitácora histórica particionable** — el "por qué" de las decisiones, en append-only, con índice y partición automática por tamaño.
+3. **Verificación continua** — mecánica (estructura, no mezcla de capas) y semántica (lo construido sigue siendo lo especificado).
+4. **Coordinación multi-agente** — un motor único + adaptadores finos por herramienta, con `AGENTS.md` como punto de coordinación universal.
+
+## Alcance (qué no es)
+
+- No es un ORM de documentación ni genera documentos de cientos de líneas por defecto: produce el mínimo indispensable (spec §10).
+- El resultado del audit semántico no es determinístico: lo produce un subagente a partir de la estructura y el prompt que genera el CLI (spec §10).

logsayer-0.6.0/docs/02_technical/decisions.md

@@ -0,0 +1,23 @@
+# Decisiones técnicas — logsayer
+
+Registro de las decisiones de arquitectura activas. Cada una tiene su porqué (entrada de logbook en su momento); acá solo la referencia viva.
+
+## D1. Un motor único + adaptadores finos (spec §6)
+
+Toda la lógica vive en `logsayer/core/` y `cli.py`. Los archivos generados por `agent add` son wrappers finos que llaman al CLI — agregar un agente nuevo no duplica lógica. *Referencia: bitácora fase 3.*
+
+## D2. Alias plano como puerta de entrada (spec §13)
+
+`logsayer audit run` ≡ `logsayer truthsayer audit run`. El lore Dune da identidad pero nunca debe ser la única puerta de entrada a la funcionalidad.
+
+## D3. Template mínimo por HU (spec §10)
+
+Un solo `README.md` por HU con "Qué hay que construir" + "Cómo se valida". Nada de documentos de cientos de líneas por defecto (anti "sea of markdown").
+
+## D4. `init --here` en modo adopt (spec §5)
+
+`logsayer init --here` scaffoldea sobre un proyecto existente: crea lo que falta y **no sobrescribe** archivos ya presentes (AGENTS.md, logsayer.toml, estado, índice). Cerrado en el dogfooding del propio repo (fase del marco de sesiones).
+
+## D5. Audit semántico honesto (spec §10)
+
+El CLI genera estructura + prompt; el resultado lo produce un subagente. No se promete determinismo: se documenta. La responsabilidad es generar la estructura del reporte y el prompt, no el veredicto.

logsayer-0.6.0/docs/02_technical/tech-stack.md

@@ -0,0 +1,22 @@
+# Stack técnico — logsayer (fuente: spec §11 y `pyproject.toml`)
+
+| Componente | Elección | Por qué |
+|---|---|---|
+| Lenguaje | Python 3.11+ (`requires-python >=3.11`) | Tipado moderno, ecosistema CLI, targets compatibles |
+| CLI framework | Typer `>=0.12` | Comandos anidados + alias con poco boilerplate |
+| Templates | Jinja2 `>=3.1` | Render de `AGENTS.md`, estado, índice, HUs y adaptadores |
+| Config | TOML (`logsayer.toml`) | Spec §4: umbrales en un solo archivo, parsing nativo (`tomllib`) |
+| Empaquetado | `pyproject.toml` + hatchling | `packages = ["src/logsayer"]`, publicación vía PyPI |
+| Distribución | `uv tool install` / `pipx` | Instalación global de CLIs sin contaminar entornos |
+| Verificación | pytest, ruff, mypy (`--strict`) | Tests + lint + tipado estricto (`pyproject.toml`) |
+
+## Layout
+
+```
+src/logsayer/
+├── cli.py         # comandos Typer + alias planos
+├── config.py      # LogsayerConfig (umbrales)
+├── scaffold.py    # init / modo adopt
+├── core/          # motor único: specs, logbook, audit, suk, fremen, checks, project
+└── adapters/      # por agente: opencode, claude — wrappers finos al CLI
+```

logsayer-0.6.0/docs/03_process/definition-of-ready.md

@@ -0,0 +1,18 @@
+# Definition of Ready — logsayer
+
+Criterios objetivo para considerar una HU lista para trabajar y para cerrar (Capa 5 — Fremen). Reglas del equipo; el framework solo verifica su cumplimiento estructural.
+
+## Para arrancar una HU
+
+- La HU vive en `docs/04_user_stories/HU-XX/` con su README (qué construir + cómo se valida).
+- La fase del roadmap está reflejada en `docs/project_state.md` (Capa 2).
+- El contador de auditoría está por debajo del umbral (`audit status`); si no, se audita antes.
+
+## Para cerrar una HU
+
+- `pytest` pasa completo.
+- `ruff check src tests` pasa.
+- `mypy src` (strict) pasa.
+- `logsayer check` reporta estado sano (estructura y capas).
+- Si el cambio toca el CLI o la estructura: `logsayer fremen verify` sano.
+- Se incrementa el contador de HUs en `project_state.md` y se registra la entrada de logbook.

logsayer-0.6.0/docs/03_process/merge-checklist.md

@@ -0,0 +1,21 @@
+# Checklist de merge — logsayer
+
+Protocolo de integración (Capa 5 — Fremen). Convención del repo: feature branches convergen en `develop`; los releases llevan tag semver.
+
+## Antes de mergear a `develop`
+
+- [ ] Rama originada desde `develop` actualizado.
+- [ ] `pytest` en verde.
+- [ ] `ruff check src tests` en verde.
+- [ ] `mypy src` (strict) en verde.
+- [ ] `logsayer check` sano sobre el repo (dogfooding).
+- [ ] Si corresponde, bump de versión sincronizado entre `pyproject.toml` y `src/logsayer/__init__.py`.
+- [ ] Commit(es) con mensaje conventional (`feat`, `fix`, `docs`, `chore`, `test`, `merge`).
+- [ ] Merge `--no-ff` con mensaje `merge(<fase>): <resumen>`.
+
+## Publicación (PyPI)
+
+- [ ] `python -m build` genera wheel + sdist sin errores.
+- [ ] Instalación en venv limpio: `init` + `check` OK.
+- [ ] Tag semver (`vX.Y.Z`) y push a `origin`.
+- [ ] `uv publish` / `twine upload` con token de `3m1l10j4v13r4qu1n0` (manual).

logsayer-0.6.0/docs/04_user_stories/HU-01/README.md

@@ -0,0 +1,24 @@
+# HU-01 — `logsayer init` y scaffold de la estructura de capas
+
+> Fase 1 del roadmap (MVP). Cerrada: merge `78ad74c` en develop, tag `v0.1.0`.
+
+## Qué hay que construir
+
+El comando `logsayer init <project-name>` (y `init --here`) que scaffoldee, sobre un destino vacío:
+
+- `docs/` con las 7 carpetas de capas (`01_global`, `02_technical`, `03_process`, `04_user_stories`, `05_agile_methodology`, `06_audits`, `logbooks`), cada una con `.gitkeep`.
+- `docs/project_state.md` (Capa 2), `docs/logbooks/00_index.md` (Capa 3, índice vacío).
+- `AGENTS.md` coordinador con los umbrales renderizados del `logsayer.toml`.
+- `logsayer.toml` con los 3 umbrales definidos (spec §4): `session_close_context_threshold = 0.70`, `bitacora_max_lines = 400`, `audit_threshold_hus = 3`.
+
+Validación de entrada: nombre requerido salvo `--here`; slug válido (`[A-Za-z0-9._-]+`); destino no vacío rechazado.
+
+## Cómo se valida
+
+- `pytest` cubre config (`test_config`), scaffold (`test_scaffold`) y CLI (`test_cli`): estructura completa, umbrales renderizados, rechazo de slug inválido y de destino ocupado.
+- `ruff check` y `mypy --strict` pasan.
+- `logsayer check` sobre un proyecto recién scaffoldeado reporta estado sano.
+
+## Log
+
+- `2026-09-24` — merge de fase 1 en `develop` (`78ad74c`). Bump a `v0.1.0`.

logsayer-0.6.0/docs/04_user_stories/HU-02/README.md

@@ -0,0 +1,21 @@
+# HU-02 — Comandos core (spec, log, audit) con alias plano
+
+> Fase 2 del roadmap (comandos core). Cerrada: merge `eae09ec` en develop, tag `v0.2.0`.
+
+## Qué hay que construir
+
+- `logsayer spec new <hu>` — crea la carpeta `04_user_stories/HU-XX/` con un template mínimo de HU (spec §10, sin documentos de cientos de líneas).
+- `logsayer log add "…"` — append en el logbook activo (`docs/logbooks/logbook_<fase>_NN.md`); si supera `bitacora_max_lines`, particiona en `NN+1`.
+- `logsayer log index` — reconstruye `docs/logbooks/00_index.md` desde los archivos reales.
+- `logsayer audit run` — genera la estructura del reporte + prompt semántico en `06_audits/` (el juicio lo produce la Decidora; ver riesgo §10).
+- `logsayer audit status` — contador de HUs vs umbral y último reporte.
+- Registro de los comandos bajo el grupo de rol (`mentat spec new`, `navigator state show`, `reverend-mother log add`, `truthsayer audit run`) Y con alias plano en la raíz (`spec new`, `state show`, `log add`, `audit run`).
+
+## Cómo se valida
+
+- `pytest` cubre specs (`test_specs`), logbook con partición (`test_logbook`), audit (`test_audit`) y los alias por CLI (`test_cli_commands`).
+- `ruff check` y `mypy --strict` pasan.
+
+## Log
+
+- `2026-09-24` — merge de fase 2 en `develop` (`eae09ec`). Bump de versión a `0.2.0` (`b193158`).

logsayer-0.6.0/docs/04_user_stories/HU-03/README.md

@@ -0,0 +1,21 @@
+# HU-03 — Adaptadores multi-agente (opencode y claude)
+
+> Fase 3 del roadmap (adaptadores). Cerrada: merge `196d9eb` en develop, tag `v0.3.0`.
+
+## Qué hay que construir
+
+`logsayer agent add <opencode|claude>` que genere, en la convención nativa de cada herramienta, subagentes por rol (mentat, navigator, reverend-mother, truthsayer) como **wrappers finos**: archivos que invocan al CLI (`logsayer log add "…"`, etc.), sin duplicar lógica del framework (spec §6 y §10 — todo el juicio vive en `logsayer/core/`).
+
+- opencode → `.opencode/agents/<rol>.md`
+- claude → `.claude/agents/<rol>.md`
+
+Registro por agente en un registry desacoplado (`adapters/registry.py`) para permitir sumar agentes nuevos sin tocar el motor. La convención estándar (`AGENTS.md`) queda como el punto de coordinación universal (spec §6).
+
+## Cómo se valida
+
+- `pytest` cubre los adapters (`test_adapters`): registro por nombre, generación de archivos en la ruta nativa, falla controlada para agentes desconocidos.
+- `ruff check` y `mypy --strict` pasan.
+
+## Log
+
+- `2026-09-24` — merge de fase 3 en `develop` (`196d9eb`), poblando primero los entornos propios (opencode y Claude Code), resto por demanda (spec §9).

logsayer-0.6.0/docs/04_user_stories/HU-04/README.md

@@ -0,0 +1,19 @@
+# HU-04 — Validación mecánica (Suk Doctor) y de proceso (Fremen)
+
+> Fase 4 del roadmap (validación). Cerrada: merge `c5fdf66` en develop, tag `v0.4.0`.
+
+## Qué hay que construir
+
+- `logsayer suk doctor` (alias `logsayer check`) — chequeo mecánico determinístico (bot, spec §2): marca de raíz, estructura completa de capas, estado de Capa 2 presente, índice de bitácora, ubicación de las HUs, y **detección de capas mezcladas** (un documento en la capa equivocada). Exit code 1 si algo falla.
+- `logsayer fremen verify` (alias `logsayer process check`) — chequeo de proceso: estado documentado, proceso desplegado, acuerdo de coordinación y Definition of Ready.
+
+Ambos comparten el mismo motor de chequeos (`core/checks.py`) y renderización (`_render_checks` en `cli.py`).
+
+## Cómo se valida
+
+- `pytest` cubre `checks` (`test_checks`), `suk` y `fremen` (`test_cli_commands`): sano con estructura correcta, falla con capas mezcladas o ausentes, exit code 1.
+- `ruff check` y `mypy --strict` pasan.
+
+## Log
+
+- `2026-09-24` — merge de fase 4 en `develop` (`c5fdf66`). Bump a `v0.4.0`.