planlens-agent 0.1.0__tar.gz

planlens_agent-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,17 @@
+---
+name: Bug report
+about: A wrong verdict, a crash or instructions that do not work
+---
+
+**Version:** output of `planlens-agent --version`
+
+**Python and operating system:**
+
+**Exact command and exit status:**
+
+**Smallest catalog, contract and plan that show the problem:**
+<!-- Remove credentials and anything confidential. -->
+
+**What you expected, and which rule should or should not have applied:**
+
+**Full output:**

planlens_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+# Runs the same stages as `python scripts/ci_local.py`. No secrets and no model calls.
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - run: uv run --no-project --python 3.14 scripts/ci_local.py lint --python 3.14
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - run: uv run --no-project --python ${{ matrix.python }} scripts/ci_local.py test --python ${{ matrix.python }}
+
+  package:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.14"]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - run: uv run --no-project --python ${{ matrix.python }} scripts/ci_local.py package --python ${{ matrix.python }}
+
+  journey:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - run: uv run --no-project --python 3.14 scripts/ci_local.py journey --python 3.14 --log journey.log
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: journey-${{ matrix.os }}
+          path: journey.log
+          if-no-files-found: warn
+
+  recipe:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.14"]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - run: uv run --no-project --python ${{ matrix.python }} scripts/ci_local.py recipe --python ${{ matrix.python }} --log recipe-journey.log
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: recipe-journey-${{ matrix.python }}
+          path: recipe-journey.log
+          if-no-files-found: warn
+
+  pilot:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.14"]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - run: uv run --no-project --python ${{ matrix.python }} scripts/ci_local.py pilot --python ${{ matrix.python }}
+
+  docs:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.14"]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - run: uv run --no-project --python ${{ matrix.python }} scripts/ci_local.py docs --python ${{ matrix.python }}

planlens_agent-0.1.0/.github/workflows/consumer-demo.yml

