stackvitals 0.1.1__tar.gz → 0.1.3__tar.gz

stackvitals-0.1.3/.github/workflows/daily.yml

@@ -0,0 +1,118 @@
+name: Daily
+
+on:
+  schedule:
+    - cron: "17 5 * * *"
+    # Backup in case GitHub skips the first; it stops at once when today's snapshot is already published.
+    - cron: "47 13 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: read  # shared benchmark figures arrive as issues
+
+concurrency:
+  group: daily
+  cancel-in-progress: false
+
+jobs:
+  daily:
+    # Runs only in the private repo that holds the crawl data; elsewhere the job is skipped.
+    if: github.repository == 'kaushik-yadav/merge-scout'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      MS_DATA_DIR: ${{ github.workspace }}/data
+      MS_RELEASE_TOKEN: ${{ github.token }}
+    steps:
+      - name: Skip a scheduled run when today's snapshot is already published
+        id: guard
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [ "${{ github.event_name }}" = "schedule" ] &&              gh release view "data-$(date -u +%F)" --repo "${{ github.repository }}" > /dev/null 2>&1; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Today's snapshot is already published; nothing to do."
+          fi
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        if: steps.guard.outputs.skip != 'true'
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        if: steps.guard.outputs.skip != 'true'
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # Downloaded crawl bundles are kept between runs, so each day fetches only new ones.
+      - uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0
+        if: steps.guard.outputs.skip != 'true'
+        with:
+          path: data/bronze
+          key: bronze-${{ github.run_id }}
+          restore-keys: bronze-
+      - run: pip install ".[pipeline]"
+        if: steps.guard.outputs.skip != 'true'
+      # The package map is reused for a week per package and OSV advisories until they change, so both sources are asked little.
+      - name: Fetch yesterday's package map, vulnerability history and ownership watch
+        if: steps.guard.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          mkdir -p out
+          for f in deps-map.json deps-osv.json deps-owners.json; do
+            gh release download bench-latest -p "$f" -D out --clobber || echo "no $f yet"
+          done
+      - name: Build signals and the snapshot from the crawl releases
+        id: build
+        if: steps.guard.outputs.skip != 'true'
+        run: python -m mergescout.snapshot build --from-releases --out out
+      # The snapshot first: users depend on it; the signal tables are only an extra copy.
+      - name: Publish the snapshot
+        if: steps.guard.outputs.skip != 'true'
+        run: python -m mergescout.snapshot publish out
+      - name: Publish the signal tables
+        if: always() && steps.build.outcome == 'success'
+        run: python -m mergescout.store put out/signals.tar --tag signals-latest
+      # Opt-in figures that teams filed as issues; a group is published only with 10+ repos.
+      - name: Build peer groups from shared benchmark figures
+        if: always() && steps.build.outcome == 'success'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python -m mergescout.bench.shared --repo "$GITHUB_REPOSITORY" --repo stackvitals/stackvitals --out out/shared-benchmarks.json || echo "shared figures skipped"
+      # Each extra is published when it was built; a skipped one keeps yesterday's file.
+      - name: Publish the review-flow benchmarks, the triage model, the upgrade ledger and the package map
+        if: always() && steps.build.outcome == 'success'
+        run: |
+          for f in flow-benchmarks.json delivery-benchmarks.json community-benchmarks.json triage-model.json deps-ledger.json deps-map.json watch-repos.txt deps-trends.json deps-osv.json deps-owners.json shared-benchmarks.json; do
+            if [ -f "out/$f" ]; then python -m mergescout.store put "out/$f" --tag bench-latest; else echo "out/$f was not built"; fi
+          done
+      # The Action reads the CI and shared benchmarks from the public repo's release; without its token the copy is skipped.
+      - name: Check for the public benchmark token
+        id: public_bench
+        if: always() && steps.guard.outputs.skip != 'true'
+        env:
+          PUBLIC_BENCH_TOKEN: ${{ secrets.PUBLIC_BENCH_TOKEN }}
+        run: |
+          if [ -n "$PUBLIC_BENCH_TOKEN" ]; then echo "set=true" >> "$GITHUB_OUTPUT"; else echo "No PUBLIC_BENCH_TOKEN; the public copy is skipped."; fi
+      - name: Copy the CI and shared benchmarks to the public release
+        if: always() && steps.public_bench.outputs.set == 'true'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PUBLIC_BENCH_TOKEN: ${{ secrets.PUBLIC_BENCH_TOKEN }}
+        run: |
+          mkdir -p public-bench
+          for f in ci-benchmarks.json shared-benchmarks.json; do
+            gh release download bench-latest -R "$GITHUB_REPOSITORY" -p "$f" -D public-bench --clobber || echo "no $f yet"
+          done
+          files=$(find public-bench -name '*.json')
+          if [ -z "$files" ]; then echo "Nothing to copy."; exit 0; fi
+          export GH_TOKEN="$PUBLIC_BENCH_TOKEN"
+          gh release view bench-latest -R stackvitals/stackvitals > /dev/null 2>&1 ||
+            gh release create bench-latest -R stackvitals/stackvitals --title "Benchmarks" --notes "Peer benchmarks the StackVitals Action compares with, refreshed daily."
+          # shellcheck disable=SC2086
+          gh release upload bench-latest $files -R stackvitals/stackvitals --clobber
+      - name: Sizes
+        if: always()
+        run: du -sh data out || true

