pumuki 6.3.55 → 6.3.56

package/README.md

@@ -238,87 +238,18 @@ Legacy parity report (strict comparator):
 node --import tsx scripts/build-legacy-parity-report.ts --legacy=<legacy-evidence-path> --enterprise=<enterprise-evidence-path> --out=<output-path>
 ```
 
-## Command Reference
+## Command Paths
 
-### Lifecycle (Consumer)
+Use these docs instead of treating `README.md` as the full command manual:
 
-```bash
-npx --yes pumuki install
-npx --yes pumuki update --latest
-npx --yes pumuki uninstall --purge-artifacts
-npx --yes pumuki remove
-npx --yes pumuki doctor
-npx --yes pumuki status
-```
-
-### SDD / OpenSpec (Consumer)
-
-```bash
-npx --yes pumuki sdd status
-npx --yes pumuki sdd session --open --change=<change-id>
-npx --yes pumuki sdd session --refresh
-npx --yes pumuki sdd session --close
-npx --yes pumuki sdd validate --stage=PRE_COMMIT
-```
-
-### Loop Runner (Consumer)
-
-```bash
-npx --yes pumuki loop run --objective="stabilize gate before commit" --max-attempts=3 --json
-npx --yes pumuki loop status --session=<session-id> --json
-npx --yes pumuki loop stop --session=<session-id> --json
-npx --yes pumuki loop resume --session=<session-id> --json
-npx --yes pumuki loop list --json
-npx --yes pumuki loop export --session=<session-id> --output-json=.audit-reports/loop-session.json
-```
-
-### Stage Gates (Consumer)
-
-```bash
-npx --yes --package pumuki@latest pumuki-pre-write
-npx --yes --package pumuki@latest pumuki-pre-commit
-npx --yes --package pumuki@latest pumuki-pre-push
-npx --yes --package pumuki@latest pumuki-ci
-```
-
-### MCP Servers (Optional, Long-Running)
-
-```bash
-npx --yes --package pumuki@latest pumuki-mcp-evidence
-npx --yes --package pumuki@latest pumuki-mcp-evidence-stdio
-npx --yes --package pumuki@latest pumuki-mcp-enterprise
-npx --yes --package pumuki@latest pumuki-mcp-enterprise-stdio
-```
-
-## Validation and Diagnostics (Framework-Only)
-
-These commands are for maintainers and may require additional arguments, external repo context, or authenticated GitHub access.
-
-```bash
-npm run validation:consumer-ci-artifacts -- --repo <owner/repo>
-npm run validation:consumer-ci-auth-check -- --repo <owner/repo>
-npm run validation:consumer-workflow-lint -- --repo-path <absolute-path-to-consumer-repo>
-npm run validation:consumer-support-bundle -- --repo <owner/repo>
-npm run validation:consumer-support-ticket-draft
-npm run validation:consumer-startup-unblock-status
-npm run validation:consumer-startup-triage -- --repo <owner/repo> --skip-workflow-lint
-npm run validation:mock-consumer-ab-report
-npm run validation:adapter-readiness
-npm run validation:adapter-session-status
-npm run validation:adapter-real-session-report
-npm run validation:phase5-blockers-readiness
-npm run validation:phase5-execution-closure-status
-npm run validation:phase5-execution-closure -- --repo <owner/repo> --skip-workflow-lint
-npm run validation:phase5-external-handoff
-npm run validation:clean-artifacts
-```
-
-Important:
-
-- Several validation scripts intentionally return non-zero when verdict is `BLOCKED`, `PENDING`, or `MISSING_INPUTS`.
-- Non-zero in these scripts is often diagnostic output, not a runtime crash.
-- `validation:consumer-support-ticket-draft` expects an existing support bundle generated by `validation:consumer-support-bundle`.
-- If workflow lint is required in your flow, provide `--repo-path` and `--actionlint-bin`; otherwise use `--skip-workflow-lint`.
+- Installation and bootstrap:
+  - `docs/product/INSTALLATION.md`
+- Daily usage, gates, menu, lifecycle, SDD and troubleshooting:
+  - `docs/product/USAGE.md`
+- Operator-focused short playbook:
+  - `PUMUKI.md`
+- Validation runbooks and framework-only diagnostics:
+  - `docs/validation/README.md`
 
 ## Menu Walkthrough and Screenshots
 
@@ -348,13 +279,13 @@ Important:
 
 Extended annotated walkthrough:
 
-- `docs/operations/framework-menu-option-1-walkthrough.md`
+- `docs/operations/framework-menu-consumer-walkthrough.md`
 
 ## Enterprise Operations Baseline
 
 Pumuki production SaaS operation baseline is defined in:
 
-- `docs/operations/OPERATIONS.md`
+- `docs/operations/production-operations-policy.md`
 
 Highlights:
 
@@ -384,11 +315,11 @@ Highlights:
 - Configuration: `docs/product/CONFIGURATION.md`
 - Code standards: `docs/governance/CODE_STANDARDS.md`
 - Branch protection: `docs/governance/BRANCH_PROTECTION_GUIDE.md`
-- MCP servers: `docs/mcp/MCP_SERVERS.md`
-- MCP evidence server: `docs/mcp/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- MCP consumption: `docs/mcp/MCP_AGENT_CONTEXT_CONSUMPTION.md`
+- MCP servers: `docs/mcp/mcp-servers-overview.md`
+- MCP evidence server: `docs/mcp/evidence-context-server.md`
+- MCP consumption: `docs/mcp/agent-context-consumption.md`
 - Evidence schema v2.1: `docs/mcp/ai-evidence-v2.1-contract.md`
