pactkit 2.24.2__tar.gz → 2.25.1__tar.gz

{pactkit-2.24.2 → pactkit-2.25.1}/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [2.25.1] - 2026-09-01
+
+### Fixed
+- **`pactkit gate authorize <scope>` parses as documented** — 2.25.0's parser accepted only the bare positional form (`pactkit gate <scope>`), so the form printed by every block message and the L1 Override Protocol failed with "unrecognized arguments"; both forms now parse (HOTFIX-slim-20260830bbb5bc219d35).
+- **Cross-repo commands are judged by the repo they operate on** — `cd <other-repo> && git push` was evaluated against the session cwd's enforcement config; `hook_entry` now resolves the last `cd` target before the git command and evaluates gates against that repository (HOTFIX-slim-20260830bbb5bc219d35).
+- **commit-gate no longer misfires on docs/meta-only commits** — three defects that blocked a zero-code design-baseline commit three times and forced test-writing before allowing it (HOTFIX-slim-20260901469666ef23a8): `.gitignore`/`.claude/**`/`.codex/**` are now doc-only (repo/agent metadata carries no runtime code and no longer disqualifies the change set from the skip path); the full-suite target falls back from `tests/unit/` to `tests/` when only a flat layout exists, and a zero-collected run reports "no tests collected" instead of implying failures (still RED — the TDD contract is unchanged); "No module named pytest" from the venv-less fallback interpreter raises `GateUnavailable` → WARN + allow, matching the missing-binary path (R3 self-lock protection).
+
+## [2.25.0] - 2026-08-30
+
+### Added
+- **Protected-branch push gate** — `git push` to a protected branch (default `main`/`master`) is intercepted across all three channels (PreToolUse, codex hooks.json, git pre-push) and blocked with an actionable message: the sanctioned path (feature branch + PR), the human bypass (`PACTKIT_ALLOW_DIRECT_PUSH=1` via the `!` prefix), and the repo-owner config (`enforcement.allow_direct_push`). Direct commits on protected branches block by default instead of merely running the full suite; `--no-verify` is no longer a free PreToolUse bypass (the agent can type it; only the env var proves a human channel). Every block and bypass is audited under `push_gate`.
+- **Tamper guard** — agent modification of enforcement artifacts is blocked: `.git/hooks/**`, `.pactkit/enforcement/**`, `.codex/hooks.json` fully; `.claude/settings.json` only when the edit removes a gate registration. Bypass: `PACTKIT_ALLOW_CONFIG_EDIT=1` or `enforcement.tamper_guard: false`.
+- **L1 Hard-Rule Override Protocol** — core rules now state that L1 rules are never waivable in conversation: a conflicting user instruction is refused (not obeyed), and editing rules/hooks/gate config to comply is itself L1 tampering. Sanctioned channels: do it the sanctioned way, the human runs the command via `!`, or the repo owner changes the config.
+- **Stack-aware commit-gate test commands** — the gate runs the detected stack's real suite (`npm test` / `go test ./...` / `mvn|gradle test`) instead of forcing pytest onto Node/Go/Java repos; `pactkit doctor` probes report stack-specific availability. Python keeps the venv-aware pytest path verbatim (monorepos included).
+- **Session context hooks** — `pactkit gate --hook session-start` regenerates `.pactkit/context.md` and prints it (SessionStart injects stdout as context; fires post-compaction too), `--hook pre-compact` refreshes state as a side effect and never blocks compaction. Cold-start orientation is deterministic instead of prompt-hoped.
+- **Spec tampering guard** — during Act, editing a spec with an active preflight receipt is blocked ("Spec is Law", L1); Plan-phase spec writing is unaffected (no receipt exists yet). Bypass: `PACTKIT_ALLOW_SPEC_EDIT=1` or `pactkit gate authorize spec_edit`.
+- **Authorization gate** — external-effect commands (`gh pr create`, `gh release create|delete|upload`, `gh repo create|delete`, `npm`/`pnpm`/`yarn`/`cargo publish`, `twine upload`, `docker push`) block until the user authorizes: ask first, then `pactkit gate authorize <scope>` opens a short-TTL audited window; the strict human channel is `PACTKIT_AUTHORIZED=1` via `!`. Read-only variants never match. Honest threat model: prevents forgetting, not malice — all uses leave records.
+- **Secrets gate** — Bash commands containing literal credential material (AWS `AKIA…`, `ghp_`/`github_pat_`, `glpat-`, `xox?-`, `sk-…`, private keys, `password=`/`pwd=`/`passwd=` with a literal value) block by default; env-var indirection (`password=$DB_PASS`) is exempt as the sanctioned pattern. Bypass: `PACTKIT_ALLOW_SECRET=1` or `enforcement.secrets_gate: false`.
+- **`pactkit gate` command** — one entry for session hooks and `authorize <scope> [--ttl-minutes N]` (token lives in the tamper-guard-protected `.pactkit/enforcement/`).
+- **Gate telemetry** — gate blocks, authorizations, and Skill invocations feed the run-event stream (`gate_blocked` / `authorization_asked` / `authorization_granted` / `command_invoked`) so `pactkit stats` reflects real direct-PDCA usage, not only the workflow engine: per-gate block counts, per-command invocation counts, and the authorization pair at project scope. Telemetry is best-effort and never blocks a gate verdict.
+- **`enforcement` config section** — `protected_branches` (default `[main, master]`), `allow_direct_push` (false), `tamper_guard` (true), `spec_guard` (true), `auth_gate` (true), `secrets_gate` (true), `auth_ttl_minutes` (30). Missing/malformed values fall back to safe defaults.
+
+### Fixed
+- **Git hooks no longer lock out machines without pactkit** — generated pre-commit/pre-push scripts probe `command -v pactkit` and WARN + allow when the binary is missing (was: exit 127 blocking every commit for teammates/CI in non-Python teams).
+- **Audit records no longer persist credentials** — command-derived text is redacted (`[REDACTED:{pattern}]`) before any persistence (enforcement reasons, event details, stderr); `pactkit clean` scrubs legacy records once. Found in the 2026-08-30 fleet inspection: a blocked `PGPASSWORD=…` command had written the literal password into the on-disk audit record.
+
+### Changed
+- **Behavior change (intentional)**: direct commits on `main`/`master` that previously "just ran more tests" now block by default — set `enforcement.allow_direct_push: true` (PactKit's own repo does) or use the bypass env var.
+- `pactkit stats` output gains a project-scoped `Gate telemetry` section (JSON: `gate_telemetry`).
+- Constitution baseline: core protocol word budget 735→900 (L1 Override Protocol + authorize channel).
+
 ## [2.24.2] - 2026-08-27
 
 ### Fixed

{pactkit-2.24.2 → pactkit-2.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 2.24.2
+Version: 2.25.1
 Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
 Project-URL: Homepage, https://pactkit.dev
 Project-URL: Repository, https://github.com/pactkit/pactkit-public
@@ -23,7 +23,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: all
-Requires-Dist: pactkit-codex<2.25.0,>=2.24.0; extra == 'all'
+Requires-Dist: pactkit-codex<2.26.0,>=2.25.0; extra == 'all'
 Requires-Dist: pactkit-opencode>=2.9.0; extra == 'all'
 Requires-Dist: ruff>=0.4; extra == 'all'
 Requires-Dist: tree-sitter-go>=0.25; extra == 'all'
@@ -31,7 +31,7 @@ Requires-Dist: tree-sitter-java>=0.23; extra == 'all'
 Requires-Dist: tree-sitter-typescript>=0.23; extra == 'all'
 Requires-Dist: tree-sitter>=0.25; extra == 'all'
 Provides-Extra: codex
-Requires-Dist: pactkit-codex<2.25.0,>=2.24.0; extra == 'codex'
+Requires-Dist: pactkit-codex<2.26.0,>=2.25.0; extra == 'codex'
 Provides-Extra: lint
 Requires-Dist: ruff>=0.4; extra == 'lint'
 Provides-Extra: opencode
@@ -280,7 +280,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 ## CLI Subcommands
 
-PactKit ships 36 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+PactKit ships 45 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
 
 | Command | Purpose |
 |---------|---------|
@@ -312,11 +312,27 @@ PactKit ships 36 deterministic CLI subcommands — operations that were previous
 | `pactkit lint-lessons` | Validate lessons.md structure |
 | `pactkit lint-testcase` | Validate test case structure |
 | `pactkit done-verify` | Archive honesty gate: requirement→test evidence chain, checkbox↔case consistency, status machine (blocks `/project-done` on FAIL) |
-| `pactkit commit-gate` | Pre-commit test gate with skip≠pass transparency; PreToolUse hook + git pre-commit channels, auto-installed per format |
+| `pactkit commit-gate` | Pre-commit test gate with skip≠pass transparency; stack-aware (pytest/npm test/go test/mvn/gradle); PreToolUse hook + git pre-commit/pre-push channels, auto-installed per format |
+| `pactkit gate` | Session context hooks (`--hook session-start/pre-compact`) + external-effect authorization (`pactkit gate <scope> [--ttl-minutes N]`) |
 | `pactkit deps` | External dependency check (`deps check`) and guided install (`deps install`) for node/codegraph/gh |
 | `pactkit schema config` | List every pactkit.yaml key with default, effective value, and source |
 | `pactkit sync` | Sync codegraph index |
 
+### Enforcement Gates (2.25.0)
+
+The hook layer enforces the rules prompt text can only state — protected branches, specs, credentials, and external effects survive a conflicting instruction instead of losing to it:
+
+| Gate | Blocks | Bypass (human/config only) |
+|------|--------|---------------------------|
+| `push_gate` | Direct push to a protected branch (default `main`/`master`) | `PACTKIT_ALLOW_DIRECT_PUSH=1` or `enforcement.allow_direct_push` |
+| `commit_gate` | Commits on protected branches (default) and RED test suites | same as push_gate; `develop` keeps the full-suite rule |
+| `spec_guard` | Editing a spec that has an active preflight receipt (Spec is Law during Act) | `PACTKIT_ALLOW_SPEC_EDIT=1` or `pactkit gate spec_edit` |
+| `auth_gate` | External-effect commands (PR/release/publish/repo) until the user confirms | `pactkit gate <scope>` TTL token or `PACTKIT_AUTHORIZED=1` |
+| `secrets_gate` | Literal credential material in commands (env-var indirection is exempt) | `PACTKIT_ALLOW_SECRET=1` |
+| `tamper_guard` | Modifying enforcement artifacts (hooks, gate registrations, audit records) | `PACTKIT_ALLOW_CONFIG_EDIT=1` |
+
+All blocks/bypasses are audited (`.pactkit/enforcement/`) and feed `pactkit stats` as gate telemetry (per-gate block counts, per-command invocation counts, authorization pairs) — the friction data that decides what to tune next.
+
 ## Deployment Architecture
 
 PactKit supports three deployment formats:

{pactkit-2.24.2 → pactkit-2.25.1}/README.md

@@ -235,7 +235,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 ## CLI Subcommands
 
-PactKit ships 36 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+PactKit ships 45 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
 
 | Command | Purpose |
 |---------|---------|
@@ -267,11 +267,27 @@ PactKit ships 36 deterministic CLI subcommands — operations that were previous
 | `pactkit lint-lessons` | Validate lessons.md structure |
 | `pactkit lint-testcase` | Validate test case structure |
 | `pactkit done-verify` | Archive honesty gate: requirement→test evidence chain, checkbox↔case consistency, status machine (blocks `/project-done` on FAIL) |
-| `pactkit commit-gate` | Pre-commit test gate with skip≠pass transparency; PreToolUse hook + git pre-commit channels, auto-installed per format |
+| `pactkit commit-gate` | Pre-commit test gate with skip≠pass transparency; stack-aware (pytest/npm test/go test/mvn/gradle); PreToolUse hook + git pre-commit/pre-push channels, auto-installed per format |
+| `pactkit gate` | Session context hooks (`--hook session-start/pre-compact`) + external-effect authorization (`pactkit gate <scope> [--ttl-minutes N]`) |
 | `pactkit deps` | External dependency check (`deps check`) and guided install (`deps install`) for node/codegraph/gh |
 | `pactkit schema config` | List every pactkit.yaml key with default, effective value, and source |
 | `pactkit sync` | Sync codegraph index |
 
+### Enforcement Gates (2.25.0)
+
+The hook layer enforces the rules prompt text can only state — protected branches, specs, credentials, and external effects survive a conflicting instruction instead of losing to it:
+
+| Gate | Blocks | Bypass (human/config only) |
+|------|--------|---------------------------|
+| `push_gate` | Direct push to a protected branch (default `main`/`master`) | `PACTKIT_ALLOW_DIRECT_PUSH=1` or `enforcement.allow_direct_push` |
+| `commit_gate` | Commits on protected branches (default) and RED test suites | same as push_gate; `develop` keeps the full-suite rule |
+| `spec_guard` | Editing a spec that has an active preflight receipt (Spec is Law during Act) | `PACTKIT_ALLOW_SPEC_EDIT=1` or `pactkit gate spec_edit` |
+| `auth_gate` | External-effect commands (PR/release/publish/repo) until the user confirms | `pactkit gate <scope>` TTL token or `PACTKIT_AUTHORIZED=1` |
+| `secrets_gate` | Literal credential material in commands (env-var indirection is exempt) | `PACTKIT_ALLOW_SECRET=1` |
+| `tamper_guard` | Modifying enforcement artifacts (hooks, gate registrations, audit records) | `PACTKIT_ALLOW_CONFIG_EDIT=1` |
+
+All blocks/bypasses are audited (`.pactkit/enforcement/`) and feed `pactkit stats` as gate telemetry (per-gate block counts, per-command invocation counts, authorization pairs) — the friction data that decides what to tune next.
+
 ## Deployment Architecture
 
 PactKit supports three deployment formats:

pactkit-2.25.1/docs/architecture/governance/lessons/LESSON-20260828102433-81cd3e00a0.md

@@ -0,0 +1,10 @@
+---
+schema_version: 1
+id: LESSON-20260828102433-81cd3e00a0
+date: '2026-08-28'
+story_id: STORY-slim-20260828897396a935ab
+context: session_gate.py:pre_compact_entry
+tags: []
+---
+
+SessionStart/PreCompact 契约不对称：前者 stdout 注入上下文且 compact 后触发，后者 stdout 只进 debug log——压缩前刷新状态文件必须做成副作用而非打印

pactkit-2.25.1/docs/architecture/governance/lessons/LESSON-20260830034504-4f7d0f8c58.md

@@ -0,0 +1,10 @@
+---
+schema_version: 1
+id: LESSON-20260830034504-4f7d0f8c58
+date: '2026-08-30'
+story_id: STORY-slim-20260830c65491123af1
+context: run_stats.py:collect_gate_telemetry
+tags: []
+---
+
+计数器断线的根因是聚合端与发射端分离：run_stats 早已统计 authorization_asked/granted 但只有 workflow engine 发射——补遥测的正确切入点是 gate 拦截咽喉点（_record_gate/tamper_guard、check_command 各 gate）而非聚合层

{pactkit-2.24.2 → pactkit-2.25.1}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 4711+ tests must pass before any commit to `main`.
+1. All 4791+ tests must pass before any commit to `main`.
 2. Specs (`docs/specs/`) are the source of truth — code conforms to specs, not the reverse.
 3. CLI entry point is `pactkit` via `src/pactkit/cli.py:main`.
 4. No runtime dependencies beyond `pyyaml`.

pactkit-2.25.1/docs/product/stories/HOTFIX-slim-20260828ee6cde3108fb.yaml

@@ -0,0 +1,13 @@
+schema_version: 1
+id: HOTFIX-slim-20260828ee6cde3108fb
+title: git hooks must not lock everyone out when pactkit is missing
+spec_path: docs/specs/HOTFIX-slim-20260828ee6cde3108fb.md
+status: archived
+tasks:
+- id: task-ce700c4d7c
+  title: PATH probe in generated pre-commit/pre-push scripts
+  completed: true
+created_at: '2026-08-28T09:40:06+00:00'
+updated_at: '2026-08-28T10:25:19+00:00'
+completed_at: '2026-08-28T09:45:19+00:00'
+archived_at: '2026-08-28T10:25:19+00:00'

pactkit-2.25.1/docs/product/stories/HOTFIX-slim-20260830bbb5bc219d35.yaml

@@ -0,0 +1,19 @@
+schema_version: 1
+id: HOTFIX-slim-20260830bbb5bc219d35
+title: gate CLI syntax + push-gate cross-repo root
+spec_path: docs/specs/HOTFIX-slim-20260830bbb5bc219d35.md
+status: archived
+tasks:
+- id: task-28c4e1d550
+  title: Accept authorize keyword in gate CLI
+  completed: true
+- id: task-f5de85695c
+  title: Resolve cd-target repo in hook_entry
+  completed: true
+- id: task-0764566491
+  title: Focused tests + golden refresh
+  completed: true
+created_at: '2026-08-30T04:48:13+00:00'
+updated_at: '2026-09-01T09:06:16+00:00'
+completed_at: '2026-08-30T04:52:32+00:00'
+archived_at: '2026-09-01T09:06:16+00:00'

pactkit-2.25.1/docs/product/stories/HOTFIX-slim-20260901469666ef23a8.yaml

@@ -0,0 +1,16 @@
+schema_version: 1
+id: HOTFIX-slim-20260901469666ef23a8
+title: commit-gate misfires on docs/meta-only commits
+spec_path: docs/specs/HOTFIX-slim-20260901469666ef23a8.md
+status: archived
+tasks:
+- id: task-b98663e6af
+  title: 'Fix three defects: doc-only patterns miss repo meta files (.gitignore/.claude/.codex);
+    full-suite target hard-codes tests/unit/ with no tests/ fallback and counts exit
+    4/5 as RED; missing pytest module (pipx fallback) reads as RED instead of GateUnavailable.
+    From harness-backend 2026-09-01 friction.'
+  completed: true
+created_at: '2026-09-01T08:29:59+00:00'
+updated_at: '2026-09-01T09:06:16+00:00'
+completed_at: '2026-09-01T08:50:16+00:00'
+archived_at: '2026-09-01T09:06:16+00:00'

pactkit-2.25.1/docs/product/stories/STORY-slim-20260828897396a935ab.yaml

@@ -0,0 +1,31 @@
+schema_version: 1
+id: STORY-slim-20260828897396a935ab
+title: 'Hook coverage expansion: session context, spec/auth/secrets gates'
+spec_path: docs/specs/STORY-slim-20260828897396a935ab.md
+status: archived
+tasks:
+- id: task-88ef617a79
+  title: auth_gate module + TTL token
+  completed: true
+- id: task-4fe2f5e463
+  title: secrets_gate credential patterns
+  completed: true
+- id: task-3599c86e37
+  title: session_gate SessionStart/PreCompact
+  completed: true
+- id: task-9ea9b99702
+  title: spec_guard in tamper_guard
+  completed: true
+- id: task-dbae64cef8
+  title: dispatch wiring + install registration
+  completed: true
+- id: task-58f20fc032
+  title: config/enforcement/cli extensions
+  completed: true
+- id: task-fe4d5a6fb7
+  title: unit tests AC1-AC6
+  completed: true
+created_at: '2026-08-28T10:12:42+00:00'
+updated_at: '2026-08-28T10:25:19+00:00'
+completed_at: '2026-08-28T10:23:54+00:00'
+archived_at: '2026-08-28T10:25:19+00:00'

pactkit-2.25.1/docs/product/stories/STORY-slim-202608289e83eeb30df4.yaml

@@ -0,0 +1,31 @@
+schema_version: 1
+id: STORY-slim-202608289e83eeb30df4
+title: Protected-branch push gate + L1 hard-rule override protocol
+spec_path: docs/specs/STORY-slim-202608289e83eeb30df4.md
+status: archived
+tasks:
+- id: task-ea1a074f1b
+  title: Extend hook_entry with git push matching + branch resolution + block/bypass
+  completed: true
+- id: task-0697f734bc
+  title: Add enforcement config section to config.py
+  completed: true
+- id: task-99362d5614
+  title: Install pre-push hook + tamper guard registration + ensure_gate_channel
+  completed: true
+- id: task-642a8a34e6
+  title: Extend GATES + probe_push_gate + doctor output
+  completed: true
+- id: task-0697d362c6
+  title: 'Upgrade prompts/rules.py: L1 entries + Override Protocol'
+  completed: true
+- id: task-3957ff25e0
+  title: Write unit tests for AC1-AC8
+  completed: true
+- id: task-4ae76ca85f
+  title: Set pactkit self-config allow_direct_push/tamper_guard
+  completed: true
+created_at: '2026-08-28T07:32:17+00:00'
+updated_at: '2026-08-28T10:25:19+00:00'
+completed_at: '2026-08-28T09:37:23+00:00'
+archived_at: '2026-08-28T10:25:19+00:00'

pactkit-2.25.1/docs/product/stories/STORY-slim-20260828d43fae4edbb6.yaml

@@ -0,0 +1,22 @@
+schema_version: 1
+id: STORY-slim-20260828d43fae4edbb6
+title: Stack-aware commit-gate test commands (node/go/java)
+spec_path: docs/specs/STORY-slim-20260828d43fae4edbb6.md
+status: archived
+tasks:
+- id: task-2f9bce4ef2
+  title: utils.stack_test_command marker resolution
+  completed: true
+- id: task-f3ec4c758a
+  title: run_pytest stack dispatch + GateUnavailable
+  completed: true
+- id: task-9fe787b9dd
+  title: probe_commit_gate stack-aware
+  completed: true
+- id: task-8c24910f22
+  title: unit tests AC1-AC5
+  completed: true
+created_at: '2026-08-28T09:43:04+00:00'
+updated_at: '2026-08-28T10:25:19+00:00'
+completed_at: '2026-08-28T09:45:19+00:00'
+archived_at: '2026-08-28T10:25:19+00:00'

pactkit-2.25.1/docs/product/stories/STORY-slim-20260830c65491123af1.yaml

@@ -0,0 +1,28 @@
+schema_version: 1
+id: STORY-slim-20260830c65491123af1
+title: Gate telemetry truthfulness + audit-record redaction
+spec_path: docs/specs/STORY-slim-20260830c65491123af1.md
+status: archived
+tasks:
+- id: task-e925929544
+  title: redact_command helper + persisted reason redaction
+  completed: true
+- id: task-52f121ef11
+  title: EVENT_TYPES extension + gate event emission
+  completed: true
+- id: task-14aa0a45c6
+  title: Skill matcher telemetry branch
+  completed: true
+- id: task-c2d0f91cc2
+  title: run_stats gate/command counters
+  completed: true
+- id: task-ca9189a213
+  title: clean-time legacy record scrub
+  completed: true
+- id: task-31e039b53c
+  title: unit tests AC1-AC5
+  completed: true
+created_at: '2026-08-30T03:29:00+00:00'
+updated_at: '2026-08-30T03:46:05+00:00'
+completed_at: '2026-08-30T03:35:56+00:00'
+archived_at: '2026-08-30T03:46:05+00:00'

pactkit-2.25.1/docs/specs/HOTFIX-slim-20260828ee6cde3108fb.md

@@ -0,0 +1,40 @@
+# HOTFIX-slim-20260828ee6cde3108fb: git hooks must not lock everyone out when pactkit is missing
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-20260828ee6cde3108fb |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.25.0 |
+
+## Background
+
+The git hooks written by `install_git_hook` / `install_pre_push_hook`
+(`src/pactkit/commit_gate.py`) call `exec pactkit commit-gate`.  On a
+machine without the pactkit binary on PATH (teammates, CI runners, docker
+builds — the default state in Node.js teams that never install Python),
+the shell exits 127 and git treats the failed hook as a block: **every
+commit and push is locked out by a broken gate**, violating the R3
+self-lock protection principle (a gate that cannot run must WARN and
+allow, not masquerade as enforcement).
+
+## Target
+
+`src/pactkit/commit_gate.py` — `install_git_hook` (~:687) and
+`install_pre_push_hook` (~:702): generated hook scripts gain a PATH probe
+(`command -v pactkit`) that prints a WARN and exits 0 when the binary is
+missing.  The chain-onto-existing-hook path gets the same probe.
+
+## Fix
+
+Prepend to both generated scripts:
+
+```sh
+command -v pactkit >/dev/null 2>&1 || {
+  echo "[WARN] pactkit not on PATH — gate skipped (unavailable, not enforced)"
+  exit 0
+}
+```
+
+Verification: unit tests assert the probe is present in installed hook
+scripts (`tests/unit/test_commit_gate.py`, `tests/unit/test_push_gate.py`).

pactkit-2.25.1/docs/specs/HOTFIX-slim-20260830bbb5bc219d35.md

@@ -0,0 +1,42 @@
+# HOTFIX-slim-20260830bbb5bc219d35: gate CLI syntax mismatch + push-gate cross-repo blind spot
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-20260830bbb5bc219d35 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.25.1 |
+
+## Background
+
+Two defects surfaced during the 2.25.0 release run (post-tag, so they
+ship in 2.25.1):
+
+1. **auth-gate teaches a CLI form that does not exist.** The block
+   message (and the L1 Override Protocol prompt text, and
+   critical-rules.md on the user's machine) instructs
+   `pactkit gate authorize <scope>` — but the `gate` parser accepts only
+   the bare positional `pactkit gate <scope>`. The documented form fails
+   with "unrecognized arguments". Unit tests call `auth_gate.authorize()`
+   directly, so the CLI layer was never exercised. Every internal user
+   hits this on their first external-effect command.
+2. **push-gate evaluates the wrong repository for cross-repo commands.**
+   `cd ~/other-repo && git push` is judged against the SESSION cwd's
+   enforcement config (payload `cwd`), not the target repo's — observed
+   live when the plugin-repo push was allowed by pactkit's own
+   `allow_direct_push: true` although the plugin repo has no config.
+
+## Fix
+
+1. `cli.py`: `gate` accepts both `pactkit gate authorize <scope>` and
+   `pactkit gate <scope>` (positional `scope` becomes `nargs="*"`; an
+   `authorize` keyword is normalized away). Help text documents both.
+   All existing message/prompt text becomes correct as-is.
+2. `commit_gate.py`: `_command_root()` resolves the last `cd <dir>`
+   prefix target in the command (absolute, or relative to the payload
+   root; non-dirs ignored) and `hook_entry` evaluates gates against that
+   root — a `cd`-prefixed command is judged by the repo it operates on.
+
+Verification: focused unit tests for both behaviors + full suite +
+regenerated `gate.txt` help golden. Push to main only; no release, no
+version bump, no adapter/plugin/site sync (deferred to 2.25.1).

pactkit-2.25.1/docs/specs/HOTFIX-slim-20260901469666ef23a8.md

@@ -0,0 +1,55 @@
+# HOTFIX-slim-20260901469666ef23a8: commit-gate misfires on docs/meta-only commits
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-20260901469666ef23a8 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.25.1 |
+
+## Background
+
+A zero-code design-baseline commit (harness-backend root commit,
+2026-09-01) was blocked three times by the commit gate with "FULL —
+impact mapping empty — full unit suite (safe default)" and finally
+forced the agent to write tests, move them to `tests/unit/`, and
+bootstrap a venv before the commit went through. Three defects
+conspired, each violating the gate's own documented intent:
+
+1. **Repo meta files break doc-only classification.** `.gitignore` and
+   `.claude/settings.json` carry no runtime code, yet they disqualify
+   the whole change set from the doc-only skip
+   (`regression.py` `_DOC_ONLY_PATTERNS`), contradicting the module's
+   own "doc-only — safe to skip tests" contract.
+2. **"Repo has no tests" is treated as "tests failed".** The full
+   strategy hard-codes `tests/unit/`; a repo whose tests live at
+   `tests/` (or that has none yet) yields exit 4/5, and `run_gate`
+   counts any nonzero returncode as RED — converting "nothing to
+   verify" into "write tests before any commit".
+3. **Missing pytest module reads as RED, not unavailable.** With no
+   project venv, `pytest_command` falls back to the pipx interpreter;
+   `python -m pytest` exits 1 with "No module named pytest", which
+   `run_gate` reports as failing tests. This violates R3 self-lock
+   protection (a gate that cannot run must WARN and allow) and is
+   inconsistent with the existing `FileNotFoundError` → WARN path for
+   a missing pytest binary.
+
+## Fix
+
+1. `regression.py`: `_DOC_ONLY_PATTERNS` gains `.gitignore`,
+   `.claude/**`, `.codex/**` — agent/repo metadata with no runtime
+   code. Tamper guard is a separate channel and is unaffected.
+2. `commit_gate.py run_pytest`: the full-suite target falls back from
+   `tests/unit/` to `tests/` when only the latter exists, so a
+   non-convention suite is still run instead of erroring. A repo with
+   no tests at all keeps the RED verdict — the TDD contract ("code
+   changes require tests") is untouched, but the verdict message now
+   says "no tests collected" instead of implying failures.
+3. `commit_gate.py run_pytest`: output containing "No module named
+   pytest" raises `GateUnavailable` → WARN + allow, matching the
+   missing-binary path (R3).
+
+Out of scope (unchanged): trunk full-suite rule, protected-branch
+block rule, tamper guard, secrets gate.
+
+Verification: focused unit tests for all three behaviors + full suite.