# API Reference (v2.x) This document describes the active TypeScript API surface used by the deterministic gate flow in this repository. ## Stage policies File: `integrations/gate/stagePolicies.ts` - `policyForPreCommit(): GatePolicy` - `policyForPrePush(): GatePolicy` - `policyForCI(): GatePolicy` - `applyHeuristicSeverityForStage(rules, stage): RuleSet` ## Git stage runners File: `integrations/git/stageRunners.ts` - `runPreCommitStage(): Promise` - `runPrePushStage(): Promise` - `runCiStage(): Promise` Exit code contract: - `0` on pass/warn - `1` on block or runner error - `1` on `PRE_PUSH` when no upstream tracking branch is configured (fail-safe). ## Platform wrappers (exports) File: `integrations/git/index.ts` - `runPreCommitIOS`, `runPreCommitBackend`, `runPreCommitFrontend`, `runPreCommitAndroid` - `runPrePushIOS`, `runPrePushBackend`, `runPrePushFrontend`, `runPrePushAndroid` - `runCiIOS`, `runCiBackend`, `runCiFrontend`, `runCiAndroid` - `evaluateStagedIOS` (legacy compatibility entry still exported) ## Shared execution entry File: `integrations/git/runPlatformGate.ts` Primary function: - `runPlatformGate(params: { policy: GatePolicy; scope: GateScope; auditMode?: 'gate' | 'engine'; sddShortCircuit?: boolean }): Promise` Behavior: - Builds facts from staged or range scope. - Detects platforms from facts. - Loads and merges baseline + project rules. - Applies optional heuristic rule-pack and stage-aware promotion. - Evaluates findings + gate decision. - Supports dual runtime contract: - `auditMode='gate'`: strict enforcement (SDD short-circuit by default) - `auditMode='engine'`: full diagnostics (no SDD short-circuit by default) - Computes rules coverage telemetry (`active/evaluated/matched/unevaluated`) per stage. - Emits `governance.rules.coverage.incomplete` and forces `BLOCK` when active rules remain unevaluated in `PRE_COMMIT`, `PRE_PUSH`, or `CI`. - Emits `governance.skills.detector-mapping.incomplete` and forces `BLOCK` when AUTO skills rules have no mapped detector. - Writes `.ai_evidence.json` via `generateEvidence`. ## Skills rules engine APIs Files: - `integrations/config/coreSkillsLock.ts` - `integrations/config/skillsEffectiveLock.ts` - `integrations/config/skillsCustomRules.ts` - `integrations/config/skillsRuleSet.ts` Key functions: - `loadCoreSkillsLock(): SkillsLockV1 | undefined` - `loadEffectiveSkillsLock(repoRoot?): SkillsLockV1 | undefined` - `loadCustomSkillsRulesFile(repoRoot?): CustomSkillsRulesFileV1 | undefined` - `loadCustomSkillsLock(repoRoot?): SkillsLockV1 | undefined` - `resolveSkillImportSources({ repoRoot?, explicitSources? }): string[]` - `importCustomSkillsRules({ repoRoot?, sourceFiles? }): CustomSkillsImportResult` - `loadSkillsRuleSetForStage(stage, repoRoot?, detectedPlatforms?)` Deterministic precedence: - `core + repo + custom` merged into one effective lock. - Conflict policy: `custom > repo > core` by `ruleId` during ruleset materialization. ## Git scope helpers Files: - `integrations/git/getCommitRangeFacts.ts` - `integrations/git/resolveGitRefs.ts` - `integrations/git/runCliCommand.ts` Key helpers: - `getFactsForCommitRange({ fromRef, toRef, extensions })` - `resolveUpstreamRef()` (`string | null`; `null` when upstream is missing) - `resolveCiBaseRef()` - `runCliCommand(runner)` ## AI Gate evaluator File: `integrations/gate/evaluateAiGate.ts` - `evaluateAiGate({ repoRoot, stage, maxAgeSecondsByStage?, protectedBranches? })` Contract: - Unified evaluation for `PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI`. - Blocks on: - missing/invalid/stale `.ai_evidence.json` - evidence `ai_gate.status = BLOCKED` - protected branch use (`main/master/develop/dev` by default) - Returns deterministic payload: `status`, `allowed`, `violations[]`, `evidence`, `repo_state`. - Evidence source contract (auditability): - `evidence.source.source` - `evidence.source.path` - `evidence.source.digest` - `evidence.source.generated_at` ## PRE_WRITE JSON envelope File: `integrations/lifecycle/cli.ts` - `pumuki sdd validate --stage=PRE_WRITE --json` - Returns deterministic envelope: - `sdd` - `ai_gate` - `telemetry.chain = "pumuki->ai_gate->ai_evidence"` - `telemetry.stage` ## SaaS diagnostics CLI File: `integrations/lifecycle/cli.ts` - `pumuki analytics hotspots report [--top=] [--since-days=] [--json]` - `pumuki analytics hotspots diagnose [--json]` Exit code contract: - `0` when diagnostics status is `healthy` or `degraded` - `1` when diagnostics status is `blocked` ## Lifecycle status / doctor version contract Files: - `integrations/lifecycle/packageInfo.ts` - `integrations/lifecycle/status.ts` - `integrations/lifecycle/doctor.ts` Machine-readable fields exposed by both `pumuki status --json` and `pumuki doctor --json`: - `version.effective` - `version.runtime` - `version.consumerInstalled` - `version.lifecycleInstalled` - `version.source` - `version.driftFromRuntime` - `version.driftFromLifecycleInstalled` - `version.driftWarning` - `version.alignmentCommand` - `version.pathExecutionHazard` - `version.pathExecutionWarning` - `version.pathExecutionWorkaroundCommand` Compatibility note: - `packageVersion` is preserved for backward compatibility. - `packageVersion` mirrors `version.effective`. Interpretation contract: - `effective`: version currently governing the consumer decision path. - `runtime`: version of the executing package instance. - `consumerInstalled`: version installed in the consumer repository. - `lifecycleInstalled`: version recorded in managed lifecycle metadata. - `driftWarning`: compact human-readable explanation when those values diverge. - `alignmentCommand`: exact remediation command to align dependency and lifecycle state with the current runtime version. - `pathExecutionHazard`: boolean flag raised when the repo root contains the platform `PATH` delimiter and `npx/npm exec` can fail to resolve `pumuki`. - `pathExecutionWarning`: compact warning explaining why `PATH` resolution is unsafe in that repo. - `pathExecutionWorkaroundCommand`: safe local-node entrypoint to use when `pathExecutionHazard=true`. ## Evidence API Files: - `integrations/evidence/schema.ts` - `integrations/evidence/buildEvidence.ts` - `integrations/evidence/writeEvidence.ts` - `integrations/evidence/generateEvidence.ts` Key types: - `AiEvidenceV2_1` - `Snapshot` - `LedgerEntry` - `PlatformState` - `RulesetState` - `RepoState` Contract: - Source of truth: `version: "2.1"` - Deterministic output order - Snapshot + ledger merge model - Snapshot persists `audit_mode` (`gate` | `engine`) for runtime traceability. - Snapshot includes deterministic `rules_coverage` contract: - `active_rule_ids[]` - `evaluated_rule_ids[]` - `matched_rule_ids[]` - `unevaluated_rule_ids[]` - `unsupported_auto_rule_ids[]` (optional; present when AUTO skills have no detector mapping) - `counts` + `coverage_ratio` - Severity metrics include dual projections: - legacy: `severity_metrics.by_severity` (`CRITICAL/ERROR/WARN/INFO`) - enterprise: `severity_metrics.by_enterprise_severity` (`CRITICAL/HIGH/MEDIUM/LOW`) ## Rule packs Files: - `core/rules/presets/iosEnterpriseRuleSet.ts` - `core/rules/presets/backendRuleSet.ts` - `core/rules/presets/frontendRuleSet.ts` - `core/rules/presets/androidRuleSet.ts` - `core/rules/presets/astHeuristicsRuleSet.ts` - `core/rules/presets/rulePackVersions.ts` ## MCP read-only evidence context Files: - `integrations/mcp/evidenceContextServer.ts` - `integrations/mcp/evidenceContextServer.cli.ts` CLI: ```bash npm run mcp:evidence ``` Read-only endpoints: - `GET /health` - `GET /status` - includes `context_api.endpoints[]`, `context_api.filters`, and `context_api.pagination_bounds` capabilities - `GET /ai-evidence` - `GET /ai-evidence/summary` - snapshot metadata includes `has_findings` (fast boolean gate for non-empty findings) - snapshot metadata includes `findings_files_count` (deterministic count of distinct files with findings) - snapshot metadata includes `findings_rules_count` (deterministic count of distinct rule IDs in findings) - snapshot metadata includes `findings_with_lines_count` (deterministic count of findings with line metadata) - snapshot metadata includes `findings_without_lines_count` (deterministic count of findings without line metadata) - includes `rulesets_platforms_count` (deterministic count of distinct platforms covered by loaded rulesets) - includes `rulesets_bundles_count` (deterministic count of distinct loaded ruleset bundles) - includes `rulesets_hashes_count` (deterministic count of distinct loaded ruleset hashes) - includes `ledger_files_count` (deterministic count of distinct files with open ledger entries) - includes `ledger_rules_count` (deterministic count of distinct rule IDs with open ledger entries) - includes `suppressed_replacement_rules_count` (deterministic count of distinct replacement rule IDs in suppressed findings) - includes `suppressed_platforms_count` (deterministic count of distinct platforms represented in suppressed findings) - includes `suppressed_files_count` (deterministic count of distinct files represented in suppressed findings) - includes `suppressed_rules_count` (deterministic count of distinct original rule IDs represented in suppressed findings) - snapshot metadata includes `severity_counts` (deterministic key order) - snapshot metadata includes `findings_by_platform` (deterministic platform-key order) - snapshot metadata includes `highest_severity` (deterministic severity ranking) - snapshot metadata includes `blocking_findings_count` (count of CRITICAL+ERROR findings) - includes `ledger_by_platform` (deterministic platform-key order) - includes `rulesets_by_platform` (deterministic platform-key order) - includes `rulesets_fingerprint` (deterministic ordered hash signature) - includes `platform_confidence_counts` (deterministic counts by platform confidence level) - includes `suppressed_findings_count` (deterministic count of suppressed findings in consolidation) - includes `tracked_platforms_count` (deterministic count of currently tracked platforms) - includes `detected_platforms_count` (deterministic count of currently detected platforms) - includes `non_detected_platforms_count` (deterministic count of currently tracked but non-detected platforms) - `GET /ai-evidence/snapshot` - `GET /ai-evidence/findings` - `GET /ai-evidence/findings?limit=...&offset=...` - deterministic bound: `maxLimit=100` - pagination metadata includes `has_more` when `limit` is provided - `GET /ai-evidence/rulesets` - `GET /ai-evidence/rulesets?platform=...&bundle=...` - `GET /ai-evidence/rulesets?limit=...&offset=...` - deterministic bound: `maxLimit=100` - pagination metadata includes `has_more` when `limit` is provided - `GET /ai-evidence/platforms` - `GET /ai-evidence/platforms?detectedOnly=false&confidence=...` - `GET /ai-evidence/platforms?detectedOnly=false&limit=...&offset=...` - deterministic bound: `maxLimit=100` - pagination metadata includes `has_more` when `limit` is provided - `GET /ai-evidence/ledger` - `GET /ai-evidence/ledger?lastSeenAfter=...&lastSeenBefore=...` - `GET /ai-evidence/ledger?lastSeenAfter=...&lastSeenBefore=...&limit=...&offset=...` - deterministic bound: `maxLimit=100` - pagination metadata includes `has_more` when `limit` is provided Reference: `docs/mcp/evidence-context-server.md`. Consumption: `docs/mcp/agent-context-consumption.md`. ## Local execution quick refs ```bash npm run framework:menu npm run adapter:install -- --agent=codex --dry-run npx --yes pumuki adapter install --agent=cursor npm run toolkit:adapter-readiness npm run typecheck npm run test:deterministic ``` Menu UI rollout controls: - `PUMUKI_MENU_UI_V2=0|1` (`0` default = classic, `1` = modern grouped renderer) - `PUMUKI_MENU_MODE=consumer|advanced` - `PUMUKI_MENU_COLOR`, `PUMUKI_MENU_WIDTH` - v2 renderer failures auto-fallback to classic renderer Consumer menu pre-flight: - options `1/2/3/4` execute pre-flight before gate evaluation - pre-flight checks `repo_state`, stale/missing evidence, git-flow protected branches, and AI gate chain consistency - stage mapping is deterministic: `1/3 -> PRE_COMMIT`, `2/4 -> PRE_PUSH` - consumer mode is a read-only shell: `1/2/3/4` are gate flows, `8` is the matching markdown export, and `5/6/7/9` are `Legacy Read-Only Diagnostics` - in modern UI mode (`PUMUKI_MENU_UI_V2=1`) options are grouped by domains while preserving IDs and execution wiring - advanced maintenance option `33` imports custom rules from `AGENTS.md/SKILLS.md` to `/.pumuki/custom-rules.json` - menu audits no longer bypass SDD; `sdd.policy.blocked` can be emitted in menu-driven runs - advanced options `28/29/30/32` are legacy read-only audits: they help inspect evidence snapshots, but they do not redefine the canonical gate verdict - acceptance baseline helper: `npm run validation:consumer-matrix-baseline -- --repo-root /absolute/path/to/ --fixture --rounds 3 --json` - baseline outputs are written under `.audit-reports/fixture-matrix//consumer-menu-matrix-baseline/{report.json,summary.md}` and return exit `1` on drift - baseline `report.json` also carries `status.policyValidation`, `status.experimentalFeatures`, `doctor.blocking`, and `doctor.layerSummary` - validated acceptance snapshots on `2026-03-14`: `ios-architecture-showcase=stable YES`, `SAAS:APP_SUPERMERCADOS=stable YES`, `R_GO=stable YES` ## Optional support toolkit Primary namespace is `toolkit:*`. Legacy `validation:*` aliases remain only for compatibility. Files: - `scripts/build-adapter-readiness.ts` - `scripts/adapter-readiness-lib.ts` - `scripts/build-phase5-blockers-readiness.ts` - `scripts/phase5-blockers-readiness-lib.ts` - `scripts/build-phase5-execution-closure-status.ts` - `scripts/phase5-execution-closure-status-lib.ts` - `scripts/run-phase5-execution-closure.ts` - `scripts/phase5-execution-closure-lib.ts` - `scripts/clean-validation-artifacts.ts` - `scripts/clean-validation-artifacts-lib.ts` - `scripts/framework-menu.ts` Commands: - `npm run toolkit:adapter-readiness` - `npm run toolkit:adapter-session-status` - `npm run toolkit:adapter-real-session-report` - `npm run toolkit:phase5-blockers-readiness` - `npm run toolkit:phase5-execution-closure-status` - `npm run toolkit:phase5-execution-closure` - `npm run toolkit:clean-artifacts` `toolkit:phase5-execution-closure` notes: - defaults to output directory `.audit-reports/phase5` - runs auth preflight and fails fast on auth/scope blockers - supports `--skip-auth-preflight` when preflight must be bypassed Framework menu action: - `Toolkit: build adapter readiness report` - `Toolkit: build phase5 execution closure status report` - `Toolkit: run phase5 execution closure` - `Toolkit: clean local validation artifacts` Frozen legacy support namespace: - `npm run toolkit:legacy:phase5-external-handoff` - `npm run toolkit:legacy:phase5-latest:refresh` - `npm run toolkit:legacy:phase5-latest:ready-check` - `npm run toolkit:legacy:phase5-escalation:prepare` - `npm run toolkit:legacy:phase8:doctor` - `npm run toolkit:legacy:phase8:close-ready` Legacy advanced menu action: - `Toolkit legacy: build phase5 external handoff report` Deterministic argument builders exported from menu module: - `buildAdapterReadinessCommandArgs({ scriptPath, adapterReportFile, outFile })` - `buildCleanValidationArtifactsCommandArgs({ scriptPath, dryRun })` - `buildImportCustomSkillsCommandArgs()` - `buildPhase5BlockersReadinessCommandArgs({ scriptPath, adapterReportFile, consumerTriageReportFile, outFile })` - `buildPhase5ExecutionClosureStatusCommandArgs({ scriptPath, phase5BlockersReportFile, consumerUnblockReportFile, adapterReadinessReportFile, outFile, requireAdapterReadiness })` - `buildPhase5ExternalHandoffCommandArgs({ scriptPath, repo, phase5StatusReportFile, phase5BlockersReportFile, consumerUnblockReportFile, mockAbReportFile, runReportFile, outFile, artifactUrls, requireArtifactUrls, requireMockAbReport })` - `buildPhase5ExecutionClosureCommandArgs({ scriptPath, repo, limit, outDir, runWorkflowLint, includeAuthPreflight, repoPath, actionlintBin, includeAdapter, requireAdapterReadiness })` Current adapter implementation note: - The adapter report input flag is named `adapterReportFile` / `--adapter-report` for compatibility with existing runbooks.