@@ -0,0 +1,115 @@
+# Shows the gate as a consumer would use it. Started by hand only.
+#
+# `reject-demo` and `sarif-demo` FAIL ON PURPOSE: the candidates break the contract, and the
+# gate's failing status is kept. A red run of this workflow is the expected result.
+# Every plan is an authored example. The baselines here are generated inside the job so the
+# demo stands alone; a real baseline is an owner-reviewed file. See docs/ci.md.
+name: Consumer demo
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pass-demo:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - name: Install the built wheel
+        run: |
+          uv build --wheel --out-dir wheel
+          uv venv --python 3.14 demo
+          uv pip install --python demo/bin/python --no-deps wheel/*.whl
+          demo/bin/planlens-agent init release-basic project
+      - name: Gate on passing candidates
+        working-directory: project
+        run: ../demo/bin/planlens-agent suite run suite.toml --plans-dir candidates/v3 --output candidate.run.json
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: pass-demo-run
+          path: project/*.run.json
+          if-no-files-found: warn
+
+  reject-demo:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - name: Install the built wheel
+        run: |
+          uv build --wheel --out-dir wheel
+          uv venv --python 3.14 demo
+          uv pip install --python demo/bin/python --no-deps wheel/*.whl
+          demo/bin/planlens-agent init release-basic project
+      - name: Create the demonstration baseline
+        working-directory: project
+        run: ../demo/bin/planlens-agent suite run suite.toml --plans-dir candidates/v3 --output baseline.run.json
+      - name: Gate on rejecting candidates (fails on purpose)
+        working-directory: project
+        run: ../demo/bin/planlens-agent suite run suite.toml --plans-dir candidates/v2 --output candidate.run.json
+      - name: Show what changed (also fails, because findings are new)
+        if: always()
+        working-directory: project
+        run: ../demo/bin/planlens-agent suite diff baseline.run.json candidate.run.json --output comparison.json
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: reject-demo-diagnostics
+          path: |
+            project/*.run.json
+            project/comparison.json
+          if-no-files-found: warn
+
+  sarif-demo:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      actions: read # upload-sarif reads this workflow run; needed on private repositories
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - name: Install the built wheel
+        run: |
+          uv build --wheel --out-dir wheel
+          uv venv --python 3.14 demo
+          uv pip install --python demo/bin/python --no-deps wheel/*.whl
+      - name: Check a rejected plan and write SARIF (fails on purpose)
+        run: |
+          demo/bin/planlens-agent check src/planlens_agent/templates/release_basic/plans/reversed-review.json \
+            --contract src/planlens_agent/templates/release_basic/contract.toml \
+            --catalog src/planlens_agent/templates/release_basic/catalog.toml \
+            --format sarif --output planlens.sarif --source-root .
+      - uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
+        if: always()
+        with:
+          sarif_file: planlens.sarif
+          category: planlens-agent-demo
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: sarif-demo-log
+          path: planlens.sarif
+          if-no-files-found: warn

planlens_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,104 @@
+# Publishes one checked wheel and sdist to PyPI through Trusted Publishing.
+# Manual only. Run it from the release tag, after the steps in release/PUBLISHING.md.
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to publish, without the leading v
+        required: true
+        type: string
+      commit:
+        description: Full commit SHA that the tag and main must both be
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.3"
+          enable-cache: false
+      - name: Stop unless this is the approved tag, commit and main
+        env:
+          REF: ${{ github.ref }}
+          VERSION: ${{ inputs.version }}
+          COMMIT: ${{ inputs.commit }}
+        run: |
+          test "$REF" = "refs/tags/v$VERSION"
+          test "$(git rev-parse HEAD)" = "$COMMIT"
+          test "$(git rev-parse refs/remotes/origin/main)" = "$COMMIT"
+      - name: Stop unless CI passed for this exact commit
+        env:
+          COMMIT: ${{ inputs.commit }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python3 scripts/ci_gate.py --commit "$COMMIT"
+      - name: Build the pair once
+        run: uv build --python 3.14 --out-dir release-pair/dist
+      - name: Check that pair
+        env:
+          VERSION: ${{ inputs.version }}
+        run: >-
+          uv run --no-project --python 3.14 scripts/release_check.py
+          --wheel "release-pair/dist/planlens_agent-$VERSION-py3-none-any.whl"
+          --sdist "release-pair/dist/planlens_agent-$VERSION.tar.gz"
+          --sums release-pair/SHA256SUMS
+          --tag "v$VERSION"
+          --python "$(uv python find --no-project 3.14)"
+      - name: Check the description renders
+        run: >-
+          uvx --from twine==7.0.0 --with "readme-renderer[md]==46.0"
+          twine check --strict release-pair/dist/*
+      - name: Record the hashes for the approver
+        run: cat release-pair/SHA256SUMS >> "$GITHUB_STEP_SUMMARY"
+      - name: Keep the CI gate for the check just before upload
+        run: cp scripts/ci_gate.py release-pair/ci_gate.py
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release-pair
+          path: release-pair
+          if-no-files-found: error
+
+  publish:
+    needs: check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/project/planlens-agent/
+    permissions:
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-pair
+          path: release-pair
+      - name: Stop unless these are exactly the checked files
+        working-directory: release-pair/dist
+        run: |
+          files=(*)
+          test "${#files[@]}" -eq 2
+          sha256sum --check --strict ../SHA256SUMS
+      - name: Stop unless CI still passes for this exact commit
+        env:
+          COMMIT: ${{ inputs.commit }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python3 release-pair/ci_gate.py --commit "$COMMIT"
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          packages-dir: release-pair/dist

planlens_agent-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

planlens_agent-0.1.0/AUTHORS.md

@@ -0,0 +1,21 @@
+# Authors
+
+PlanLens (distributed as `planlens-agent`) is by, in this order:
+
+| Author | Role |
+| --- | --- |
+| Nurdaulet Abdrakhman | Project lead and primary maintainer; primary project contact |
+| Daniyal Kozyrev | Co-author and contributor |
+
+Nurdaulet Abdrakhman leads the project and is responsible for its maintenance. Contact:
+[LinkedIn](https://www.linkedin.com/in/nurdaulet-abdrakhman-523784375).
+
+These names and roles were confirmed by the project owner.
+
+Implementation of this product used an AI coding assistant, Claude Code, under the project lead's direction.
+
+## Research artifact
+
+This product is separate from the PlanLens research artifact. That repository's `AUTHORS.md` lists Nurdaulet
+Abdrakhman (primary and contact author) and Daniyal Kozyrev (coauthor). That is a statement about the
+research artifact, whose own attribution and copyright are recorded there; see `NOTICE` and `PROVENANCE.md`.

planlens_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Changelog
+
+## 0.1.0 - first public release
+
+Changed
+
+- Version 0.1.0, with the package maturity classifier `Development Status :: 3 - Alpha`. The
+  public API may evolve during 0.x.
+- Installation is documented as `python -m pip install "planlens-agent==0.1.0"`.
+- The package description comes from `README.pypi.md`, because the GitHub README uses relative
+  images and links that would break on PyPI.
+- The README opens with a walkthrough of one authored example, built from real package output and
+  a real Inspector capture, and the summary now reads "Catch plan errors before execution".
+- The logo is the approved "Planform" mark, with light, dark and one-colour variants.
+- The selected names are recorded in `docs/naming.md`, with PyPI registration pending.
+
+Compatibility
+
+- The evaluator digest covers `_version.py`, so runs saved by a `0.1.0.dev0` build are
+  `not_comparable` (exit 2) with runs from 0.1.0. Regenerate those baselines and review them.
+  Strict comparison and the engine-version check on approvals are unchanged.
+
+No checker rule, diagnostic meaning, schema or policy behaviour changed from the last development
+build, and no runtime dependency was added.
+
+Added
+
+- `scripts/release_check.py` checks a built wheel and sdist as one pair, and `release/` holds the
+  release notes and publishing procedure.
+- `.github/workflows/publish.yml`, a manual-only PyPI Trusted Publishing workflow.
+  `scripts/ci_gate.py` stops it unless GitHub's Actions API shows CI passed for the exact commit.
+
+## 0.1.0.dev0 - unreleased (checkpoint B2)
+
+Added
+
+- `suite run` and `suite diff`: run developer-supplied candidates through `check()`, save
+  an auditable run (`planlens-agent/run/v1`), and compare two runs
+  (`planlens-agent/run-diff/v1`). See `docs/suites.md`.
+- Runs record plan content and digests, contract and catalog identity, report and rule
+  versions, and an evaluator digest that tells apart builds sharing a version string.
+- `load_suite`, `run_suite`, `load_run`, `compare_runs` in the SDK; schemas for suites, runs
+  and comparisons.
+- `candidates/` and `suite.toml` in the `release-basic` template, all authored.
+- `examples/langgraph_gate`: a planner, check, execute-or-reject graph, tested with
+  LangGraph 1.2.20. The core still has no runtime dependencies.
+- `.github/workflows/ci.yml` and `consumer-demo.yml`, prepared and not yet run on a hosted
+  service; `scripts/ci_local.py` runs the same stages locally; `scripts/journey.py` walks the
+  whole journey against an installed command.
+
+Fixed
+
+- A file name too long for the operating system made `check()` raise, and the CLI report an
+  internal error, for plans, contracts and catalogs. It is now an `unreadable` finding, with
+  no source location invented. The same fault is fixed in `--source-root`, `init` and
+  `regress`.
+
+Fixed after independent review of B2 (B2-r2)
+
+- LangGraph recipe: a returned state or caller-supplied fields could authorize a later
+  invocation whose planner failed, and removing the plan after the check skipped the
+  comparison. The graph now accepts only `request`, every invocation starts clean, and
+  execution needs a current plan.
+- `load_run`: every declared type is checked before use, so a malformed value is a
+  `RunFileError` instead of an uncaught `TypeError`. Booleans and floats are no longer
+  accepted as integers, identifiers cannot end in a newline, and findings must agree with the
+  run's rule versions.
+- `suite diff`: two runs agreeing on an unsupported `report_schema` are `not_comparable`.
+- `suite diff --output` refuses to replace either input, including through other spellings,
+  symlinks and hard links.
+
+Fixed after independent review of B2-r2 (B2-r3)
+
+- `check`, `inspect` and `suite run --overwrite` could overwrite their own inputs. All of them
+  now refuse, with exit 2, an output that is the plan, contract, catalog, suite manifest or a
+  candidate in use, including through other spellings, symlinks and hard links.
+
+Developer experience
+
+- README rebuilt around the journey; quickstart with an owner-defined workflow; evidence page.
+- An authored demo GIF, a static fallback and an inspector screenshot, generated from installed-wheel
+  output by `scripts/make_demo_media.py`.
+- `scripts/docs_check.py` and a `docs` CI stage run the copy-and-run blocks exactly as written. Each
+  command has its own status, so a failure in the middle of a block is fatal, and the README's
+  development command is run from a clean shell.
+
+Presentation
+
+- PlanLens wordmark, a README built around the first questions a developer asks, a saved diagnosis
+  in a collapsed section, a docs index, an examples index and contributor guidance.
+- Terminal media is now a labelled excerpt with a complete transcript beside it.
+
+Project details
+
+- Owner-confirmed authors, maintainer, copyright holder and contact in `AUTHORS.md`, `NOTICE`, the README
+  and package metadata. `CONTRIBUTING.md` is now in the sdist.
+
+Fixed on hosted CI
+
+- `.gitattributes` keeps LF on every platform and leaves the vendored OASIS schema untouched.
+  Windows checkouts had rewritten its line endings.
+- The SARIF demo job has the `actions: read` permission that `upload-sarif` needs on private
+  repositories.
+
+Unchanged
+
+- `check` and `inspect` output: byte-identical to the previous checkpoint's wheel across the
+  acceptance cases and bundled plans.
+
+## 0.1.0.dev0 - unreleased (checkpoint A)
+
+Not published. Distribution, module and command names are provisional
+(see `docs/naming.md`).
+
+Added
+
+- Owner-supplied action catalog and contract (`.toml` or `.json`), validated
+  together before any plan is read: schema, catalog pin, unknown actions,
+  prerequisite cycles, inconsistent or unsatisfiable artifact rules, and
+  unsupported rule kinds.
+- Ordered sequential plans with unique step ids and `"<step>.<output>"`
+  artifact references.
+- Checks: unknown actions, required actions, prerequisites, reference
+  resolution and order, input binding and type, planned artifact identity, and
+  attempts by a plan to override policy.
+- One diagnostic model for the SDK, CLI and JSON reports
+  (`planlens-agent/report/v1`), with stable rule ids and offline explanations.
+- CLI `planlens-agent` with `check` (exit 0 / 1 / 2), `validate-policy`,
+  `regress`, `init`, `rules`, `explain`.
+- `ApprovedPlan` snapshots and a `ReferenceRunner` that dispatches only the
+  exact approved snapshot.
+- `release-basic` template, regression fixtures, JSON Schemas.
+
+Fixed during the checkpoint A source review
+
+- An integer longer than 4,300 digits in a JSON or TOML document made `check()`
+  raise `ValueError`; through the CLI it was reported as an internal error with
+  no report. It is now a `<doc>/limit` finding.
+- Excessive nesting was reported as `malformed` or `schema` depending on which
+  depth check fired first. It is now always `<doc>/limit`.
+
+Fixed after the second source review
+
+- A validated policy exposed mutable dicts, so clearing an action's inputs made a
+  rejected plan pass under the same digest. Catalog and contract are now
+  read-only private copies bound to their content; `check(policy=...)` and the
+  runner refuse a policy that no longer matches (`PolicyIntegrityError`).
+- The runner re-checked the plan, then dispatched from `approval.plan`, which a
+  caller could mutate during dispatch. It now dispatches its own validated
+  read-only copy, and `ApprovedPlan` always holds a private copy.
+- A JSON escape for an unpaired surrogate (`"\ud800"`) crashed checking of plans,
+  contracts and catalogs. It is now a `<doc>/schema` finding with a location.
+- `contract/unsatisfiable-input` (rule version 2) now detects required actions
+  whose inputs cannot be bootstrapped, not only types no action outputs.
+- `uv.lock` is included in the sdist.
+
+Added in checkpoint B1
+
+- `planlens-agent inspect PLAN --output FILE`: a self-contained HTML report of one
+  check, built from an explicit view model (`build_view`, `render_html`).
+- `planlens-agent check --format sarif [--source-root DIR]`: SARIF 2.1.0 export
+  (`to_sarif`, `to_sarif_json`). `--output` saves what is printed in this mode;
+  text and JSON modes are unchanged.
+- `Policy.catalog_origin` and `Policy.contract_origin`, so a syntax error in a policy
+  document can be located in its file.
+
+Fixed after the B1 source review
+
+- More than 702 distinct artifact references in one report made `build_view` raise
+  `IndexError`, so `inspect` gave no report. Group labels now continue past ZZ with no
+  limit, and a label stands for one reference across all rules.
+- SARIF export resolved relative paths against the working directory at export time.
+  Locations are now fixed when each document is read (`CheckResult.plan_source`,
+  `Policy.contract_source`, `Policy.catalog_source`).
+- The diagram's relationship limit is now checked before any of it is built.
+- Raw observed and required data moved behind native disclosure controls, with a compact
+  summary from the same structured fields left visible.

planlens_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+PlanLens is in its 0.x series, and its public API may evolve. You need Git and [uv](https://docs.astral.sh/uv/).
+
+## Set up and test
+
+<!-- run prereq -->
+```sh
+git clone https://github.com/nurdauletabdurahman777-maker/planlens-agent.git
+```
+
+Run everything below from the root of the clone. No virtual environment has to be active: `uv run` creates
+`.venv` and uses it.
+
+<!-- run dev contains=" passed" contains="Success: no issues found" -->
+```sh
+uv run --locked --extra dev pytest tests -q
+uvx ruff@0.17.4 format --check .
+uvx ruff@0.17.4 check .
+uvx mypy@2.4.1 --strict src/planlens_agent
+```
+
+Every CI stage, as CI runs it:
+
+```text
+uv run --no-project --python 3.14 scripts/ci_local.py all --python 3.14
+```
+
+## What to keep true
+
+- The core has no runtime dependencies. Development tools stay out of the wheel.
+- The checker is deterministic and makes no model calls.
+- Every command in a `sh` block in the README, Quickstart or this file must work as written. The `docs` CI stage
+  runs them. A command that is meant to fail goes last in its block.
+- Label authored examples as authored. Do not report results that were not observed.
+
+## Regenerate media
+
+On macOS with Google Chrome, from the root of the clone:
+
+```text
+uv run --script scripts/make_demo_media.py
+```
+
+This rebuilds `docs/media` and `docs/brand` from the real package. Its tools are used only by that script.
+
+## Report a bug
+
+Open an issue, and include:
+
+- the output of `planlens-agent --version`, your Python version and operating system;
+- the exact command and its exit status;
+- the smallest catalog, contract and plan that show the problem;
+- what you expected, and the full output.
+
+Remove credentials and anything confidential first. A wrong verdict is the most important kind of bug: include
+the plan, and say which rule should or should not have applied.