pumuki 6.3.7

package/docs/MCP_SERVERS.md

@@ -0,0 +1,114 @@
+# MCP Servers (v2.x)
+
+This repository currently exposes a single active MCP-oriented server implementation:
+
+- **Evidence Context Server** (read-only)
+
+## Evidence Context Server
+
+### Source files
+
+- `integrations/mcp/evidenceContextServer.ts`
+- `integrations/mcp/evidenceContextServer.cli.ts`
+- `integrations/mcp/index.ts`
+
+### Purpose
+
+Expose deterministic evidence (`.ai_evidence.json`) to external agents without allowing writes.
+
+### Contract
+
+- Serves evidence only when file exists and `version === "2.1"`.
+- Returns deterministic JSON payload from local repo root.
+
+### Default runtime
+
+- Host: `127.0.0.1`
+- Port: `7341`
+- Route: `/ai-evidence`
+
+### Endpoints
+
+- `GET /health`
+  - `200 { "status": "ok" }`
+- `GET /status`
+  - `200` with evidence health summary and `context_api` filter/pagination capabilities (including `present`, `valid`, `version`, `stage`, `outcome`, `has_findings`, `tracked_platforms_count`, `detected_platforms_count`, `non_detected_platforms_count`, `suppressed_findings_count`, `suppressed_replacement_rule_platform_pairs_ratio_pct`, `suppressed_non_replacement_rule_platform_pairs_ratio_pct`, and related suppression facets)
+- `GET /ai-evidence`
+  - `200` with evidence payload when valid
+  - `404` when missing or invalid
+- `GET /ai-evidence/summary`
+  - `200` with compact deterministic summary (including `snapshot.has_findings`, `snapshot.findings_files_count`, `snapshot.findings_rules_count`, `snapshot.findings_with_lines_count`, `snapshot.findings_without_lines_count`, `snapshot.severity_counts`, `snapshot.findings_by_platform`, `snapshot.highest_severity`, `snapshot.blocking_findings_count`, `ledger_count`, `ledger_files_count`, `ledger_rules_count`, `ledger_by_platform`, `rulesets_count`, `rulesets_platforms_count`, `rulesets_bundles_count`, `rulesets_hashes_count`, `rulesets_by_platform`, `rulesets_fingerprint`, `platform_confidence_counts`, `suppressed_findings_count`, `suppressed_replacement_rules_count`, `suppressed_platforms_count`, `suppressed_files_count`, `suppressed_rules_count`, `tracked_platforms_count`, `detected_platforms_count`, `non_detected_platforms_count`, `suppressed_replacement_rule_platform_pairs_ratio_pct`, `suppressed_non_replacement_rule_platform_pairs_ratio_pct`)
+  - `404` when missing or invalid
+- `GET /ai-evidence/snapshot`
+  - `200` with deterministic snapshot + findings
+  - `404` when missing or invalid
+- `GET /ai-evidence/findings`
+  - `200` with deterministic findings list
+  - supports `?severity=...&ruleId=...&platform=...`
+  - supports `?limit=...&offset=...` for deterministic pagination
+  - applies deterministic `maxLimit=100` bound
+  - paginated responses include `pagination.has_more`
+  - `404` when missing or invalid
+- `GET /ai-evidence/rulesets`
+  - `200` with deterministic sorted rulesets
+  - supports `?platform=...&bundle=...` for deterministic filtered slices
+  - supports `?limit=...&offset=...` for deterministic pagination (`maxLimit=100`)
+  - paginated responses include `pagination.has_more`
+  - `404` when missing or invalid
+- `GET /ai-evidence/platforms`
+  - `200` with detected platforms only
+  - supports `?detectedOnly=false` for full platform state
+  - supports `?confidence=HIGH|MEDIUM|LOW` for deterministic filtered slices
+  - supports `?limit=...&offset=...` for deterministic pagination (`maxLimit=100`)
+  - paginated responses include `pagination.has_more`
+  - `404` when missing or invalid
+- `GET /ai-evidence/ledger`
+  - `200` with deterministic sorted open-ledger entries
+  - supports `?lastSeenAfter=...&lastSeenBefore=...` for deterministic time-window slices
+  - supports `?limit=...&offset=...` for deterministic pagination (`maxLimit=100`)
+  - paginated responses include `pagination.has_more`
+  - `404` when missing or invalid
+
+### Run locally
+
+```bash
+npm run mcp:evidence
+```
+
+Or directly:
+
+```bash
+npx tsx integrations/mcp/evidenceContextServer.cli.ts
+```
+
+### Environment variables
+
+- `PUMUKI_EVIDENCE_HOST`
+- `PUMUKI_EVIDENCE_PORT`
+- `PUMUKI_EVIDENCE_ROUTE`
+
+Example:
+
+```bash
+PUMUKI_EVIDENCE_PORT=7342 npm run mcp:evidence
+```
+
+## Testing
+
+Server behavior is covered in:
+
+- `integrations/mcp/__tests__/evidenceContextServer.test.ts`
+
+Run:
+
+```bash
+npm run test:mcp
+```
+
+## Scope note
+
+Legacy MCP references (older automation/watcher services) are not part of the active v2.x documentation surface.
+
+Consumption pattern reference:
+
+- `docs/MCP_AGENT_CONTEXT_CONSUMPTION.md`

