pumuki 6.3.7

package/docs/BRANCH_PROTECTION_GUIDE.md

@@ -0,0 +1,50 @@
+# Branch Protection Guide (v2.x)
+
+Recommended protection for `main` in this repository.
+
+## Core protection settings
+
+Enable:
+
+- Require pull request before merging
+- Require at least 1 approval
+- Dismiss stale approvals on new commits
+- Require conversation resolution
+- Require status checks to pass
+- Require branch to be up to date before merge
+- Restrict direct pushes to maintainers
+- Disallow force pushes
+- Disallow branch deletion
+
+## Suggested required checks
+
+Use the active workflow/job checks from this repository:
+
+- `Lint`
+- `Type Check`
+- `Build Verification`
+- `Pumuki Deterministic Tests`
+- `Pumuki Heuristics Tests`
+- `iOS Gate`
+- `Backend Gate`
+- `Frontend Gate`
+- `Android Gate`
+
+Depending on your GitHub check context naming, these may appear as workflow/job variants. Configure the exact check names shown in your branch protection UI.
+
+## Optional checks
+
+- Signed commits (recommended for stricter governance)
+- CODEOWNERS review requirement
+
+## Setup steps
+
+1. Open repository settings: `Settings -> Branches`
+2. Add rule for `main`
+3. Enable the core settings above
+4. Add required checks from recent successful runs
+5. Save and verify with a test PR
+
+## Maintenance
+
+When workflow names/jobs change, update required checks in branch protection immediately to avoid accidental bypasses or merge deadlocks.

package/docs/CODE_STANDARDS.md

@@ -0,0 +1,73 @@
+# Code Standards (v2.x)
+
+## Architectural standards
+
+- Keep domain logic in `core/*`.
+- Keep adapters in `integrations/*`.
+- Do not couple `core/*` to shell, filesystem, or network concerns.
+- Do not duplicate stage logic across platform wrappers when shared runner exists.
+- Keep IDE/editor diagnostics adapters in `scripts/*`; do not couple them into `core/*` or `integrations/*` gate logic.
+- Do not read `~/.codex/**` in gate runtime execution; use repository-scoped contracts only.
+
+## Deterministic standards
+
+- Gate behavior must be stage-policy driven.
+- Evidence output must remain deterministic (`version: "2.1"`, stable ordering).
+- Findings and rule-pack loading must be reproducible for same inputs.
+
+## Severity vocabulary
+
+Use only:
+
+- `CRITICAL`
+- `ERROR`
+- `WARN`
+- `INFO`
+
+Avoid introducing alternate severity taxonomies.
+
+## TypeScript standards
+
+- Prefer explicit types on public functions and exported values.
+- Keep helpers pure where possible.
+- Use immutable/read-only inputs in evaluators when feasible.
+- Avoid `any` unless explicitly justified.
+
+## File and naming conventions
+
+- Use descriptive file names tied to behavior (`runPlatformGate`, `stagePolicies`, `buildEvidence`).
+- Keep CLI wrappers thin (`*.cli.ts`) and delegate to shared runtime.
+
+## Testing standards
+
+Before merge:
+
+```bash
+npm run typecheck
+npm run test:deterministic
+```
+
+When touching heuristics/policy:
+
+```bash
+npm run test:heuristics
+```
+
+## Documentation standards
+
+- Update docs in the same change when behavior changes.
+- Keep docs aligned with active v2.x runtime.
+- Keep active repository documentation in English (enterprise baseline).
+- Keep root markdown documentation limited to canonical governance docs (`README.md`, `ARCHITECTURE.md`, `CHANGELOG.md`, `AGENTS.md`, `CLAUDE.md`).
+- Do not add temporary markdown planning artifacts.
+
+## Commit standards
+
+Use Conventional Commits and atomic changes:
+
+- `feat:`
+- `fix:`
+- `docs:`
+- `refactor:`
+- `test:`
+- `chore:`

package/docs/CONFIGURATION.md

