pumuki 6.3.7

package/docs/USAGE.md

@@ -0,0 +1,259 @@
+# Usage Guide (v2.x)
+
+This guide describes the deterministic gate flow implemented in this repository.
+
+## Prerequisites
+
+- Node.js `>=18`
+- npm `>=9`
+- Git repository with tracked files
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+## Gate stages and policies
+
+| Stage | Input scope | blockOnOrAbove | warnOnOrAbove |
+|---|---|---|---|
+| `PRE_COMMIT` | `git diff --cached` | `CRITICAL` | `ERROR` |
+| `PRE_PUSH` | `upstream..HEAD` | `ERROR` | `WARN` |
+| `CI` | `baseRef..HEAD` | `ERROR` | `WARN` |
+
+Policy source: `integrations/gate/stagePolicies.ts`.
+
+## Run locally
+
+### 1) Interactive menu
+
+```bash
+npm run framework:menu
+```
+
+Menu supports staged evaluation, commit-range evaluation, evidence reading, and CI runner entrypoints.
+
+To avoid host-specific defaults for consumer diagnostics prompts, set:
+
+```bash
+export PUMUKI_CONSUMER_REPO_PATH=/absolute/path/to/consumer-repo
+```
+
+Optional diagnostics adapters (runtime diagnostics and consumer startup triage) are also exposed from the menu, but they are not required for PRE_COMMIT/PRE_PUSH/CI gate outcomes.
+
+Adapter readiness diagnostics are available from the interactive menu as:
+
+- `Build adapter readiness report`
+- `Build phase5 execution closure status report`
+- `Run phase5 execution closure (one-shot orchestration)`
+- `Clean local validation artifacts`
+
+### 2) Direct stage CLI execution
+
+```bash
+# PRE_COMMIT
+npx tsx integrations/git/preCommitIOS.cli.ts
+
+# PRE_PUSH
+npx tsx integrations/git/prePushBackend.cli.ts
+
+# CI
+npx tsx integrations/git/ciFrontend.cli.ts
+```
+
+### 2.1) Lifecycle CLI (install / uninstall / remove / update / doctor / status)
+
+Canonical npm package commands:
+
+```bash
+npm install --save-exact pumuki
+npm update pumuki
+npm uninstall pumuki
+```
+
+`npm upgrade pumuki` is valid where npm maps `upgrade` to `update`.
+
+```bash
+# install managed hooks
+npx --yes pumuki install
+
+# inspect enterprise baseline safety checks
+npx --yes pumuki doctor
+
+# show lifecycle status
+npx --yes pumuki status
+
+# update dependency to latest and re-apply hooks
+npx --yes pumuki update --latest
+
+# uninstall managed hooks and purge untracked evidence artifacts
+npx --yes pumuki uninstall --purge-artifacts
+
+# one-command cleanup + dependency removal from package.json
+npx --yes pumuki remove
+```
+
+`pumuki remove` is the enterprise-safe removal path because it performs lifecycle cleanup before package uninstall.
+When no modules remain, it also prunes orphan `node_modules/.package-lock.json` residue.
+
+Safety rule:
+- If tracked files exist under `node_modules/`, `pumuki install` and `pumuki update` intentionally fail.
+- This prevents lifecycle contamination in enterprise repositories.
+
+Notes:
+- CLI wrappers call shared stage runners via `integrations/git/runCliCommand.ts`.
+- Execution path is centralized in `integrations/git/runPlatformGate.ts`.
+- Platform detection is multi-platform and combined per run.
+
+### 3) Diagnostics reports (optional adapters)
+
+```bash
+# Adapter-only readiness
+# (current adapter implementation consumes --adapter-report as input path)
+npm run validation:adapter-readiness -- \
+  --adapter-report .audit-reports/adapter/adapter-real-session-report.md \
+  --out .audit-reports/adapter/adapter-readiness.md
+
+# Adapter runtime status/report aliases (provider-agnostic command naming)
+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
+
+# Phase 5 consolidated readiness (consumer triage required, adapter report optional by default)
+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
+
+# Phase 5 execution-closure status snapshot
+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
+
+# One-shot: run full Phase 5 execution-closure orchestration
+npm run validation:phase5-execution-closure -- \
+  --repo <owner>/<repo> \
+  --out-dir .audit-reports/phase5 \
+  --skip-workflow-lint
+
+# Local mock-consumer closure (no external GH dependency)
+npm run validation:phase5-execution-closure -- \
+  --repo <owner>/<repo> \
+  --out-dir .audit-reports/phase5 \
+  --mock-consumer
+
+# Optional: disable auth preflight fail-fast
+npm run validation:phase5-execution-closure -- \
+  --repo <owner>/<repo> \
+  --out-dir .audit-reports/phase5 \
+  --skip-workflow-lint \
+  --skip-auth-preflight
+
+# Optional: clean local generated validation artifacts
+npm run validation:clean-artifacts
+npm run validation:clean-artifacts -- --dry-run
+```
+
+## Scope behavior
+
+### PRE_COMMIT
+
+- Reads staged changes with `git diff --cached --name-status`.
+- Builds facts from staged content.
+
+### PRE_PUSH
+
+- Resolves upstream with `git rev-parse @{u}`.
+- Evaluates `upstream..HEAD` commit range.
+
+### CI
+
+- Resolves base ref from `GITHUB_BASE_REF` when available.
+- Fallback base ref: `origin/main`.
+- Evaluates `baseRef..HEAD`.
+
+Resolver source: `integrations/git/resolveGitRefs.ts`.
+
+## Evidence output
+
+Each run writes deterministic evidence to:
+
+- `.ai_evidence.json`
+
+Schema and behavior:
+
+- `version: "2.1"` is the source of truth
+- `snapshot` + `ledger`
+- `platforms` and `rulesets` tracking
+- stable JSON ordering for deterministic diffs
+
+Reference: `docs/evidence-v2.1.md`.
+
+## Rule packs and overrides
+
+Baseline packs:
+
+- `iosEnterpriseRuleSet`
+- `backendRuleSet`
+- `frontendRuleSet`
+- `androidRuleSet`
+- `astHeuristicsRuleSet` (optional)
+
+Version map: `core/rules/presets/rulePackVersions.ts`.
+
+Project overrides:
+
+- `.pumuki/rules.ts`
+- `pumuki.rules.ts`
+
+Locked rules can only be downgraded when `allowOverrideLocked: true`.
+
+## Heuristic pilot flag
+
+Enable AST semantic heuristics:
+
+```bash
+PUMUKI_ENABLE_AST_HEURISTICS=true npx tsx integrations/git/prePushIOS.cli.ts
+```
+
+Details: `docs/rule-packs/heuristics.md`.
+
+## 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`
+
+All upload `.ai_evidence.json` as artifact.
+
+## Deterministic validation suite
+
+```bash
+npm run typecheck
+npm run test:heuristics
+npm run test:deterministic
+```
+
+## Troubleshooting
+
+### No upstream configured for PRE_PUSH
+
+Set upstream once:
+
+```bash
+git branch --set-upstream-to origin/<branch>
+```
+
+### Empty evidence or PASS with no findings
+
+Confirm changed files match supported extensions and platform paths expected by detectors.
+
+### CI base ref mismatch
+
+Set `GITHUB_BASE_REF` in CI context or ensure `origin/main` exists.