package/docs/README.md

@@ -0,0 +1,85 @@
+# Documentation Index (v2.x)
+
+This index is the canonical entry point for framework documentation in this repository.
+
+Language baseline: active repository documentation is maintained in English.
+
+## Core Architecture
+
+- `ARCHITECTURE.md`: normative architecture contract and layer boundaries.
+- `ARCHITECTURE_DETAILED.md`: deeper implementation-level architecture details.
+- `HOW_IT_WORKS.md`: operational flow from facts to evidence.
+- `API_REFERENCE.md`: exported APIs and integration entrypoints.
+- `AST_HEURISTICS_REINTRODUCTION_PLAN.md`: staged plan for semantic heuristics.
+
+## Configuration and Operations
+
+- `INSTALLATION.md`: installation and bootstrap.
+- `USAGE.md`: daily usage patterns and stage execution.
+- `CONFIGURATION.md`: runtime and repository configuration.
+- `CONTRIBUTING.md`: contribution standards and guardrails.
+- `CODE_STANDARDS.md`: coding conventions for v2.x work.
+- `DEPENDENCIES.md`: dependency policy and maintenance notes.
+- `TESTING.md`: validation strategy and test command matrix.
+- `BRANCH_PROTECTION_GUIDE.md`: branch protection policy and setup.
+- `skills-repo-enforcement-migration.md`: migration path for skills enforcement.
+
+## Evidence and Integrations
+
+- `evidence-v2.1.md`: deterministic evidence schema and behavior.
+- `MCP_EVIDENCE_CONTEXT_SERVER.md`: evidence context server contract.
+- `MCP_SERVERS.md`: MCP integration overview.
+- `MCP_AGENT_CONTEXT_CONSUMPTION.md`: deterministic pre-action context consumption pattern for agents.
+
+## Rule Packs
+
+- `rule-packs/README.md`: rule pack versions and override model.
+- `rule-packs/ios.md`
+- `rule-packs/backend.md`
+- `rule-packs/frontend.md`
+- `rule-packs/android.md`
+- `rule-packs/heuristics.md`
+
+## Validation and Runbooks
+
+- `validation/README.md`: validation docs policy.
+- `validation/consumer-ci-startup-failure-playbook.md`
+- `validation/consumer-startup-escalation-handoff-latest.md`
+- `validation/phase5-execution-closure.md`
+- `validation/phase8-external-rollout-pack.md`
+- `validation/phase8-post-billing-reactivation-runbook.md`
+- `validation/adapter-hook-runtime-validation.md`
+- `validation/adapter-hook-runtime-local-report.md`
+- `validation/adapter-real-session-report-template.md`
+- `validation/enterprise-consumer-isolation-policy.md`
+- `validation/mock-consumer-integration-runbook.md`
+- `validation/github-support-ticket-template-startup-failure.md`
+- `validation/skills-rollout-consumer-repositories.md`
+- `validation/archive/README.md`: historical validation reports.
+
+## Vendored Codex Skills
+
+- `codex-skills/swift-concurrency.md`
+- `codex-skills/swiftui-expert-skill.md`
+- `codex-skills/windsurf-rules-android.md`
+- `codex-skills/windsurf-rules-backend.md`
+- `codex-skills/windsurf-rules-frontend.md`
+- `codex-skills/windsurf-rules-ios.md`
+
+## Assets
+
+- `images/README.md`: visual asset inventory and usage notes.
+
+## Change Tracking
+
+- `RELEASE_NOTES.md`: v2.x release notes and rollout checkpoints.
+- `TODO.md`: active operational work tracking.
+- `REFRACTOR_PROGRESS.md`: linear phase-by-phase status (done/in-progress/pending).
+
+## Root-Level Pointers
+
+- `README.md` (repository root) is the product-facing overview.
+- `ARCHITECTURE.md` (repository root) is a conceptual shortcut; use this index and `docs/ARCHITECTURE.md` for canonical references.
+- `CHANGELOG.md` (repository root) tracks top-level package changes for the active baseline.
+- `AGENTS.md` (repository root) defines repository execution constraints for coding agents.
+- `CLAUDE.md` (repository root) provides a concise agent profile aligned with repository policies.