@@ -0,0 +1,132 @@
+# Configuration (v2.x)
+
+## Project rule overrides
+
+Create a project-level rules file in one of these locations:
+
+- `.pumuki/rules.ts`
+- `pumuki.rules.ts`
+
+Example:
+
+```ts
+import type { ProjectRulesConfig } from './integrations/config/projectRules';
+
+const config: ProjectRulesConfig = {
+  allowOverrideLocked: false,
+  rules: [
+    {
+      id: 'ios.no-print',
+      description: 'Disallow print() usage in iOS code.',
+      severity: 'CRITICAL',
+      scope: { include: ['**/*.swift'] },
+      when: { kind: 'FileContent', contains: ['print('] },
+      then: {
+        kind: 'Finding',
+        message: 'print() usage is not allowed.',
+        code: 'IOS_NO_PRINT',
+      },
+    },
+  ],
+};
+
+export default config;
+```
+
+## Override rules of engagement
+
+You can:
+
+- Add new rules.
+- Update unlocked rules.
+- Raise severity for locked baseline rules.
+
+You cannot (unless `allowOverrideLocked: true`):
+
+- Downgrade locked baseline rules.
+- Remove locked baseline rules.
+- Replace locked baseline conditions/consequences.
+
+## Skills Contracts and Enforcement Inputs
+
+Repository-level contracts for deterministic skills enforcement:
+
+- `skills.sources.json`
+- `skills.lock.json`
+- `skills.policy.json`
+
+Typed contract, compiler, and loader/validator modules:
+
+- `integrations/config/skillsLock.ts`
+- `integrations/config/skillsPolicy.ts`
+
+Current enforcement scope:
+
+- deterministic schema validation + hashing for lock/policy contracts
+- curated template compilation (`skills.sources.json` -> `skills.lock.json`)
+- stage-aware policy resolution via `resolvePolicyForStage`
+- additive skills-derived rules merged through the shared gate runner
+- evidence traceability for active skills bundles and policy source/hash in `.ai_evidence.json`
+
+Ownership model:
+
+- Contracts are repository artifacts and must be committed.
+- CI and team members must evaluate the same committed contract files.
+- User-home skill sources (`~/.codex/**`) are not runtime inputs for CI gate decisions.
+
+Compile/check commands:
+
+```bash
+npm run skills:compile
+npm run skills:lock:check
+```
+
+CI guardrail:
+
+- `.github/workflows/ci.yml` includes `Skills Lock Freshness` and fails when committed lock is stale.
+
+Migration guide:
+
+- `docs/skills-repo-enforcement-migration.md`
+
+## Stage policies
+
+Defined in `integrations/gate/stagePolicies.ts`:
+
+- `PRE_COMMIT`: block `CRITICAL`, warn from `ERROR`
+- `PRE_PUSH`: block `ERROR`, warn from `WARN`
+- `CI`: block `ERROR`, warn from `WARN`
+
+## Heuristic pilot flag
+
+Enable semantic heuristic rules:
+
+```bash
+PUMUKI_ENABLE_AST_HEURISTICS=true
+```
+
+When enabled, stage-based heuristic severity maturity applies via `applyHeuristicSeverityForStage`.
+
+## Rule packs
+
+Version map lives in `core/rules/presets/rulePackVersions.ts`.
+
+Documentation:
+
+- `docs/rule-packs/README.md`
+- `docs/rule-packs/ios.md`
+- `docs/rule-packs/backend.md`
+- `docs/rule-packs/frontend.md`
+- `docs/rule-packs/android.md`
+- `docs/rule-packs/heuristics.md`
+
+## Evidence contract
+
+Configuration outcomes are reflected in `.ai_evidence.json`:
+
+- active `platforms`
+- loaded `rulesets`
+- `snapshot` outcome
+- `ledger` continuity
+
+Schema reference: `docs/evidence-v2.1.md`.

