pactkit 3.0.2__tar.gz → 3.0.4__tar.gz

pactkit-3.0.4/.github/workflows/pactkit.yml

@@ -0,0 +1,34 @@
+# pactkit:generated source=pactkit.yaml renderer=github-workflow
+name: PactKit CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: slimmini
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[visualize]"
+          pip install pytest ruff
+          pactkit init
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest tests/ -v

pactkit-3.0.4/.github/workflows/publish.yml

@@ -0,0 +1,133 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    # 2026-09-24: not `ubuntu-latest`. The org `actions` budget is $0 with
+    # prevent_further_usage, so a job asking for a hosted runner gets none
+    # (runner_id=0, fails in seconds) — which would leave this release gate
+    # permanently un-runnable. The org-level self-hosted runner carries the
+    # `slimmini` label. Only private repos are affected by the budget.
+    runs-on: slimmini
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      # fetch-depth: 0 — same reason as PactKit CI: the AC6/AC7 Spec-scope
+      # guards need the commit that names their Spec, and a default checkout
+      # does not have it. Without this the release is blocked by four guards
+      # that cannot attribute changes plus two that silently measure the
+      # working tree.
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[visualize,lint,test]"
+          pip install ruff
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest tests/ -q
+
+  publish:
+    needs: test
+    # See the `test` job above. OIDC trusted publishing is supported on
+    # self-hosted runners — the token is still minted by GitHub for this job —
+    # and the 45-minute acceptance-wait loop below is free here rather than
+    # billed by the minute.
+    runs-on: slimmini
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+      # 2026-09-11 review round 2, F4: the acceptance-wait step reads workflow
+      # runs via `gh run list`; without an explicit `actions: read` the job
+      # token is denied and the wait degrades into a 45-minute timeout.
+      actions: read
+    steps:
+      - uses: actions/checkout@v7
+
+      # STORY-slim-20260911b2bbd79889e0 C2/R8 (2026-09-11 review, finding 5):
+      # a tag may only publish after the Release Acceptance workflow has
+      # accepted the SAME commit — real wheels installed into a clean
+      # environment, adapter suites green with zero skips, journey verified.
+      # Fail-closed: no acceptance conclusion within the timeout, no publish.
+      # API/permission failures fail FAST with the stderr shown — only a
+      # legitimately still-running acceptance keeps waiting.
+      - name: Wait for Release Acceptance (this tag, this commit)
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          SHA="${{ github.sha }}"
+          # The SAME commit now has more than one acceptance run: the daily
+          # single-version one (push to main) and the release four-version one
+          # (this tag).  `--commit` alone is ambiguous, and `.[0]` was "whichever
+          # the API listed first" — a green daily run could satisfy the gate
+          # without the release matrix ever finishing.  Match the run that
+          # actually belongs to this release: this tag's push event.
+          TAG="${{ github.ref_name }}"
+          deadline=$(( $(date +%s) + 2700 ))
+          while :; do
+            if ! gh run list --workflow=release-acceptance.yml --commit "$SHA" \
+                 --json status,conclusion,event,headBranch,headSha \
+                 > "$RUNNER_TEMP/acceptance-runs.json" 2>"$RUNNER_TEMP/gh-err"; then
+              echo "::error::gh run list failed — permissions or API error, "
+              echo "NOT an acceptance-still-running state (review round 2, F4):"
+              cat "$RUNNER_TEMP/gh-err"
+              exit 1
+            fi
+            jq -r '.[] | "  candidate: event=\(.event) ref=\(.headBranch) status=\(.status) conclusion=\(.conclusion)"' \
+              "$RUNNER_TEMP/acceptance-runs.json"
+            row=$(jq -r --arg tag "$TAG" --arg sha "$SHA" \
+              '[.[] | select(.event == "push" and .headBranch == $tag and .headSha == $sha)] | .[0] // empty' \
+              "$RUNNER_TEMP/acceptance-runs.json")
+            if [ -z "$row" ]; then
+              echo "no release acceptance for tag $TAG yet — waiting"
+            fi
+            if [ -n "$row" ]; then
+              status=$(printf '%s' "$row" | jq -r '.status')
+              conclusion=$(printf '%s' "$row" | jq -r '.conclusion')
+              echo "release-acceptance: status=$status conclusion=$conclusion"
+              if [ "$status" = "completed" ]; then
+                if [ "$conclusion" = "success" ]; then
+                  echo "Release Acceptance passed for $SHA"
+                  exit 0
+                fi
+                echo "::error::Release Acceptance concluded: $conclusion — refusing to publish"
+                exit 1
+              fi
+            fi
+            if [ "$(date +%s)" -ge "$deadline" ]; then
+              echo "::error::timed out waiting for Release Acceptance on $SHA"
+              exit 1
+            fi
+            sleep 30
+          done
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pactkit-3.0.4/.github/workflows/release-acceptance.yml

