pactkit 2.0.2__tar.gz → 2.1.0__tar.gz

{pactkit-2.0.2 → pactkit-2.1.0}/.gitignore

@@ -43,3 +43,4 @@ docs/architecture/snapshots/
 *.bak
 .mcp.json
 coder/
+docker/

pactkit-2.1.0/.opencode/pactkit.yaml

@@ -0,0 +1,110 @@
+# PactKit Configuration
+# Edit this file to customize which components are deployed.
+# Remove items from a list to disable them. Default: all enabled.
+
+version: "2.1.0"
+stack: python
+root: .
+developer: "slim"
+
+# Agents — AI role definitions
+agents:
+  - code-explorer
+  - product-designer
+  - qa-engineer
+  - repo-maintainer
+  - security-auditor
+  - senior-developer
+  - system-architect
+  - system-medic
+  - visual-architect
+
+# Commands — PDCA playbooks
+commands:
+  - project-act
+  - project-check
+  - project-design
+  - project-done
+  - project-hotfix
+  - project-init
+  - project-plan
+  - project-sprint
+  - project-clarify
+  - project-pr
+  - project-release
+
+# Skills — tool scripts
+skills:
+  - pactkit-board
+  - pactkit-doctor
+  - pactkit-draw
+  - pactkit-release
+  - pactkit-review
+  - pactkit-scaffold
+  - pactkit-status
+  - pactkit-trace
+  - pactkit-visualize
+  - pactkit-analyze
+
+# Rules — constitution modules
+rules:
+  - 01-core-protocol
+  - 02-hierarchy-of-truth
+  - 03-file-atlas
+  - 04-routing-table
+  - 05-workflow-conventions
+  - 06-mcp-integration
+  - 07-shared-protocols
+  - 08-architecture-principles
+
+# CI/CD — set provider to github or gitlab to generate pipeline config
+ci:
+  provider: github
+
+# Issue Tracker — set provider to github to link stories to issues
+issue_tracker:
+  provider: github
+
+# Hooks — safe, report-only hook templates (command-type only)
+hooks:
+  post_test_coverage: false
+  pre_commit_lint: false
+  pre_push_check: false
+
+# Lint — configure lint behavior in /project-done
+lint_blocking: false
+auto_fix: false
+
+# Virtual Environment — configure venv detection and paths
+venv:
+  auto_detect: true
+
+# Release — configure release automation behavior
+release:
+  github_release: true
+
+# Regression — configure impact-based test selection strategy
+regression:
+  strategy: impact
+  max_impact_tests: 50
+
+# Check — configure QA verification behavior
+check:
+  security_checklist: true
+  security_scope_override: none
+
+# Done — configure commit and lesson quality behavior
+done:
+  lesson_quality_threshold: 15
+
+# Agent Models — override default model per agent (inherit = use account default)
+agent_models:
+  code-explorer: haiku
+  product-designer: opus
+  qa-engineer: sonnet
+  repo-maintainer: sonnet
+  security-auditor: sonnet
+  senior-developer: sonnet
+  system-architect: opus
+  system-medic: haiku
+  visual-architect: sonnet

{pactkit-2.0.2 → pactkit-2.1.0}/AGENTS.md

@@ -56,3 +56,4 @@ src/pactkit/
 - Global rules: `~/.config/opencode/AGENTS.md` (loaded automatically by OpenCode)
 
 @./docs/product/context.md
+output MUST use Chinese