stackvitals-0.1.3/.github/workflows/mcp-registry.yml

@@ -0,0 +1,32 @@
+name: MCP registry
+# Lists server.json in the MCP registry after each successful release (or by hand). GitHub's OIDC token proves the
+# org namespace, so no token is stored.
+on:
+  workflow_run:
+    workflows: [Release]
+    types: [completed]
+  workflow_dispatch:
+permissions: {}
+jobs:
+  publish:
+    if: github.repository == 'stackvitals/stackvitals' && (github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write   # the registry's GitHub OIDC sign-in
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+          # The released commit, not whatever main holds now.
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+      - name: Install mcp-publisher (pinned, checksum checked)
+        run: |
+          curl -sSfL -o mcp-publisher.tar.gz https://github.com/modelcontextprotocol/registry/releases/download/v1.8.7/mcp-publisher_linux_amd64.tar.gz
+          echo "00b21004149a4ce66f0782508ae4a2bce67d1bea395a8da0bd8028159fb59579  mcp-publisher.tar.gz" | sha256sum -c -
+          tar -xzf mcp-publisher.tar.gz mcp-publisher
+      - name: Publish
+        run: |
+          ./mcp-publisher login github-oidc
+          ./mcp-publisher publish

stackvitals-0.1.3/.github/workflows/prospective.yml

@@ -0,0 +1,79 @@
+name: Prospective tests
+
+# The pre-registered reads, scored on their dates whatever they show: reviewer suggestions (from 2027-01-15), the
+# finder's ranking (from 2027-03-20) and the adoption study (from 2027-07-01, then every three months). Each scorer
+# refuses to run early or on a changed frozen file, and a finished read is not scored again; results come back as a PR.
+on:
+  schedule:
+    - cron: "0 7 16 1 *"
+    - cron: "0 7 21 3 *"
+    - cron: "0 7 2 1,4,7,10 *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: prospective
+  cancel-in-progress: false
+
+jobs:
+  score:
+    # Runs only in the private repo that holds the crawl data; elsewhere the job is skipped.
+    if: github.repository == 'kaushik-yadav/merge-scout'
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      MS_DATA_DIR: ${{ github.workspace }}/data
+      # Code search (finding adopters) needs a person's token; the built-in one reads everything else.
+      GH_TOKEN: ${{ secrets.PROSPECTIVE_TOKEN || github.token }}
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install ".[pipeline]"
+      - name: Download the crawl
+        env:
+          MS_RELEASE_TOKEN: ${{ github.token }}
+        run: |
+          python -c "
+          import os; from pathlib import Path
+          from mergescout.github.releases import Releases
+          from mergescout.store.sync import fetch_bronze
+          fetch_bronze(Releases(os.environ['MS_RELEASE_TOKEN'], os.environ['GITHUB_REPOSITORY']), Path(os.environ['MS_DATA_DIR']))"
+      - name: Score every test that is due
+        run: |
+          set +e
+          {
+            # A read that already has its results stands; it is not scored again.
+            echo "## Reviewer suggestions"
+            if [ -f bench/accuracy/team/prospective-results.json ]; then echo "Already scored; the read stands."
+            else python bench/accuracy/team/prospective.py score; echo "exit $?"; fi
+            echo "## Finder's ranking"
+            if [ -f bench/accuracy/contribute/prospective-results.json ]; then echo "Already scored; the read stands."
+            else python bench/accuracy/contribute/prospective.py score --crawl data/bronze/crawl; echo "exit $?"; fi
+            # study.py refuses by itself (exit 4) once a read included 20+ adopters or after 2028-07-01.
+            echo "## Adoption study"
+            if [ "$(date -u +%F)" \> "2027-06-30" ]; then python bench/accuracy/adoption/study.py find; fi
+            python bench/accuracy/adoption/study.py score --crawl data/bronze/crawl; echo "exit $?"
+          } 2>&1 | tee scores.log
+      - name: Open a pull request with the results
+        run: |
+          for f in bench/accuracy/team/prospective-results.json bench/accuracy/contribute/prospective-results.json \
+            bench/accuracy/adoption/adopters.json bench/accuracy/adoption/results.json; do
+            if [ -f "$f" ]; then git add "$f"; fi
+          done
+          if git diff --cached --quiet; then echo "Nothing was due."; exit 0; fi
+          branch="test/prospective-$(date -u +%F)-${{ github.run_id }}"
+          git -c user.name="github-actions[bot]" -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
+            commit -q -m "test(measure): Score the pre-registered prospective tests due $(date -u +%F)"
+          git push -q origin "HEAD:refs/heads/$branch"
+          body="$(printf 'Scored by the Prospective tests workflow, published whatever the results show.\n\n```\n%s\n```\n' "$(tail -c 60000 scores.log)")"
+          # Repos that don't let Actions open pull requests get an issue pointing at the branch instead.
+          gh pr create --head "$branch" --title "Prospective test results $(date -u +%F)" --body "$body" ||
+            gh issue create --title "Prospective test results $(date -u +%F) (branch $branch)" --body "$body"

stackvitals-0.1.3/.github/workflows/release.yml

@@ -0,0 +1,102 @@
+name: Release
+# A version tag (v0.1.0) builds the package with read-only rights, then a second job signs every file keylessly with
+# Sigstore, writes a software bill of materials and a build provenance attestation, and publishes them on the release.
+# A third job then uploads the same wheel and sdist to PyPI by trusted publishing (no stored token).
+on:
+  push:
+    # Version tags only: moving the floating `v0` tag must not make a release.
+    tags: ["v*.*.*"]
+permissions: {}
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
+      - name: Build
+        # The build backend is pinned, so a new upload to PyPI can never change what gets signed.
+        run: uv build --build-constraint .github/build-constraints.txt --no-cache --out-dir dist
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: dist
+          path: dist/
+          retention-days: 1
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Reviewers on this environment and a tag ruleset decide who can publish (repo settings).
+    environment: release
+    permissions:
+      contents: write      # the release and its files
+      id-token: write      # Sigstore's keyless signing and the provenance attestation
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist
+      - name: Find the wheel
+        id: wheel
+        run: echo "path=$(ls dist/*.whl)" >> "$GITHUB_OUTPUT"
+      - name: Software bill of materials
+        # What the wheel installs, not the whole source tree with its test and bench tools.
+        uses: anchore/sbom-action@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c # v0.24.3
+        with:
+          file: ${{ steps.wheel.outputs.path }}
+          format: spdx-json
+          output-file: sbom.spdx.json
+          upload-artifact: false
+          upload-release-assets: false
+      - name: Keep the SBOM with the release files
+        run: mv sbom.spdx.json dist/stackvitals.spdx.json
+      - name: Sign with Sigstore
+        uses: sigstore/gh-action-sigstore-python@790bc6befb9d733738f18d8f895854b453640ec9 # v3.5.0
+        with:
+          inputs: ./dist/*.whl ./dist/*.tar.gz ./dist/stackvitals.spdx.json
+          upload-signing-artifacts: false
+          release-signing-artifacts: false
+      - name: Build provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: dist/*
+      - name: Publish the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          REPO: ${{ github.repository }}
+        run: gh release create "$TAG" dist/* --repo "$REPO" --title "$TAG" --generate-notes --verify-tag
+  pypi:
+    needs: [build, publish]
+    # The real home only (forks and copies skip it); update this name if the repo moves (launch step C1).
+    if: github.repository == 'stackvitals/stackvitals'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # PyPI's trusted publisher names this repo, release.yml and this environment; nothing else can upload.
+    environment: release
+    permissions:
+      id-token: write      # the short-lived PyPI upload token, by OIDC
+    steps:
+      # The files the build job made and the publish job signed, not a rebuild.
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist
+      - name: Check the tag matches the package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          ls dist
+          test -f "dist/stackvitals-${TAG#v}.tar.gz" && test "$(ls dist | wc -l)" -eq 2
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          packages-dir: dist/
+      # The MCP registry listing is a separate, manual step: docs/release-checklist.md, "Publishing".

stackvitals-0.1.3/.github/workflows/tests.yml

@@ -0,0 +1,28 @@
+name: Tests
+# The committed workflow tests on every pull request, with a read-only token and no secrets.
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          node-version: 22
+      # The web app's build tools, so the suite can rebuild the app and check the committed build is current.
+      - name: Install the web app's build tools
+        working-directory: web
+        run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Run the tests
+        run: uv run --locked --extra dev pytest -q

stackvitals-0.1.3/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## 0.1.3 (2026-10-31)
+
+- The app's About page and the project site say Apache 2.0 (they said MIT); the site shows the cube logo and the
+  one-command setup.
+- The app's Setup page and Help give `stackvitals init owner/repo` as the terminal way to set a repo up.
+- PyPI lists the project's links (home, docs, source, issues, changelog).
+- Docs: the install page says how to get the command; guides, quickstart and modules lead with `stackvitals init`;
+  contradictions fixed (golden paths, GitLab, GitHub Enterprise Server, sign-in, private repos' CI runs, cycle-time
+  phases); the PR verdicts are a table; the settings page says which switches are on by default; the architecture
+  diagrams list every trigger and show Portal running from the org's repo; a release checklist with the real steps.
+- A code of conduct (Contributor Covenant 2.1), with reports through the repository's private reporting form.
+
+## 0.1.2 (2026-10-31)
+
+- `stackvitals init owner/repo` sets StackVitals up in one command: commits the workflow (or opens a pull request), follows
+  the first run and turns on Pages for a public repo; a private repo keeps Pages off and opens with `stackvitals ui`.
+- The StackVitals cube is the app's logo in the sidebar, the browser tab and the splash; the logo picker is gone.
+- The README opens with the logo, a short tour and the architecture; the architecture docs open with a detailed diagram.
+
+## 0.1.1 (2026-10-31)
+
+- The Action's description is shorter, to fit the GitHub Marketplace listing. No other change.
+
+## 0.1.0 (2026-10-31)
+
+First release of StackVitals: one Action, one CLI and one MCP server over these modules. History stays in your repo's
+`stackvitals-data` branch, with an app on your repo's GitHub Pages (or `stackvitals ui owner/repo` on your machine).
+
+**CI Health**
+- Finds flaky jobs and tests from your GitHub Actions history: a failure that later passed with no code change, on a re-run or on another run of the same code. Outages, gatekeeper jobs and GitHub-managed workflows are ignored.
+- Calls a failure likely flaky only with a flake's sign in the log and no changed file named; likely flakes are re-run once, never passed by the verdict check.
+- Reads JUnit XML and CTRF JSON test reports from run artifacts (or `stackvitals ci upload` from any CI, GitLab CI included), groups failures by root cause, names the matrix variant flakes came from, and keeps each test's state with the day it began.
+- One comment per pull request: which failures are known flakes, which already fail on the default branch (with the same error), and which are new.
+- What each flaky test cost and the pull requests it got in the way of; what CI costs by workflow and job; the first-try share opened into the pushes that missed it.
+- Opt-in automation: re-run known flakes once, retry only failed tests in the job, quarantine inside Playwright, Maven and dotnet test runs (ending after `max_days`), burn-in for new tests, one issue or Jira/Linear ticket per flaky test, verified fix requests for real CI breaks, and Slack, Discord or Teams alerts.
+- Test impact: picks the tests a change can affect, with a replay of the rule on past pull requests.
+
+**Team Flow and Delivery**
+- Who acts next on each open pull request, review stages, insiders and outside contributors, suggested reviewers, size labels and PR rules as code.
+- LinearB's six cycle-time phases with P50 and P75 (weekends and holidays left out with a working calendar), and DORA counted exactly as DevLake's dashboard counts it, with an export in DevLake's table shapes.
+- Deployments from the Deployments API, releases, merges or workflow runs, with release and GitFlow branches; deployments and incidents from any tool through `repository_dispatch`; GitLab merge requests and deployments.
+- A deployments tab, all four DORA metrics week by week, per team and per service in a monorepo, several repos pooled into one project, and every DORA number opened into the pull requests and deployments behind it (`stackvitals explain` in the terminal).
+- Coding agents' work, review load and how much of people's and agents' code lasts 30 and 90 days; AI tool usage and spend beside AI-involved pull requests.
+- Change risk on open pull requests where the repo's own backtest shows it works; what changed in the hours before an incident; a capitalisation CSV for finance.
+
+**Insights and alerts**
+- One ranked list of what to fix first, in hours at stake, and alerts when pickup, review, cycle time or change failure rate crosses a threshold.
+
+**Dependency Steward**
+- Known vulnerabilities and malware in every lockfile OSV-Scanner reads, .NET project files and SBOMs, the Actions your workflows use and container base images; exploited advisories, dependency paths, development-only packages and Go reachability.
+- The smallest fixing upgrade with its command, licence checks on new packages, look-alike package names, `osv-scanner.toml` ignores honoured, SARIF for GitHub's Security tab, and OpenSSF Scorecard's checks run on the repo itself.
+
+**Community, Portal and Explore**
+- Newcomers waiting for a first answer (maintainers, regular responders and triagers count as the project's answer), the contributor funnel, cohorts and star history, with forums and chat.
+- An org catalog with owners, scorecards, golden paths, required checks, an org-wide view and a Backstage export.
+- SQL over your history in the browser, with links to share a query.
+
+**Contribute (MergeScout)**
+- Open-source issues an outsider can get merged, with evidence, from a daily snapshot of public repos.
+
+**The app**
+- One page per module in the Instrument design, with Overview and Insights first, a Data health page, a demo at `?demo=1`, and decisions and settings saved from the browser.
+- One-click setups for more repos once GitHub is connected, and a test call for every connection.
+
+**Decisions and the weekly digest**
+- `/stackvitals` commands in comments (quarantine, unquarantine, mute, acknowledge, snooze, exclude) from people with access, each logged with who, why and until when; temporary ones end on their own.
+- Requests from the app as prefilled issues, applied by the workflow (settings changes open a pull request when the branch is protected).
+- A weekly digest on one pinned issue and/or the webhook; findings keep "open since" and how much of the last 90 days they were active.
+
+**Integrations**
+- Jira Cloud, Linear, PagerDuty, incident.io, SonarQube or SonarCloud, Copilot usage reports, Claude Code analytics, Anthropic, OpenAI and Cursor spend, Slack, Teams, Discord, Discourse, Bitbucket, Azure DevOps, GitLab, Backstage and DevLake's tables; GitHub Enterprise Server's API addresses are followed from the job.
+- A service can be read again from a chosen date instead of starting over.
+
+**Settings and install**
+- `.github/stackvitals.toml`, read on every run; every key is listed in docs/settings.md.
+- Modules can be installed one at a time, each asking only for the permissions it uses.
+
+**Measured, with the losses published**
+- Accuracy cards with ranges for every headline rule, labels checked by two model families and a model panel, and one command to reproduce each result ([docs/accuracy.md](docs/accuracy.md)).
+- Pre-registered side-by-side runs against Apache DevLake, Middleware and OpenSSF Scorecard on public repos.
+
+**Security**
+- Every action pinned to a commit, release files signed with Sigstore with an SBOM and build provenance, locked installs, and test reports from forks not trusted.
+
+**For AI agents**
+- `stackvitals serve`: one MCP server with every module's tools (11 core tools by default, all 35 with `--tools all`), each answer stamped with when and where it came from, a skill pack and `llms.txt`.

stackvitals-0.1.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,113 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience
+for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status, nationality, personal appearance,
+race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy
+community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take
+appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
+issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially
+representing the community in public spaces. Examples of representing our community include using an official e-mail
+address, posting via an official social media account, or acting as an appointed representative at an online or
+offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders
+responsible for enforcement privately, through GitHub's private reporting form for this repository: open the
+**Security** tab of [stackvitals/stackvitals](https://github.com/stackvitals/stackvitals/security), choose **Report a
+vulnerability**, and start the title with "Conduct:". Only the maintainers can read it. You can also use GitHub's
+[Report content](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam)
+on any comment, issue or pull request. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they
+deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the
+community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the
+violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved,
+including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels like social media. Violating these
+terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a
+specified period of time. No public or private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to
+a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate
+behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

stackvitals-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thanks for helping. StackVitals is small enough that one person can read any part of it in an afternoon; please
+keep it that way. Everyone taking part follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Set up
+
+You need Python 3.11+, [uv](https://docs.astral.sh/uv/), git and Node 22 (a few tests check the app's scripts).
+
+Clone the repo, then from its folder:
+
+```
+uv run --extra dev pytest tests -q
+```
+
+The tests need no token and no network. [docs/architecture.md](docs/architecture.md) explains how the parts fit.
+
+**The web app** is TypeScript in `web/`, built into `src/stackvitals/web/app/`, and the built files are committed
+(they ship in the package). After changing it:
+
+```
+cd web
+npm ci
+npm run build
+npm test
+```
+
+Commit `web/` and the rebuilt `src/stackvitals/web/` together; a test fails when the build is out of date.
+[web/README.md](web/README.md) explains its layout and the browser tests (`npm run e2e`).
+
+## What a good change looks like
+
+- **A bug:** a failing test first, then the fix. Task-sized tests go in `tests/local/`; a test that guards a real
+  bug or finding for a whole flow goes in the `tests/test_flow_<area>.py` file for that area.
+- **A new rule or a changed one** (anything that decides a verdict or a number people see): add or update its entry in
+  [bench/accuracy/registry.json](bench/accuracy/registry.json) with what it was tuned on, what it was checked on and
+  the bar, check it on public data the rule never saw, then run `python bench/accuracy/summary.py` to regenerate
+  [docs/accuracy.md](docs/accuracy.md) and [docs/rules.md](docs/rules.md). A change that makes a number look better
+  without held-out evidence won't be merged; a change that publishes a loss will.
+- **A new setting:** add it to `src/stackvitals/core/schema.py`; [docs/settings.md](docs/settings.md) is generated
+  from it and a test checks they match.
+- **Anything that reaches a new host or needs a new permission:** say so in the pull request. The privacy page lists
+  every outside host and a test fails if code can reach one it doesn't name ([docs/privacy.md](docs/privacy.md)).
+- **A new action in a workflow:** pin it to a commit with the version in a comment; a test fails otherwise.
+
+## Style
+
+- Code reads like the code around it. Comments are short, plain and say why, not what.
+- Copy people see is plain English: what happened, how many, since when, and what to do. No unexplained jargon, and
+  never a number without its sample size.
+- Each test says what real bug or finding it guards; the `tests/test_flow_*.py` files stay few and test whole flows.
+
+## Pull requests
+
+- Branch names: `type/short-topic` (`fix/flake-window`). Commit messages follow
+  [Conventional Commits](https://www.conventionalcommits.org/): `fix(ci): Keep the failing step when a job is re-run`.
+- The Tests workflow runs on every pull request. A maintainer reviews within a week; if it has been longer, comment
+  to ask.
+- By contributing you agree your work is released under the [Apache License 2.0](LICENSE).
+
+## Security problems
+
+Never in a public issue: see [SECURITY.md](SECURITY.md).