package/docs/REFRACTOR_PROGRESS.md

@@ -0,0 +1,155 @@
+# Refactor Progress Tracker
+
+Estado consolidado del refactor con seguimiento de tareas y evidencia del avance.
+
+## Leyenda
+- ✅ Completada
+- 🚧 En progreso
+- ⏳ Pendiente
+
+## Fase 1 — Crítico (bloquea release)
+- ✅ Corregir `jest.config.js` para descubrir y ejecutar tests TS reales de Jest (`*.spec.ts`) con `babel-jest`.
+- ✅ Validar ejecución de suites tras corrección: suites y pruebas recuperadas, cobertura global `4.12%`.
+- ✅ Definir baseline mínimo de cobertura para rutas críticas (`gate`, `evidence`, `heuristics`).
+
+## Fase 2 — Alto (calidad)
+- ⏳ Dividir `integrations/mcp/evidenceFacets.ts` por dominios de facetas.
+- ⏳ Dividir `integrations/mcp/evidencePayloads.ts` por builders/contextos.
+- ✅ Particionar `integrations/gate/__tests__/stagePolicies-promotions-first.test.ts` en suites pequeñas.
+- ✅ Particionar `integrations/gate/__tests__/stagePolicies-promotions-second.test.ts` en suites pequeñas.
+- ✅ Particionar `integrations/gate/__tests__/stagePolicies-promotions-third.test.ts` en suites pequeñas.
+- ✅ Consolidar micro-módulos redundantes en `scripts/`:
+  - `consumer-support-bundle-gh-*`
+  - `framework-menu-runners-validation-*`
+  - `consumer-support-bundle-markdown-sections-*`
+- ⏳ Reducir backlog de archivos sin test en `core/` e `integrations/`.
+- ✅ Añadir test unitario para `integrations/git/runPlatformGateOutput.ts`.
+- ✅ Añadir test unitario para `integrations/git/runPlatformGateFacts.ts`.
+- ✅ Añadir test unitario para `integrations/git/runPlatformGateEvidence.ts`.
+- ✅ Añadir test unitario para `integrations/git/runPlatformGateEvaluation.ts`.
+- ✅ Añadir test unitario para `integrations/git/runPlatformGate.ts`.
+- ✅ Añadir test unitario para `integrations/git/getCommitRangeFacts.ts`.
+- ✅ Añadir test unitario para `integrations/git/baselineRuleSets.ts`.
+- ✅ Añadir test unitario para `integrations/git/GitService.ts`.
+- ✅ Añadir test unitario para `integrations/git/runCliCommand.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciIOS.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciAndroid.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciBackend.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciFrontend.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitIOS.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitAndroid.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitBackend.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitFrontend.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushIOS.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushAndroid.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushBackend.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushFrontend.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushIOS.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushAndroid.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushBackend.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/prePushFrontend.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitIOS.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitAndroid.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitBackend.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/preCommitFrontend.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciIOS.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciAndroid.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciBackend.cli.ts`.
+- ✅ Añadir test unitario para `integrations/git/ciFrontend.cli.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/text/utils.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/text/android.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/text/ios.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/browser/index.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/security/index.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/typescript/index.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/vm/index.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/process/core.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/process/shell.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/process/spawn.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/callbacks.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/promises.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart1.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart1Metadata.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart1FileOps.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart1DirTimes.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart2.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart2Core.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart2Permissions.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart2Io.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart2Times.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart3.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart3DescriptorIo.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart3Links.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/syncPart3PathOps.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/fs/sync.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/process/index.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/security/securityCredentials.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/security/securityCrypto.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/security/securityJwt.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/security/securityTls.ts`.
+- ✅ Añadir test unitario para `core/facts/detectors/utils/astHelpers.ts`.
+- ✅ Añadir test unitario para `core/facts/index.ts`.
+- ✅ Añadir test unitario para `core/facts/Fact.ts`.
+- ✅ Añadir test unitario para `core/facts/FactSet.ts`.
+- ✅ Añadir test unitario para `core/facts/FileChangeFact.ts`.
+- ✅ Añadir test unitario para `core/facts/FileContentFact.ts`.
+- ✅ Añadir test unitario para `core/facts/DependencyFact.ts`.
+- ✅ Añadir test unitario para `core/facts/HeuristicFact.ts`.
+- ✅ Añadir test unitario para `core/gate/Finding.ts`.
+- ✅ Añadir test unitario para `core/gate/GateOutcome.ts`.
+- ✅ Añadir test unitario para `core/gate/GatePolicy.ts`.
+- ✅ Añadir test unitario para `core/gate/GateStage.ts`.
+- ✅ Añadir test unitario para `core/gate/conditionMatches.ts`.
+- ✅ Añadir test unitario para `core/gate/evaluateRules.ts`.
+- ✅ Añadir test unitario para `core/gate/evaluateGate.ts`.
+- ✅ Añadir test unitario para `core/gate/index.ts`.
+- ✅ Añadir test unitario para `core/rules/Condition.ts`.
+- ✅ Añadir test unitario para `core/rules/Consequence.ts`.
+- ✅ Añadir test unitario para `core/rules/RuleDefinition.ts`.
+- ✅ Añadir test unitario para `core/rules/RuleSet.ts`.
+- ✅ Añadir test unitario para `core/rules/Severity.ts`.
+- ✅ Añadir test unitario para `core/rules/index.ts`.
+- ✅ Añadir test unitario para `core/rules/presets/index.ts`.
+- ✅ Añadir test unitario para `core/rules/presets/rulePackVersions.ts`.
+- ✅ Añadir test unitario para `core/rules/presets/androidRuleSet.ts`.
+- ✅ Añadir test unitario para `core/rules/presets/backendRuleSet.ts`.
+- ✅ Añadir test unitario para `core/rules/presets/frontendRuleSet.ts`.
+- ✅ Añadir test unitario para `core/rules/presets/exampleRuleSet.ts`.
+- ⏳ Añadir test unitario para `core/rules/presets/iosEnterpriseRuleSet.ts`.
+
+## Fase 3 — Medio (deuda técnica)
+- ✅ Reducir acoplamiento en `integrations/git/runPlatformGate.ts`.
+- ✅ Particionar detectores grandes (`core/facts/detectors/fs/sync.ts`, `core/facts/detectors/process/index.ts`).
+- ✅ Resolver ciclos detectados por `madge` en scripts de `phase5`/`mock-consumer`.
+
+## Fase 4 — Bajo (nice-to-have)
+- ✅ Añadir guardrail de tamaño de archivo/imports en CI.
+- ✅ Normalizar documentación mínima en módulos críticos.
+
+## Operaciones de entorno
+- ✅ Convertir `ast-intelligence-hooks` en repositorio Git standalone (sin dependencia de `worktree` legacy).
+- ✅ Verificar integridad post-conversión (`.git` directorio propio, branch/HEAD intactos, estado limpio).
+- ✅ Ejecutar siguiente lote de refactor solicitado por el usuario.
+- ✅ Ejecutar demo end-to-end de Pumuki sobre mock consumer (pack → install → stages).
+- ✅ Validar estado base del mock consumer antes de reinstalar Pumuki.
+- ✅ Resetear `pumuki-mock-consumer` a estado base sin instalación activa de `pumuki`.
+- ✅ Limpiar worktree del mock consumer (tracked restaurado, untracked aislado fuera del repo).
+- ✅ Diagnosticar residuos en mock: `node_modules/pumuki` y `node_modules/.package-lock.json` están versionados (tracked), no ignorados.
+- ✅ Corregir empaquetado NPM para incluir runtime faltante (`core/utils`, heuristics presets, AST detectors) y desbloquear runtime en consumidor mock.
+- ✅ Implementar lifecycle enterprise (`pumuki install|uninstall|update|doctor|status`) con estado local en `git config` y hooks idempotentes.
+- ✅ Integrar guardrail lifecycle round-trip en `validation:package-smoke` (`install -> stages -> uninstall`) con verificación de `git status` estable.
+- ✅ Validar guardrails del lote (`validation:package-manifest`, `validation:package-smoke`, `validation:package-smoke:minimal`).
+- ✅ Alinear el lote de lifecycle con reglas activas del repositorio (cambios mínimos y comportamiento determinista).
+- ✅ Revalidar lifecycle en local (`typecheck`, `lifecycle tests`, `validation:package-manifest`, `validation:lifecycle-smoke`, `validation:package-smoke`).
+- ✅ Corregir `test:mcp` para suite MCP dividida y revalidar `test:deterministic` completo.
+- ✅ Añadir comando de una sola ejecución `pumuki remove` (cleanup + desinstalación de paquete) y validar E2E en consumidor temporal.
+- ✅ Sincronizar documentación afectada por lifecycle (`README`, `CHANGELOG`, `INSTALLATION`, `USAGE`) en el mismo lote.
+- ✅ Endurecer `pumuki remove` para podar residuo huérfano `node_modules/.package-lock.json` y validar con test dedicado.
+- ✅ Completar `pumuki-mock-consumer` con escenarios reproducibles multi-plataforma (`clean`, `violations`, `mixed`) y script de aplicación de escenarios.
+- ✅ Unificar iOS del mock exclusivamente bajo `apps/ios/` (eliminando duplicación `ios/`) para mantener estructura homogénea `apps/*`.
+- ✅ Migrar nombre canónico del paquete a `pumuki` y alinear comandos enterprise cortos (`npm install/update/uninstall pumuki`) con documentación y validaciones.
+- 🚧 Ejecutar matriz E2E completa en `pumuki-mock-consumer` (`install -> pre-commit/pre-push/ci -> remove`) sobre escenarios `clean`, `violations` y `mixed`.
+
+## Notas
+- Estrategia obligatoria: commits atómicos por tarea.
+- Limpieza inmediata de ramas feature tras merge completado.

