pumuki 6.3.17 → 6.3.19

package/README.md

@@ -1,162 +1,165 @@
 # Pumuki
 
+![Pumuki](assets/logo.png)
+
 [![npm version](https://img.shields.io/npm/v/pumuki?color=1d4ed8)](https://www.npmjs.com/package/pumuki)
 [![CI](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
 
 Enterprise governance framework for AI-assisted software delivery.
 
-Pumuki enforces deterministic decisions across local hooks, PRE_WRITE guardrails, and CI using one execution model:
+Pumuki gives engineering teams one deterministic execution model across local development, hooks, and CI:
 
-`Facts -> Rules -> Gate -> ai_evidence v2.1`
+`Facts -> Rules -> Gate -> .ai_evidence.json (v2.1)`
 
-## What Pumuki Solves
+## Who This README Is For
 
-Pumuki gives teams a single operational contract for AI-era code quality:
+| Profile | Use this path first |
+|---|---|
+| Consumer repository team | [5-Minute Quick Start (Consumer)](#5-minute-quick-start-consumer) |
+| Framework maintainers (this repo) | [Framework Maintainer Flow](#framework-maintainer-flow-this-repo) |
+| Platform/architecture owners | [Enterprise Operations Baseline](#enterprise-operations-baseline) |
 
-- Deterministic gate decisions with auditable evidence.
-- Unified stage model: `PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, `CI`.
-- Multi-platform rule evaluation (iOS, Android, Backend, Frontend).
-- Mandatory OpenSpec/SDD policy enforcement.
-- Optional MCP runtime for agent integrations.
+## 5-Minute Quick Start (Consumer)
 
-## Core Capabilities
+Prerequisites:
 
-### 1) Deterministic Gate + Evidence
+- Node.js `>= 18`
+- npm `>= 9`
+- Git repository
 
-Every stage can emit `.ai_evidence.json` with stable structure (`version: 2.1`) including:
+Install and bootstrap:
 
-- `snapshot` (stage/outcome/findings)
-- `ledger` (persistent open violations)
-- `rulesets` and `platforms`
-- `sdd_metrics`
-- `repo_state` (`git` + lifecycle + optional hard mode state)
+```bash
+npm install --save-exact pumuki
+npx --yes pumuki install
+npx --yes pumuki doctor
+npx --yes pumuki status
+```
 
-Reference: `docs/evidence-v2.1.md`.
+OpenSpec/SDD baseline:
 
-### 2) Unified AI Gate for PRE_WRITE/MCP
+```bash
+npx --yes pumuki sdd status
+mkdir -p openspec/changes/<change-id>
+npx --yes pumuki sdd session --open --change=<change-id>
+npx --yes pumuki sdd validate --stage=PRE_COMMIT
+```
 
-The same AI gate evaluator is shared across CLI and MCP:
+Run local gates:
 
-- stale/missing/invalid evidence detection
-- blocked evidence gate status detection
-- protected branch guardrail (`main/master/develop/dev`)
-- policy trace visibility (`default`, `skills.policy`, `hard-mode`)
+```bash
+npx --yes pumuki-pre-write
+npx --yes pumuki-pre-commit
+```
 
-Reference: `integrations/gate/evaluateAiGate.ts`.
+Run push/CI gates (requires proper git context):
 
-### 3) Mandatory OpenSpec + SDD Policy
+```bash
+git push --set-upstream origin <branch>
+npx --yes pumuki-pre-push
+npx --yes pumuki-ci
+```
 
-Pumuki enforces OpenSpec/SDD as first-class guardrails:
+Expected behavior:
 
-- `PRE_WRITE`: OpenSpec installed/project/session valid.
-- `PRE_COMMIT`, `PRE_PUSH`, `CI`: valid session + stage validation.
-- Blocking SDD findings are traceable via `source: "sdd-policy"`.
+- `PRE_WRITE` and `PRE_COMMIT`: should pass when SDD session is valid and rules are satisfied.
+- `PRE_PUSH`: blocks if branch has no upstream tracking reference.
+- `CI`: requires a valid diff range context (not `HEAD..HEAD` with ambiguous range).
 
-### 4) Lifecycle and Enterprise Safety
+## Why Pumuki
 
-Managed lifecycle commands (`install/update/uninstall/remove`) include:
+Modern teams need fast feedback with strict governance. Pumuki combines:
 
-- hook management (`pre-commit`, `pre-push`)
-- OpenSpec bootstrap/migration
-- deterministic evidence bootstrap
-- safety block when tracked files exist under `node_modules/`
+- Deterministic enforcement per stage (`PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, `CI`).
+- A single evidence contract (`.ai_evidence.json`, v2.1) for auditability and automation.
+- Multi-platform governance (iOS, Android, Backend, Frontend).
+- Unified skills engine with deterministic precedence (`core -> repo -> custom`).
+- Mandatory OpenSpec/SDD checks for enterprise change control.
+- Unified CLI plus optional MCP servers for agent-driven workflows.
 
-### 5) Adapter Scaffolding (IDE/Agent)
+## Enterprise Execution Model
 
-Provider-agnostic adapter scaffolding for consumer repositories:
+Each execution follows the same pipeline:
 
-- `codex`
-- `claude`
-- `cursor`
-- `windsurf`
-- `opencode`
+1. Facts extraction from staged/range/repo scope.
+2. Rule evaluation by platform and stage policy.
+3. Gate decision (`PASS`, `WARN`, `BLOCK`) with deterministic thresholds.
+4. Evidence emission (`.ai_evidence.json`) with findings, metadata, and coverage telemetry.
 
-## Quick Start (Consumer Repository)
+Rules resolution order:
 
-Prerequisites:
+1. Core rules (embedded package snapshot).
+2. Repo rules (`skills.lock.json`), optional.
+3. Custom rules (`.pumuki/custom-rules.json`), optional.
 
-- `Node.js >= 18`
-- `npm >= 9`
-- `git`
+Conflict policy:
 
-### 1) Install package
+- `custom > repo > core` (last writer wins by `ruleId`).
+- Platform rules activate only for detected platforms.
+- `generic/text` rules remain available as cross-platform governance guards.
 
-```bash
-npm install --save-exact pumuki
-```
+Rule modes:
 
-### 2) Install managed lifecycle + bootstrap
+- `AUTO`: mapped to deterministic detectors/heuristics.
+- `DECLARATIVE`: valid only when explicitly declared in lock/custom payload (no silent fallback for rules extracted from skills markdown).
 
-```bash
-npx --yes pumuki install
-```
+## Core Capabilities
 
-### 3) Verify environment
+1. Deterministic stage gates with consistent exit semantics.
+2. Evidence v2.1 with rules coverage enforcement and stable ordering.
+3. Unified skills rules engine (core + repo + custom).
+4. Unified AI gate behavior across CLI and MCP surfaces.
+5. Mandatory OpenSpec/SDD policy checks.
+6. Interactive menu UX (consumer + advanced modes).
+7. Hard mode policy hardening (`.pumuki/hard-mode.json` + env overrides).
+8. Lifecycle commands for install/update/diagnostics/teardown.
+9. Provider-agnostic adapter scaffolding (`codex`, `claude`, `cursor`, `windsurf`, `opencode`).
+10. Optional MCP servers for evidence and enterprise context.
 
-```bash
-npx --yes pumuki doctor
-npx --yes pumuki status
-npx --yes pumuki sdd status
-```
+## Framework Maintainer Flow (This Repo)
 
-### 4) Open an SDD session
+Use this only when working in the Pumuki framework repository itself:
 
 ```bash
-npx --yes pumuki sdd session --open --change=<change-id>
+npm run framework:menu
+PUMUKI_MENU_UI_V2=1 npm run framework:menu
+PUMUKI_MENU_MODE=advanced npm run framework:menu
 ```
 
-### 5) Run gates
+Skills engine operations:
 
 ```bash
-npx --yes pumuki-pre-write
-npx --yes pumuki-pre-commit
-npx --yes pumuki-pre-push
-npx --yes pumuki-ci
+npm run skills:compile
+npm run skills:lock:check
+npm run skills:import:custom
+npm run skills:import:custom -- --source <absolute-path-to-SKILL.md> --source <second-absolute-path-to-SKILL.md>
 ```
 
-## Hard Mode (Policy Hardening)
-
-Pumuki supports hard-mode policy resolution via `.pumuki/hard-mode.json`.
-
-Example:
+Adapter scaffolding:
 
-```json
-{
-  "enabled": true,
-  "profile": "critical-high"
-}
+```bash
+npx --yes pumuki adapter install --agent=codex --dry-run
+npx --yes pumuki adapter install --agent=cursor
+npm run adapter:install -- --agent=claude
 ```
 
-Current profile support:
-
-- `critical-high`
-
-Environment overrides:
+Operational matrix/canary:
 
-- `PUMUKI_HARD_MODE` (`true|false|1|0|on|off`)
-- `PUMUKI_HARD_MODE_PROFILE` (`critical-high`)
-
-Runtime traceability:
-
-- policy trace is exposed in AI Gate outputs
-- hard mode state is captured in `repo_state.lifecycle.hard_mode`
-
-## PRE_WRITE Contract
+```bash
+node --import tsx -e "const mod = await import('./scripts/framework-menu-matrix-runner-lib.ts'); const report = await mod.default.runConsumerMenuMatrix({ repoRoot: process.cwd() }); console.log(JSON.stringify(report, null, 2));"
+node --import tsx -e "const mod = await import('./scripts/framework-menu-matrix-canary-lib.ts'); const report = await mod.default.runConsumerMenuCanary({ repoRoot: process.cwd() }); console.log(JSON.stringify(report, null, 2));"
+```
 
-For deterministic pre-write integrations:
+Legacy parity report (strict comparator):
 
 ```bash
-npx --yes pumuki sdd validate --stage=PRE_WRITE --json
+node --import tsx scripts/build-legacy-parity-report.ts --legacy=<legacy-evidence-path> --enterprise=<enterprise-evidence-path> --out=<output-path>
 ```
 
-Returns a chained envelope with:
-
-- `sdd`
-- `ai_gate`
-- `telemetry.chain = "pumuki->ai_gate->ai_evidence"`
+## Command Reference
 
-## Lifecycle Commands
+### Lifecycle (Consumer)
 
 ```bash
 npx --yes pumuki install
@@ -167,125 +170,157 @@ npx --yes pumuki doctor
 npx --yes pumuki status
 ```
 
-Important:
-
-- `pumuki remove` is the full teardown path (hooks + artifacts + dependency cleanup logic).
-- `npm uninstall pumuki` only removes dependency entries.
-
-## Adapter Commands
+### SDD / OpenSpec (Consumer)
 
 ```bash
-npx --yes pumuki adapter install --agent=codex --dry-run
-npx --yes pumuki adapter install --agent=cursor
-npm run adapter:install -- --agent=claude
+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
 ```
 
-## MCP Servers (Optional)
-
-Pumuki core does not depend on MCP, but MCP is available for external agents.
-
-Evidence MCP:
+### Stage Gates (Consumer)
 
 ```bash
-npx --yes pumuki-mcp-evidence
+npx --yes pumuki-pre-write
+npx --yes pumuki-pre-commit
+npx --yes pumuki-pre-push
+npx --yes pumuki-ci
 ```
 
-Enterprise MCP:
+### MCP Servers (Optional, Long-Running)
 
 ```bash
+npx --yes pumuki-mcp-evidence
 npx --yes pumuki-mcp-enterprise
 ```
 
-References:
+## Validation and Diagnostics (Framework-Only)
 
-- `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- `docs/MCP_SERVERS.md`
-- `docs/MCP_AGENT_CONTEXT_CONSUMPTION.md`
-
-## Framework Repository (This Repo)
+These commands are for maintainers and may require additional arguments, external repo context, or authenticated GitHub access.
 
 ```bash
-git clone https://github.com/SwiftEnProfundidad/ast-intelligence-hooks.git
-cd ast-intelligence-hooks
-npm ci
+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
 ```
 
-Recommended baseline:
+Important:
 
-```bash
-npm run typecheck
-npm run test
-npm run test:deterministic
-npm run validation:package-manifest
-npm run skills:lock:check
-```
+- 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`.
 
-Interactive menu:
+## Menu Walkthrough and Screenshots
 
-```bash
-npm run framework:menu
-```
+### Capture 1 — Consumer Menu (v2)
 
-Consumer repositories typically run:
+![Consumer Menu v2](assets/readme/menu-option1/01-menu-consumer-v2.png)
 
-```bash
-npx --yes pumuki-framework
-```
+### Capture 2 — Option 1 Pre-flight (BLOCK context)
 
-## Published Binaries
+![Option 1 Pre-flight Block](assets/readme/menu-option1/02-option1-preflight-block.png)
 
-- `pumuki`
-- `pumuki-framework`
-- `pumuki-pre-write`
-- `pumuki-pre-commit`
-- `pumuki-pre-push`
-- `pumuki-ci`
-- `pumuki-mcp-evidence`
-- `pumuki-mcp-enterprise`
+### Capture 3 — Option 1 Final Summary (BLOCK)
 
-## Troubleshooting
+![Option 1 Final Summary Block](assets/readme/menu-option1/03-option1-final-summary-block.png)
 
-Hook/lifecycle drift:
+### Capture 4 — Option 1 Pre-flight (PASS scenario)
 
-```bash
-npx --yes pumuki doctor
-npx --yes pumuki status
-```
+![Option 1 Pre-flight Pass Scenario](assets/readme/menu-option1/04-option1-preflight-pass.png)
 
-Missing upstream for `PRE_PUSH`:
+### Capture 5 — Option 1 Final Summary (PASS)
 
-```bash
-git push --set-upstream origin <branch>
-```
+![Option 1 Final Summary Pass](assets/readme/menu-option1/05-option1-final-summary-pass.png)
 
-Emergency SDD bypass (incident-only):
+### Capture 6 — Menu Status After PASS Run
 
-```bash
-PUMUKI_SDD_BYPASS=1 npx --yes pumuki sdd validate --stage=PRE_COMMIT
-```
+![Menu After Pass Run](assets/readme/menu-option1/06-menu-after-run-pass.png)
+
+Extended annotated walkthrough:
 
-## Documentation Map
+- `docs/README_MENU_WALKTHROUGH.md`
 
-Primary index: `docs/README.md`
+## Enterprise Operations Baseline
 
-Core docs:
+Pumuki production SaaS operation baseline is defined in:
 
-- `docs/ARCHITECTURE.md`
-- `docs/INSTALLATION.md`
-- `docs/USAGE.md`
-- `docs/CONFIGURATION.md`
-- `docs/API_REFERENCE.md`
-- `docs/evidence-v2.1.md`
-- `docs/MCP_SERVERS.md`
-- `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- `docs/validation/README.md`
+- `docs/OPERATIONS.md`
 
-Contributor docs:
+Highlights:
 
-- `docs/CONTRIBUTING.md`
-- `docs/CODE_STANDARDS.md`
-- `CHANGELOG.md`
+- Minimum SLO/SLA targets for ingestion availability, latency, freshness, and isolation.
+- Severity model (`SEV1/SEV2/SEV3`) with response and RCA expectations.
+- Mandatory controls for tenant/repo isolation, auth policy, idempotency, and auditing.
+- Go-live checklist and rollback requirements.
+
+## Troubleshooting
+
+- `OpenSpec change "<id>" not found`: ensure `openspec/changes/<id>` exists before opening session.
+- `SDD_SESSION_MISSING`: open and validate session first.
+- `pre-push blocked: branch has no upstream`: run `git push --set-upstream origin <branch>`.
+- `Missing required argument --repo` / `--repo-path`: pass required flags for validation scripts.
+- Legacy parity report usage requires `--legacy=<path>` and `--enterprise=<path>` (equals form).
+- If menu v2 rendering fails, Pumuki falls back to classic UI.
+
+## Documentation Index
+
+- Installation: `docs/INSTALLATION.md`
+- Usage: `docs/USAGE.md`
+- Testing: `docs/TESTING.md`
+- API reference: `docs/API_REFERENCE.md`
+- Architecture: `docs/ARCHITECTURE.md`
+- Configuration: `docs/CONFIGURATION.md`
+- Code standards: `docs/CODE_STANDARDS.md`
+- Branch protection: `docs/BRANCH_PROTECTION_GUIDE.md`
+- MCP servers: `docs/MCP_SERVERS.md`
+- MCP evidence server: `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`
+- MCP consumption: `docs/MCP_AGENT_CONTEXT_CONSUMPTION.md`
+- Evidence schema v2.1: `docs/evidence-v2.1.md`
+- Operations policy (SLA/SLO): `docs/OPERATIONS.md`
+- Release notes: `docs/RELEASE_NOTES.md`
+- Changelog: `CHANGELOG.md`
+
+## Collaboration
+
+Contributions are welcome. For high-quality collaboration:
+
+1. Read `docs/CONTRIBUTING.md` and `docs/CODE_STANDARDS.md`.
+2. Create a dedicated branch per change.
+3. Keep scope focused and include deterministic evidence when relevant.
+4. Before opening a PR, run at least:
+   - `npm run typecheck`
+   - `npm run test:operational-memory`
+   - `npm run test:saas-ingestion`
+5. Open a PR with clear problem statement, approach, and validation evidence.
+
+## Support and Security
+
+- Functional/usage issues: open a GitHub issue with reproducible steps.
+- Enterprise diagnostics: include generated reports from `.audit-reports` when applicable.
+- Security-sensitive findings: use GitHub Security Advisories for coordinated disclosure.
 
 ## License
 
-MIT (`LICENSE`)
+MIT. See `LICENSE`.
+
+## If Pumuki Helped You
+
+If this project was useful for your team, please consider leaving a GitHub star:
+
+[Star Pumuki on GitHub](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks)

package/VERSION

@@ -1 +1 @@
-v6.3.17
+v6.3.19

package/assets/benchmarks/c021-baseline-precommit-v001-baseline.json

@@ -0,0 +1,145 @@
+{
+  "stage": "PRE_COMMIT",
+  "audit_mode": "engine",
+  "outcome": "BLOCK",
+  "files_scanned": 987,
+  "total_violations": 146,
+  "by_enterprise_severity": {
+    "CRITICAL": 42,
+    "HIGH": 44,
+    "MEDIUM": 60,
+    "LOW": 0
+  },
+  "rules_coverage": {
+    "active": 417,
+    "evaluated": 417,
+    "unevaluated": 0,
+    "coverage_ratio": 1
+  },
+  "top_rules": [
+    {
+      "ruleId": "common.types.unknown_without_guard",
+      "count": 60
+    },
+    {
+      "ruleId": "common.types.undefined_in_base_type",
+      "count": 33
+    },
+    {
+      "ruleId": "common.types.record_unknown_requires_type",
+      "count": 26
+    },
+    {
+      "ruleId": "common.network.missing_error_handling",
+      "count": 6
+    },
+    {
+      "ruleId": "common.error.empty_catch",
+      "count": 4
+    },
+    {
+      "ruleId": "skills.backend.no-empty-catch",
+      "count": 4
+    },
+    {
+      "ruleId": "skills.frontend.no-empty-catch",
+      "count": 4
+    },
+    {
+      "ruleId": "heuristics.ts.child-process-spawn-sync.ast",
+      "count": 2
+    },
+    {
+      "ruleId": "heuristics.ts.child-process-exec-file-sync.ast",
+      "count": 1
+    },
+    {
+      "ruleId": "heuristics.ts.child-process-exec-file-untrusted-args.ast",
+      "count": 1
+    },
+    {
+      "ruleId": "heuristics.ts.child-process-exec.ast",
+      "count": 1
+    },
+    {
+      "ruleId": "heuristics.ts.dynamic-shell-invocation.ast",
+      "count": 1
+    },
+    {
+      "ruleId": "heuristics.ts.process-exit.ast",
+      "count": 1
+    },
+    {
+      "ruleId": "workflow.bdd.insufficient_features",
+      "count": 1
+    },
+    {
+      "ruleId": "workflow.bdd.missing_feature_files",
+      "count": 1
+    }
+  ],
+  "top_files": [
+    {
+      "file": "scripts/framework-menu-matrix-canary-lib.ts",
+      "count": 6
+    },
+    {
+      "file": "core/facts/extractHeuristicFacts.ts",
+      "count": 4
+    },
+    {
+      "file": "integrations/lifecycle/gitService.ts",
+      "count": 4
+    },
+    {
+      "file": "core/facts/detectors/typescript/index.ts",
+      "count": 3
+    },
+    {
+      "file": "integrations/config/skillsCustomRules.ts",
+      "count": 3
+    },
+    {
+      "file": "integrations/lifecycle/update.ts",
+      "count": 3
+    },
+    {
+      "file": "integrations/mcp/enterpriseServer.ts",
+      "count": 3
+    },
+    {
+      "file": "scripts/adapter-session-status-writes-log-filter-lib.ts",
+      "count": 3
+    },
+    {
+      "file": "PROJECT_ROOT",
+      "count": 2
+    },
+    {
+      "file": "core/facts/detectors/browser/index.ts",
+      "count": 2
+    },
+    {
+      "file": "core/facts/detectors/process/core.ts",
+      "count": 2
+    },
+    {
+      "file": "core/facts/detectors/process/shell.ts",
+      "count": 2
+    },
+    {
+      "file": "core/facts/detectors/process/spawn.ts",
+      "count": 2
+    },
+    {
+      "file": "core/facts/detectors/security/securityCredentials.ts",
+      "count": 2
+    },
+    {
+      "file": "core/facts/detectors/security/securityCrypto.ts",
+      "count": 2
+    }
+  ],
+  "source": ".audit_tmp/c021-0-t2/enterprise-menu1.json",
+  "generated_at": "2026-02-24T09:18:27Z"
+}