package/docs/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing (v2.x)
+
+Thanks for contributing to `ast-intelligence-hooks`.
+
+## Scope
+
+This repository is currently centered on deterministic framework behavior:
+
+`Facts -> Rules -> Gate -> ai_evidence v2.1`
+
+Contributions should preserve that model.
+
+## Prerequisites
+
+- Node.js `>=18`
+- npm `>=9`
+- Git
+
+## Setup
+
+```bash
+git clone https://github.com/SwiftEnProfundidad/ast-intelligence-hooks.git
+cd ast-intelligence-hooks
+npm ci
+```
+
+## Working rules
+
+- Keep domain decisions in `core/*`.
+- Keep shell/file/network adapters in `integrations/*`.
+- Do not introduce architectural shortcuts that bypass stage runners.
+- Prefer incremental, atomic commits.
+
+## Branching
+
+Use short, semantic branches:
+
+- `feat/<topic>`
+- `fix/<topic>`
+- `docs/<topic>`
+- `refactor/<topic>`
+- `test/<topic>`
+
+## Commit convention
+
+Use Conventional Commits:
+
+- `feat:`
+- `fix:`
+- `docs:`
+- `refactor:`
+- `test:`
+- `chore:`
+
+Examples:
+
+```bash
+docs(v2): rewrite architecture mcp and testing guides
+feat(heuristics): add stage-based severity maturity across gates
+```
+
+## Validation before PR
+
+```bash
+npm run typecheck
+npm run test:deterministic
+```
+
+When touching heuristics or policy behavior, also run:
+
+```bash
+npm run test:heuristics
+```
+
+## Pull request checklist
+
+- Code follows architecture boundaries.
+- Deterministic tests pass locally.
+- Docs updated when behavior changes.
+- No temporary/residual files.
+- Commit history is atomic and readable.
+
+## Documentation hygiene policy
+
+- Keep docs aligned to active v2.x runtime.
+- Remove or rewrite stale legacy references instead of extending them.
+- Do not add temporary markdown artifacts for planning.
+
+## Notes for automation contributors
+
+This repository still contains legacy hooks/scripts for compatibility.
+For framework refactor commits, maintainers may use `--no-verify` to avoid unrelated legacy hook failures.

package/docs/DEPENDENCIES.md

@@ -0,0 +1,54 @@
+# Dependencies (v2.x)
+
+This document tracks active dependencies used by the current deterministic framework surface.
+
+## Runtime dependencies
+
+- `glob` (`^10.5.0`)
+  - File matching utilities for adapter/runtime workflows.
+- `ts-morph` (`>=21.0.0`)
+  - TypeScript AST support used by analysis components.
+
+## Peer dependencies
+
+- `ts-morph` (`>=21.0.0`)
+
+## Development dependencies
+
+- `typescript` (`^5.3.0`)
+- `@types/node` (`^20.10.0`)
+- `eslint` (`^9.12.0`)
+- `jest` (`^30.2.0`)
+- `@babel/parser` (`^7.28.5`)
+- `@babel/traverse` (`^7.28.5`)
+- `@babel/generator` (`^7.28.5`)
+- `jscodeshift` (`^17.3.0`)
+- `recast` (`^0.23.11`)
+
+## Engine requirements
+
+- Node.js: `>=18.0.0`
+- npm: `>=9.0.0`
+
+## Dependency policy
+
+- Add dependencies only when required by active `core/*` or `integrations/*` behavior.
+- Prefer existing primitives before introducing new packages.
+- Document dependency purpose in PR description.
+- Avoid adding dependencies only for one-off migration/cleanup tasks.
+
+## Security and maintenance
+
+Recommended checks:
+
+```bash
+npm ci
+npm run typecheck
+npm run test:deterministic
+npm audit
+```
+
+## Notes
+
+Some package scripts and exports still include legacy compatibility entrypoints.
+Dependency decisions for new work should prioritize the active v2.x deterministic surface.

package/docs/HOW_IT_WORKS.md