@@ -0,0 +1,261 @@
+name: Release Acceptance
+
+# STORY-slim-20260911b2bbd79889e0 C2/R8 + 2026-09-11 reviews: install the
+# ACTUAL core wheel that is about to ship in a clean environment and prove
+# the package-level surface. The ordinary CI tests the editable checkout;
+# it cannot see packaging-level breaks (missing files in the wheel,
+# dependency misdeclaration). This job can. publish.yml waits for this
+# workflow's conclusion before publishing a tag.
+#
+# Zero-credential split (2026-09-11, first real runner run 34607922520):
+# GITHUB_TOKEN cannot read the private adapter repos, and the owner chose
+# no PAT/secrets. The core wheel + adapter COMBO acceptance therefore runs
+# in each adapter repo's own release-acceptance workflow — it checks out
+# ITSELF (its token suffices) and installs the RELEASED core from PyPI,
+# which the resolver pins for real. Each adapter repo covers classic + its
+# own host; the union covers all three. What remains here is the core-only
+# quality gate: wheel build/install/version, documented extras, wheel-mode
+# prompt snapshots (classic; the host assertion scales with installed
+# adapters), and the classic journey.
+
+on:
+  push:
+    branches: [main]
+    # Same inert-doc set as PactKit CI — spec/acceptance docs are not in the
+    # wheel, so the packaging assertions cannot see them.  Tags always run
+    # (publish gate) regardless of paths.
+    paths-ignore:
+      - "docs/specs/**"
+      - "docs/acceptance/**"
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "daily (3.11 single version) or release (3.10-3.13 full matrix)"
+        type: choice
+        options: [daily, release]
+        default: daily
+
+# STORY-slim-20260917c943d7aaeb7c (CI cost): same rationale as PactKit CI —
+# cancel superseded branch runs.  Tag runs are excluded from the group name
+# so a push to main can never cancel an in-flight tag acceptance that
+# publish.yml is waiting on.
+concurrency:
+  group: release-acceptance-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # R4 (STORY-slim-20260917c18f4a962b70): the acceptance matrix is layered
+  # by event — daily (PR / push main / manual daily) proves the 3.11
+  # baseline cheaply; release (tag v* / manual release) proves the full
+  # supported range.  The assertions are IDENTICAL in both configs — only
+  # the version dimension shrinks (降低版本维度不删验收断言).  PRs and main
+  # both run: a PR green light never skips the final main integration run;
+  # an opened PR's branch pushes fire `synchronize` and rerun this workflow.
+  config:
+    # 2026-09-24: the org `actions` budget is $0 with prevent_further_usage, so
+    # a job that asks for `ubuntu-latest` gets no runner at all (runner_id=0,
+    # seconds to fail) — see the runner migration in the sibling workflow. The
+    # org-level runner carries the `slimmini` label. The budget blocks hosted
+    # jobs for private repos only; public repos are unaffected.
+    runs-on: slimmini
+    outputs:
+      versions: ${{ steps.pick.outputs.versions }}
+      config_name: ${{ steps.pick.outputs.config_name }}
+    steps:
+      - name: Pick the acceptance matrix for this event
+        id: pick
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/v* ]] \
+             || [[ "${{ inputs.mode }}" == "release" ]]; then
+            echo 'versions=["3.10","3.11","3.12","3.13"]' >> "$GITHUB_OUTPUT"
+            echo "config_name=release (full 3.10-3.13 matrix)" >> "$GITHUB_OUTPUT"
+          else
+            echo 'versions=["3.11"]' >> "$GITHUB_OUTPUT"
+            echo "config_name=daily (3.11 single version)" >> "$GITHUB_OUTPUT"
+          fi
+
+  core-wheel:
+    needs: config
+    # See the `config` job above for why this is not `ubuntu-latest`.
+    runs-on: slimmini
+    strategy:
+      fail-fast: false
+      # R8: the accepted Python range must match what the package claims
+      # (pyproject requires-python >=3.10) — proven IN FULL on release
+      # events; daily events prove the 3.11 baseline only.
+      matrix:
+        python-version: ${{ fromJSON(needs.config.outputs.versions) }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build the core wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel --outdir dist/ .
+          python -m build --sdist --outdir dist/ .
+
+      # STORY-slim-20260917beaa87bc5d27: the dev repo is private and the
+      # public mirror is curated docs only — for a procurement review the
+      # PyPI artifacts ARE the source of record for license and code.  A
+      # packaging regression that drops LICENSE from the wheel/sdist would
+      # otherwise surface as a customer-side legal question, not a red build.
+      - name: Built artifacts carry LICENSE and sources (procurement)
+        run: |
+          python -m pip install --upgrade pip build > /dev/null 2>&1 || true
+          WHEEL=$(ls dist/pactkit-*.whl)
+          SDIST=$(ls dist/pactkit-*.tar.gz)
+          python - "$WHEEL" "$SDIST" <<'PY'
+          import sys, tarfile, zipfile
+          wheel, sdist = sys.argv[1], sys.argv[2]
+          names = zipfile.ZipFile(wheel).namelist()
+          assert any(n.endswith("LICENSE") for n in names), "wheel is missing LICENSE"
+          py = [n for n in names if n.endswith(".py")]
+          assert len(py) >= 90, f"wheel source count suspicious: {len(py)} files"
+          tarnames = tarfile.open(sdist).getnames()
+          assert any(n.endswith("LICENSE") for n in tarnames), "sdist is missing LICENSE"
+          assert any(n.endswith("src/pactkit/__init__.py") for n in tarnames), "sdist is missing sources"
+          print(f"LICENSE + sources verified: wheel {len(py)} .py, sdist ok")
+          PY
+
+      - name: The runner provides a per-job temp directory
+        run: |
+          # Every path below lives under $RUNNER_TEMP, not /tmp. On a hosted
+          # runner /tmp is a fresh VM per run, so a leftover venv was
+          # impossible; on a persistent self-hosted runner it survives, and
+          # the AC11 assertion below would then be checking a venv built by an
+          # earlier run — a clean-environment guarantee that quietly stopped
+          # holding. Assert the runner supplies the directory rather than
+          # discovering it as a stray `/accept`.
+          test -n "$RUNNER_TEMP" \
+            || { echo "::error::RUNNER_TEMP is unset — this job needs a runner that provides one"; exit 1; }
+
+      - name: Install from the wheel into a clean environment (AC11)
+        run: |
+          python -m venv "$RUNNER_TEMP/accept"
+          # Direct wheel path: the package under acceptance comes from the
+          # local dist/ (never PyPI, never editable); third-party deps
+          # (pyyaml) resolve from the index.
+          "$RUNNER_TEMP/accept/bin/pip" install dist/pactkit-*.whl
+          ! "$RUNNER_TEMP/accept/bin/pip" list | grep -q '\-e '
+          "$RUNNER_TEMP/accept/bin/pactkit" version
+
+      - name: Base wheel + documented extras resolve (AC11)
+        run: |
+          python -m venv "$RUNNER_TEMP/extras"
+          # The extras README documents must actually resolve from the built
+          # wheel. Adapter extras are deliberately excluded here: they pin
+          # the released core from the index, which during release prep is
+          # older than this build (core-first publish order).
+          WHEEL=$(ls dist/pactkit-*.whl)
+          "$RUNNER_TEMP/extras/bin/pip" install "$WHEEL[lint,visualize]"
+          "$RUNNER_TEMP/extras/bin/pactkit" version
+
+      - name: Prompt-body snapshots from the wheel (AC10/R7)
+        env:
+          PACTKIT_SNAPSHOT_FROM_WHEEL: "1"
+        run: |
+          # Wheel mode: the deploy subprocesses must import the WHEEL — no
+          # checkout PYTHONPATH, provenance asserted (site-packages origin),
+          # and every installed host participates in the comparison (this
+          # core-only environment compares classic; each adapter repo's
+          # acceptance adds its own host). A skip fails the step. The empty
+          # `-c` ini keeps the checkout's pyproject (pythonpath=src) from
+          # shadowing the installed wheel.
+          "$RUNNER_TEMP/accept/bin/pip" install pytest
+          printf '[pytest]\n' > "$RUNNER_TEMP/acceptance-pytest.ini"
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/accept/bin/pytest" \
+            "$GITHUB_WORKSPACE/tests/unit/test_c1_body_snapshots.py" \
+            -c "$RUNNER_TEMP/acceptance-pytest.ini" -p no:cacheprovider \
+            --junitxml="$RUNNER_TEMP/snap-results.xml" -q \
+            || { echo "::error::prompt-body snapshot comparison failed"; exit 1; }
+          # The heredoc is quoted, so the path is passed as an argument rather
+          # than interpolated.
+          "$RUNNER_TEMP/accept/bin/python" - "$RUNNER_TEMP/snap-results.xml" <<'EOF'
+          import sys
+          import xml.etree.ElementTree as ET
+
+          root = ET.parse(sys.argv[1]).getroot()
+          skipped = sum(int(s.get("skipped", 0)) for s in root.iter("testsuite"))
+          errors = sum(int(s.get("errors", 0)) for s in root.iter("testsuite"))
+          if skipped or errors:
+              print(f"::error::snapshot step: {skipped} skipped, {errors} errors — "
+                    "skip is failure under release acceptance")
+              sys.exit(1)
+          print("snapshots: 0 skipped, 0 errors")
+          EOF
+
+      - name: Classic journey from the wheel (AC12, CLI layer)
+        run: |
+          # The CLI is invoked by ABSOLUTE PATH from the acceptance venv
+          # (review round 2, F3): a bare `pactkit` would resolve against
+          # whatever the runner has preinstalled — or nothing at all.
+          # OpenCode/Codex journeys run in their own adapter repos'
+          # acceptance workflows (zero-credential split).
+          PACTKIT="$RUNNER_TEMP/accept/bin/pactkit"
+          command -v "$PACTKIT" >/dev/null 2>&1 \
+            || { echo "::error::acceptance venv has no pactkit entry point"; exit 1; }
+          export HOME="$RUNNER_TEMP/journey-home"
+          export XDG_CONFIG_HOME="$RUNNER_TEMP/journey-home/.config"
+          rm -rf "$HOME" "$RUNNER_TEMP/journey-proj"
+          mkdir -p "$HOME" "$RUNNER_TEMP/journey-proj"
+          cd "$RUNNER_TEMP/journey-proj"
+          git init -q .
+          git config user.email journey@example.invalid
+          git config user.name journey
+
+          fail() { echo "::error::journey: $1"; exit 1; }
+          root="$HOME/.claude"
+          "$PACTKIT" version
+          "$PACTKIT" init --format classic > init.log 2>&1 \
+            || { cat init.log; fail "classic init failed"; }
+          [ -f "$root/.pactkit-deployed.json" ] || fail "no deployment manifest"
+          entry="$root/skills/project-plan/SKILL.md"
+          [ -f "$entry" ] || fail "method entry point missing ($entry)"
+
+          mkdir -p "$root/rules"
+          printf '# My team conventions\n- ours, not PactKit\x27s\n' > "$root/rules/my-team.md"
+          "$PACTKIT" update --format classic > update.log 2>&1 \
+            || { cat update.log; fail "classic update failed"; }
+          [ -f "$root/rules/my-team.md" ] || fail "user rule file lost by update"
+
+          "$PACTKIT" uninstall --target "$root" > uninstall.log 2>&1 \
+            || { cat uninstall.log; fail "classic uninstall failed"; }
+          [ -f "$root/rules/my-team.md" ] || fail "user file deleted by uninstall"
+          [ ! -f "$root/skills/pactkit-board/scripts/board.py" ] \
+            || fail "manifest-owned file survived uninstall"
+          echo "classic journey OK (CLI layer)"
+          # Real-host runtime sessions are NOT exercised here — recorded as
+          # UNVERIFIED per R8: 自动化 CLI/产物检查与真实宿主运行记录 MUST
+          # 分开标注.
+
+      # R8 (STORY-slim-20260917c18f4a962b70): every CI summary states the
+      # event, SHA, verification config, Python/host coverage and the
+      # actual run/skip reasons — a green core-only acceptance must never
+      # read as "all hosts verified".
+      - name: CI summary (R8)
+        if: always()
+        run: |
+          ALL='${{ needs.config.outputs.versions }}'
+          {
+            echo "## Release Acceptance — ${{ needs.config.outputs.config_name }}"
+            echo ""
+            echo "| field | value |"
+            echo "|---|---|"
+            echo "| event | \`${{ github.event_name }}\` |"
+            echo "| ref | \`${{ github.ref }}\` |"
+            echo "| sha | \`${{ github.sha }}\` |"
+            echo "| config | ${{ needs.config.outputs.config_name }} |"
+            echo "| versions this config | $ALL |"
+            echo "| this runner | ${{ matrix.python-version }} |"
+            echo "| host coverage | core-only: classic prompt snapshots compared; opencode/codex adapters are NOT verified here (their own repos' release-acceptance covers them) |"
+            echo "| skip policy | a skip in the snapshot step fails the step (skip = failure, never a pass) |"
+          } >> "$GITHUB_STEP_SUMMARY"

pactkit-3.0.4/.github/workflows/runner-heartbeat.yml

@@ -0,0 +1,48 @@
+name: Runner heartbeat
+
+# The self-hosted runner is the only place this org's private-repo CI can run:
+# the org `actions` budget is $0 with `prevent_further_usage: true`, so hosted
+# jobs stop outright and there is no fallback to fail over to. A runner outage
+# is therefore a *silent* CI outage — jobs sit in `queued` with no runner to
+# take them, which looks exactly like a slow queue.
+#
+# This is the cheapest possible detector: one echo on the runner label. It is
+# deliberately not a test — it measures whether the runner picks up work, not
+# whether the code is good, and it must stay cheap enough to run often.
+#
+# Reading the result (the part that is easy to get wrong):
+#   * run succeeded, runner_name == slimmini-colima  -> healthy
+#   * run still `queued`, runner_name empty          -> the runner is down
+#   * run failed fast, runner_id == 0                -> the budget is blocking
+#                                                       (a different fault, and
+#                                                       one this job cannot fix)
+# Checking only "did the run go green" cannot tell the first from the third,
+# and checking only the runner's `status` field lags by minutes — GitHub marks a
+# runner offline only after its heartbeat expires.
+
+on:
+  schedule:
+    # Every 20 minutes. Off :00 and :30 on purpose: scheduled workflows across
+    # GitHub pile up on the round marks, and a heartbeat is never urgent enough
+    # to deserve that queue.
+    - cron: "7,27,47 * * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  heartbeat:
+    runs-on: slimmini
+    # A running job that wedges should fail loudly rather than hang. This does
+    # NOT cover the runner-is-offline case: a job with no runner never starts,
+    # so it never reaches this timeout — it just queues, which is precisely the
+    # state the external watchdog looks for.
+    timeout-minutes: 5
+    steps:
+      - name: The runner picked this up
+        run: |
+          echo "runner=${RUNNER_NAME}"
+          echo "os=${RUNNER_OS} arch=${RUNNER_ARCH}"
+          echo "host=$(hostname)"
+          echo "python=$(python3 --version 2>&1)"

pactkit-3.0.4/.gitignore

@@ -0,0 +1,81 @@
+# Python
+*.pyc
+__pycache__/
+.coverage
+*.py[cod]
+*$py.class
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+*.tmp
+*.log
+
+# PactKit - generated artifacts (auto-regenerated; not versioned).
+# Named files, NOT the whole directory: the authored diagrams
+# (system_design.mmd, workflow_graph.mmd, reverse_call_graph.mmd) live in the
+# same directory and MUST stay tracked. A directory-wide rule is what let 7
+# generated files stay tracked for four months — .gitignore does not apply to
+# already-tracked paths (STORY-slim-2026091893aad6f3d8ac R3).
+docs/architecture/graphs/call_graph.mmd
+docs/architecture/graphs/class_graph.mmd
+docs/architecture/graphs/code_graph.mmd
+docs/architecture/graphs/module_graph.mmd
+docs/architecture/graphs/report.html
+docs/architecture/graphs/call_graph.db
+docs/architecture/graphs/focus_file_graph.mmd
+# Whole directory is safe HERE (unlike graphs/ above): every file is a
+# version-stamped machine artifact ({version}_{mode}.mmd) — no authored
+# asset lives here. Untracked 2026-09-18; 53 files were tracked while the
+# rule said otherwise (STORY-slim-2026091893aad6f3d8ac).
+docs/architecture/snapshots/
+
+# PactKit - previously excluded for IP protection (repo is now private, all tracked)
+
+# Claude Code local config
+.claude/
+
+# Codex CLI local config
+.codex/
+
+# GitHub Copilot deployment artifacts (generated by pactkit update)
+.github/
+!.github/workflows/
+
+# Office files
+~$*
+*.pptx
+
+# Secrets
+.pypirc
+
+# Playwright MCP
+.playwright-mcp/
+
+# Backup
+*.bak
+.mcp.json
+.pactkit/
+coder/
+docker/
+docs/slides/
+
+
+# Call graph SQLite output (STORY-slim-121)
+docs/architecture/graphs/*.db