# 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`)
- Upstream resolution: `git rev-parse @{u}`
- Fail-safe behavior: if upstream is missing, stage exits `1` with guidance; it does not fallback to `HEAD`.
- Policy:
  - `blockOnOrAbove: ERROR`
  - `warnOnOrAbove: WARN`

### CI

- Scope: commit range (`baseRef..HEAD`)
- Base ref resolution:
  - `GITHUB_BASE_REF` literal (if resolvable)
  - `origin/${GITHUB_BASE_REF}` (if literal does not resolve)
  - `origin/main`
  - `main`
  - `HEAD` (final deterministic fallback)
- Policy:
  - `blockOnOrAbove: ERROR`
  - `warnOnOrAbove: WARN`

Policy source: `integrations/gate/stagePolicies.ts`.

### `pumuki audit` (full tracked tree)

The lifecycle command **`pumuki audit`** runs `runPlatformGate` with **`GateScope` = `repo`**: facts come from **`git ls-files`** filtered by the default code extensions, using the working tree contents of those paths. It is **not** the same as the `PRE_COMMIT` hook, which uses **`staged`** scope only.

JSON output includes how many **untracked** paths would have matched those extensions (`untracked_matching_extensions_count`); they are still excluded from facts unless you use a different scope (for example consumer menu options that include unstaged paths).

## 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/mcp/ai-evidence-v2.1-contract.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
```

## Support toolkit (optional)

Adapter diagnostics and rollout helpers are intentionally outside the deterministic gate runtime and outside the product baseline.

- They live under `scripts/*` and `docs/validation/*`.
- They do not change PRE_COMMIT/PRE_PUSH/CI outcomes.
- They support rollout diagnostics and incident triage as auxiliary toolkit.

Typical commands:

```bash
npm run toolkit:adapter-readiness -- \
  --adapter-report .audit-reports/adapter/adapter-real-session-report.md \
  --out .audit-reports/adapter/adapter-readiness.md

npm run toolkit:adapter-session-status -- \
  --out .audit-reports/adapter/adapter-session-status.md

npm run toolkit:adapter-real-session-report -- \
  --status-report .audit-reports/adapter/adapter-session-status.md \
  --out .audit-reports/adapter/adapter-real-session-report.md

npm run toolkit: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 toolkit: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
```

Primary namespace is `toolkit:*`; legacy `validation:*` aliases remain only for compatibility. Current adapter readiness command still 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
```