pumuki 6.3.13 → 6.3.15

package/README.md

@@ -21,8 +21,9 @@ Pumuki converts code changes into traceable, reproducible decisions:
 - [Quick Start for Consumer Repositories](#quick-start-for-consumer-repositories)
 - [Lifecycle Commands](#lifecycle-commands)
 - [Gate Commands](#gate-commands)
+- [OpenSpec SDD (Mandatory)](#openspec-sdd-mandatory)
 - [Architecture and Policy Model](#architecture-and-policy-model)
-- [MCP Evidence Context Server (Optional)](#mcp-evidence-context-server-optional)
+- [MCP Servers (Optional)](#mcp-servers-optional)
 - [Framework Development (This Repository)](#framework-development-this-repository)
 - [Deterministic Validation Suite](#deterministic-validation-suite)
 - [Troubleshooting](#troubleshooting)
@@ -47,10 +48,11 @@ Legacy package `pumuki-ast-hooks` is deprecated and frozen at `6.3.7`.
 ## Capabilities
 
 - Stage-aware gate policies: `PRE_COMMIT`, `PRE_PUSH`, `CI`.
+- OpenSpec SDD enforcement across `PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, and `CI`.
 - Multi-platform detection and combined evaluation: iOS, Backend, Frontend, Android.
 - Rules + overrides with locked baseline semantics.
 - Deterministic evidence (`.ai_evidence.json`) for machine and human workflows.
-- Optional read-only MCP evidence server for agent consumption.
+- Optional MCP servers (evidence + enterprise baseline surface) for agent consumption.
 
 ## Quick Start for Consumer Repositories
 
@@ -74,14 +76,21 @@ Run from the target repository root:
 npx pumuki install
 ```
 
-### 3) Verify lifecycle status
+### 3) Verify lifecycle and SDD status
 
 ```bash
 npx pumuki doctor
 npx pumuki status
+npx pumuki sdd status
 ```
 
-### 4) Run stage gates manually (optional)
+### 4) Open SDD session for your active OpenSpec change (required)
+
+```bash
+npx pumuki sdd session --open --change=<change-id>
+```
+
+### 5) Run stage gates manually (optional)
 
 ```bash
 npx pumuki-pre-commit
@@ -89,10 +98,11 @@ npx pumuki-pre-push
 npx pumuki-ci
 ```
 
-### 5) Expected outputs
+### 6) Expected outputs
 
 - Gate exit code: `0` (allow) or `1` (block).
 - Deterministic evidence file: `.ai_evidence.json`.
+- SDD telemetry in evidence: `snapshot.sdd_metrics`.
 
 ### Update and remove
 
@@ -118,6 +128,9 @@ The `pumuki` binary provides repository lifecycle operations:
 | `pumuki update --latest` | Update package and re-apply managed hooks |
 | `pumuki doctor` | Safety checks (hook drift, tracked `node_modules`, lifecycle state) |
 | `pumuki status` | Current lifecycle snapshot |
+| `pumuki sdd status` | OpenSpec/SDD compatibility and active session snapshot |
+| `pumuki sdd validate --stage=<...>` | SDD decision for selected stage (`PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, `CI`) |
+| `pumuki sdd session --open|--refresh|--close` | Manage active SDD session lifecycle per repository |
 
 `pumuki remove` is dependency-safe by design: it never deletes non-Pumuki third-party dependencies and preserves pre-existing third-party empty directories.
 Use `pumuki remove` (or `pumuki uninstall --purge-artifacts` + `npm uninstall pumuki`) for complete teardown.
@@ -131,6 +144,47 @@ Dedicated gate binaries are available:
 | `pumuki-pre-commit` | `PRE_COMMIT` |
 | `pumuki-pre-push` | `PRE_PUSH` |
 | `pumuki-ci` | `CI` |
+| `pumuki-pre-write` | `PRE_WRITE` |
+
+## OpenSpec SDD (Mandatory)
+
+Pumuki now enforces SDD/OpenSpec as a first-class guardrail.
+
+### Enforcement behavior
+
+- `PRE_WRITE`: requires valid OpenSpec installation/project/session.
+- `PRE_COMMIT`, `PRE_PUSH`, `CI`: require valid session plus `openspec validate --changes`.
+- Blocking SDD decisions are emitted into evidence as finding `sdd.policy.blocked` with `source: "sdd-policy"`.
+
+### Auto-bootstrap and compatibility
+
+- `pumuki install` auto-bootstraps OpenSpec when needed:
+  - installs `@fission-ai/openspec@latest` (when `package.json` exists and OpenSpec is missing/incompatible),
+  - scaffolds `openspec/` baseline (`project` file plus archive/spec placeholders) when absent.
+- `pumuki update --latest` migrates legacy `openspec` package to `@fission-ai/openspec` before reapplying hooks.
+
+### Minimal daily flow
+
+```bash
+# one-time per repo
+npx pumuki install
+
+# start/restart work on a change
+npx pumuki sdd session --open --change=<change-id>
+# or
+npx pumuki sdd session --refresh
+
+# verify policy explicitly
+npx pumuki sdd validate --stage=PRE_COMMIT
+```
+
+### Emergency bypass (restricted)
+
+```bash
+PUMUKI_SDD_BYPASS=1 npx pumuki sdd validate --stage=PRE_COMMIT
+```
+
+Use only for controlled incident recovery. Bypass should be temporary and auditable.
 
 ## Architecture and Policy Model
 
@@ -161,11 +215,11 @@ Dedicated gate binaries are available:
 | Frontend | `apps/frontend/**/*.{ts,tsx,js,jsx}` and `apps/web/**/*.{ts,tsx,js,jsx}` |
 | Android | `*.kt`, `*.kts` |
 
-## MCP Evidence Context Server (Optional)
+## MCP Servers (Optional)
 
 MCP is optional. Pumuki core does not depend on MCP.
 
-### Consumer repository usage
+### Consumer repository usage (Evidence Server)
 
 Use the published binary from npm:
 
@@ -181,12 +235,32 @@ Use the published binary from npm:
 }
 ```
 
+### Consumer repository usage (Enterprise Baseline Server)
+
+```json
+{
+  "mcpServers": {
+    "pumuki-enterprise": {
+      "command": "npx",
+      "args": ["--yes", "pumuki-mcp-enterprise"],
+      "cwd": "/absolute/path/to/your-consumer-repo"
+    }
+  }
+}
+```
+
+Enterprise server baseline surface:
+- Resources: `evidence://status`, `gitflow://state`, `context://active`, `sdd://status`, `sdd://active-change`.
+- Tools: `ai_gate_check`, `check_sdd_status`, `validate_and_fix`, `sync_branches`, `cleanup_stale_branches`.
+- Mutating tools are always forced to `dry-run` in baseline mode.
+
 ### Framework repository usage
 
 If you are developing this framework locally:
 
 ```bash
 npm run mcp:evidence
+npm run mcp:enterprise
 ```
 
 ## Framework Development (This Repository)
@@ -215,6 +289,18 @@ Operational menu:
 npm run framework:menu
 ```
 
+Consumer repositories should use:
+
+```bash
+npx --yes pumuki-framework
+```
+
+Menu behavior:
+- Default mode is `Consumer` (focused options: staged/range gates, bundles, evidence, exit).
+- Type `A` to switch to `Advanced` mode (full operational surface).
+- Type `C` in advanced mode to return to consumer mode.
+- Set `PUMUKI_MENU_MODE=advanced` to start directly in advanced mode.
+
 ## Deterministic Validation Suite
 
 Core validation commands used by maintainers:
@@ -234,6 +320,8 @@ Core validation commands used by maintainers:
 | Symptom | Typical cause | Action |
 | --- | --- | --- |
 | Gate behaves differently in local and CI | Skills lock or policy drift | `npm run skills:lock:check` |
+| `pumuki-pre-push` blocks with missing upstream guidance | Branch has no upstream tracking ref | `git push --set-upstream origin <branch>` |
+| CI result differs from expected base range | `GITHUB_BASE_REF` missing and fallback refs unavailable | Ensure `GITHUB_BASE_REF`, or keep `origin/main` / `main` available |
 | `tsx` runtime errors | Unsupported Node runtime | Upgrade to `Node >= 18` |
 | Upgrade side effects | Inconsistent modules/lockfile state | `rm -rf node_modules package-lock.json && npm install` |
 | Consumer repo still has artifacts after tests | Lifecycle was not removed | `npx --yes pumuki remove` |

package/VERSION

@@ -1 +1 @@
-v6.3.11
+v6.3.15

package/bin/pumuki-mcp-enterprise.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runTsEntry } = require('./_run-ts-entry');
+
+process.exit(runTsEntry('integrations/mcp/enterpriseServer.cli.ts', process.argv.slice(2)));

package/bin/pumuki-pre-write.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const { runTsEntry } = require('./_run-ts-entry');
+
+process.exit(
+  runTsEntry('integrations/lifecycle/cli.ts', [
+    'sdd',
+    'validate',
+    '--stage=PRE_WRITE',
+  ])
+);

package/docs/API_REFERENCE.md

@@ -23,6 +23,7 @@ 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)
 
@@ -61,7 +62,7 @@ Files:
 Key helpers:
 
 - `getFactsForCommitRange({ fromRef, toRef, extensions })`
-- `resolveUpstreamRef()`
+- `resolveUpstreamRef()` (`string | null`; `null` when upstream is missing)
 - `resolveCiBaseRef()`
 - `runCliCommand(runner)`
 

package/docs/CORE_INTEGRATIONS_UNTESTED_INVENTORY.md

@@ -0,0 +1,57 @@
+# Deterministic Inventory: core/integrations without direct tests
+
+## Criteria
+- Scope: `*.ts` files under `core/` and `integrations/`, excluding `__tests__/`, `*.test.ts`, `*.spec.ts`, and `*.d.ts`.
+- A file is considered "without direct test" when no sibling `file.test.ts` / `file.spec.ts` exists (or under local `__tests__/`).
+- Deterministic impact prioritization: `score = (reverse_dependencies * 20) + loc`.
+- Priority levels: `P1` (deps>=8 or loc>=220), `P2` (deps>=4 or loc>=140), `P3` (deps>=2 or loc>=70), `P4` otherwise.
+
+## Summary
+- Total source files analyzed: **204**
+- Total test files detected: **208**
+- Total without direct test: **22**
+- Priority distribution: P1=1, P2=1, P3=9, P4=11
+
+## Top 60 by impact
+| Priority | Score | RevDeps | LOC | File |
+|---|---:|---:|---:|---|
+| P1 | 399 | 5 | 299 | `integrations/gate/stagePolicies.ts` |
+| P2 | 138 | 4 | 58 | `integrations/platform/detectPlatforms.ts` |
+| P3 | 172 | 2 | 132 | `integrations/mcp/evidenceContextServer.ts` |
+| P3 | 131 | 3 | 71 | `integrations/mcp/evidencePayloadConfig.ts` |
+| P3 | 103 | 2 | 63 | `integrations/sdd/types.ts` |
+| P3 | 87 | 2 | 47 | `integrations/mcp/evidenceFacetsRulesets.ts` |
+| P3 | 79 | 3 | 19 | `integrations/mcp/evidenceFacetsPlatforms.ts` |
+| P3 | 75 | 2 | 35 | `integrations/mcp/evidenceFacetsFindings.ts` |
+| P3 | 71 | 3 | 11 | `integrations/sdd/index.ts` |
+| P3 | 66 | 3 | 6 | `integrations/mcp/evidenceFacets.ts` |
+| P3 | 64 | 2 | 24 | `integrations/mcp/evidenceFacetsLedger.ts` |
+| P4 | 82 | 1 | 62 | `integrations/mcp/evidencePayloadSummary.ts` |
+| P4 | 46 | 1 | 26 | `integrations/platform/detectFrontend.ts` |
+| P4 | 42 | 1 | 22 | `integrations/platform/detectAndroid.ts` |
+| P4 | 39 | 1 | 19 | `integrations/platform/detectBackend.ts` |
+| P4 | 22 | 1 | 2 | `integrations/mcp/evidenceFacetsSuppressedShare.ts` |
+| P4 | 13 | 0 | 13 | `integrations/git/index.ts` |
+| P4 | 13 | 0 | 13 | `integrations/mcp/evidenceContextServer.cli.ts` |
+| P4 | 9 | 0 | 9 | `integrations/mcp/enterpriseServer.cli.ts` |
+| P4 | 4 | 0 | 4 | `integrations/mcp/evidenceFacetsSnapshot.ts` |
+| P4 | 3 | 0 | 3 | `integrations/mcp/evidenceFacetsBase.ts` |
+| P4 | 2 | 0 | 2 | `integrations/mcp/index.ts` |
+
+## Full artifact
+- See full list in `docs/CORE_INTEGRATIONS_UNTESTED_INVENTORY.json`.
+
+## Selected Initial Atomic Batch (Batch 01)
+- `integrations/gate/stagePolicies.ts` (P1, score 399)
+- `integrations/platform/detectPlatforms.ts` (P2, score 138)
+- `integrations/mcp/evidenceContextServer.ts` (P3, score 172)
+
+### Selection criteria
+- Impact-first selection (score + priority) over the deterministic inventory.
+- Cross-domain coverage (`gate`, `platform`, `mcp`) to reduce early systemic risk.
+- Strict operational limit: maximum 3 files to keep the cycle atomic and traceable.
+
+### Batch 01 exit criteria
+- At least one direct unit test exists for each file in the batch.
+- Batch tests pass locally.
+- Tracker is updated with Batch 01 as ✅ and Batch 02 as the only 🚧 active task.

package/docs/INSTALLATION.md

@@ -1,6 +1,7 @@
 # Installation Guide (v2.x)
 
 This guide covers the active setup for the deterministic framework implementation in this repository.
+From v2.x, SDD with OpenSpec is part of the default enterprise installation path.
 
 ## Prerequisites
 
@@ -33,101 +34,135 @@ npm run test:deterministic
 
 If both commands pass, the workspace is ready.
 
-## Run the framework locally
+## Enterprise consumer installation (recommended)
 
-### Interactive menu
+### 1) Install package
 
 ```bash
-npm run framework:menu
+npm install --save-exact pumuki
 ```
 
-Menu includes deterministic gate actions and optional operational diagnostics adapters.
-
-Optional adapter readiness check:
+### 2) Install managed lifecycle and OpenSpec bootstrap
 
 ```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
+npx --yes pumuki install
 ```
 
-Note: the current adapter implementation uses `--adapter-report` as the adapter input flag.
+Behavior:
+- Installs managed hooks (`pre-commit`, `pre-push`).
+- Auto-installs `@fission-ai/openspec@latest` when OpenSpec is missing/incompatible (when `package.json` exists).
+- Scaffolds `openspec/` baseline if missing (`project` file plus archive/spec placeholders).
 
-### Direct stage runners
+### 3) Verify lifecycle and SDD status
 
 ```bash
-# PRE_COMMIT
-npx tsx integrations/git/preCommitIOS.cli.ts
+npx --yes pumuki doctor
+npx --yes pumuki status
+npx --yes pumuki sdd status
+```
 
-# PRE_PUSH
-npx tsx integrations/git/prePushBackend.cli.ts
+### 4) Open active SDD session
 
-# CI
-npx tsx integrations/git/ciFrontend.cli.ts
+```bash
+npx --yes pumuki sdd session --open --change=<change-id>
 ```
 
-## Lifecycle commands (enterprise consumer repositories)
-
-Install the package from npm (canonical enterprise command):
+Optional maintenance:
 
 ```bash
-npm install --save-exact pumuki
+npx --yes pumuki sdd session --refresh
+npx --yes pumuki sdd validate --stage=PRE_COMMIT
 ```
 
-Install managed Git hooks in the current repository:
+### 5) Run gates
 
 ```bash
-npx --yes pumuki install
+npx --yes pumuki-pre-write
+npx --yes pumuki-pre-commit
+npx --yes pumuki-pre-push
+npx --yes pumuki-ci
 ```
 
-Run lifecycle doctor before rollout:
+## Run menu from this framework repository
+
+### Interactive menu
 
 ```bash
-npx --yes pumuki doctor
+npm run framework:menu
 ```
 
-Uninstall and purge untracked Pumuki artifacts:
+Menu starts in `Consumer` mode by default (focused options for day-to-day gate usage).
+Use `A` to switch to the full `Advanced` menu and `C` to switch back.
+Each option includes a short inline description.
+
+Consumer repositories do not have the `framework:menu` npm script by default.
+Use the published binary instead:
 
 ```bash
-npx --yes pumuki uninstall --purge-artifacts
+npx --yes pumuki-framework
 ```
 
-One-command cleanup and package removal:
+### Direct stage runners
 
 ```bash
-npx --yes pumuki remove
-```
+# PRE_WRITE
+npx --yes pumuki-pre-write
 
-Use this command instead of plain `npm uninstall pumuki` when you need deterministic lifecycle cleanup.
-It also removes orphan `node_modules/.package-lock.json` residue when `node_modules` has no other entries.
-Plain `npm uninstall pumuki` removes only the dependency entry and leaves managed hooks/lifecycle state untouched.
+# PRE_COMMIT
+npx --yes pumuki-pre-commit
 
-Update to latest published Pumuki and re-apply hooks:
+# PRE_PUSH
+npx --yes pumuki-pre-push
 
-```bash
-npx --yes pumuki update --latest
+# CI
+npx --yes pumuki-ci
 ```
 
-Package-level updates/removal also support short npm commands:
+## Lifecycle + SDD commands
 
 ```bash
+# package level
+npm install --save-exact pumuki
 npm update pumuki
 npm uninstall pumuki
+
+# lifecycle
+npx --yes pumuki install
+npx --yes pumuki update --latest
+npx --yes pumuki doctor
+npx --yes pumuki status
+npx --yes pumuki uninstall --purge-artifacts
+npx --yes pumuki remove
+
+# sdd
+npx --yes pumuki sdd status
+npx --yes pumuki sdd validate --stage=PRE_WRITE
+npx --yes pumuki sdd validate --stage=PRE_COMMIT
+npx --yes pumuki sdd validate --stage=PRE_PUSH
+npx --yes pumuki sdd validate --stage=CI
+npx --yes pumuki sdd session --open --change=<change-id>
+npx --yes pumuki sdd session --refresh
+npx --yes pumuki sdd session --close
 ```
 
-## Optional: enable heuristic pilot
+Notes:
+- `pumuki remove` is the deterministic teardown path (`hooks + state + managed artifacts + dependency removal`).
+- Plain `npm uninstall pumuki` removes only the dependency entry.
+- `pumuki update --latest` migrates legacy `openspec` package to `@fission-ai/openspec` when required.
+
+## Guardrails
+
+- `pumuki install` / `pumuki update` block when tracked files exist under `node_modules`.
+- `PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, and `CI` enforce SDD/OpenSpec policy.
+
+Emergency bypass (incident-only):
 
 ```bash
-PUMUKI_ENABLE_AST_HEURISTICS=true npx tsx integrations/git/prePushIOS.cli.ts
+PUMUKI_SDD_BYPASS=1 npx --yes pumuki sdd validate --stage=PRE_COMMIT
 ```
 
+Remove bypass immediately after remediation.
+
 ## CI workflows
 
 The repository ships reusable and platform workflows:
@@ -140,15 +175,16 @@ The repository ships reusable and platform workflows:
 
 Each run uploads `.ai_evidence.json` artifact.
 
-## MCP evidence context server
-
-Start read-only evidence server:
+## MCP servers
 
 ```bash
 npm run mcp:evidence
+npm run mcp:enterprise
 ```
 
-Reference: `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`.
+References:
+- `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`
+- `docs/MCP_SERVERS.md`
 
 ## Evidence file
 
@@ -161,13 +197,24 @@ Schema reference: `docs/evidence-v2.1.md`.
 ### PRE_PUSH fails due to missing upstream
 
 ```bash
-git branch --set-upstream-to origin/<branch>
+git push --set-upstream origin <branch>
 ```
 
 ### CI cannot resolve base ref
 
-Ensure `GITHUB_BASE_REF` is present or that `origin/main` exists.
+Ensure `GITHUB_BASE_REF` is present, or that `origin/main` (preferred) or `main` exists.
+CI fallback order is `origin/main` -> `main` -> `HEAD`.
 
-### No findings while expecting violations
+### SDD blocks installation or gates
 
-Confirm changed files match supported platform paths/extensions consumed by platform detectors.
+```bash
+npx --yes pumuki sdd status
+npx --yes pumuki sdd validate --stage=PRE_COMMIT
+```
+
+Then reopen/refresh active session:
+
+```bash
+npx --yes pumuki sdd session --open --change=<change-id>
+npx --yes pumuki sdd session --refresh
+```