pactkit 2.24.2__tar.gz → 2.25.0__tar.gz

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

@@ -1,5 +1,29 @@
 # Changelog
 
+## [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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 2.24.2
+Version: 2.25.0
 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

pactkit-2.25.0/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.0/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.0}/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.0/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.0/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.0/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.0/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.0/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.0/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.0/docs/specs/STORY-slim-20260828897396a935ab.md

@@ -0,0 +1,246 @@
+# STORY-slim-20260828897396a935ab: Hook coverage expansion: session context, spec/auth/secrets gates
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-20260828897396a935ab |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.25.0 |
+
+## Background
+
+Claude Code exposes 7 hook event families; PactKit uses one (PreToolUse).
+The 2026-08-28 hook-coverage analysis identified five mechanisms whose
+rules today live only in prompt text (the layer that loses to context
+growth and compaction — the exact failure mode behind this release
+train's original incident):
+
+1. **Cold-start orientation**: `.pactkit/context.md` is generated by
+   `pactkit context` but relies on prompt discipline to be read.
+2. **"Spec is Law" (L1)**: agents MUST NOT amend a Spec unilaterally
+   during Act — unenforced. Preflight receipts already bind spec hashes.
+3. **Workflow state loss on compaction**: PDCA state (story, phase,
+   next action) evaporates with the compacted context.
+4. **Authorization list (Runtime Contract)**: push/PR/release/publish/
+   external messages require user authorization — pure prompt today.
+   push-gate (STORY-slim-202608289e83eeb30df4) covers `git push` only.
+5. **Secrets red line (L1)**: never print credentials — unenforced.
+   (Observed live this session: a plaintext password in a curl command
+   entered a transcript.)
+
+Doc-verified hook contracts: SessionStart stdout (plain text) IS injected
+as context and fires with matcher sources including `compact`; PreCompact
+stdout is NOT injected (debug log only) — it is useful for side effects
+only. User-confirmed design decisions: authorization gate = block + TTL
+token (conversation flow, audited, honor-system); secrets gate = block by
+default with env bypass.
+
+## Requirements
+
+### R1: SessionStart context injection (MUST)
+
+A new hook command `pactkit gate --hook session-start` MUST regenerate
+`.pactkit/context.md` (via the existing `context_gen.generate_context`)
+and print it to stdout — SessionStart injects plain-text stdout as
+context, making cold-start orientation deterministic instead of
+prompt-hoped. Because SessionStart fires on source `compact` as well,
+post-compaction re-orientation comes free. When generation fails, the
+hook MUST exit 0 with a one-line WARN (context injection is an aid, never
+a gate). Registered only for Claude Code formats (classic/all); Codex and
+other channels skip session events (not portable).
+
+### R2: PreCompact state refresh (MUST)
+
+`pactkit gate --hook pre-compact` MUST refresh `.pactkit/context.md` as a
+side effect (stdout is discarded by the harness for this event — the
+refresh serves the subsequent SessionStart(compact) injection).
+Compaction MUST NOT be blocked under any code path (exit 0 always; a
+failed refresh is logged, never fatal). Deliberately redundant with R1:
+belt-and-suspenders against SessionStart-source variance.
+
+### R3: Spec tampering guard (MUST)
+
+`tamper_guard.check_edit_tool` and `check_bash_command` MUST block agent
+modification of `docs/specs/*.md` when a preflight receipt exists for
+that story (`.pactkit/preflight/{story_id}/current.json`): during Act the
+Spec is Law, and amendments MUST go back through `/project-plan` (the RFC
+gate's "do not modify the Spec unilaterally"). Plan-phase spec writing is
+unaffected — no receipt exists until spec-preflight runs. Release:
+`PACTKIT_ALLOW_SPEC_EDIT=1` (human channel) or a valid `spec_edit`
+authorization token. Audit under gate name `spec_guard`. Config:
+`enforcement.spec_guard` (default `true`).
+
+### R4: Authorization gate (MUST)
+
+The PreToolUse Bash dispatch (`commit_gate.hook_entry`) MUST block
+external-effect commands until the user has authorized them: `gh pr
+create`, `gh release create|delete|upload`, `gh repo create|delete`,
+`npm publish`, `pnpm publish`, `yarn publish`, `cargo publish`, `twine
+upload`, `docker push`. Read-only variants (`gh pr view`, `gh release
+list`, …) MUST NOT match (subcommand-anchored patterns only). The block
+message MUST instruct: ask the user; after explicit confirmation run
+`pactkit gate authorize <scope>`; the strict human channel is
+`PACTKIT_AUTHORIZED=1` via the `!` prefix. Every block and authorized
+allow MUST be audited under gate name `auth_gate`. Honest threat model
+(documented in the block message rationale): this gate prevents
+forgetting, not malice — the token is agent-invocable by design, all uses
+leave records. Config: `enforcement.auth_gate` (default `true`),
+`enforcement.auth_ttl_minutes` (default `30`).
+
+### R5: Secrets gate (MUST)
+
+The PreToolUse Bash dispatch MUST block commands containing literal
+credential material: `AKIA[0-9A-Z]{16}` (AWS), `ghp_`/`github_pat_`
+(GitHub), `glpat-` (GitLab), `xox[baprs]-` (Slack), `sk-` + 20+ chars
+(API keys), `-----BEGIN … PRIVATE KEY-----`, and `password=`/`pwd=`/
+`passwd=` with a non-empty literal value. Environment-variable
+references (`$VAR`, `${VAR}`) MUST be exempt — indirection is the
+sanctioned pattern. Block by default (user decision), with
+`PACTKIT_ALLOW_SECRET=1` bypass and config `enforcement.secrets_gate`
+(default `true`). Audited under gate name `secrets_gate`.
+
+### R6: authorize CLI + token + registration + doctor (MUST)
+
+`pactkit gate authorize <scope> [--ttl-minutes N]` MUST atomically write
+`.pactkit/enforcement/authorization.json` (`{scope, expires_at, ts}`),
+valid for the configured TTL; guards R3/R4 read it via a shared helper.
+The token file lives under `.pactkit/enforcement/` — already inside the
+tamper guard's protected surface, so raw file tampering stays blocked and
+the CLI is the single audited write path. `install_hook` MUST register
+the SessionStart and PreCompact entries (classic/all formats only).
+`config.py`'s `enforcement` section extends with `spec_guard`,
+`auth_gate`, `secrets_gate` (bool, default `true`) and `auth_ttl_minutes`
+(int, default `30`); the validator's known-key set updates accordingly.
+`GATES` extends with `spec_guard`, `auth_gate`, `secrets_gate`; each gets
+a doctor probe; all three fold into the existing `_enforcement_settings`
+normalization (missing/malformed values fall back to safe defaults).
+
+## Acceptance Criteria
+
+### AC1: SessionStart injects context (R1)
+
+- **Given** a deployed project with board stories and a git repo
+- **When** `pactkit gate --hook session-start` runs
+- **Then** stdout contains the regenerated context (Sprint Status / Current Stories sections) and exit code is 0
+- **Given** generation raises (e.g. unreadable board)
+- **Then** the hook exits 0 with a one-line WARN on stderr, never non-zero
+
+### AC2: PreCompact refreshes state without blocking (R2)
+
+- **Given** a project with workflow state
+- **When** `pactkit gate --hook pre-compact` runs
+- **Then** `.pactkit/context.md` is refreshed (mtime changes) and the exit code is 0
+- **Given** the refresh fails internally
+- **Then** the exit code is still 0 (compaction must never be blocked)
+
+### AC3: Spec tampering blocked during Act (R3)
+
+- **Given** a spec with an active preflight receipt (`current.json` exists and matches the story)
+- **When** an Edit tool call targets `docs/specs/{story}.md`
+- **Then** the hook exits 2 with a "Spec is Law" message and a `spec_guard` record is written
+- **Given** `PACTKIT_ALLOW_SPEC_EDIT=1` in the environment, or a valid `spec_edit` token
+- **When** the same Edit is attempted
+- **Then** it is allowed
+- **Given** a spec with NO receipt (Plan phase, fresh story)
+- **When** an Edit targets it
+- **Then** it is allowed (spec writing is legitimate)
+
+### AC4: External-effect commands gated (R4)
+
+- **Given** a project with default enforcement config
+- **When** the hook receives `gh release create v1.0.0` (or `npm publish`, `gh pr create`, `docker push`, `twine upload dist/*`)
+- **Then** it exits 2 with the ask-first message naming `pactkit gate authorize`, and an `auth_gate` record is written
+- **Given** a valid `release` token (fresh `pactkit gate authorize release`)
+- **When** the same command is received
+- **Then** it is allowed and the authorized allow is recorded
+- **Given** an expired token (> TTL)
+- **When** the same command is received
+- **Then** it is blocked again
+- **Given** read-only commands (`gh pr view 12`, `gh release list`)
+- **When** received
+- **Then** they pass untouched (exit 0, no record)
+
+### AC5: Secrets blocked by default (R5)
+
+- **Given** default enforcement config
+- **When** the hook receives a command containing `AKIAIOSFODNN7EXAMPLE` or `password=Test@1234` or `-----BEGIN RSA PRIVATE KEY-----`
+- **Then** it exits 2 with the secrets red-line message, and a `secrets_gate` record is written
+- **Given** the same command with `PACTKIT_ALLOW_SECRET=1` in the environment, or `password=$DB_PASS` (env indirection)
+- **When** received
+- **Then** it is allowed
+
+### AC6: Registration, config, doctor (R6)
+
+- **Given** `pactkit init --format all` on a fresh project
+- **When** deployment finishes
+- **Then** `.claude/settings.json` contains SessionStart and PreCompact entries alongside the existing PreToolUse matchers, `.codex/hooks.json` does NOT contain session-event entries (not portable), and `pactkit doctor` reports `spec_guard`, `auth_gate`, `secrets_gate` probe status
+- **Given** a pactkit.yaml with `enforcement: {auth_ttl_minutes: "30 minutes"}`
+- **When** config validation runs
+- **Then** a warning is emitted (must be an integer)
+
+## Target Call Chain
+
+```
+SessionStart / PreCompact (Claude Code only, classic|all formats)
+  └─ cli.py (new `gate` subcommand) → session_gate.py (new)
+       ├─ session_start: context_gen.generate_context → print stdout (injected)
+       └─ pre_compact:   context_gen.generate_context (side effect only)
+
+PreToolUse (existing single entry, extended dispatch)
+  └─ commit_gate.hook_entry
+       ├─ git push → check_push                      (existing)
+       ├─ git commit → run_gate                       (existing)
+       └─ otherwise → tamper_guard / new checks:
+            ├─ secrets_gate.scan_command              (new, first — L1)
+            ├─ auth_gate.check_command                (new)
+            ├─ spec_guard: docs/specs/*.md edit check (new, in tamper_guard)
+            └─ tamper_guard.check_bash_command         (existing)
+
+pactkit gate authorize <scope> → authorization.json (atomic, in tamper-guard-
+    protected .pactkit/enforcement/) → shared token reader for R3/R4
+
+config.py enforcement += spec_guard/auth_gate/secrets_gate/auth_ttl_minutes
+enforcement.py GATES += spec_guard/auth_gate/secrets_gate + probes
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/auth_gate.py` (new) | External-effect patterns, token read/write, `pactkit gate authorize` logic | None | Medium |
+| 2 | `src/pactkit/secrets_gate.py` (new) | Credential pattern scan + env-indirection exemption | None | Low |
+| 3 | `src/pactkit/session_gate.py` (new) | session-start / pre-compact entries over context_gen | None | Low |
+| 4 | `src/pactkit/tamper_guard.py` | spec_guard check (receipt lookup) + protected-path integration | Step 1 | Medium |
+| 5 | `src/pactkit/commit_gate.py` | Dispatch wiring: secrets → auth ordering; install SessionStart/PreCompact entries | Steps 1-3 | Medium |
+| 6 | `src/pactkit/config.py` | enforcement keys + validator update | None | Low |
+| 7 | `src/pactkit/enforcement.py` | GATES + probes | Steps 1-4 | Low |
+| 8 | `src/pactkit/cli.py` | `gate` subcommand (`--hook`, `authorize`) | Steps 1-3 | Low |
+| 9 | `tests/unit/test_hook_expansion.py` (new) | AC1-AC6 coverage | Steps 1-8 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | New gate modules; parsing stays regex/JSON with isinstance guards, no eval/shell assembly; token file written atomically |
+| SEC-2 | Yes | Hook stdin is untrusted JSON (existing shape guards); authorization.json is agent-writable by design — document the honor-system threat model |
+| SEC-5 | Yes | The token is a capability credential (short-TTL, local file, tamper-guard protected); MUST NOT contain or derive from real secrets; scopes are a closed set |
+| SEC-7 | Yes | Failure semantics fixed per channel: session hooks never block compaction (exit 0); PreToolUse gates block on their own contract only; every fallback writes a status record |
+| SEC-8 | No | No dependency manifests changed |
+
+## Dependency Surface
+
+| Field | Value |
+|-------|-------|
+| Depends on | STORY-slim-202608289e83eeb30df4 (hook_entry dispatch, tamper_guard surface, enforcement section — same release train, committed 1df1512) |
+| Provides | `pactkit gate` subcommand; `authorization.json` token; gates `spec_guard`/`auth_gate`/`secrets_gate`; session-event registration |
+| Touches | `src/pactkit/{auth_gate,secrets_gate,session_gate,tamper_guard,commit_gate,config,enforcement,cli}.py`, `tests/unit/` (new file) |
+| Conflict risk | LOW |
+
+## Out of Scope
+
+- Stop hook / completion-evidence enforcement (loop-risk design needed — separate story)
+- model-gate (Task-matcher alias rewriting — pending the user's routing decision)
+- PostToolUse fast-lint feedback
+- UserPromptSubmit conditional rule injection
+- Codex/OpenCode parity for session events (not portable; git-fallback channels unchanged)
+- Output-stream secret scanning (PostToolUse) — command-string scan only