package/docs/evidence-v2.1.md

@@ -0,0 +1,49 @@
+# ai_evidence v2.1
+
+`ai_evidence v2.1` is the deterministic state store used by Git stages and CI.
+
+## Structure
+
+- `version`: must be `2.1` and is the source of truth
+- `timestamp`: ISO timestamp of generation
+- `snapshot`:
+  - `stage`: `PRE_COMMIT` | `PRE_PUSH` | `CI`
+  - `outcome`: `PASS` | `WARN` | `BLOCK`
+  - `findings[]`: normalized findings for the current run
+- `ledger[]`:
+  - persistent open violations by key (`ruleId + file + lines`)
+  - `firstSeen` / `lastSeen` maintained deterministically
+- `platforms`:
+  - active detected platforms with confidence (`HIGH` | `MEDIUM` | `LOW`)
+- `rulesets[]`:
+  - loaded bundles with versioned name and hash
+- `human_intent`:
+  - preserved user goal state (or `null` when missing/expired)
+  - `expires_at` is enforced deterministically (expired intent is ignored)
+- `ai_gate`:
+  - compatibility status and violation list
+  - mirrors `human_intent` to avoid state drift
+- `severity_metrics`:
+  - gate status + totals by severity
+- `consolidation` (optional):
+  - `suppressed[]`: trace of equivalent findings removed from snapshot by deterministic semantic-family precedence
+
+## Deterministic behavior
+
+- Findings are deduplicated by `ruleId + file + lines`.
+- For selected semantic rule families, equivalent baseline/heuristic duplicates on the same file are consolidated to a single finding, keeping the highest-severity signal deterministically.
+- Consolidation scope is file-level in v2.1: repeated same-family findings (including same rule on different lines) collapse to one deterministic representative.
+- When consolidation removes findings, `consolidation.suppressed[]` keeps the trace (`ruleId`, `replacedByRuleId`, `reason`) for auditability.
+- Ledger entries are updated if a violation still exists.
+- Cleared violations are removed from ledger.
+- Output JSON is written in stable key order.
+- Canonical writer path is `integrations/evidence/generateEvidence.ts` (`buildEvidence` + `writeEvidence`).
+
+## Overrides
+
+Project overrides come from:
+
+- `.pumuki/rules.ts`
+- `pumuki.rules.ts`
+
+Baseline locked rules remain immutable unless `allowOverrideLocked: true`.

