pactkit 2.26.0__tar.gz → 2.27.0__tar.gz

{pactkit-2.26.0 → pactkit-2.27.0}/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## [2.27.0] - 2026-09-17
+
+> 安全加固版本：六轮对抗评审修复 34 条门禁缺陷 + 项目契约生命周期
+> （adopt / reconcile / project-preflight）。包含行为变更，升级前请阅读 Migration。
+
+### Migration (2.26.1 → 2.27.0)
+
+- **spec_guard：内容漂移从「解锁」改为「锁定」**。live receipt 的哈希与 Spec
+  不符意味着 Spec 被改过——这正是该门禁存在的理由，此前却作为"receipt 失效"
+  解锁编辑，且改动本身又解锁 Edit 面（spec_guard 退化为一次性减速带）。已授权
+  修改不受影响（`pactkit gate authorize spec_edit` / env / 关闸）。
+- **secrets_gate 与 auth_gate 的审计和提示不再回显命令文本**。清洗只覆盖已知的
+  凭据形态，同一条命令里任何未命中的凭据会随之进入审计记录。现在只记录命中的
+  形态名。
+- **tamper_guard 保护面扩大**：`.pactkit/**` 整个状态目录（含 preflight
+  receipt）、`.claude/settings.local.json`（宿主把 settings 的 env 注入 hook
+  进程且会话内热加载——一次 Write 即可植入 `PACTKIT_ALLOW_*` 关掉全部门禁）、
+  全部四份 `pactkit.yaml` 候选（`.opencode/` 与 `.github/` 优先级更高却曾被
+  排除在保护外）、更多写动词（`touch`/`ln`/`install`/`rsync`）。需要 agent
+  编辑这些文件的团队用 `PACTKIT_ALLOW_CONFIG_EDIT=1` 人工通道或关闭该门禁。
+- **core↔adapter 钉版同步升至 2.27.0**：`pactkit[opencode]`/`pactkit[codex]`
+  要求 adapter ≥2.27.0。core 与三个 adapter 需一起升级（发布顺序：core 先发，
+  adapter 紧随）。
+
+### Added
+
+- **项目契约生命周期**（PR #13）：`pactkit adopt`（最小本地契约，仅在四份配置
+  候选全部缺席时创建）、`pactkit reconcile`（确定性安全迁移：行级插入
+  `schema_version` 保留注释与未知键、写前回读验证、`utils.atomic_write` 落盘）、
+  `pactkit project-preflight`（UNADOPTED / RECONCILE / CURRENT / BLOCKED 四态，
+  过新或非法 schema 给出可行动的阻断信息）。项目采用保持纯本地——无项目注册表、
+  无全局扫描、无跨项目变更。CLI 子命令 52 → 55。
+- **支持矩阵** `docs/guides/support-matrix.md`：宿主 × 门禁 × Python × OS。
+  宿主表从 `gate_matrix.gate_coverage()` 派生并有守卫测试钉住——OpenCode /
+  Copilot 只有 git-hook 层，四个 pre-tool 门禁（auth/secrets/tamper/spec）
+  在该层不存在；macOS 未被 CI 覆盖、Windows 分支零覆盖，均如实写明。
+
+### Fixed — 六轮对抗评审（34 条）
+
+评审覆盖了全部六个门禁的输入解析；每条均带对照组端到端复现后修复。
+
+- **push_gate**：带引号 refspec（`git push origin 'main'`）与强推标记
+  （`+main`）曾放行受保护分支并写入"not protected"假保证；`$VAR`/反斜杠
+  refspec 现判为不可解析（WARN + DEGRADED，不再产出确定性放行）；git
+  pre-push hook 改用 git 交给 hook 的 stdin refspec（此前硬编码当前分支，
+  feature 分支上 `push origin HEAD:main` 曾真实放行）；`git -C` 现决定被检查
+  的仓库（"检查 A、提交 B"）。
+- **commit_gate**：`git -c core.hooksPath=/dev/null commit` 曾交棒给不会运行的
+  hook 使 RED 代码零验证落地（含大小写变体 `core.hookspath` 与
+  `GIT_CONFIG_COUNT/KEY_n/VALUE_n` 环境注入）；分派改为锚定命令位置
+  （`printf ... '{"note":"git commit"}' > .codex/hooks.json` 曾因字符串共现
+  跳过 tamper 并交棒）；命令替换（`git commit -m "$(rm ...)"`）补检；审计写
+  失败不再把 BLOCK 翻成崩溃（exit 1 对宿主是非阻塞）；畸形 stdin 从静默放行
+  改为留 WARN。
+- **tamper_guard**：复合命令分段回归（`cd .git/hooks && rm -f pre-commit` 曾
+  放行，`cd` 相对路径写受保护文件同样已覆盖）；`pactkit.yaml` 弱化即拦截
+  （关 gate 标志 / 开 allow_direct_push / 删 protected_branches，普通编辑与
+  已是 false 的值不误拦不自锁）；settings env 旁路通道（见 Migration）；
+  `rm -rf .pactkit && touch .pactkit` 曾把状态目录替换成普通文件使所有
+  凭据命令崩溃放行；符号链接 spec 与 `DOCS/SPECS` 大小写拼写（Edit + Bash
+  两个面）；Edit 模拟尊重 `replace_all`；Bash 面只读操作（备份/统计 spec）
+  不再误拦。
+- **secrets_gate**：补齐自身动机案例与常见形态——`curl -u/--user`、
+  `Authorization: Bearer/Basic`、`sk-proj-`/`sk-ant-`、AWS secret key、URL
+  userinfo、sshpass/docker login/redis-cli/openssl 内联口令；私钥清洗从只吞
+  BEGIN 行改为整段（此前密钥正文原样进入 `.pactkit/events/`——防泄露门禁
+  自己在制造持久化泄露）；含空格口令整段清洗；误拦收敛（`rg -n 'pwd='`
+  不再命中）。
+- **auth_gate**：`gh -R owner/repo pr create` 等子命令前置全局旗标此前不
+  命中；审计不再回显命令（同 secrets_gate）。
+- **基础设施**：`config._atomic_write_text` 并发写崩溃（与 utils 侧已修的
+  同源副本，统一到单一 `temp_sibling` 实现）；`enforcement._status_path`
+  gate 名路径逃逸守卫；YAML 解析的 TypeError/RecursionError 不再逃出 hook
+  且不再锁死修复；`pactkit clean` 对符号链接不再崩溃且不跟随。
+
+### Docs
+
+- README 计数改为从注册表**派生**并由守卫测试钉住（防漂移测试此前从错误的
+  注册表派生、认证了过时数字；commands/skills/rules 11/10/8 → 12/25/21）；
+  Copilot 列为第四宿主；新增 Troubleshooting 与受限/CI 环境段；
+  SECURITY.md 支持版本表必须覆盖当前发布版本（守卫钉住）；
+  CONTRIBUTING/CODE_OF_CONDUCT 的 404 仓库链接修正（贡献 clone 指向源码仓
+  pactkit-src，安全通告与 issue 指向 pactkit-public）。
+
+## [2.26.1] - 2026-09-15
+
+### Fixed
+- **deploy 不再因扫描根下的不可读目录崩溃**——`Path.exists()` 只吞 ENOENT/ENOTDIR/ELOOP，EACCES 会直接抛出；GitHub Ubuntu runner 的 `/tmp` 含 root 属主 0750 的 `systemd-private-*` 目录，中性 cwd 下 `deploy → cleaners.detect_stacks` 的子目录 marker 检查抛 `PermissionError`（pactkit-opencode 2.26.0 Release Acceptance 8 项失败、publish 被拒）。`cleaners.detect_stacks` 与 `utils.stack_test_plans/_issues` 的全部 marker 检查改为 OSError 安全版（一律视为无 marker）。
+
+
 ## [2.26.0] - 2026-09-15
 
 > 产品重定位版本：PactKit 收敛为**轻量开发赋能脚手架**——无管理员、无集中控制、