package/docs/RELEASE_NOTES.md

@@ -0,0 +1,175 @@
+# 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`).
+
+## 2026-02 (enterprise-refactor updates)
+
+### Documentation governance hardening
+
+- Active docs quality guardrails expanded and integrated into stage-gates:
+  - English-only baseline check for active enterprise docs.
+  - Markdown reference-integrity check for active docs.
+  - Root governance docs (`README.md`, `ARCHITECTURE.md`, `CHANGELOG.md`, `CLAUDE.md`) included in active-doc guardrails.
+- Stage-gates command simplified to glob-based test targets for maintainability while preserving deterministic coverage.
+- Root `CHANGELOG.md` normalized to active enterprise v2 baseline to avoid legacy drift.
+
+### Deterministic gate foundation
+
+- Shared execution flow consolidated in `integrations/git/runPlatformGate.ts`.
+- Stage runners unified in `integrations/git/stageRunners.ts`.
+- Stage policies standardized in `integrations/gate/stagePolicies.ts`.
+
+### Multi-platform support
+
+- Combined detection and evaluation for `ios`, `backend`, `frontend`, `android`.
+- Stage wrappers exported for all supported platforms (`PRE_COMMIT`, `PRE_PUSH`, `CI`).
+
+### Evidence v2.1
+
+- Canonical schema and deterministic write path (`snapshot + ledger`).
+- Stable serialization and rule-pack hash traceability.
+- `human_intent` preservation + expiry enforcement.
+
+### CI integration
+
+- Reusable gate workflow template plus platform-specific workflows.
+- Evidence artifact upload standardized across runs.
+- Package-install smoke gate added for published/runtime behavior:
+  - workflow: `.github/workflows/pumuki-package-smoke.yml`
+  - `block` matrix mode validates expected blocking path (`exit 1`, `outcome=BLOCK`)
+  - `minimal` matrix mode validates expected pass path (`exit 0`, `outcome=PASS`)
+  - both modes validate evidence v2.1 stage metadata and upload artifacts
+- Package manifest guardrail added:
+  - command: `npm run validation:package-manifest`
+  - enforces required runtime paths in tarball and forbids legacy/tests/archive diagnostics content
+- Package manifest guardrail internal hardening:
+  - reusable inspection library: `scripts/package-manifest-lib.ts`
+  - regression test coverage in stage-gates:
+    - `scripts/__tests__/package-manifest-lib.test.ts`
+- Framework menu portability hardening:
+  - removed host-specific consumer repo path defaults from `scripts/framework-menu.ts`
+  - added `PUMUKI_CONSUMER_REPO_PATH` support for environment-specific menu defaults
+- Mock consumer validation hardening:
+  - new runbook: `docs/validation/mock-consumer-integration-runbook.md`
+  - formalized package-smoke + manual mock-consumer A/B checklist
+  - validation docs hygiene allowlist updated accordingly
+- Phase 5 mock-closure automation:
+  - `scripts/build-mock-consumer-startup-triage.ts` generates triage + unblock reports from local package-smoke summaries
+  - `validation:phase5-execution-closure` supports `--mock-consumer`
+  - mock mode now includes a deterministic mock consumer A/B report step:
+    - output: `.audit-reports/phase5/mock-consumer-ab-report.md`
+  - mock mode disables external GH preflight/workflow-lint by default and keeps closure flow deterministic
+  - local mock execution now reaches:
+    - `phase5-blockers-readiness` => `verdict=READY`
+    - `phase5-execution-closure-status` => `verdict=READY`
+- Mock consumer A/B validation automation:
+  - `scripts/build-mock-consumer-ab-report.ts` validates block/minimal smoke outcomes plus evidence v2.1 contract
+  - command: `npm run validation:mock-consumer-ab-report -- --repo <owner>/<repo>`
+  - output: `.audit-reports/mock-consumer/mock-consumer-ab-report.md`
+  - framework menu action:
+    - `Build mock consumer A/B validation report`
+- Phase5 mock-closure CI hardening:
+  - workflow: `.github/workflows/pumuki-phase5-mock.yml`
+  - deterministic sequence: package smoke (`block`, `minimal`) -> phase5 mock closure one-shot
+  - artifact bundle: `phase5-mock-closure`
+  - workflow contract guardrail:
+    - `scripts/__tests__/phase5-mock-workflow-contract.test.ts`
+
+### AST heuristics pilot
+
+- Typed heuristic facts extracted in core domain.
+- Declarative heuristic rule-pack with optional feature flag.
+- iOS force-cast (`as!`) heuristic added to coverage.
+- Stage-aware heuristic maturity:
+  - `PRE_COMMIT`: heuristic findings remain `WARN`
+  - `PRE_PUSH` / `CI`: selected heuristics promoted to `ERROR`
+
+### Documentation cleanup
+
+- Primary and secondary docs rewritten to v2.x model:
+  - `README.md`
+  - `docs/USAGE.md`
+  - `docs/HOW_IT_WORKS.md`
+  - `docs/API_REFERENCE.md`
+
+### Hardening and validation updates (latest)
+
+- Evidence consolidation hardened:
+  - deterministic file-level collapse across same semantic family, including same-rule multi-line duplicates
+  - additive `consolidation.suppressed[]` trace for auditability
+- MCP evidence server expanded with compact/full filters:
+  - `includeSuppressed=false`
+  - `view=compact|full`
+- IDE adapter cascade-hook runtime hardening (Adapter baseline):
+  - robust Node resolver wrapper
+  - optional strict mode `PUMUKI_HOOK_STRICT_NODE=1`
+  - explicit diagnostics (`--diagnose`, `PUMUKI_HOOK_DIAGNOSTIC=1`)
+  - local diagnostics collector + repeatable local simulation command:
+    - `npm run validate:adapter-hooks-local`
+  - provider-agnostic alias commands:
+    - `npm run validation:adapter-session-status`
+    - `npm run validation:adapter-real-session-report`
+  - real-session validation checklist:
+    - `docs/validation/adapter-hook-runtime-validation.md`
+- Consumer startup diagnostics one-shot orchestrator:
+  - `npm run validation:consumer-startup-triage`
+- Phase 5 blockers readiness report:
+  - `npm run validation:phase5-blockers-readiness`
+  - Adapter report is optional by default; use `--require-adapter-report` for strict adapter-mode gating.
+  - deterministic verdicts: `READY | BLOCKED | MISSING_INPUTS`
+- Phase 5 execution closure status snapshot:
+  - `npm run validation:phase5-execution-closure-status`
+  - deterministic verdicts: `READY | BLOCKED | MISSING_INPUTS`
+  - framework menu action:
+    - `Build phase5 execution closure status report`
+- Phase 5 execution closure one-shot orchestration:
+  - `npm run validation:phase5-execution-closure`
+  - executes adapter diagnostics (optional), consumer startup triage, blockers readiness, and closure status in one command
+  - includes consumer auth/scope preflight and fail-fast behavior before triage
+  - optional bypass: `--skip-auth-preflight`
+  - emits deterministic run summary (recommended out-dir): `.audit-reports/phase5/phase5-execution-closure-run-report.md`
+  - framework menu action:
+    - `Run phase5 execution closure (one-shot orchestration)`
+- Phase 5 external handoff report:
+  - `npm run validation:phase5-external-handoff`
+  - deterministic verdicts: `READY | BLOCKED | MISSING_INPUTS`
+  - optional strict flags:
+    - `--require-mock-ab-report`
+    - `--require-artifact-urls`
+  - framework menu action:
+    - `Build phase5 external handoff report`
+- Adapter-only readiness report:
+  - `npm run validation:adapter-readiness`
+  - deterministic verdicts: `READY | BLOCKED | PENDING`
+- IDE-agnostic gate boundary hardening:
+  - runtime boundary test in `integrations/git/__tests__/ideAgnosticBoundary.test.ts`
+  - explicit architecture/docs contract that IDE diagnostics remain optional adapters
+- Active docs governance hardening:
+  - provider-agnostic docs guardrail test:
+    - `scripts/__tests__/enterprise-docs-agnostic.test.ts`
+  - docs index coverage guardrail test:
+    - `scripts/__tests__/docs-index-coverage.test.ts`
+- Compatibility command hardening:
+  - legacy provider-named hook scripts now delegate to adapter-native scripts in `package.json`
+  - regression guardrail:
+    - `scripts/__tests__/adapter-script-aliases.test.ts`
+- Provider-agnostic legacy ruleset resolution:
+  - `integrations/git/resolveLegacyRulesetFile.ts`
+  - discovers legacy tooling rule directories without provider-specific hardcoding
+  - regression guardrail:
+    - `integrations/git/__tests__/resolveLegacyRulesetFile.test.ts`
+- Phase 5 execution closure runbook:
+  - `docs/validation/phase5-execution-closure.md`
+- Validation artifact hygiene helper:
+  - `npm run validation:clean-artifacts` (`--dry-run` supported)
+  - cleans local generated `docs/validation/**/artifacts` directories and `.audit_tmp`
+  - framework menu action:
+    - `Clean local validation artifacts`
+- Rule-pack docs drift prevention:
+  - automated version sync test `scripts/__tests__/rule-pack-docs-sync.test.ts`
+
+## Notes
+
+- Legacy 5.3.4 migration/release notes were removed from active docs to avoid drift.
+- Historical commit trace remains available in Git history.