{pactkit-2.0.2 → pactkit-2.1.0}/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.1.0] - 2026-03-17
+
+### Added
+- **FormatProfile Abstraction** (STORY-slim-005) — Frozen dataclass registry (`profiles.py`) replaces scattered if-else format branching. Adding a new tool format requires only one registry entry. `VALID_FORMATS` and `PACTKIT_YAML_CANDIDATES` auto-generated from `FORMAT_PROFILES`.
+- **Prompt Template Variables** (STORY-slim-006) — 48 hardcoded env-specific paths replaced with 11 named placeholders (`{SKILLS_ROOT}`, `{BOARD_CMD}`, `{PACTKIT_YAML}`, etc.) resolved at deploy time by `_render_prompt(template, profile)`.
+- **Document Schema Registry** (STORY-slim-007) — New `schemas.py` centralizes all document structure rules (Spec sections, Board headers, context.md sections, lessons.md format). New CLI command `pactkit schema [type]` for rule discovery.
+- **Deploy Chain Parity** (STORY-slim-008) — `_deploy_opencode()` now reads `pactkit.yaml` for selective deployment, calls `auto_merge_config_file()`, `_cleanup_legacy()`, generates project-level `AGENTS.md`, prints MCP recommendations. `_generate_config_if_missing(format=)` is format-aware.
+- **Architecture Principles Rule** — New `08-architecture-principles.md` codifies 8 principles (SOLID, DRY, 12-Factor, Defense-in-Depth) derived from project practice. `CLAUDE_MD_TEMPLATE` auto-generated from `RULES_FILES`.
+- **Codex CLI Pre-Research** (STORY-slim-001) — Tool integration checklist (11 dimensions, 60+ checks) and Codex capability matrix completed. Integration specs (STORY-slim-002/003/004) ready.
+- **Daily Retro Skill** — Personal growth feedback loop with 6 dimensions (engineering, architecture, new skills, thinking patterns, process, career). Triggered by cross-day context.md detection.
+- **Docker Containers** — Isolated `claude-code` and `opencode` containers for clean deployment verification.
+
+### Fixed
+- **BUG-slim-001**: `/project-init` no longer creates `.claude/` directory in OpenCode environment. Environment detection moved before `pactkit init` call. Playbook paths now use `$SKILLS_PATH` variable.
+- **Config Priority**: `.opencode/` now takes precedence over `.claude/` in `pactkit.yaml` resolution (newer environment preferred).
+- **Scaffold Developer Prefix**: `create_spec`, `git_start`, `create_e2e` auto-inject developer prefix from `pactkit.yaml`.
+
+### Changed
+- `opencode_format` boolean parameter removed from `_deploy_agents()`, `_deploy_commands()`, `_deploy_skills()` — replaced by `profile: FormatProfile`.
+- `OPENCODE_SKILLS_PREFIX` constant removed — use `get_profile("opencode").skills_path_var`.
+- `CLAUDE_ONLY_FIELDS` hardcoded set replaced by `profile.excluded_agent_fields` (extensible per format).
+- `TRACE_PROMPT` converted from f-string to regular string for template variable compatibility.
+- Spec scaffold template now uses `TBD` as Release placeholder (enforced by spec-lint E008 at Act time).
+
+## [2.0.2] - 2026-03-16
+
 ## [1.6.9] - 2026-03-13
 
 ### Fixed