package/docs/images/README.md

@@ -0,0 +1,20 @@
+# Visual Assets Guide
+
+This folder stores framework diagrams and screenshots used in documentation.
+
+## Standard
+
+- Prefer `SVG` for diagrams (resolution-independent, diff-friendly).
+- Keep screenshot assets (`PNG`) only for terminal/UI captures where vector format is not available.
+- Use `docs/images/*.svg` links in docs when an SVG equivalent exists.
+- Keep naming stable (`ast_intelligence_0X.svg`) to avoid link churn across docs.
+
+## Current migration status
+
+- Architecture and workflow diagrams are standardized on SVG:
+  - `ast_intelligence_01.svg`
+  - `ast_intelligence_02.svg`
+  - `ast_intelligence_03.svg`
+  - `ast_intelligence_04.svg`
+  - `ast_intelligence_05.svg`
+- PNG counterparts are retained only as legacy/backward-compatible assets.

package/docs/rule-packs/README.md

@@ -0,0 +1,45 @@
+# Rule Packs
+
+This folder documents the baseline Rule Packs used by the v2.x deterministic gate flow.
+
+## Current versions
+
+- `iosEnterpriseRuleSet@1.0.0`
+- `rulesgold.mdc@1.0.0`
+- `rulesbackend.mdc@1.0.0`
+- `backendRuleSet@1.0.0`
+- `frontendRuleSet@1.0.0`
+- `androidRuleSet@1.0.0`
+- `astHeuristicsRuleSet@0.4.0` (enabled only when `PUMUKI_ENABLE_AST_HEURISTICS` is true)
+
+## Evidence linkage
+
+Each execution writes loaded Rule Packs to `.ai_evidence.json` in `rulesets[]` with:
+
+- `platform`
+- `bundle` (name + version)
+- `hash` (content hash used for traceability)
+
+## Override model
+
+Project-level overrides are loaded from:
+
+- `.pumuki/rules.ts`
+- `pumuki.rules.ts`
+
+Locked baseline rules remain locked unless:
+
+- `allowOverrideLocked: true`
+
+Example:
+
+```ts
+import type { ProjectRulesConfig } from './integrations/config/projectRules';
+
+const config: ProjectRulesConfig = {
+  allowOverrideLocked: false,
+  rules: [],
+};
+
+export default config;
+```

package/docs/rule-packs/android.md

@@ -0,0 +1,21 @@
+# Android Rule Pack
+
+## Pack
+
+- `androidRuleSet@1.0.0`
+- Platform: `android`
+
+## Source
+
+- `core/rules/presets/androidRuleSet.ts`
+
+## Scope
+
+- `apps/android/**/*.{kt,kts}`
+- Enforced through shared evaluator in `PRE_COMMIT`, `PRE_PUSH`, and `CI`
+
+## Baseline rules
+
+- Block `Thread.sleep(...)` (`CRITICAL`)
+- Warn on `GlobalScope` usage (`WARN`)
+- Warn on `runBlocking(...)` in production paths (`WARN`)

package/docs/rule-packs/backend.md

@@ -0,0 +1,24 @@
+# Backend Rule Pack
+
+## Pack
+
+- `rulesgold.mdc@1.0.0`
+- `rulesbackend.mdc@1.0.0`
+- `backendRuleSet@1.0.0`
+- Platform: `backend`
+
+## Sources
+
+- `legacy/tooling/*/rules/rulesgold.mdc` (legacy source material)
+- `legacy/tooling/*/rules/rulesbackend.mdc` (legacy source material)
+- Legacy editor-export equivalents when present
+- `core/rules/presets/backendRuleSet.ts`
+
+## Scope
+
+- Backend TypeScript paths under `apps/backend/**/*.ts`
+- Enforced through shared evaluator in `PRE_COMMIT`, `PRE_PUSH`, and `CI`
+
+## Notes
+
+- The evidence file records both bundles and hashes for deterministic auditing.

package/docs/rule-packs/frontend.md

@@ -0,0 +1,22 @@
+# Frontend Rule Pack
+
+## Pack
+
+- `frontendRuleSet@1.0.0`
+- Platform: `frontend`
+
+## Source
+
+- `core/rules/presets/frontendRuleSet.ts`
+
+## Scope
+
+- `apps/frontend/**/*.{ts,tsx,js,jsx}`
+- `apps/web/**/*.{ts,tsx,js,jsx}`
+- Enforced through shared evaluator in `PRE_COMMIT`, `PRE_PUSH`, and `CI`
+
+## Baseline rules
+
+- Block `console.log` in frontend code (`CRITICAL`)
+- Warn on `debugger` usage (`WARN`)
+- Warn on single-letter variable declarations (`WARN`)