tracemantle 1.6.0__tar.gz

tracemantle-1.6.0/.gitattributes

@@ -0,0 +1,5 @@
+# Keep source and digest-verified fixtures identical on every CI platform.
+* text=auto eol=lf
+# This parser control must retain its literal CRLF bytes.
+tests/fixtures/tracemantle/cases/valid-crlf.md -text whitespace=cr-at-eol
+*.docx binary

tracemantle-1.6.0/.github/banner.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="800" y2="200" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#0f0f23"/>
+      <stop offset="100%" stop-color="#1a1a3e"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#d4a574"/>
+      <stop offset="100%" stop-color="#e8c9a0"/>
+    </linearGradient>
+  </defs>
+  <rect width="800" height="200" rx="12" fill="url(#bg)"/>
+  <!-- check icon -->
+  <g transform="translate(220, 55)">
+    <circle cx="40" cy="40" r="36" stroke="url(#accent)" stroke-width="3" fill="none" opacity="0.9"/>
+    <polyline points="22,42 36,56 60,28" stroke="#4ade80" stroke-width="4.5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+  </g>
+  <!-- title -->
+  <text x="400" y="108" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace" font-size="42" font-weight="700" fill="url(#accent)">
+    <tspan dx="52">TraceMantle</tspan>
+  </text>
+  <!-- subtitle -->
+  <text x="400" y="142" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif" font-size="15" fill="#8b8ba7" letter-spacing="0.5">
+    Static analysis and release evidence for agent skill bundles
+  </text>
+</svg>

tracemantle-1.6.0/.github/workflows/ci.yml

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c constraints-dev.txt -e ".[dev]"
+
+      - name: Run tests
+        # The coverage floor is applied here rather than in pyproject addopts,
+        # which would also fail single-file local runs. See the comment there.
+        run: python -m pytest tests/ -v --tb=short --cov-fail-under=80
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install dev dependencies
+        run: pip install -c constraints-dev.txt -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check src tests scripts
+
+      - run: python scripts/generate_reference.py --check
+
+      - name: Mypy strict
+        # Bare mypy uses the [tool.mypy] files list (src plus the checked-in
+        # scripts), so the utility scripts are type-gated alongside the package.
+        run: mypy
+
+  package:
+    needs: [test, lint, tokenizer]
+    # Smoke-check that the project builds and the wheel installs on every push
+    # and PR. Attestation and PyPI publishing happen only on tag pushes, in
+    # release.yml, so this job stays read-only.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install reproducible build tools
+        run: pip install -c constraints-dev.txt build hatchling
+
+      - name: Build exact release artifacts
+        run: python -m build --no-isolation --outdir candidate-dist
+
+      - name: Verify wheel and source installs
+        run: python scripts/verify_artifacts.py candidate-dist --output artifact-verification.json
+
+      - name: Retain verified artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: tracemantle-dist
+          path: candidate-dist/*
+          if-no-files-found: error
+
+      - name: Retain artifact verification report
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: tracemantle-verification
+          path: artifact-verification.json
+          if-no-files-found: error
+
+  tokenizer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install -c constraints-dev.txt -e ".[dev,tiktoken]"
+      - run: python -m pytest tests/ -q --cov-fail-under=80
+      - run: python scripts/calibrate_advisories.py --output calibration.json
+      - run: pip install -c constraints-dev.txt strictyaml click
+      - run: python scripts/verify_reference_corpus.py --output conformance.json

tracemantle-1.6.0/.github/workflows/compare.yml

@@ -0,0 +1,51 @@
+name: Trusted bundle comparison
+on:
+  workflow_dispatch:
+    inputs:
+      base_revision:
+        description: Full trusted base commit SHA
+        required: true
+      candidate_revision:
+        description: Candidate commit SHA to inspect without executing
+        required: true
+      bundle_path:
+        description: Relative bundle directory in both revisions
+        required: true
+        default: skills/tracemantle
+permissions:
+  contents: read
+jobs:
+  compare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ inputs.base_revision }}
+          path: trusted
+          persist-credentials: false
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ inputs.candidate_revision }}
+          path: candidate
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - name: Install only the trusted tool
+        run: pip install -c trusted/constraints-dev.txt ./trusted
+      - name: Compare against immutable trusted policy
+        env:
+          BASE_REVISION: ${{ inputs.base_revision }}
+          BUNDLE_PATH: ${{ inputs.bundle_path }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          args=()
+          if [ -d candidate/evidence/records ]; then
+            while IFS= read -r -d '' record; do
+              args+=(--evidence "$record")
+            done < <(find candidate/evidence/records -maxdepth 1 -type f -name '*.json' -print0)
+          fi
+          tracemantle compare "trusted/$BUNDLE_PATH" "candidate/$BUNDLE_PATH" \
+            --trusted-root trusted --base-revision "$BASE_REVISION" \
+            --format github "${args[@]}"

tracemantle-1.6.0/.github/workflows/release-notes.yml

@@ -0,0 +1,98 @@
+name: Release notes
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  promote-unreleased:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Promote [Unreleased] to released version heading
+        id: promote
+        shell: bash
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          today=$(date -u +%Y-%m-%d)
+          python3 - "$version" "$today" <<'PY'
+          import re
+          import sys
+          from pathlib import Path
+
+          version, today = sys.argv[1], sys.argv[2]
+          path = Path("CHANGELOG.md")
+          text = path.read_text(encoding="utf-8")
+
+          # Locate the [Unreleased] block: its content runs until the next ## heading.
+          match = re.search(r"^##\s*\[Unreleased\]\s*\n", text, re.MULTILINE)
+          if not match:
+              print("CHANGELOG.md has no [Unreleased] heading; nothing to promote.")
+              sys.exit(0)
+
+          start = match.end()
+          next_heading = re.search(r"^##\s*\[", text[start:], re.MULTILINE)
+          end = start + next_heading.start() if next_heading else len(text)
+          body = text[start:end].strip()
+
+          if not body:
+              print("[Unreleased] is empty; nothing to promote.")
+              # Signal an empty promotion to the next step.
+              Path("PROMOTED.flag").write_text("empty", encoding="utf-8")
+              sys.exit(0)
+
+          # A heading for the released version already exists, so the developer
+          # promoted by hand. Promoting again would duplicate entries, but going
+          # quiet is what stranded nine shipped fixes outside the v1.4.1 notes:
+          # the hand promotion was partial and the remainder stayed here. There
+          # is content and nowhere safe to put it, so fail instead of no-oping.
+          if re.search(rf"^##\s*\[{re.escape(version)}\]", text, re.MULTILINE):
+              print(
+                  f"[{version}] heading already present, but [Unreleased] still has entries. "
+                  f"They shipped in {version} and are not recorded under it. Move them under "
+                  f"[{version}] by hand, or hold them for the next version.",
+                  file=sys.stderr,
+              )
+              print(body, file=sys.stderr)
+              sys.exit(1)
+
+          new_block = (
+              f"## [Unreleased]\n\n"
+              f"## [{version}] - {today}\n\n{body}\n\n"
+          )
+          updated = text[:match.start()] + new_block + text[end:].lstrip()
+          path.write_text(updated, encoding="utf-8")
+          Path("PROMOTED.flag").write_text("promoted", encoding="utf-8")
+          print(f"Promoted [Unreleased] -> [{version}] - {today}")
+          PY
+          if [ -f PROMOTED.flag ]; then
+            echo "result=$(cat PROMOTED.flag)" >> "$GITHUB_OUTPUT"
+            rm PROMOTED.flag
+          else
+            echo "result=skipped" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Open PR with the promoted CHANGELOG
+        if: steps.promote.outputs.result == 'promoted'
+        uses: peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c # v6.1.0
+        with:
+          commit-message: |
+            docs(changelog): promote [Unreleased] to [${{ github.event.release.tag_name }}]
+          title: "docs(changelog): promote [Unreleased] to [${{ github.event.release.tag_name }}]"
+          body: |
+            Automated promotion triggered by the `${{ github.event.release.tag_name }}` GitHub release.
+            Moves the `[Unreleased]` block under a new `[${{ github.event.release.tag_name }}]` heading dated today.
+          branch: changelog/promote-${{ github.event.release.tag_name }}
+          base: main
+          labels: docs, automation

tracemantle-1.6.0/.github/workflows/release.yml

@@ -0,0 +1,130 @@
+name: Release
+
+# Publishes to PyPI and attests build provenance when an immutable version tag
+# is pushed. The v*.*.* filter matches patch tags (v1.2.3) but not the moving
+# major tag (v1), so the moving tag does not trigger a duplicate publish.
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: quality
+    if: vars.TRACEMANTLE_PUBLISH_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    # Trusted publishing resolves against this environment on the PyPI side.
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # PyPI trusted publishing (OIDC) and provenance signing
+      attestations: write # actions/attest-build-provenance
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      # Runs before publishing so a CHANGELOG that release-notes.yml cannot
+      # promote stops the release instead of shipping unrecorded entries.
+      # See scripts/check_changelog_release.py for the two rejected states.
+      - name: Verify the CHANGELOG can be promoted for this tag
+        run: python3 scripts/check_changelog_release.py "${GITHUB_REF_NAME}"
+
+      - name: Download the exact quality-gated artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: tracemantle-dist
+          path: dist
+
+      - name: Refuse the legacy distribution
+        run: |
+          python - <<'PYCODE'
+          import pathlib, zipfile
+          artifacts = sorted(pathlib.Path("dist").iterdir())
+          assert len(artifacts) == 2
+          assert all(p.name.startswith("tracemantle-") for p in artifacts)
+          for path in artifacts:
+              if path.suffix == ".whl":
+                  with zipfile.ZipFile(path) as wheel:
+                      metadata = next(n for n in wheel.namelist() if n.endswith(".dist-info/METADATA"))
+                      assert "\nName: tracemantle\n" in "\n" + wheel.read(metadata).decode()
+          PYCODE
+
+      - name: Verify wheel installs and version matches the tag
+        run: |
+          set -euo pipefail
+          pip install -c constraints-dev.txt dist/tracemantle-*.whl
+          installed="$(tracemantle --version | awk '{print $NF}')"
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$installed" != "$tag" ]; then
+            echo "Built version '$installed' does not match tag '$tag'." >&2
+            echo "Bump the version in pyproject.toml and __init__.py before tagging." >&2
+            exit 1
+          fi
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2.4.0
+        with:
+          subject-path: |
+            dist/tracemantle-*.whl
+            dist/tracemantle-*.tar.gz
+
+      - name: Publish to PyPI
+        # Pinned to a version tag, not a commit SHA: this action runs a Docker
+        # container whose image (ghcr.io/pypa/gh-action-pypi-publish) is tagged
+        # by release version, never by commit SHA. A SHA ref makes the inner
+        # pull request an image tag that does not exist (manifest unknown), and
+        # would pin nothing anyway since the image is fetched by tag regardless.
+        #
+        # Keep this current with the build backend. The step above installs
+        # hatchling with constraints, so the wheel carries the Metadata-Version
+        # that the selected hatchling emits. v1.12.4 (January 2025) bundles a twine that
+        # rejects Metadata-Version 2.5, which is what hatchling writes today,
+        # and it failed the 1.5.0 publish with "not a valid metadata version".
+        uses: pypa/gh-action-pypi-publish@v1.14.2
+
+  # After a TraceMantle release, Action users may select `@v1`, so the moving
+  # major tag has to follow every patch release. Moving it by hand was missed
+  # for v1.3.0 and v1.4.1, which left `@v1` resolving to v1.2.3 for two months
+  # while the action installs from its own checkout. This job runs only after a
+  # successful publish and holds the only `contents: write` scope in the file,
+  # so the publishing job above stays least-privilege.
+  move-major-tag:
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Point the major tag at this release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          # Plain vN.N.N only. The `v*.*.*` trigger glob also matches prerelease
+          # tags such as v2.0.0-rc1, which must not move the stable major tag.
+          if ! printf '%s' "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "Tag '$TAG' is not a plain vN.N.N release tag; major tag unchanged."
+            exit 0
+          fi
+          major="${TAG%%.*}"
+          echo "Moving '$major' to $SHA ($TAG)."
+          # PATCH updates the existing ref. POST creates it on the first release
+          # of a new major line, where the major tag does not exist yet.
+          if gh api "repos/${GITHUB_REPOSITORY}/git/refs/tags/${major}" >/dev/null 2>&1; then
+            gh api -X PATCH "repos/${GITHUB_REPOSITORY}/git/refs/tags/${major}" \
+              -f sha="$SHA" -F force=true
+          else
+            gh api -X POST "repos/${GITHUB_REPOSITORY}/git/refs" \
+              -f ref="refs/tags/${major}" -f sha="$SHA"
+          fi

tracemantle-1.6.0/.gitignore

@@ -0,0 +1,37 @@
+.env
+.DS_Store
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+*.egg
+CLAUDE.md
+# Field test artifacts (kept locally, not in git)
+runs/
+
+# Launch post drafts (kept locally, never push)
+launch-post/
+LAUNCH_CHECKLIST.md
+LAUNCH_POST_*.md
+
+# Per-skill history ledgers written by `tracemantle --history`; running the tool
+# against a file in the repo drops one next to it and it must never be committed.
+.skillcheck-history.json
+
+# Verification venvs (created by end-to-end verification runs)
+.venv-verify/
+
+# Agent scratchpads (kept locally; never push)
+.codex
+review.md
+.venv/
+
+candidate-dist/
+.tracemantle/

tracemantle-1.6.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: tracemantle
+  name: tracemantle
+  entry: tracemantle
+  args: ["--no-color"]
+  language: python
+  files: '(^|/)SKILL\.md$'
+  pass_filenames: true