{pactkit-2.26.0 → pactkit-2.27.0}/CODE_OF_CONDUCT.md

@@ -60,8 +60,8 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement via
-[GitHub Security Advisories](https://github.com/pactkit/pactkit/security/advisories/new)
-or by opening a [GitHub Issue](https://github.com/pactkit/pactkit/issues).
+[GitHub Security Advisories](https://github.com/pactkit/pactkit-public/security/advisories/new)
+or by opening a [GitHub Issue](https://github.com/pactkit/pactkit-public/issues).
 
 All complaints will be reviewed and investigated promptly and fairly.
 

{pactkit-2.26.0 → pactkit-2.27.0}/CONTRIBUTING.md

@@ -4,8 +4,9 @@ Thank you for your interest in contributing to PactKit!
 
 ## Getting Started
 
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/pactkit.git`
+1. Fork [`pactkit/pactkit-src`](https://github.com/pactkit/pactkit-src) — the
+   source repository (`pactkit-public` is a curated mirror with no code)
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/pactkit-src.git`
 3. Create a branch: `git checkout -b feature/your-feature`
 4. Install in development mode: `pip install -e ".[lint,visualize,test]"` plus
    `pip install -e <path-to-adapter-repo>` for any adapter you're touching
@@ -42,4 +43,4 @@ refactor(scope): code refactoring
 
 ## Code of Conduct
 
-This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior through [GitHub Security Advisories](https://github.com/pactkit/pactkit/security/advisories/new) or by opening a [GitHub Issue](https://github.com/pactkit/pactkit/issues).
+This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior through [GitHub Security Advisories](https://github.com/pactkit/pactkit-public/security/advisories/new) or by opening a [GitHub Issue](https://github.com/pactkit/pactkit-public/issues).

{pactkit-2.26.0 → pactkit-2.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 2.26.0
+Version: 2.27.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,19 +23,19 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: all
-Requires-Dist: pactkit-codex<2.27.0,>=2.26.0; extra == 'all'
-Requires-Dist: pactkit-opencode>=2.9.0; extra == 'all'
+Requires-Dist: pactkit-codex<2.28.0,>=2.27.0; extra == 'all'
+Requires-Dist: pactkit-opencode<2.28.0,>=2.27.0; extra == 'all'
 Requires-Dist: ruff>=0.4; extra == 'all'
 Requires-Dist: tree-sitter-go>=0.25; extra == 'all'
 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.27.0,>=2.26.0; extra == 'codex'
+Requires-Dist: pactkit-codex<2.28.0,>=2.27.0; extra == 'codex'
 Provides-Extra: lint
 Requires-Dist: ruff>=0.4; extra == 'lint'
 Provides-Extra: opencode
-Requires-Dist: pactkit-opencode>=2.9.0; extra == 'opencode'
+Requires-Dist: pactkit-opencode<2.28.0,>=2.27.0; extra == 'opencode'
 Provides-Extra: test
 Requires-Dist: pytest>=7; extra == 'test'
 Requires-Dist: tomli>=1.1.0; (python_version < '3.11') and extra == 'test'
@@ -61,7 +61,7 @@ Description-Content-Type: text/markdown
 
 > **PactKit** (Pact 契约 + Kit) is a lightweight dev-enablement scaffold: it gives AI coding assistants the standards, specs and methods of a disciplined engineering workflow, without getting in the way. Ordinary questions and ordinary coding never activate the workflow — you opt in per task. There is no admin plane, no central control, and nothing that cannot be uninstalled.
 >
-> Deterministic operations run as code, not prompts (CODE is the Law). Decisions are grounded in data, not memory (Data is the Truth). 52 CLI subcommands, 9 specialized agents, 12 commands, 13 skills, and a Plan-Act-Check-Done lifecycle you invoke when you want it. One `pip install` deploys to all 3 supported IDEs (adapters are opt-in extras).
+> Deterministic operations run as code, not prompts (CODE is the Law). Decisions are grounded in data, not memory (Data is the Truth). 55 CLI subcommands, 9 specialized agents, 12 commands, 25 skills, and a Plan-Act-Check-Done lifecycle you invoke when you want it. One `pip install` deploys to all 4 supported IDEs (adapters are opt-in extras).
 
 ### Supported AI Tools
 
@@ -70,8 +70,14 @@ Description-Content-Type: text/markdown
 | **Claude Code** | Classic | `pactkit init` |
 | **OpenCode** | OpenCode | `pactkit init` |
 | **Codex CLI** | Codex | `pactkit init` |
+| **GitHub Copilot** | Copilot | `pactkit init --format copilot` |
 
-> `pactkit init` deploys all 3 IDEs at once. Use `--format <name>` to target a single IDE.
+> `pactkit init` deploys all 4 IDE formats at once. Use `--format <name>` to target a single IDE.
+
+Gate coverage differs by host: Claude Code and Codex CLI get the full gate set
+through native hooks; OpenCode and Copilot fall back to the git-hook layer,
+which covers the commit and push gates but not the pre-tool ones
+(`auth_gate`, `secrets_gate`, `tamper_guard`, `spec_guard`).
 
 ### What it looks like
 
@@ -286,30 +292,40 @@ PactKit deploys 9 specialized agents, each with constrained tools and focused re
 
 ## Skills
 
-PactKit deploys 13 skills (4 scripted + 9 prompt-only), auto-invoked by commands:
+PactKit deploys 25 skills. That total is the 12 PDCA commands (registered as
+skills, so `/project-plan` and `pactkit-visualize` deploy the same way) plus the
+13 tool skills below, auto-invoked by commands:
+
+13 tool skills (4 scripted + 9 prompt-only):
 
 | Skill | Type | Purpose |
 |-------|------|---------|
 | **pactkit-visualize** | Scripted | Code dependency graph (Mermaid .mmd): file-level, class-level, call-level |
 | **pactkit-board** | Scripted | Sprint board operations: add story, update task, archive |
 | **pactkit-scaffold** | Scripted | File scaffolding: create spec, test files, git branches, skills |
+| **pactkit-report** | Scripted | Interactive HTML dashboard from Mermaid architecture graphs |
 | **pactkit-trace** | Prompt-only | Deep code tracing and execution flow analysis |
 | **pactkit-draw** | Prompt-only | Generate Draw.io XML architecture diagrams |
 | **pactkit-analyze** | Prompt-only | Cross-artifact consistency check: Spec <-> Board <-> Test Cases |
+| **pactkit-audit** | Prompt-only | H1-H7 AI readiness assessment and hotspot analysis |
 | **pactkit-status** | Prompt-only | Cold-start project overview (sprint + git + health) |
 | **pactkit-doctor** | Prompt-only | Configuration drift detection and health report |
+| **pactkit-garden** | Prompt-only | Codebase quality patrol: dead code, stale docs, duplication |
 | **pactkit-review** | Prompt-only | PR code review with SOLID/Security/Quality checklists |
 | **pactkit-release** | Prompt-only | Version bump, architecture snapshot, git tag |
 
 ## CLI Subcommands
 
-PactKit ships 52 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 55 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 |
 |---------|---------|
 | `pactkit init` | Deploy toolkit to AI coding assistant |
 | `pactkit update` | Update playbooks (preserves config) |
 | `pactkit upgrade` | Upgrade with format selection |
+| `pactkit adopt` | Create a minimal versioned contract for the current project |
+| `pactkit reconcile` | Preview or apply safe project-schema migrations |
+| `pactkit project-preflight` | Check adoption and compatibility before governed work |
 | `pactkit version` | Show installed version |
 | `pactkit schema` | Print document schemas |
 | `pactkit doctor` | Diagnose project health (HLD drift, board, config, deployment content parity, adapter skew) |
@@ -341,6 +357,42 @@ PactKit ships 52 deterministic CLI subcommands — operations that were previous
 | `pactkit schema config` | List every pactkit.yaml key with default, effective value, and source |
 | `pactkit sync` | Sync codegraph index |
 
+### Commit Path Convergence (2.26.0)
+
+- **Single test executor**: worktree and `core.hooksPath` layouts resolve the
+  real git hooks path — the host PreToolUse pass defers to the shared git
+  pre-commit hook instead of double-running the suite.
+- **Real incremental selection**: a changed test file maps to itself
+  (`test_X.py` runs `test_X.py`); an empty mapping runs the fast layer with an
+  explicit full-suite recommendation instead of silently escalating; polyglot
+  repos run every detected workspace's native test command.
+- **Observability**: the gate prints its plan (strategy, reason, command,
+  scope) before any test runs, streams pytest output, and records per-phase
+  timings into the enforcement record.
+- **Staged-first scope**: the gate checks what this commit will introduce
+  (`git diff --cached`); unstaged work is reported as excluded.
+
+### Verification Facts & Governance (2.26.0)
+
+- Verification records are keyed by **content fingerprint** (cross-story
+  reuse); with no fresh, unambiguous preflight receipt the post-commit stamp
+  lands **unattributed** instead of guessing a story.
+- PreCompact writes a lightweight marker — one context generation per
+  compaction cycle.
+- The spec guard binds a receipt only while its spec hash matches and the
+  receipt is fresh (expired/drifted receipts unlock with a reason).
+- `telemetry.enabled: false` skips event-stream writes without touching gate
+  semantics.
+
+### Engineering Guidance by Gap (2.26.0)
+
+- The reuse classification (availability / applicability / decisions /
+  evidence) lives once in the shared lifecycle capsule loaded by all four
+  phases; Act loads guidance by gap — an empty `pactkit risk` result is never
+  "no risk", 0 guides is valid when there is no gap, and confirmed risks
+  past the first three are still read and verified.
+- `pactkit risk --json` returns the full per-concern decisions for review.
+
 ### 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:
@@ -358,15 +410,15 @@ All blocks/bypasses are audited (`.pactkit/enforcement/`) and feed `pactkit stat
 
 ## Deployment Architecture
 
-PactKit supports three deployment formats:
+PactKit supports four deployment formats:
 
 ### Claude Code (Classic)
 
 ```
 ~/.claude/
 ├── CLAUDE.md                 <- Project context entry point
-├── rules/                    <- 8 rule modules (loaded per-command, not globally)
-├── skills/                   <- 21 skill packages (11 commands + 10 embedded)
+├── rules/                    <- 21 rule modules (loaded per-command, not globally)
+├── skills/                   <- 25 skill packages (12 commands + 13 tool skills)
 └── agents/                   <- 9 agent definitions
 ```
 
@@ -377,10 +429,10 @@ Commands are deployed as skills (`skills/project-*/SKILL.md`), invoked with `/pr
 ```
 ~/.config/opencode/
 ├── AGENTS.md                 <- On-demand @reference index (lazy rule loading)
-├── rules/                    <- 8 rule modules (3 core always-load + 6 on-demand)
-├── commands/                 <- 11 command playbooks (auto-discovered, invoked via /)
+├── rules/                    <- 21 rule modules
+├── commands/                 <- 12 command playbooks (auto-discovered, invoked via /)
 ├── agents/                   <- 9 agent definitions (mode: subagent)
-├── skills/                   <- 10 skill packages (AI agent loads on demand)
+├── skills/                   <- 13 tool skills (AI agent loads on demand)
 └── opencode.json             <- Global config (model routing, instructions)
 ```
 
@@ -392,8 +444,8 @@ OpenCode uses dual mechanism: `commands/` for user-facing PDCA entry points, `sk
 ~/.codex/
 ├── AGENTS.md                 <- Global constitution
 ├── config.toml               <- Model, sandbox, MCP config
-├── rules/                    <- 8 rule modules
-├── skills/                   <- 21 skill packages (11 commands + 10 embedded)
+├── rules/                    <- 21 rule modules
+├── skills/                   <- 25 skill packages (12 commands + 13 tool skills)
 └── .pactkit-version          <- Version marker for updates
 ```
 
@@ -438,9 +490,11 @@ Session context is generated locally at `.pactkit/context.md` and is ignored by
 | `stack` | string | auto-detected | Project stack (`python`, `node`, `go`, `java`) |
 | `developer` | string | `""` | Developer prefix for Story IDs (multi-developer collaboration) |
 | `agents` | list | all 9 | Agent definitions to deploy |
-| `commands` | list | all 11 | Command playbooks to deploy |
-| `skills` | list | all 10 | Skills to deploy |
-| `rules` | list | all 8 | Constitution rule modules to deploy |
+| `commands` | list | all 12 | Command playbooks to deploy |
+| `skills` | list | all 25 | Skills to deploy (12 commands + 13 tool skills) |
+| `rules` | list | all 21 | Constitution rule modules to deploy |
+| `enforcement` | object | see below | Gate configuration — `protected_branches` (`["main","master"]`), `allow_direct_push` (`false`), `tamper_guard` (`true`), `spec_guard` (`true`), `auth_gate` (`true`), `secrets_gate` (`true`), `auth_ttl_minutes` (`30`) |
+| `telemetry` | object | `enabled: true` | Local-only usage telemetry (`.pactkit/events/`). Set `enabled: false` to stop recording; gate verdicts are unaffected |
 | `exclude` | object | `{}` | Components to exclude (e.g., `exclude.agents: [agent-name]`) |
 | `visualize.graph_provider` | string | (absent) | Graph query backend. Set `codegraph` to use `.codegraph/codegraph.db` for `pactkit query`. Absent = grep `.mmd` |
 | `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`). Sub-fields: `runner` (default: `ubuntu-latest`), `language_version` (default: auto per stack), `github_host` (GHE server address), `actions_ref` (GHE actions prefix) |
@@ -472,16 +526,19 @@ When conflicts arise: Spec wins. Always. The agent modifies code, never the spec
 
 ## MCP Integration
 
-PactKit conditionally integrates with MCP servers when available:
+As of **2.26.0**, PactKit is a lightweight development-enablement scaffold with
+**zero MCP server injection** — `pactkit init` no longer registers any server,
+and the self-hosted governance MCP server is retired (`pactkit mcp` prints the
+retirement note and migration path). Host-side MCP servers you configure
+yourself (Context7, Playwright, Chrome DevTools, Memory, …) still work: the
+playbooks reference them conditionally and skip gracefully when unavailable.
 
 | MCP Server | Purpose | PDCA Phase |
 |------------|---------|------------|
 | Context7 | Library documentation lookup | Act |
-| shadcn | UI component search/install | Design |
 | Playwright | Browser automation testing | Check |
 | Chrome DevTools | Performance/console/network | Check |
 | Memory | Cross-session knowledge graph | Plan/Act/Done |
-| Draw.io | Architecture diagram instant preview | Plan, Design |
 
 All MCP instructions are conditional — gracefully skipped when unavailable.
 
@@ -494,6 +551,40 @@ pactkit update    # Updates all deployed IDEs
 
 Use `pactkit update --format <name>` to update a single IDE.
 
+Rolling back is `pip install pactkit==<previous-version>` followed by
+`pactkit update`. `pactkit doctor` reports a deployment whose files no longer
+match the installed CLI, which is how a partial rollback shows up.
+
+## Restricted and CI Environments
+
+`pactkit init` and `pactkit update` accept flags for environments that cannot
+reach the network or answer prompts:
+
+| Flag | Effect |
+|------|--------|
+| `--no-git` | Skips every git operation (hook installation, `.gitignore` edits) — for air-gapped or git-less setups |
+| `--no-external` | Skips external network calls (MCP registration, `gh` CLI, `pip`) |
+| `--non-interactive` | Auto-accepts defaults — for CI/CD |
+
+PactKit never sends your code or usage data anywhere. Telemetry is written
+locally under `.pactkit/events/` and can be turned off with
+`telemetry.enabled: false`. The only network access is the package index you
+install from.
+
+## Troubleshooting
+
+Start with `pactkit doctor` — it reports configuration drift, deployment
+parity against the installed CLI, adapter version skew, hook registration, and
+rule health. `pactkit doctor --json` emits the same data for scripts.
+
+| Symptom | Likely cause | What to do |
+|---------|--------------|------------|
+| A commit is blocked with `commit-gate` | Tests are RED, or you are committing directly to a protected branch | Fix the tests, or push a feature branch and open a PR. `enforcement.allow_direct_push: true` is for single-maintainer repos that work directly on `main` |
+| A command is blocked with `push-gate` / `auth-gate` | Direct push to a protected branch, or an external-effect command (`gh pr create`, `npm publish`, …) without authorization | Run `pactkit gate authorize <scope>` after the user agrees, or have the user run it themselves |
+| Gates behave inconsistently across teammates | Deployments are stale — each clone updates independently | `pactkit update` in that project, then `pactkit doctor` |
+| `pactkit doctor` reports adapter skew | `pactkit-codex`/`-opencode` version does not match core | Upgrade the adapter extras; core and adapters are version-pinned to each other |
+| The gate blocks work and you believe it is wrong | Genuine gate bug | `PACTKIT_ALLOW_*` env vars (see the gate table above) are the human channel; report the false positive with `pactkit stats` output |
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

{pactkit-2.26.0 → pactkit-2.27.0}/README.md

@@ -13,7 +13,7 @@
 
 > **PactKit** (Pact 契约 + Kit) is a lightweight dev-enablement scaffold: it gives AI coding assistants the standards, specs and methods of a disciplined engineering workflow, without getting in the way. Ordinary questions and ordinary coding never activate the workflow — you opt in per task. There is no admin plane, no central control, and nothing that cannot be uninstalled.
 >
-> Deterministic operations run as code, not prompts (CODE is the Law). Decisions are grounded in data, not memory (Data is the Truth). 52 CLI subcommands, 9 specialized agents, 12 commands, 13 skills, and a Plan-Act-Check-Done lifecycle you invoke when you want it. One `pip install` deploys to all 3 supported IDEs (adapters are opt-in extras).
+> Deterministic operations run as code, not prompts (CODE is the Law). Decisions are grounded in data, not memory (Data is the Truth). 55 CLI subcommands, 9 specialized agents, 12 commands, 25 skills, and a Plan-Act-Check-Done lifecycle you invoke when you want it. One `pip install` deploys to all 4 supported IDEs (adapters are opt-in extras).
 
 ### Supported AI Tools
 
@@ -22,8 +22,14 @@
 | **Claude Code** | Classic | `pactkit init` |
 | **OpenCode** | OpenCode | `pactkit init` |
 | **Codex CLI** | Codex | `pactkit init` |
+| **GitHub Copilot** | Copilot | `pactkit init --format copilot` |
 
-> `pactkit init` deploys all 3 IDEs at once. Use `--format <name>` to target a single IDE.
+> `pactkit init` deploys all 4 IDE formats at once. Use `--format <name>` to target a single IDE.
+
+Gate coverage differs by host: Claude Code and Codex CLI get the full gate set
+through native hooks; OpenCode and Copilot fall back to the git-hook layer,
+which covers the commit and push gates but not the pre-tool ones
+(`auth_gate`, `secrets_gate`, `tamper_guard`, `spec_guard`).
 
 ### What it looks like
 
@@ -238,30 +244,40 @@ PactKit deploys 9 specialized agents, each with constrained tools and focused re
 
 ## Skills
 
-PactKit deploys 13 skills (4 scripted + 9 prompt-only), auto-invoked by commands:
+PactKit deploys 25 skills. That total is the 12 PDCA commands (registered as
+skills, so `/project-plan` and `pactkit-visualize` deploy the same way) plus the
+13 tool skills below, auto-invoked by commands:
+
+13 tool skills (4 scripted + 9 prompt-only):
 
 | Skill | Type | Purpose |
 |-------|------|---------|
 | **pactkit-visualize** | Scripted | Code dependency graph (Mermaid .mmd): file-level, class-level, call-level |
 | **pactkit-board** | Scripted | Sprint board operations: add story, update task, archive |
 | **pactkit-scaffold** | Scripted | File scaffolding: create spec, test files, git branches, skills |
+| **pactkit-report** | Scripted | Interactive HTML dashboard from Mermaid architecture graphs |
 | **pactkit-trace** | Prompt-only | Deep code tracing and execution flow analysis |
 | **pactkit-draw** | Prompt-only | Generate Draw.io XML architecture diagrams |
 | **pactkit-analyze** | Prompt-only | Cross-artifact consistency check: Spec <-> Board <-> Test Cases |
+| **pactkit-audit** | Prompt-only | H1-H7 AI readiness assessment and hotspot analysis |
 | **pactkit-status** | Prompt-only | Cold-start project overview (sprint + git + health) |
 | **pactkit-doctor** | Prompt-only | Configuration drift detection and health report |
+| **pactkit-garden** | Prompt-only | Codebase quality patrol: dead code, stale docs, duplication |
 | **pactkit-review** | Prompt-only | PR code review with SOLID/Security/Quality checklists |
 | **pactkit-release** | Prompt-only | Version bump, architecture snapshot, git tag |
 
 ## CLI Subcommands
 
-PactKit ships 52 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 55 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 |
 |---------|---------|
 | `pactkit init` | Deploy toolkit to AI coding assistant |
 | `pactkit update` | Update playbooks (preserves config) |
 | `pactkit upgrade` | Upgrade with format selection |
+| `pactkit adopt` | Create a minimal versioned contract for the current project |
+| `pactkit reconcile` | Preview or apply safe project-schema migrations |
+| `pactkit project-preflight` | Check adoption and compatibility before governed work |
 | `pactkit version` | Show installed version |
 | `pactkit schema` | Print document schemas |
 | `pactkit doctor` | Diagnose project health (HLD drift, board, config, deployment content parity, adapter skew) |
@@ -293,6 +309,42 @@ PactKit ships 52 deterministic CLI subcommands — operations that were previous
 | `pactkit schema config` | List every pactkit.yaml key with default, effective value, and source |
 | `pactkit sync` | Sync codegraph index |
 
+### Commit Path Convergence (2.26.0)
+
+- **Single test executor**: worktree and `core.hooksPath` layouts resolve the
+  real git hooks path — the host PreToolUse pass defers to the shared git
+  pre-commit hook instead of double-running the suite.
+- **Real incremental selection**: a changed test file maps to itself
+  (`test_X.py` runs `test_X.py`); an empty mapping runs the fast layer with an
+  explicit full-suite recommendation instead of silently escalating; polyglot
+  repos run every detected workspace's native test command.
+- **Observability**: the gate prints its plan (strategy, reason, command,
+  scope) before any test runs, streams pytest output, and records per-phase
+  timings into the enforcement record.
+- **Staged-first scope**: the gate checks what this commit will introduce
+  (`git diff --cached`); unstaged work is reported as excluded.
+
+### Verification Facts & Governance (2.26.0)
+
+- Verification records are keyed by **content fingerprint** (cross-story
+  reuse); with no fresh, unambiguous preflight receipt the post-commit stamp
+  lands **unattributed** instead of guessing a story.
+- PreCompact writes a lightweight marker — one context generation per
+  compaction cycle.
+- The spec guard binds a receipt only while its spec hash matches and the
+  receipt is fresh (expired/drifted receipts unlock with a reason).
+- `telemetry.enabled: false` skips event-stream writes without touching gate
+  semantics.
+
+### Engineering Guidance by Gap (2.26.0)
+
+- The reuse classification (availability / applicability / decisions /
+  evidence) lives once in the shared lifecycle capsule loaded by all four
+  phases; Act loads guidance by gap — an empty `pactkit risk` result is never
+  "no risk", 0 guides is valid when there is no gap, and confirmed risks
+  past the first three are still read and verified.
+- `pactkit risk --json` returns the full per-concern decisions for review.
+
 ### 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:
@@ -310,15 +362,15 @@ All blocks/bypasses are audited (`.pactkit/enforcement/`) and feed `pactkit stat
 
 ## Deployment Architecture
 
-PactKit supports three deployment formats:
+PactKit supports four deployment formats:
 
 ### Claude Code (Classic)
 
 ```
 ~/.claude/
 ├── CLAUDE.md                 <- Project context entry point
-├── rules/                    <- 8 rule modules (loaded per-command, not globally)
-├── skills/                   <- 21 skill packages (11 commands + 10 embedded)
+├── rules/                    <- 21 rule modules (loaded per-command, not globally)
+├── skills/                   <- 25 skill packages (12 commands + 13 tool skills)
 └── agents/                   <- 9 agent definitions
 ```
 
@@ -329,10 +381,10 @@ Commands are deployed as skills (`skills/project-*/SKILL.md`), invoked with `/pr
 ```
 ~/.config/opencode/
 ├── AGENTS.md                 <- On-demand @reference index (lazy rule loading)
-├── rules/                    <- 8 rule modules (3 core always-load + 6 on-demand)
-├── commands/                 <- 11 command playbooks (auto-discovered, invoked via /)
+├── rules/                    <- 21 rule modules
+├── commands/                 <- 12 command playbooks (auto-discovered, invoked via /)
 ├── agents/                   <- 9 agent definitions (mode: subagent)
-├── skills/                   <- 10 skill packages (AI agent loads on demand)
+├── skills/                   <- 13 tool skills (AI agent loads on demand)
 └── opencode.json             <- Global config (model routing, instructions)
 ```
 
@@ -344,8 +396,8 @@ OpenCode uses dual mechanism: `commands/` for user-facing PDCA entry points, `sk
 ~/.codex/
 ├── AGENTS.md                 <- Global constitution
 ├── config.toml               <- Model, sandbox, MCP config
-├── rules/                    <- 8 rule modules
-├── skills/                   <- 21 skill packages (11 commands + 10 embedded)
+├── rules/                    <- 21 rule modules
+├── skills/                   <- 25 skill packages (12 commands + 13 tool skills)
 └── .pactkit-version          <- Version marker for updates
 ```
 
@@ -390,9 +442,11 @@ Session context is generated locally at `.pactkit/context.md` and is ignored by
 | `stack` | string | auto-detected | Project stack (`python`, `node`, `go`, `java`) |
 | `developer` | string | `""` | Developer prefix for Story IDs (multi-developer collaboration) |
 | `agents` | list | all 9 | Agent definitions to deploy |
-| `commands` | list | all 11 | Command playbooks to deploy |
-| `skills` | list | all 10 | Skills to deploy |
-| `rules` | list | all 8 | Constitution rule modules to deploy |
+| `commands` | list | all 12 | Command playbooks to deploy |
+| `skills` | list | all 25 | Skills to deploy (12 commands + 13 tool skills) |
+| `rules` | list | all 21 | Constitution rule modules to deploy |
+| `enforcement` | object | see below | Gate configuration — `protected_branches` (`["main","master"]`), `allow_direct_push` (`false`), `tamper_guard` (`true`), `spec_guard` (`true`), `auth_gate` (`true`), `secrets_gate` (`true`), `auth_ttl_minutes` (`30`) |
+| `telemetry` | object | `enabled: true` | Local-only usage telemetry (`.pactkit/events/`). Set `enabled: false` to stop recording; gate verdicts are unaffected |
 | `exclude` | object | `{}` | Components to exclude (e.g., `exclude.agents: [agent-name]`) |
 | `visualize.graph_provider` | string | (absent) | Graph query backend. Set `codegraph` to use `.codegraph/codegraph.db` for `pactkit query`. Absent = grep `.mmd` |
 | `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`). Sub-fields: `runner` (default: `ubuntu-latest`), `language_version` (default: auto per stack), `github_host` (GHE server address), `actions_ref` (GHE actions prefix) |
@@ -424,16 +478,19 @@ When conflicts arise: Spec wins. Always. The agent modifies code, never the spec
 
 ## MCP Integration
 
-PactKit conditionally integrates with MCP servers when available:
+As of **2.26.0**, PactKit is a lightweight development-enablement scaffold with
+**zero MCP server injection** — `pactkit init` no longer registers any server,
+and the self-hosted governance MCP server is retired (`pactkit mcp` prints the
+retirement note and migration path). Host-side MCP servers you configure
+yourself (Context7, Playwright, Chrome DevTools, Memory, …) still work: the
+playbooks reference them conditionally and skip gracefully when unavailable.
 
 | MCP Server | Purpose | PDCA Phase |
 |------------|---------|------------|
 | Context7 | Library documentation lookup | Act |
-| shadcn | UI component search/install | Design |
 | Playwright | Browser automation testing | Check |
 | Chrome DevTools | Performance/console/network | Check |
 | Memory | Cross-session knowledge graph | Plan/Act/Done |
-| Draw.io | Architecture diagram instant preview | Plan, Design |
 
 All MCP instructions are conditional — gracefully skipped when unavailable.
 
@@ -446,6 +503,40 @@ pactkit update    # Updates all deployed IDEs
 
 Use `pactkit update --format <name>` to update a single IDE.
 
+Rolling back is `pip install pactkit==<previous-version>` followed by
+`pactkit update`. `pactkit doctor` reports a deployment whose files no longer
+match the installed CLI, which is how a partial rollback shows up.
+
+## Restricted and CI Environments
+
+`pactkit init` and `pactkit update` accept flags for environments that cannot
+reach the network or answer prompts:
+
+| Flag | Effect |
+|------|--------|
+| `--no-git` | Skips every git operation (hook installation, `.gitignore` edits) — for air-gapped or git-less setups |
+| `--no-external` | Skips external network calls (MCP registration, `gh` CLI, `pip`) |
+| `--non-interactive` | Auto-accepts defaults — for CI/CD |
+
+PactKit never sends your code or usage data anywhere. Telemetry is written
+locally under `.pactkit/events/` and can be turned off with
+`telemetry.enabled: false`. The only network access is the package index you
+install from.
+
+## Troubleshooting
+
+Start with `pactkit doctor` — it reports configuration drift, deployment
+parity against the installed CLI, adapter version skew, hook registration, and
+rule health. `pactkit doctor --json` emits the same data for scripts.
+
+| Symptom | Likely cause | What to do |
+|---------|--------------|------------|
+| A commit is blocked with `commit-gate` | Tests are RED, or you are committing directly to a protected branch | Fix the tests, or push a feature branch and open a PR. `enforcement.allow_direct_push: true` is for single-maintainer repos that work directly on `main` |
+| A command is blocked with `push-gate` / `auth-gate` | Direct push to a protected branch, or an external-effect command (`gh pr create`, `npm publish`, …) without authorization | Run `pactkit gate authorize <scope>` after the user agrees, or have the user run it themselves |
+| Gates behave inconsistently across teammates | Deployments are stale — each clone updates independently | `pactkit update` in that project, then `pactkit doctor` |
+| `pactkit doctor` reports adapter skew | `pactkit-codex`/`-opencode` version does not match core | Upgrade the adapter extras; core and adapters are version-pinned to each other |
+| The gate blocks work and you believe it is wrong | Genuine gate bug | `PACTKIT_ALLOW_*` env vars (see the gate table above) are the human channel; report the false positive with `pactkit stats` output |
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

{pactkit-2.26.0 → pactkit-2.27.0}/SECURITY.md

@@ -4,14 +4,17 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 2.25.x  | :white_check_mark: |
-| 2.24.x  | :white_check_mark: |
-| < 2.24  | :x:                |
+| 2.27.x  | :white_check_mark: |
+| 2.26.x  | :white_check_mark: |
+| < 2.26  | :x:                |
 
 We provide security fixes for the current and previous minor release. Users on
 older versions should upgrade — the version is reported by `pactkit version`,
 and `pactkit doctor` flags a deployment that lags the installed CLI.
 
+> This table is refreshed on every minor release; a guard test fails whenever
+> the version in `pyproject.toml` is missing from it.
+
 ## Reporting a Vulnerability
 
 **Please do NOT report security vulnerabilities through public GitHub issues.**