-- Operations policy (SLA/SLO): `docs/operations/OPERATIONS.md`
+- Operations policy (SLA/SLO): `docs/operations/production-operations-policy.md`
 - Release notes: `docs/operations/RELEASE_NOTES.md`
 - Changelog: `CHANGELOG.md`
 

package/VERSION

@@ -1 +1 @@
-v6.3.41
+v6.3.56

package/docs/README.md

@@ -2,27 +2,57 @@
 
 Mapa corto y humano de la documentación oficial de Pumuki.
 
-## Estructura
+## Si buscas algo concreto
+
+- Quiero instalar y arrancar Pumuki en un repo consumidor:
+  - `README.md`
+  - `docs/product/INSTALLATION.md`
+  - `docs/product/USAGE.md`
+
+- Quiero entender cómo funciona por dentro:
+  - `ARCHITECTURE.md`
+  - `docs/product/ARCHITECTURE.md`
+  - `docs/product/HOW_IT_WORKS.md`
+
+- Quiero el contrato técnico de CLI, status, doctor o evidence:
+  - `docs/product/API_REFERENCE.md`
+  - `docs/mcp/ai-evidence-v2.1-contract.md`
+
+- Quiero la parte MCP:
+  - `docs/mcp/mcp-servers-overview.md`
+  - `docs/mcp/evidence-context-server.md`
+  - `docs/mcp/agent-context-consumption.md`
+
+- Quiero operación diaria o releases:
+  - `PUMUKI.md`
+  - `docs/operations/production-operations-policy.md`
+  - `docs/operations/framework-menu-consumer-walkthrough.md`
+  - `docs/operations/RELEASE_NOTES.md`
+
+- Quiero runbooks de validación:
+  - `docs/validation/README.md`
+
+- Quiero saber en qué estamos ahora:
+  - `docs/tracking/estado-ejecutivo.md`
+  - `docs/tracking/plan-activo-de-trabajo.md`
+
+## Estructura oficial
 
 - `docs/product/`
   - Manual funcional y técnico del producto.
-  - Archivos clave: `ARCHITECTURE.md`, `HOW_IT_WORKS.md`, `API_REFERENCE.md`, `INSTALLATION.md`, `USAGE.md`, `CONFIGURATION.md`, `DEPENDENCIES.md`, `TESTING.md`.
+  - Contiene arquitectura, instalación, uso, configuración, testing y referencia API.
 
 - `docs/governance/`
   - Reglas de contribución y gobierno del repo.
-  - Archivos clave: `CODE_STANDARDS.md`, `CONTRIBUTING.md`, `BRANCH_PROTECTION_GUIDE.md`.
 
 - `docs/mcp/`
   - Contratos MCP, evidence y consumo por agentes.
-  - Archivos clave: `MCP_SERVERS.md`, `MCP_EVIDENCE_CONTEXT_SERVER.md`, `MCP_AGENT_CONTEXT_CONSUMPTION.md`, `ai-evidence-v2.1-contract.md`.
 
 - `docs/operations/`
   - Operación diaria, walkthroughs y notas de release.
-  - Archivos clave: `OPERATIONS.md`, `framework-menu-option-1-walkthrough.md`, `RELEASE_NOTES.md`.
 
 - `docs/validation/`
   - Runbooks y contratos estables de validación.