{pactkit-2.0.2 → pactkit-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.0.2
+Version: 2.1.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

{pactkit-2.0.2 → pactkit-2.1.0}/docs/architecture/governance/lessons.md

@@ -92,3 +92,9 @@
 | 2026-03-17 | When the target tool lacks `@import` syntax (OpenCode vs Claude Code), use its native config mechanism (`opencode.json` `instructions: ["rules/*.md"]`) for modular rule loading instead of inlining everything into a single file; `_update_global_opencode_json()` with merge strategy preserves user-owned fields (`provider`) while adding tool-managed fields (`instructions`) — same principle as `CLAUDE.local.md` but achieved through JSON merge instead of file separation | STORY-071 |
 | 2026-03-17 | Tool-internal config files (pactkit.yaml) must not be hardcoded to a single tool's directory — `load_config()` multi-path lookup (`.claude/` → `.opencode/`) with `find_pactkit_yaml()` helper + env-aware `resolve_pactkit_yaml_dir()` for generation keeps the CLI tool-agnostic; skill scripts (board.py) that run standalone cannot import library modules, so must inline the path lookup logic rather than calling `from pactkit.config import find_pactkit_yaml` | STORY-072 |
 | 2026-03-17 | OpenCode command-level model routing requires `model:` in frontmatter (not just `agent.{name}.model` in opencode.json) — `_resolve_opencode_model_id()` maps shortnames (sonnet/opus/haiku) to full `provider/model-id` by scanning `opencode.json` providers; `command_models` in pactkit.yaml enables user override; also: any config YAML comments referencing `~/.claude/` must be tool-agnostic since OpenCode users see those comments in `.opencode/pactkit.yaml` | STORY-073 |
+| 2026-03-17 | Tool integration checklists need a Dimension 0 capability matrix before any code — `docs/guides/tool-integration-checklist.md` shows that OpenCode (architecture-compatible with Claude Code) needed 6 stories while Codex (no agents, no rules, single provider) would require a completely different strategy; filling the matrix first prevents writing code that assumes the wrong architecture | STORY-slim-001 |
+| 2026-03-17 | When format-specific logic is scattered across 10+ locations (deployer, config, prompts), use a frozen dataclass registry (`FormatProfile` in `profiles.py`) so adding a new tool format requires only one registry entry — functions read `profile.skills_path_var`, `profile.excluded_agent_fields`, etc. instead of checking `if format == "opencode"`; review caught unreachable duplicate code from copy-paste during migration (lines 59-61 in `_rewrite_skills_prefix`) | STORY-slim-005 |
+| 2026-03-17 | Prompt templates with hardcoded env paths should use named placeholders (`{BOARD_CMD}`, `{SKILLS_ROOT}` etc.) resolved at deploy time by `_render_prompt(template, profile)`; use sequential `str.replace()` over `str.format_map()` because user-facing templates contain complex keys like `{R1, R2, ...}` and `{version}_*.mmd` that cause `ValueError: Empty attribute` in Python's format parser; f-string prompt constants must be converted to plain strings first | STORY-slim-006 |
+| 2026-03-17 | Document structure rules should live in a single `schemas.py` registry — `spec_linter.py` and `scaffold.py` both had diverged copies of required fields/patterns; when standalone skill scripts (board.py, scaffold.py) cannot import the library, inline copies with a `# STORY-slim-007: canonical values in src/pactkit/schemas.py` comment; standalone script fallbacks in spec_linter.py's except ImportError block must be kept bit-for-bit identical to schemas.py values | STORY-slim-007 |
+| 2026-03-17 | When two deploy functions share logic (classic/opencode), add missing functions one-by-one rather than creating a shared `_deploy_standard()` up-front — `_deploy_opencode()` was missing `auto_merge_config_file`, `_cleanup_legacy`, `_generate_project_agents_md`, and `_print_mcp_recommendations_opencode`; adding them separately is safer than a premature abstraction that could break the plugin/marketplace modes which use different parameter patterns (`_legacy_prefix`) | STORY-slim-008 |
+| 2026-03-17 | Architecture principles derived from project practice should be codified as a named rule module (08-architecture-principles.md) and deployed to all tool environments via `RULES_FILES`; the `CLAUDE_MD_TEMPLATE` auto-generate pattern (building `@import` list from `sorted(RULES_FILES.values())`) prevents new rules from being silently omitted from Classic mode while OpenCode picks them up via `instructions: ["rules/*.md"]` glob — a DRY fix exposed by adding the new module | chore/rules |

pactkit-2.1.0/docs/architecture/governance/rules.md

@@ -0,0 +1,22 @@
+# Governance Rules
+
+## Architecture Decisions
+
+| ID | Decision | Rationale | Date |
+|----|----------|-----------|------|
+| ADR-001 | Python 3.10+ with hatchling build | Broad compatibility, modern packaging | 2025-01 |
+| ADR-002 | Prompt templates as Python string constants | Zero external deps for core, easy to test | 2025-01 |
+| ADR-003 | pactkit.yaml for selective deployment config | User controls which agents/commands/rules deploy | 2025-02 |
+| ADR-004 | FormatProfile dataclass registry (`profiles.py`) | OCP: new tool = one registry entry; eliminates if-else branching | 2026-03 |
+| ADR-005 | schemas.py as document structure source of truth | DRY: one place for Spec/Board/Context/Lessons/TestCase rules | 2026-03 |
+| ADR-006 | Sequential str.replace in `_render_prompt()` | Safe with user-facing complex keys; format_map fails on `{R1, R2}` | 2026-03 |
+| ADR-007 | Deploy chain parity over premature abstraction | Add functions one-by-one rather than shared `_deploy_standard()` | 2026-03 |
+
+## Invariants
+
+1. All 2307+ 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`.
+5. New tool format requires only a `FormatProfile` entry — no other file changes needed.
+6. Document structure rules exist only in `schemas.py` — consumers inline with source-of-truth comment.

pactkit-2.1.0/docs/guides/codex-integration-preresearch.md

@@ -0,0 +1,185 @@
+# Codex CLI Integration Pre-Research
+
+> **Purpose**: Pre-research template for adapting PactKit to Codex CLI.
+> Fill in each "待填写" item before starting implementation.
+> Reference: `docs/guides/tool-integration-checklist.md` Dimension 1.
+>
+> **Codex CLI repo**: https://github.com/openai/codex
+> **Last updated**: 2026-03-17 (initial template)
+
+---
+
+## 0. Known Facts (from initial GitHub scan)
+
+| Fact | Source |
+|------|--------|
+| Has `.codex/skills/` directory | Repo root observed |
+| Uses `AGENTS.md` as project instruction file | Repo root observed |
+| Written in Rust | 96.2% Rust per GitHub |
+| Global config in `~/.codex/` | Logs written to `~/.codex/log/` |
+| Supports `codex exec` (non-interactive) | install.md |
+| OpenAI models only (ChatGPT Plus/Pro or API key) | README |
+
+---
+
+## 1. Target Tool Research
+
+### 1.1 Official Documentation URLs
+
+| Concept | URL | Status |
+|---------|-----|--------|
+| Agents (multi-role) | 待填写 | ❓ |
+| Commands (custom `/cmd`) | 待填写 | ❓ |
+| Skills format | 待填写 | ❓ |
+| Rules / AGENTS.md | 待填写 | ❓ |
+| Config format | 待填写 | ❓ |
+| Permissions / Sandbox | 待填写 | ❓ |
+| MCP support | 待填写 | ❓ |
+| Model selection | 待填写 | ❓ |
+
+### 1.2 Config Format Differences vs Claude Code
+
+| Feature | Claude Code | Codex CLI | Notes |
+|---------|-------------|-----------|-------|
+| Agent definition format | `.claude/agents/*.md` with YAML frontmatter | 待填写 | Does Codex have agents? |
+| Command format | `.claude/commands/*.md` with `allowed-tools:` | 待填写 | Unknown — Codex may not have custom commands |
+| Rules loading | `@import` in `CLAUDE.md` | 待填写 | `AGENTS.md` inline? |
+| Skill format | `SKILL.md` with `name`+`description` | 待填写 | `.codex/skills/` structure? |
+| Permission model | `settings.json` deny list | Sandbox mode (待填写 details) | What sandbox levels? |
+| Model config | N/A (Anthropic only) | 待填写 | How to select GPT-4o vs o3? |
+
+### 1.3 File System Conventions
+
+| Path | Purpose | Status |
+|------|---------|--------|
+| `~/.codex/` | Global config dir | Confirmed (log dir exists) |
+| `~/.codex/config.toml`? | Global config file | 待填写 — confirm filename and format |
+| `.codex/` | Project config dir | Confirmed (skills dir exists) |
+| `.codex/skills/` | Project skills | Confirmed |
+| `./AGENTS.md` | Project instruction file | Confirmed (repo has it) |
+| `.codex/pactkit.yaml`? | PactKit config location | 待填写 — confirm `.codex/` is right choice |
+
+### 1.4 Rules Loading Mechanism
+
+| Question | Answer |
+|----------|--------|
+| Does Codex support `@import` or similar? | 待填写 |
+| How does Codex load `AGENTS.md`? | 待填写 |
+| Can multiple rule files be referenced? | 待填写 |
+| Is there an `instructions` field or equivalent? | 待填写 |
+| What is the context window limit? | 待填写 |
+
+### 1.5 Model Routing
+
+| Question | Answer |
+|----------|--------|
+| Can different agents use different models? | 待填写 |
+| Can different commands use different models? | 待填写 |
+| How is model specified (config file, CLI flag)? | 待填写 |
+| What models are available? | 待填写 (GPT-4o, o3, o4-mini?) |
+| Is there a `small_model` equivalent? | 待填写 |
+
+### 1.6 Permission / Sandbox Model
+
+| Question | Answer |
+|----------|--------|
+| What sandbox levels exist? | 待填写 |
+| How is file write permission controlled? | 待填写 |
+| How is shell command permission controlled? | 待填写 |
+| Is there a deny list format? | 待填写 |
+| How does it compare to Claude Code `settings.json`? | 待填写 |
+
+### 1.7 MCP Support
+
+| Question | Answer |
+|----------|--------|
+| Does Codex support MCP? | 待填写 |
+| MCP server format (if supported)? | 待填写 |
+| Any pre-built MCP integrations? | 待填写 |
+
+### 1.8 Image / Vision Support
+
+| Question | Answer |
+|----------|--------|
+| Does Codex support image input? | 待填写 |
+| How to paste/reference images? | 待填写 |
+| Vision capability declaration needed? | 待填写 |
+
+### 1.9 `settings.json` Equivalents
+
+| Claude Code `settings.json` Feature | Codex Equivalent | Notes |
+|-------------------------------------|------------------|-------|
+| `permissions.deny` | 待填写 | |
+| `mcpServers` | 待填写 | |
+| `defaultMode: bypassPermissions` | 待填写 | |
+| `env` variables | 待填写 | |
+| `hooks` | 待填写 | |
+
+### 1.10 Dual-Layer Architecture
+
+| Question | Answer |
+|----------|--------|
+| Does Codex distinguish global (`~/.codex/`) from project (`.codex/`)? | 待填写 |
+| What goes in global vs project? | 待填写 |
+| Does `pactkit init --format codex` write to global? | 待填写 |
+| Does `/project-init` write to project? | 待填写 |
+
+---
+
+## 2. Capability Matrix (fill in after research)
+
+Based on 1.1–1.10 answers, fill in the `Codex` column in the checklist:
+
+```
+docs/guides/tool-integration-checklist.md → Dimension 0.1
+```
+
+Then determine strategy from Dimension 0.2.
+
+---
+
+## 3. Preliminary Integration Strategy (hypothesis)
+
+Based on known facts (update after full research):
+
+| Capability | Hypothesis | Confidence |
+|------------|-----------|------------|
+| Agents | None → embed roles in AGENTS.md | Medium |
+| Commands | Exists but different format → convert | Low |
+| Skills | `.codex/skills/` → adapt discovery | Medium |
+| Rules | No `@import` → inline into AGENTS.md | Medium |
+| Model routing | None → prompt-level Model Guard Protocol | Medium |
+| Provider | OpenAI only → no resolver needed | High |
+| Permission | Sandbox mode → different from deny list | Low |
+| pactkit.yaml location | `.codex/pactkit.yaml` | Medium |
+
+---
+
+## 4. Open Questions (to resolve before coding)
+
+1. Does Codex have a concept of custom agents (multi-role)? Or is it always single-agent?
+2. What is the exact format for custom commands in Codex?
+3. What does `.codex/skills/` expect — same `SKILL.md` frontmatter as OpenCode?
+4. Is there a global config file (`~/.codex/config.toml`?) and what fields does it support?
+5. How does Codex handle `AGENTS.md` — is it a system prompt? Loaded on startup?
+6. Is the sandbox mode configurable or fixed?
+7. Does Codex have an equivalent to `opencode.json` `instructions` field?
+8. What version of Codex should we target? (CLI is Rust-based, separate from Codex Web)
+9. **Version compatibility**: Should PactKit check `codex --version` at deploy time and warn if below minimum? What is the minimum version that supports skills/AGENTS.md?
+
+---
+
+## 5. Estimated Effort (fill in after research)
+
+| Dimension | Estimated Stories | Notes |
+|-----------|------------------|-------|
+| 2: Deploy architecture | 待填写 | |
+| 3: Agent format | 待填写 | Likely: N/A if no agent concept |
+| 4: Command format | 待填写 | |
+| 5: Rules loading | 待填写 | Likely: inline into AGENTS.md |
+| 6: Skills format | 待填写 | |
+| 7: pactkit.yaml | 待填写 | Add `.codex/` to candidates |
+| 8: Playbook text | 待填写 | |
+| 9: CLI | 待填写 | Add `codex` to format choices |
+| 10: Verification | 待填写 | |
+| **Total** | | |