@@ -0,0 +1,155 @@
+# How It Works (v2.x)
+
+## Purpose
+
+This repository implements a deterministic quality gate for AI-assisted development.
+
+Pipeline:
+
+`Facts -> Rules -> Gate -> ai_evidence v2.1`
+
+## End-to-end flow
+
+1. Collect facts from Git scope.
+2. Detect active platforms from facts.
+3. Load baseline rule packs for detected platforms.
+4. Merge project overrides (respecting locked baseline rules).
+5. Evaluate rules to produce findings.
+6. Evaluate gate outcome using stage policy.
+7. Persist deterministic evidence in `.ai_evidence.json`.
+
+## Stage execution model
+
+### PRE_COMMIT
+
+- Scope: staged changes (`git diff --cached --name-status`)
+- Policy:
+  - `blockOnOrAbove: CRITICAL`
+  - `warnOnOrAbove: ERROR`
+
+### PRE_PUSH
+
+- Scope: commit range (`upstream..HEAD`)
+- Policy:
+  - `blockOnOrAbove: ERROR`
+  - `warnOnOrAbove: WARN`
+
+### CI
+
+- Scope: commit range (`baseRef..HEAD`)
+- Base ref resolution:
+  - `GITHUB_BASE_REF` if present
+  - fallback: `origin/main`
+- Policy:
+  - `blockOnOrAbove: ERROR`
+  - `warnOnOrAbove: WARN`
+
+Policy source: `integrations/gate/stagePolicies.ts`.
+
+## Main runtime components
+
+- `integrations/git/runPlatformGate.ts`
+  - Shared execution path for staged/range scopes
+  - Multi-platform detection + combined evaluation
+  - Evidence generation (`generateEvidence`)
+- `integrations/git/stageRunners.ts`
+  - Stage-specific runners (`runPreCommitStage`, `runPrePushStage`, `runCiStage`)
+- `integrations/git/resolveGitRefs.ts`
+  - Upstream and CI base reference resolution
+- `integrations/evidence/buildEvidence.ts`
+  - Deterministic `snapshot + ledger` builder
+- `integrations/evidence/writeEvidence.ts`
+  - Stable, ordered evidence serialization
+
+## Platform and rule-pack loading
+
+Detected platforms can include `ios`, `backend`, `frontend`, `android` in the same run.
+
+Loaded baseline packs:
+
+- `iosEnterpriseRuleSet`
+- `backendRuleSet`
+- `frontendRuleSet`
+- `androidRuleSet`
+- `astHeuristicsRuleSet` (when `PUMUKI_ENABLE_AST_HEURISTICS=true`)
+
+Version map: `core/rules/presets/rulePackVersions.ts`.
+
+## Evidence contract
+
+Output file: `.ai_evidence.json`
+
+- `version: "2.1"` is authoritative
+- `snapshot` contains current stage findings and outcome (`PASS` | `WARN` | `BLOCK`)
+- `ledger` tracks open violations over time
+- `platforms` stores detected platform state
+- `rulesets` stores loaded bundles and hashes
+- `ai_gate` mirrors compatibility status (`ALLOWED` | `BLOCKED`)
+
+Full schema: `docs/evidence-v2.1.md`.
+
+## Interfaces to run it
+
+### Interactive
+
+```bash
+npm run framework:menu
+```
+
+### CLI wrappers
+
+```bash
+npx tsx integrations/git/preCommitIOS.cli.ts
+npx tsx integrations/git/prePushBackend.cli.ts
+npx tsx integrations/git/ciFrontend.cli.ts
+```
+
+## Operational adapters (optional)
+
+Adapter diagnostics are intentionally outside the deterministic gate runtime.
+
+- They live under `scripts/*` and `docs/validation/*`.
+- They do not change PRE_COMMIT/PRE_PUSH/CI outcomes.
+- They support rollout diagnostics and incident triage.
+
+Typical commands:
+
+```bash
+npm run validation:adapter-readiness -- \
+  --adapter-report .audit-reports/adapter/adapter-real-session-report.md \
+  --out .audit-reports/adapter/adapter-readiness.md
+
+npm run validation:adapter-session-status -- \
+  --out .audit-reports/adapter/adapter-session-status.md
+
+npm run validation:adapter-real-session-report -- \
+  --status-report .audit-reports/adapter/adapter-session-status.md \
+  --out .audit-reports/adapter/adapter-real-session-report.md
+
+npm run validation:phase5-blockers-readiness -- \
+  --consumer-triage-report .audit-reports/consumer-triage/consumer-startup-triage-report.md \
+  --out .audit-reports/phase5/phase5-blockers-readiness.md
+
+npm run validation:phase5-execution-closure-status -- \
+  --phase5-blockers-report .audit-reports/phase5/phase5-blockers-readiness.md \
+  --consumer-unblock-report .audit-reports/consumer-triage/consumer-startup-unblock-status.md \
+  --out .audit-reports/phase5/phase5-execution-closure-status.md
+```
+
+Note: current adapter readiness command uses `--adapter-report` as the adapter input file flag.
+
+### CI 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`
+
+## Deterministic validation
+
+```bash
+npm run typecheck
+npm run test:heuristics
+npm run test:deterministic
+```