-  - Punto de entrada: `docs/validation/README.md`.
 
 - `docs/rule-packs/`
   - Packs de reglas oficiales por ámbito.
@@ -32,21 +62,20 @@ Mapa corto y humano de la documentación oficial de Pumuki.
 
 - `docs/tracking/`
   - Seguimiento permitido y solo el imprescindible.
-  - Maestro: `docs/tracking/maestro-de-seguimiento.md`
-  - Plan activo: `docs/tracking/plan-activo-pumuki.md`
+  - Maestro: `docs/tracking/estado-ejecutivo.md`
+  - Plan activo: `docs/tracking/plan-activo-de-trabajo.md`
   - Históricos técnicos permitidos:
     - `docs/tracking/historico-validacion-ruralgo-03-03-2026.md`
-    - `docs/tracking/historico-c022-contrato-aceptacion.md`
+    - `docs/tracking/historico-contrato-aceptacion-c022.md`
   - Regla hard: solo puede existir una tarea `🚧` en el plan activo.
 
 ## Fuera de `docs/`
 
-- Gobierno raíz:
-  - `README.md`
-  - `ARCHITECTURE.md`
-  - `CHANGELOG.md`
-  - `AGENTS.md`
-  - `PUMUKI.md`
+- `README.md`
+- `ARCHITECTURE.md`
+- `CHANGELOG.md`
+- `AGENTS.md`
+- `PUMUKI.md`
 
 ## Lo que no se conserva
 

package/docs/mcp/{MCP_AGENT_CONTEXT_CONSUMPTION.md → agent-context-consumption.md}

@@ -183,6 +183,6 @@ Summary facet contract:
 
 ## Related References
 
-- `docs/mcp/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- `docs/mcp/MCP_SERVERS.md`
+- `docs/mcp/evidence-context-server.md`
+- `docs/mcp/mcp-servers-overview.md`
 - `docs/product/API_REFERENCE.md`

package/docs/mcp/{MCP_SERVERS.md → mcp-servers-overview.md}

@@ -275,6 +275,6 @@ npm run test:mcp
 
 ## Referencias
 
-- `docs/mcp/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- `docs/mcp/MCP_AGENT_CONTEXT_CONSUMPTION.md`
+- `docs/mcp/evidence-context-server.md`
+- `docs/mcp/agent-context-consumption.md`
 - `docs/mcp/ai-evidence-v2.1-contract.md`

package/docs/operations/RELEASE_NOTES.md

@@ -1,10 +1,23 @@
 # Release Notes (v2.x line)
 
 This file tracks the active deterministic framework line used in this repository.
-Detailed commit history remains available through Git history (`git log` / `git show`).
+Canonical release chronology lives in `CHANGELOG.md`.
+This file keeps only the operational highlights and rollout notes that matter while running the framework.
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-11 (v6.3.56)
+
+- RuralGo consumer hygiene fix:
+  - `PRE_COMMIT` now restores tracked `.ai_evidence.json` from `HEAD` when that file was not staged before the gate,
+  - the hook no longer injects the refreshed artifact into unrelated commits after a successful run.
+- Operational impact:
+  - closes RuralGo bug `PUMUKI-INC-069`,
+  - minimal commits such as `README.md` stop being contaminated by `.ai_evidence.json` during normal publish/commit flows.
+- Validation evidence:
+  - `node --import tsx --test integrations/git/__tests__/stageRunners.test.ts` (`42 pass / 0 fail`)
+  - `npm run -s typecheck` (`PASS`)
+
 ### 2026-03-06 (v6.3.55)
 
 - Safe remediation for consumers whose repository path breaks `PATH` execution:
