\n\nPumuki is an enterprise governance framework for AI-assisted software delivery.\n\nIt turns repository rules, SDD/OpenSpec workflow, Git hooks, AST intelligence, skills contracts, evidence, notifications, an interactive menu and optional MCP servers into one deterministic delivery contract:\n\n```text\nFacts -> Rules -> Gate -> Evidence\n```\n\nPumuki is built for teams that need AI agents and humans to follow the same engineering law: know the active change, evaluate the real diff, block unsafe delivery, explain the reason in developer language, and leave auditable evidence.\n\nCurrent maturity: **advanced beta**. The framework is already useful for governed internal adoption and consumer-repository rollout, but the project is still evolving quickly.\n\n## Contents\n\n- [Why Pumuki Exists](#why-pumuki-exists)\n- [What Pumuki Does](#what-pumuki-does)\n- [Architecture](#architecture)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Uninstallation and Upgrade](#uninstallation-and-upgrade)\n- [Command Reference](#command-reference)\n- [Git Hooks and CI](#git-hooks-and-ci)\n- [SDD and OpenSpec](#sdd-and-openspec)\n- [Session Continuity and AI Window Handoff](#session-continuity-and-ai-window-handoff)\n- [AST Intelligence and Rule Packs](#ast-intelligence-and-rule-packs)\n- [Evidence](#evidence)\n- [Menu and Notifications](#menu-and-notifications)\n- [MCP and Agent Adapters](#mcp-and-agent-adapters)\n- [Enterprise Operations](#enterprise-operations)\n- [Adoption Models](#adoption-models)\n- [Troubleshooting](#troubleshooting)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why Pumuki Exists\n\nAI-assisted development increases delivery speed, but it also increases the risk of ungoverned changes: skipped tests, missing specs, vague evidence, mixed commits, stale repo context, unsafe hooks, and rules that live only in documentation.\n\nPumuki makes those rules executable.\n\nIt is designed to answer operational questions before a change enters the repository:\n\n| Question | Pumuki answer |\n|---|---|\n| What is being changed? | Git scope, SDD context and repository facts. |\n| Which rules apply? | Platform rule packs, skills contracts, policy-as-code and project overrides. |\n| Can this change proceed? | Deterministic gate decision per stage. |\n| Why was it blocked? | Developer-facing cause, file, rule and remediation. |\n| What evidence remains? | `.ai_evidence.json` v2.1 plus optional MCP/telemetry access. |\n\nPumuki does not replace product tests, code review, domain acceptance criteria or security review. It enforces the delivery contract around them.\n\n## What Pumuki Does\n\nPumuki provides a governed delivery surface for modern repositories:\n\n| Capability | What it provides |\n|---|---|\n| Git lifecycle | Managed `pre-commit` and `pre-push` hooks, with chained `PRE_WRITE` by default. |\n| Stage gates | `PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH` and `CI` policies with deterministic semantics. |\n| Full audit | `pumuki audit` for tracked-repository evaluation outside a hook. |\n| SDD/OpenSpec | Change sessions, validation, evidence sync and state sync. |\n| Session continuity | Repo-owned context, SDD state, evidence and MCP resources so a new AI window can resume from facts instead of chat memory. |\n| AST intelligence | Rule-backed findings for iOS, Android, backend, frontend and generic TypeScript patterns. |\n| Skills contracts | Compiled rules from enterprise skills, with coverage checks and missing-detector protection. |\n| Evidence | Stable `.ai_evidence.json` v2.1 snapshots for auditability and automation. |\n| Developer UX | Interactive menu, clear blocking messages, terminal output and system notifications. |\n| MCP | Optional evidence and enterprise MCP servers over HTTP or stdio. |\n| Adapters | Provider-agnostic adapter scaffolding for Codex, Claude, Cursor, Windsurf and Opencode. |\n| Policy-as-code | Optional signed stage-policy contract under `.pumuki/policy-as-code.json`. |\n| Telemetry | Optional JSONL and OTLP export for enterprise observability. |\n| Brownfield control | Scope-aware gates that avoid blocking a slice for unrelated historical debt. |\n\n## Architecture\n\n
\n \n
\n\nPumuki keeps product decisions deterministic by separating domain logic from integrations:\n\n| Layer | Responsibility |\n|---|---|\n| `core/*` | Facts, rules, rule presets and gate decision model. |\n| `integrations/*` | Git scopes, stage policies, evidence, SDD, MCP, notifications and lifecycle adapters. |\n| `bin/*` | Public CLI binaries published by npm. |\n| `docs/*` | Product documentation, operation guides, MCP contracts and rule-pack references. |\n| `vendor/skills/*` | Vendored enterprise skill contracts consumed by the rules compiler. |\n\nCore pipeline:\n\n```text\nGit scope / repo state\n -> fact extraction\n -> platform detection\n -> rule-pack and skills loading\n -> stage policy evaluation\n -> gate decision\n -> evidence, notification and optional MCP/telemetry output\n```\n\nPumuki is IDE-agnostic at baseline. Git hooks, gates, lifecycle, evidence and policy enforcement do not require Cursor, Codex, Claude or any other IDE. IDE/client files are opt-in adapter output.\n\n## Quick Start\n\nPrerequisites:\n\n- Node.js `>=18`\n- npm `>=9`\n- Git repository\n\nInstall Pumuki in a consumer repository:\n\n```bash\nnpm install --save-exact pumuki\nnpx --yes pumuki bootstrap --enterprise\nnpx --yes pumuki status --json\nnpx --yes pumuki doctor --deep --json\n```\n\nAfter bootstrap, the normal developer path is intentionally small:\n\n```bash\ngit add \ngit commit\ngit push\n```\n\nManaged hooks run the required Pumuki lifecycle automatically. Teams only reach for explicit commands when they need setup, diagnostics, CI wiring, SDD evidence, MCP servers or operational recovery.\n\nOpen a governed SDD change session when the repository requires explicit SDD/OpenSpec control:\n\n```bash\nnpx --yes pumuki sdd status\nnpx --yes pumuki sdd session --open --change=\nnpx --yes pumuki sdd validate --stage=PRE_COMMIT --json\n```\n\nRun a full tracked-repository audit only for diagnostics or governance reporting:\n\n```bash\nnpx --yes pumuki audit --json\nnpx --yes pumuki audit --stage=CI --engine --json\n```\n\n## Installation\n\n### Consumer Repository\n\nRecommended enterprise path:\n\n```bash\nnpm install --save-exact pumuki\nnpx --yes pumuki bootstrap --enterprise\n```\n\nWhat the bootstrap path does:\n\n- installs managed Git hooks;\n- configures lifecycle state;\n- creates `.pumuki/adapter.json` when missing;\n- prepares OpenSpec/SDD baseline where applicable;\n- initializes evidence when missing;\n- runs deep diagnostics.\n\nThe package `postinstall` runs a baseline `pumuki install` in Git repositories unless disabled. That baseline is IDE-agnostic: hooks, lifecycle and `.pumuki/adapter.json` are the default product surface.\n\nUseful postinstall controls:\n\n| Variable | Effect |\n|---|---|\n| `PUMUKI_SKIP_POSTINSTALL=1` | Disable postinstall bootstrap. |\n| `PUMUKI_POSTINSTALL_WITH_MCP=1` | Include MCP wiring during postinstall. |\n| `PUMUKI_POSTINSTALL_MCP_AGENT=` | Select optional adapter/client wiring for postinstall. |\n| `PUMUKI_SKIP_CHAINED_PRE_WRITE=1` | Skip chained `PRE_WRITE` inside managed hooks. |\n\n### Framework Repository\n\nFor maintainers of this repository:\n\n```bash\ngit clone https://github.com/SwiftEnProfundidad/ast-intelligence-hooks.git\ncd ast-intelligence-hooks\nnpm ci\nnpm run -s typecheck\nnpm run -s test:deterministic\n```\n\n## Uninstallation and Upgrade\n\nPlain npm removal only removes the dependency. It does not remove managed lifecycle state.\n\n| Goal | Command |\n|---|---|\n| Remove managed hooks and purge runtime artifacts | `npx --yes pumuki uninstall --purge-artifacts` |\n| Remove lifecycle and dependency from package manifests | `npx --yes pumuki remove` |\n| Update to latest package and reapply hooks | `npx --yes pumuki update --latest` |\n| Standard npm dependency removal only | `npm uninstall pumuki` |\n\nRecommended upgrade check:\n\n```bash\nnpm install --save-exact pumuki@latest\nnpx --yes pumuki status --json\nnpx --yes pumuki doctor --deep --json\nnpx --yes pumuki policy reconcile --strict --json\n```\n\nIf `status` or `doctor` reports version drift, use the `alignmentCommand` printed in the JSON payload.\n\n## Command Reference\n\nThe main lifecycle binary is `pumuki`. This section is an operator reference, not the expected daily developer workflow. The intended enterprise path is progressive disclosure:\n\n1. `bootstrap` once per repository.\n2. work through normal Git operations.\n3. let managed hooks, CI and policy decide automatically.\n4. use explicit commands only for diagnostics, evidence, adapters, SDD operations or automation.\n\n```text\npumuki --version | -v\npumuki bootstrap [--enterprise] [--agent=] [--json]\npumuki install [--with-mcp] [--agent=]\npumuki uninstall [--purge-artifacts]\npumuki remove\npumuki update [--latest|--spec=]\npumuki doctor [--remote-checks] [--deep] [--parity] [--json]\npumuki audit [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--engine] [--json]\npumuki status [--json] [--remote-checks]\npumuki menu\npumuki watch [--stage=] [--scope=] [--once] [--json]\npumuki loop run --objective= [--max-attempts=] [--json]\npumuki adapter install --agent= [--dry-run] [--json]\npumuki analytics hotspots report [--top=] [--since-days=] [--json]\npumuki analytics hotspots diagnose [--json]\npumuki policy reconcile [--strict] [--apply] [--json]\npumuki context init|status|repair [--json]\npumuki sdd status|validate|session|sync-docs|sync|learn|auto-sync|evidence|state-sync\n```\n\nPublished binaries:\n\n| Binary | Purpose |\n|---|---|\n| `pumuki` | Main lifecycle CLI. |\n| `pumuki-framework`, `pumuki-ast-hooks`, `ast-hooks` | Interactive framework/menu entrypoints. |\n| `pumuki-pre-write` | PRE_WRITE gate and SDD policy surface. |\n| `pumuki-pre-commit` | PRE_COMMIT hook runner. |\n| `pumuki-pre-push` | PRE_PUSH hook runner. |\n| `pumuki-ci` | CI gate runner. |\n| `pumuki-mcp-evidence` | Evidence MCP HTTP server. |\n| `pumuki-mcp-enterprise` | Enterprise MCP HTTP server. |\n| `pumuki-mcp-evidence-stdio` | Evidence MCP stdio bridge. |\n| `pumuki-mcp-enterprise-stdio` | Enterprise MCP stdio bridge. |\n\nDetailed command documentation:\n\n- [Installation Guide](docs/product/INSTALLATION.md)\n- [Usage Guide](docs/product/USAGE.md)\n- [API Reference](docs/product/API_REFERENCE.md)\n- [Operator Playbook](PUMUKI.md)\n\n## Git Hooks and CI\n\nPumuki evaluates different scopes per stage:\n\n| Stage | Typical trigger | Scope | Purpose |\n|---|---|---|---|\n| `PRE_WRITE` | Before hook execution or explicit guard | Active write/session context | Prevent unmanaged agent work and invalid SDD state. |\n| `PRE_COMMIT` | `pre-commit` | `git diff --cached` | Protect the atomic commit. |\n| `PRE_PUSH` | `pre-push` | `upstream..HEAD` | Protect outgoing branch range. |\n| `CI` | CI job | CI base range | Repeat the same governance outside the laptop. |\n| `audit` | Manual CLI | Git tracked files | Diagnose the full tracked repository. |\n\nManaged `pre-commit` and `pre-push` hooks run `pumuki-pre-write` first by default, then the stage runner. Use `PUMUKI_SKIP_CHAINED_PRE_WRITE=1` only for explicit operational exceptions.\n\nCI entrypoint:\n\n```bash\nnpx --yes --package pumuki@latest pumuki-ci\n```\n\nWhen GitHub Actions quota or remote CI is not available, this repository uses local validation as the operational merge bar:\n\n```bash\nnpm run -s validation:local-merge-bar\n```\n\n## SDD and OpenSpec\n\nPumuki supports a mandatory SDD/OpenSpec delivery workflow for enterprise repositories.\n\nCommon commands:\n\n```bash\nnpx --yes pumuki sdd status --json\nnpx --yes pumuki sdd session --open --change= --json\nnpx --yes pumuki sdd session --refresh --ttl-minutes=90 --json\nnpx --yes pumuki sdd validate --stage=PRE_WRITE --json\nnpx --yes pumuki sdd evidence --scenario-id= --test-command='' --test-status=passed --json\nnpx --yes pumuki sdd state-sync --scenario-id= --status=done --dry-run --json\n```\n\nStage aliases:\n\n| Alias | Stage |\n|---|---|\n| `RED` | `PRE_WRITE` |\n| `GREEN` | `PRE_COMMIT` |\n| `REFACTOR` | `PRE_PUSH` |\n| `CLOSE` | `CI` |\n\nOpenSpec is resolved from the checked repository, not from a random global binary on `PATH`. Install or bootstrap Pumuki inside the repository so local and CI behavior match.\n\n## Session Continuity and AI Window Handoff\n\nPumuki is designed for AI-assisted work where the chat window, IDE session or CLI agent can change before the repository work is finished.\n\nIt does not claim to preserve private conversational memory from a vendor window. Instead, it externalizes the operational context that matters into repository-owned, auditable state:\n\n| Context surface | What it preserves |\n|---|---|\n| `.pumuki/context/context.json` | Local context contract for the repository and the instruction that an AI agent must stop if the context cannot be read or validated. |\n| `pumuki context init|status|repair` | Initialize, validate or repair the local context gate before edits, audits, commits or pushes. |\n| SDD/OpenSpec session state | Active change id, session validity and stage validation through `pumuki sdd status`, `session` and `validate`. |\n| `.ai_evidence.json` v2.1 | Last gate snapshot, findings, platform detection, rule provenance, severity breakdown and operational hints. |\n| Managed hooks and receipts | PRE_WRITE/PRE_COMMIT/PRE_PUSH/CI decisions, MCP receipt freshness and evidence age. |\n| MCP resources | Provider-agnostic resources such as `context://active`, `sdd://status`, `sdd://active-change`, `gitflow://state` and `evidence://status`. |\n\nThis makes a new AI window resumable from facts:\n\n```bash\nnpx --yes pumuki status --json\nnpx --yes pumuki context status --json\nnpx --yes pumuki sdd status --json\nnpx --yes pumuki doctor --deep --json\n```\n\nFor MCP-capable clients, the same pattern is available through read-only context resources and evidence endpoints before an agent edits files. The expected agent behavior is conservative: if context, evidence or SDD state is missing or invalid, the agent should downgrade to diagnosis and report a blocker instead of mutating production code.\n\nIn practice, Pumuki turns \"remember what we were doing\" into a repository contract: current branch, lifecycle health, active SDD change, latest evidence, blocking findings, remediation and policy provenance are recoverable without trusting the transient memory of one AI session.\n\n## AST Intelligence and Rule Packs\n\nPumuki detects active platforms and loads rule packs for the real repository shape:\n\n| Platform | Coverage area |\n|---|---|\n| iOS | Swift, SwiftUI, Swift Testing, concurrency, architecture and security patterns. |\n| Android | Kotlin, Compose, DI, lifecycle, architecture and Android-specific risk patterns. |\n| Backend | TypeScript/NestJS, DTO validation, controllers, DI, error handling, persistence and security patterns. |\n| Frontend | TypeScript/React/Next.js, JSX accessibility, API routes, UI safety and browser risk patterns. |\n| Generic | Cross-platform TypeScript, process, filesystem, dynamic code execution and security signals. |\n\nCurrent baseline families:\n\n- `iosEnterpriseRuleSet`\n- `backendRuleSet`\n- `frontendRuleSet`\n- `androidRuleSet`\n- `astHeuristicsRuleSet`\n- compiled skills bundles from `skills.lock.json`\n\nRule-pack documentation:\n\n- [Rule Packs Overview](docs/rule-packs/README.md)\n- [iOS Rule Pack](docs/rule-packs/ios.md)\n- [Android Rule Pack](docs/rule-packs/android.md)\n- [Backend Rule Pack](docs/rule-packs/backend.md)\n- [Frontend Rule Pack](docs/rule-packs/frontend.md)\n- [AST Heuristics Rule Pack](docs/rule-packs/heuristics.md)\n\nAST intelligence is not a promise that every guideline can be enforced as code. Pumuki distinguishes runtime-code rules, process rules, positive recommendations and rules that still require study, so the gate does not create false confidence.\n\n## Evidence\n\nPumuki writes deterministic evidence to `.ai_evidence.json` using the v2.1 contract.\n\nEvidence can include:\n\n- stage and policy metadata;\n- gate outcome;\n- findings and blocking causes;\n- loaded rulesets and content hashes;\n- detected platforms;\n- skills coverage;\n- SDD/OpenSpec state;\n- operational hints;\n- ledger and snapshot metadata.\n\nReference:\n\n- [AI Evidence v2.1 Contract](docs/mcp/ai-evidence-v2.1-contract.md)\n- [Evidence API](docs/product/API_REFERENCE.md#evidence-api)\n\n## Menu and Notifications\n\nPumuki includes an interactive menu for local developer operation.\n\nFramework repository:\n\n```bash\nnpm run framework:menu\nPUMUKI_MENU_MODE=advanced npm run framework:menu\n```\n\nConsumer repository:\n\n```bash\nnpx --yes --package pumuki@latest pumuki-framework\n```\n\nScreenshots from the consumer menu:\n\n| Consumer menu | Blocked pre-flight | Final summary |\n|---|---|---|\n|  |  |  |\n|  |  |  |\n\nNotification channels include terminal output, stderr mirrors for relevant blocking events and optional system notifications. Blocking messages are expected to explain:\n\n1. blocking cause;\n2. concrete rule or skill;\n3. file and line when available;\n4. missing condition;\n5. direct remediation.\n\nExtended walkthrough:\n\n- [Framework Menu Consumer Walkthrough](docs/operations/framework-menu-consumer-walkthrough.md)\n\n## MCP and Agent Adapters\n\nMCP is optional. Git hooks and gates do not depend on MCP.\n\nPumuki publishes two MCP server families:\n\n| Server | Purpose |\n|---|---|\n| `pumuki-mcp-evidence` | Read-only evidence context over HTTP. |\n| `pumuki-mcp-enterprise` | Enterprise repository state, resources and safe tools over HTTP. |\n| `pumuki-mcp-evidence-stdio` | Evidence resources over MCP stdio. |\n| `pumuki-mcp-enterprise-stdio` | Enterprise resources/tools over MCP stdio. |\n\nThe enterprise server exposes repository-state resources used for session continuity, including `context://active`, `gitflow://state`, `sdd://status`, `sdd://active-change` and `evidence://status`. The evidence server exposes compact and paginated evidence views so agents can load only the facts they need before acting.\n\nConsumer quick start:\n\n```bash\nnpx --yes --package pumuki@latest pumuki-mcp-evidence\nnpx --yes --package pumuki@latest pumuki-mcp-enterprise\nnpx --yes --package pumuki@latest pumuki-mcp-enterprise-stdio\n```\n\nAdapter scaffolding:\n\n```bash\nnpx --yes pumuki adapter install --agent=repo --dry-run --json\nnpx --yes pumuki adapter install --agent= --json\nnpx --yes pumuki adapter install --agent=cursor --dry-run --json\n```\n\nSupported adapter targets include `repo`, `cursor`, `claude`, `codex`, `windsurf` and `opencode`. These are opt-in client adapters; the managed Git hooks, gates, lifecycle, evidence and `.pumuki/adapter.json` baseline remain AI-agent, CLI and IDE agnostic.\n\nReferences:\n\n- [MCP Servers](docs/mcp/mcp-servers-overview.md)\n- [Evidence Context Server](docs/mcp/evidence-context-server.md)\n- [Agent Context Consumption](docs/mcp/agent-context-consumption.md)\n\n## Enterprise Operations\n\nPumuki includes enterprise-oriented controls for teams that need governed rollout across multiple repositories.\n\n| Area | Capability |\n|---|---|\n| Policy-as-code | `.pumuki/policy-as-code.json` with stage signatures and strict validation. |\n| Telemetry | Optional JSONL and OTLP export for gate telemetry. |\n| Version drift | `status` and `doctor` expose effective/runtime/lifecycle/package alignment. |\n| Adapter health | Deep diagnostics for hook and MCP wiring. |\n| Worktree hygiene | Guardrails for pending changes and atomic delivery. |\n| Consumer rollout | Package smoke, installed-bin smoke and consumer support tooling. |\n| Operations policy | SLO/SLA, severity model, incident response and rollback expectations. |\n\nOperational references:\n\n- [Configuration](docs/product/CONFIGURATION.md)\n- [Production Operations Policy](docs/operations/production-operations-policy.md)\n- [Validation Runbooks](docs/validation/README.md)\n- [Release Notes](docs/operations/RELEASE_NOTES.md)\n- [Changelog](CHANGELOG.md)\n\n## Adoption Models\n\n| Context | Recommended path |\n|---|---|\n| Greenfield repository | Install Pumuki early, enable SDD/OpenSpec, commit through hooks from day one. |\n| Brownfield repository | Start with scoped hooks and audits; fix active-slice debt before historical debt. |\n| AI-enabled team | Treat `AGENTS.md` and skills as the human contract, and Pumuki as executable enforcement. |\n| Multi-platform monorepo | Pin platforms when needed and let rule packs activate by detected scope. |\n| Enterprise rollout | Pilot in one consumer, validate `doctor/status/hooks`, then repin controlled repositories. |\n\nSuggested rollout checklist:\n\n1. Install exact package version.\n2. Run `pumuki bootstrap --enterprise`.\n3. Verify `status` and `doctor`.\n4. Open an SDD session for a real change.\n5. Run `PRE_WRITE` and `PRE_COMMIT`.\n6. Validate menu and notification output.\n7. Add CI gate when the local contract is stable.\n8. Document local exceptions in the consumer repository.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Action |\n|---|---|---|\n| `SDD_SESSION_MISSING` | No active SDD session. | Run `pumuki sdd session --open --change=`. |\n| `SDD_SESSION_INVALID` | Session does not match current change or expired. | Run `pumuki sdd session --refresh --ttl-minutes=90`. |\n| `OPENSPEC_MISSING` | Repo-local OpenSpec binary is missing. | Run `pumuki bootstrap --enterprise` or install the required package in the repo. |\n| PRE_PUSH blocks due to missing upstream | Branch has no tracking ref. | Run `git push --set-upstream origin `. |\n| Version drift in `doctor` | Package/runtime/lifecycle versions differ. | Use the printed `alignmentCommand`. |\n| Hook blocks unrelated brownfield debt | Scope classification may be wrong. | Capture command, staged files and JSON output; open an issue. |\n| `.ai_evidence.json` changes during docs-only work | Evidence refresh behavior is active. | Review the diff and stage only when the evidence belongs to the slice. |\n| MCP port conflict | Another instance is running. | Use `PUMUKI_ENTERPRISE_MCP_PORT=0` for dynamic port allocation. |\n\nBug report template:\n\n```text\nRepository:\nBranch:\nPumuki version:\nCommand:\nExpected result:\nActual result:\nStaged files:\nRelevant output:\nEvidence file present:\n```\n\n## Documentation\n\nStart here:\n\n- [Operator Playbook](PUMUKI.md)\n- [Documentation Index](docs/README.md)\n- [Installation](docs/product/INSTALLATION.md)\n- [Usage](docs/product/USAGE.md)\n- [Architecture](docs/product/ARCHITECTURE.md)\n- [Configuration](docs/product/CONFIGURATION.md)\n- [API Reference](docs/product/API_REFERENCE.md)\n- [Testing](docs/product/TESTING.md)\n- [MCP Servers](docs/mcp/mcp-servers-overview.md)\n- [Rule Packs](docs/rule-packs/README.md)\n- [Governance Standards](docs/governance/CODE_STANDARDS.md)\n- [Contributing](docs/governance/CONTRIBUTING.md)\n\nOptional training hub:\n\n- [Pumuki course in Stack My Architecture](https://stack-my-architecture-hub.vercel.app/pumuki/)\n\n## Contributing\n\nFor high-quality contributions:\n\n1. Read [Contributing](docs/governance/CONTRIBUTING.md) and [Code Standards](docs/governance/CODE_STANDARDS.md).\n2. Work on a dedicated branch.\n3. Keep each change atomic.\n4. Add focused regression coverage for behavior changes.\n5. Run the relevant local validation commands.\n6. Open a PR with problem, approach and evidence.\n\nMaintainer validation commands:\n\n```bash\nnpm run -s typecheck\nnpm run -s test:deterministic\nnpm run -s validation:package-manifest\nnpm run -s smoke:pumuki-surface\n```\n\nFor release-grade validation in this repository:\n\n```bash\nnpm run -s validation:local-merge-bar\nnpm publish --dry-run --access public\n```\n\nPublishing to npm is a separate release operation and may require registry auth/MFA handling.\n\n## Support and Security\n\n- Functional issues: use [GitHub Issues](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/issues).\n- Security-sensitive issues: use GitHub Security Advisories or coordinated private disclosure.\n- Enterprise diagnostics: attach command output and evidence excerpts, but never include secrets.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","readmeFilename":"README.md"}
![\"Pumuki\"](\"assets/logo_banner.png\"){kind=logo}
\n![\"npm](\"https://img.shields.io/npm/v/pumuki?color=1d4ed8\")
![\"CI\"](\"https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Node.js](\"https://img.shields.io/node/v/pumuki\")
![\"License:](\"https://img.shields.io/badge/license-MIT-16a34a\"){kind=icon}
![\"Pumuki](\"assets/readme/pumuki-governance-flow.svg\")
\n