package/docs/TESTING.md

@@ -0,0 +1,101 @@
+# Testing Guide (v2.x)
+
+This guide documents the active deterministic test surface.
+
+## Core commands
+
+```bash
+npm run typecheck
+npm run test:evidence
+npm run test:mcp
+npm run test:heuristics
+npm run test:deterministic
+npm run validation:package-manifest
+npm run validation:package-smoke
+npm run validation:package-smoke:minimal
+npm run validation:lifecycle-smoke
+```
+
+## What each suite validates
+
+- `npm run typecheck`
+  - TypeScript compile checks for production sources (`core/**/*.ts`, `integrations/**/*.ts`).
+
+- `npm run test:evidence`
+  - Deterministic evidence behavior (`snapshot`, `ledger`, `human_intent`).
+
+- `npm run test:mcp`
+  - Read-only evidence context server behavior.
+
+- `npm run test:heuristics`
+  - Typed AST heuristic fact extraction coverage across platforms.
+
+- `npm run test:deterministic`
+  - Aggregated deterministic suite (`evidence + mcp + heuristics`).
+
+- `npm run validation:package-manifest`
+  - Dry-run package manifest guardrail.
+  - Fails if required runtime files are missing or forbidden paths are bundled (`legacy/`, tests, archive docs, local audit artifacts).
+
+- `npm run validation:package-smoke`
+  - Package-install smoke (`BLOCK` scenario): `npm pack` + temporary consumer install + intentional multi-platform violations.
+  - Validates `pumuki-pre-commit` / `pumuki-pre-push` / `pumuki-ci` blocking path and evidence v2.1 metadata.
+  - Writes artifacts to `.audit-reports/package-smoke/block/`.
+
+- `npm run validation:package-smoke:minimal`
+  - Package-install smoke (`PASS` scenario): `npm pack` + temporary consumer install + clean minimal staged/range path.
+  - Validates allow path (exit `0`) with evidence v2.1 metadata.
+  - Writes artifacts to `.audit-reports/package-smoke/minimal/`.
+
+- `npm run validation:lifecycle-smoke`
+  - Lifecycle round-trip smoke on minimal scenario.
+  - Validates `pumuki install -> stage runners -> pumuki uninstall --purge-artifacts`.
+  - Fails if repo `git status --short` after uninstall differs from pre-install snapshot.
+
+## Test locations
+
+- `integrations/evidence/__tests__/buildEvidence.test.ts`
+- `integrations/evidence/__tests__/humanIntent.test.ts`
+- `integrations/mcp/__tests__/evidenceContextServer.test.ts`
+- `core/facts/__tests__/extractHeuristicFacts.test.ts`
+- `integrations/gate/__tests__/stagePolicies.test.ts`
+
+## Recommended validation before commit
+
+```bash
+npm run typecheck
+npm run test:deterministic
+```
+
+## CI alignment
+
+Workflows rely on the same deterministic model and should remain consistent with local commands:
+
+- `.github/workflows/pumuki-evidence-tests.yml`
+- `.github/workflows/pumuki-heuristics-tests.yml`
+- `.github/workflows/pumuki-gate-template.yml`
+- `.github/workflows/pumuki-package-smoke.yml`
+
+## Adding tests
+
+### Principles
+
+- Keep tests deterministic and side-effect free.
+- Prefer `node:test` for TypeScript files executed with `tsx`.
+- Keep domain tests in `core/*` and adapter tests in `integrations/*`.
+- Validate behavior, not implementation details.
+
+### Minimal `node:test` example
+
+```ts
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+test('example', () => {
+  assert.equal(1 + 1, 2);
+});
+```
+
+## Legacy note
+
+A legacy `npm test` (Jest) command exists in `package.json`, but the v2.x deterministic baseline is governed by the explicit `test:*` scripts listed above.