@@ -241,7 +254,7 @@ Detailed commit history remains available through Git history (`git log` / `git
   - smoke de instalación local hace fallback cuando `npx --no-install` falla por `MODULE_NOT_FOUND`.
   - `ai_gate_check` unifica hint de precedencia para códigos legacy `EVIDENCE_*` (incluye `EVIDENCE_INTEGRITY_MISSING`).
 - RFC y plan de rollout/rollback:
-  - `docs/validation/ast-intelligence-roadmap.md`.
+  - `docs/validation/ast-intelligence-validation-roadmap.md`.
 - Evidencia de validación:
   - `npx --yes tsx@4.21.0 --test scripts/__tests__/backlog-cli-help-exit-code.test.ts` (`11 pass / 0 fail`)
   - `npm run -s typecheck` (`PASS`)
@@ -452,13 +465,13 @@ Detailed commit history remains available through Git history (`git log` / `git
   - Consumer vs framework-maintainer command surfaces are now explicitly separated.
   - Added collaboration and support/security guidance sections.
 - New stable operations policy:
-  - `docs/operations/OPERATIONS.md` introduces SaaS production operation baseline:
+  - `docs/operations/production-operations-policy.md` introduces SaaS production operation baseline:
     - SLO/SLA minimums
     - incident severity and response windows
     - alerting thresholds and mandatory operational controls
     - go-live and rollback requirements
 - README walkthrough extraction:
-  - detailed menu Option 1 capture narrative moved to `docs/operations/framework-menu-option-1-walkthrough.md`.
+  - detailed menu Option 1 capture narrative moved to `docs/operations/framework-menu-consumer-walkthrough.md`.
   - root README now remains concise while preserving deep visual guidance by reference.
 - Command documentation hardening from end-to-end execution audit:
   - fixed legacy parity command argument format to `--legacy=<path> --enterprise=<path>`.

package/docs/product/API_REFERENCE.md

@@ -292,8 +292,8 @@ Read-only endpoints:
   - deterministic bound: `maxLimit=100`
   - pagination metadata includes `has_more` when `limit` is provided
 
-Reference: `docs/mcp/MCP_EVIDENCE_CONTEXT_SERVER.md`.
-Consumption: `docs/mcp/MCP_AGENT_CONTEXT_CONSUMPTION.md`.
+Reference: `docs/mcp/evidence-context-server.md`.
+Consumption: `docs/mcp/agent-context-consumption.md`.
 
 ## Local execution quick refs
 

package/docs/product/INSTALLATION.md

@@ -3,8 +3,14 @@
 This guide covers the active setup for the deterministic framework implementation in this repository.
 From v2.x, SDD with OpenSpec is part of the default enterprise installation path.
 
+This file is only for installation, bootstrap and first verification.
+For daily operation after setup, use:
+
+- `docs/product/USAGE.md`
+- `PUMUKI.md`
+
 For production SaaS operation requirements (SLO/SLA, incident model, alerting), see:
-- `docs/operations/OPERATIONS.md`
+- `docs/operations/production-operations-policy.md`
 
 ## Prerequisites
 
@@ -114,115 +120,17 @@ npm run adapter:install -- --agent=claude
 
 Supported agents: `codex`, `claude`, `cursor`, `windsurf`, `opencode`.
 
-## Run menu from this framework repository
-
-### Interactive menu
-
-```bash
-npm run framework:menu
-```
-
-Menu starts in `Consumer` mode by default (focused options for day-to-day gate usage).
-Use `A` to switch to the full `Advanced` menu and `C` to switch back.
-Each option includes a short inline description.
-
-Consumer repositories do not have the `framework:menu` npm script by default.
-Use the published binary instead:
-
-```bash
-npx --yes --package pumuki@latest pumuki-framework
-```
-
-### Direct stage runners
-
-```bash
-# PRE_WRITE
-npx --yes --package pumuki@latest pumuki-pre-write
-
-# PRE_COMMIT
-npx --yes --package pumuki@latest pumuki-pre-commit
-
-# PRE_PUSH
-npx --yes --package pumuki@latest pumuki-pre-push
-
-# CI
-npx --yes --package pumuki@latest pumuki-ci
-```
-
-## Lifecycle + SDD commands
-
-```bash
-# package level
-npm install --save-exact pumuki
-npm update pumuki
-npm uninstall pumuki
-
-# lifecycle
-npx --yes pumuki install
-npx --yes pumuki update --latest
-npx --yes pumuki doctor
-npx --yes pumuki status
-npx --yes pumuki uninstall --purge-artifacts
-npx --yes pumuki remove
-
-# sdd
-npx --yes pumuki sdd status
-npx --yes pumuki sdd validate --stage=PRE_WRITE
-npx --yes pumuki sdd validate --stage=PRE_COMMIT
-npx --yes pumuki sdd validate --stage=PRE_PUSH
-npx --yes pumuki sdd validate --stage=CI
-npx --yes pumuki sdd session --open --change=<change-id>
-npx --yes pumuki sdd session --refresh
-npx --yes pumuki sdd session --close
-```
-
-Notes:
-- `pumuki remove` is the deterministic teardown path (`hooks + state + managed artifacts + dependency removal`).
-- Plain `npm uninstall pumuki` removes only the dependency entry.
-- `pumuki update --latest` migrates legacy `openspec` package to `@fission-ai/openspec` when required.
-
-## Guardrails
-
-- `pumuki install` / `pumuki update` block when tracked files exist under `node_modules`.
-- `PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, and `CI` enforce SDD/OpenSpec policy.
-- `PRE_WRITE` also enforces AI Gate checks (evidence freshness/validity and protected branch guardrail).
-
-Emergency bypass (incident-only):
-
-```bash
-PUMUKI_SDD_BYPASS=1 npx --yes pumuki sdd validate --stage=PRE_COMMIT
-```
-
-Remove bypass immediately after remediation.
-
-## CI workflows
-
-The repository ships reusable and platform workflows:
-
-- `.github/workflows/pumuki-gate-template.yml`
-- `.github/workflows/pumuki-ios.yml`
-- `.github/workflows/pumuki-backend.yml`
-- `.github/workflows/pumuki-frontend.yml`
-- `.github/workflows/pumuki-android.yml`
-
-Each run uploads `.ai_evidence.json` artifact.
-
-## MCP servers
-
-```bash
-npm run mcp:evidence
-npm run mcp:enterprise
-```
-
-References:
-- `docs/mcp/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- `docs/mcp/MCP_SERVERS.md`
-
-## Evidence file
+## After installation
 
-Execution writes deterministic state to `.ai_evidence.json`.
+Once bootstrap is complete, move to the operational docs:
 
-Schema reference: `docs/mcp/ai-evidence-v2.1-contract.md`.
+- Daily usage and stage gates:
+  - `docs/product/USAGE.md`
+- Short operator playbook:
+  - `PUMUKI.md`
+- MCP references:
+  - `docs/mcp/mcp-servers-overview.md`
+  - `docs/mcp/evidence-context-server.md`
 
 ## Troubleshooting
 

package/docs/product/USAGE.md

@@ -3,11 +3,16 @@
 This guide describes the deterministic gate flow implemented in this repository.
 From v2.x, SDD with OpenSpec is mandatory for enterprise gate execution.
 
+If you still need to install or bootstrap the framework first, go to:
+
+- `docs/product/INSTALLATION.md`
+- `PUMUKI.md`
+
 Production operations baseline (SLA/SLO, incident response and alerting):
-- `docs/operations/OPERATIONS.md`
+- `docs/operations/production-operations-policy.md`
 
 Visual walkthrough for menu Option 1 captures:
-- `docs/operations/framework-menu-option-1-walkthrough.md`
+- `docs/operations/framework-menu-consumer-walkthrough.md`
 
 ## Prerequisites
 

package/docs/validation/README.md

@@ -5,7 +5,7 @@ Este directorio contiene solo documentación estable de validación y runbooks o
 ## Documentación vigente
 
 - `adapter-hook-runtime-runbook.md`
-- `ast-intelligence-roadmap.md`
+- `ast-intelligence-validation-roadmap.md`
 - `full-repo-detection-audit-baseline.md`
 - `enterprise-consumer-isolation-policy.md`
 - `mock-consumer-integration-runbook.md`
@@ -13,13 +13,13 @@ Este directorio contiene solo documentación estable de validación y runbooks o
 
 ## Estado de seguimiento
 
-- Maestro: `docs/tracking/maestro-de-seguimiento.md`
-- Plan activo: `docs/tracking/plan-activo-pumuki.md`
+- Maestro: `docs/tracking/estado-ejecutivo.md`
+- Plan activo: `docs/tracking/plan-activo-de-trabajo.md`
 - Histórico permitido: `docs/tracking/historico-validacion-ruralgo-03-03-2026.md`
 
 ## Histórico técnico conservado
 
-- `docs/tracking/historico-c022-contrato-aceptacion.md`
+- `docs/tracking/historico-contrato-aceptacion-c022.md`
 
 ## Política de higiene
 
@@ -32,5 +32,6 @@ Este directorio contiene solo documentación estable de validación y runbooks o
 
 ## Comprobaciones útiles
 
+- Higiene hard del worktree propio: `npm run -s validation:self-worktree-hygiene`
 - Suite contractual enterprise: `npm run -s validation:contract-suite:enterprise`
-- Verificación de plan activo único: `npm run -s validation:tracking-single-active`
+- Verificación de plan activo único + higiene hard del worktree propio: `npm run -s validation:tracking-single-active`