gabion 0.1.0__tar.gz → 0.1.5__tar.gz

gabion-0.1.5/.github/workflows/auto-test-tag.yml

@@ -0,0 +1,72 @@
+name: auto-test-tag
+
+on:
+  workflow_run:
+    workflows: ["mirror-next"]
+    types: [completed]
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      (github.event.workflow_run.actor.login == github.repository_owner ||
+        github.event.workflow_run.actor.login == 'github-actions[bot]')
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha }}
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+      - name: Verify next mirrors main
+        run: |
+          git fetch origin main next --tags
+          RUN_SHA=$(git rev-parse HEAD)
+          MAIN_SHA=$(git rev-parse origin/main)
+          NEXT_SHA=$(git rev-parse origin/next)
+          if [ "$RUN_SHA" != "$MAIN_SHA" ]; then
+            echo "Next must mirror main before tagging."
+            echo "workflow=$RUN_SHA"
+            echo "main=$MAIN_SHA"
+            exit 1
+          fi
+          if [ "$NEXT_SHA" != "$MAIN_SHA" ]; then
+            echo "Next must mirror main before tagging."
+            echo "next=$NEXT_SHA"
+            echo "main=$MAIN_SHA"
+            exit 1
+          fi
+      - name: Read version
+        id: version
+        run: python scripts/release_read_project_version.py --output "$GITHUB_OUTPUT"
+      - name: Create test tag if missing
+        id: tag
+        run: |
+          STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+          TAG="test-v${{ steps.version.outputs.version }}+${STAMP}"
+          TARGET="$(git rev-parse origin/next)"
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "Tag already exists: $TAG"
+            echo "tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Test release $TAG" "$TARGET"
+          git push origin "refs/tags/$TAG"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+      - name: Write tag artifact
+        if: steps.tag.outputs.tag != ''
+        run: echo "${{ steps.tag.outputs.tag }}" > tag.txt
+      - name: Upload tag artifact
+        if: steps.tag.outputs.tag != ''
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: auto-test-tag
+          path: tag.txt

{gabion-0.1.0 → gabion-0.1.5}/.github/workflows/ci.yml

@@ -4,9 +4,6 @@ on:
   push:
     branches:
       - stage
-  pull_request:
-    branches:
-      - main
   workflow_dispatch:
 
 permissions:
@@ -26,14 +23,18 @@ jobs:
         uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8
       - name: Install toolchain
         run: mise install
-      - name: Install package
-        run: mise exec -- python -m pip install -e .
-      - name: Install test deps
-        run: mise exec -- python -m pip install pytest
-      - name: Policy check (workflows)
+      - name: Create venv
         run: |
-          mise exec -- python -m pip install pyyaml
-          mise exec -- python scripts/policy_check.py --workflows
+          mise exec -- python -m venv .venv
+          echo "VIRTUAL_ENV=$PWD/.venv" >> $GITHUB_ENV
+          echo "$PWD/.venv/bin" >> $GITHUB_PATH
+      - name: Install dependencies (locked)
+        run: |
+          .venv/bin/python -m pip install --upgrade pip uv
+          .venv/bin/uv pip sync requirements.lock
+          .venv/bin/uv pip install -e .
+      - name: Policy check (workflows)
+        run: .venv/bin/python scripts/policy_check.py --workflows
       - name: Policy check (posture)
         if: github.event_name == 'push'
         env:
@@ -43,15 +44,25 @@ jobs:
             echo "POLICY_GITHUB_TOKEN not set; skipping posture check."
             exit 0
           fi
-          mise exec -- python scripts/policy_check.py --posture
+          .venv/bin/python scripts/policy_check.py --posture
       - name: Dataflow audit
-        run: mise exec -- python -m gabion check
+        run: |
+          mkdir -p artifacts/audit_reports
+          .venv/bin/python -m gabion check \
+            --report artifacts/audit_reports/dataflow_report.md \
+            --baseline baselines/dataflow_baseline.txt \
+            || (cat artifacts/audit_reports/dataflow_report.md; exit 1)
       - name: Docflow audit
-        run: mise exec -- python scripts/docflow_audit.py --root . --fail-on-violations
+        run: .venv/bin/python scripts/docflow_audit.py --root . --fail-on-violations
       - name: Tests
         run: |
           mkdir -p artifacts/test_runs
-          mise exec -- python -m pytest \
+          .venv/bin/python -m pytest \
+            --cov=src/gabion \
+            --cov-report=term-missing \
+            --cov-report=xml:artifacts/test_runs/coverage.xml \
+            --cov-report=html:artifacts/test_runs/htmlcov \
+            --cov-fail-under=100 \
             --junitxml artifacts/test_runs/junit.xml \
             --log-file artifacts/test_runs/pytest.log \
             --log-file-level=INFO
@@ -61,3 +72,9 @@ jobs:
         with:
           name: test-runs
           path: artifacts/test_runs
+      - name: Upload dataflow report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: dataflow-report
+          path: artifacts/audit_reports/dataflow_report.md

gabion-0.1.5/.github/workflows/mirror-next.yml

@@ -0,0 +1,32 @@
+name: mirror-next
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.actor == github.repository_owner
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+      - name: Mirror main to next
+        run: |
+          git fetch origin main next
+          HEAD_SHA=$(git rev-parse HEAD)
+          MAIN_SHA=$(git rev-parse origin/main)
+          if [ "$HEAD_SHA" != "$MAIN_SHA" ]; then
+            echo "Mirror blocked: workflow SHA must equal current main."
+            echo "workflow=$HEAD_SHA"
+            echo "main=$MAIN_SHA"
+            exit 1
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git push --force-with-lease origin "$HEAD_SHA":refs/heads/next

{gabion-0.1.0 → gabion-0.1.5}/.github/workflows/pr-dataflow-grammar.yml

@@ -2,11 +2,8 @@ name: pr-dataflow-grammar
 
 on:
   pull_request:
-    paths:
-      - "scripts/**"
-      - "src/**"
-      - "gabion.toml"
-      - ".github/workflows/pr-dataflow-grammar.yml"
+    branches:
+      - main
 
 permissions:
   contents: read
@@ -15,6 +12,7 @@ jobs:
   dataflow-grammar:
     runs-on: ubuntu-latest
     permissions:
+      actions: read
       contents: read
       pull-requests: write
     env:
@@ -26,6 +24,66 @@ jobs:
         uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8
       - name: Install toolchain
         run: mise install
+      - name: Verify stage CI succeeded for this SHA
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import json
+          import os
+          import time
+          import urllib.request
+
+          token = os.environ["GITHUB_TOKEN"]
+          repo = os.environ["REPO"]
+          sha = os.environ["SHA"]
+          deadline = time.time() + 20 * 60
+          url = (
+              f"https://api.github.com/repos/{repo}/actions/workflows/ci.yml/runs"
+              f"?branch=stage&per_page=50"
+          )
+
+          while True:
+              req = urllib.request.Request(
+                  url,
+                  headers={
+                      "Authorization": f"Bearer {token}",
+                      "Accept": "application/vnd.github+json",
+                  },
+              )
+              with urllib.request.urlopen(req) as resp:
+                  payload = json.loads(resp.read().decode("utf-8"))
+
+              runs = payload.get("workflow_runs", [])
+              match = next((r for r in runs if r.get("head_sha") == sha), None)
+              if match is None:
+                  if time.time() > deadline:
+                      raise SystemExit(
+                          f"Stage CI has not run for {sha}. Push to stage and wait for CI."
+                      )
+                  time.sleep(15)
+                  continue
+
+              status = match.get("status")
+              if status != "completed":
+                  if time.time() > deadline:
+                      raise SystemExit(
+                          f"Stage CI for {sha} not complete (status={status})."
+                      )
+                  time.sleep(15)
+                  continue
+
+              conclusion = match.get("conclusion")
+              if conclusion != "success":
+                  raise SystemExit(
+                      f"Stage CI for {sha} not successful (conclusion={conclusion})."
+                  )
+              print(f"Stage CI OK for {sha}.")
+              break
+          PY
       - name: Install package
         run: mise exec -- python -m pip install -e .
       - name: Render dataflow grammar report

gabion-0.1.5/.github/workflows/promote-release.yml

@@ -0,0 +1,64 @@
+name: promote-release
+
+on:
+  workflow_run:
+    workflows: ["release-testpypi"]
+    types: [completed]
+
+permissions:
+  contents: write
+  actions: read
+
+jobs:
+  promote:
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      (github.event.workflow_run.actor.login == github.repository_owner ||
+        github.event.workflow_run.actor.login == 'github-actions[bot]')
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha }}
+      - name: Download test tag artifact
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: release-testpypi-tag
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path: artifacts/release-testpypi
+      - name: Promote next to release
+        run: |
+          git fetch origin main next release --tags
+          TAG=""
+          TAG_FILE=""
+          if [ -d artifacts/release-testpypi ]; then
+            TAG_FILE="$(find artifacts/release-testpypi -name tag.txt | head -n 1 || true)"
+          fi
+          if [ -n "$TAG_FILE" ] && [ -f "$TAG_FILE" ]; then
+            TAG="$(cat "$TAG_FILE")"
+          elif [[ "${{ github.event.workflow_run.head_branch }}" == test-v* ]]; then
+            TAG="${{ github.event.workflow_run.head_branch }}"
+          fi
+          if [ -z "$TAG" ]; then
+            echo "Missing test tag for promotion."
+            exit 1
+          fi
+          HEAD_SHA=$(git rev-parse HEAD)
+          NEXT_SHA=$(git rev-parse origin/next)
+          TAG_SHA=$(git rev-parse "refs/tags/$TAG^{commit}")
+          if [ "$HEAD_SHA" != "$TAG_SHA" ]; then
+            echo "Workflow head sha must match tag."
+            exit 1
+          fi
+          if [ "$NEXT_SHA" != "$HEAD_SHA" ]; then
+            echo "Next must mirror tested commit before promoting release."
+            echo "next=$NEXT_SHA"
+            echo "tested=$HEAD_SHA"
+            exit 1
+          fi
+          git merge-base --is-ancestor "$HEAD_SHA" origin/main
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git push --force-with-lease origin "$HEAD_SHA":refs/heads/release

gabion-0.1.5/.github/workflows/release-pypi.yml

@@ -0,0 +1,89 @@
+name: release-pypi
+on:
+  push:
+    tags:
+      - "v*"
+      - "!test-v*"
+  workflow_run:
+    workflows: ["release-tag"]
+    types: [completed]
+permissions:
+  contents: read
+  actions: read
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    if: >
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      (github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success' &&
+        (github.event.workflow_run.actor.login == github.repository_owner ||
+          github.event.workflow_run.actor.login == 'github-actions[bot]'))
+    environment: pypi
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+      - name: Download release tag artifact
+        if: github.event_name == 'workflow_run'
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: release-pypi-tag
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path: artifacts/release-pypi
+      - name: Resolve release tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "push" ]; then
+            echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ ! -f artifacts/release-pypi/tag.txt ]; then
+            echo "No tag artifact found; skipping."
+            echo "tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          TAG="$(cat artifacts/release-pypi/tag.txt)"
+          if [ -z "$TAG" ]; then
+            echo "Empty tag; skipping."
+            echo "tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+      - name: Persist release tag
+        if: steps.tag.outputs.tag != ''
+        run: |
+          mkdir -p artifacts/release-pypi
+          echo "${{ steps.tag.outputs.tag }}" > artifacts/release-pypi/tag.txt
+      - name: Upload release tag artifact
+        if: steps.tag.outputs.tag != ''
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: release-pypi-tag
+          path: artifacts/release-pypi/tag.txt
+      - name: Verify release tag provenance + version
+        if: steps.tag.outputs.tag != ''
+        run: python scripts/release_verify_pypi_tag.py --tag "${{ steps.tag.outputs.tag }}"
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        if: steps.tag.outputs.tag != ''
+        with:
+          python-version: "3.11"
+      - name: Build
+        if: steps.tag.outputs.tag != ''
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+          python -m build
+      - name: Verify dist metadata
+        if: steps.tag.outputs.tag != ''
+        run: |
+          python -m pip install --upgrade twine pkginfo
+          python -m twine check dist/*
+      - name: Publish to PyPI
+        if: steps.tag.outputs.tag != ''
+        uses: pypa/gh-action-pypi-publish@03f86fee9ac21f854951f5c6e2a02c2a1324aec7
+        with:
+          verify-metadata: false

gabion-0.1.5/.github/workflows/release-tag.yml

@@ -0,0 +1,30 @@
+name: release-tag
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to create (vX.Y.Z or test-vX.Y.Z)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    if: (github.ref == 'refs/heads/release' || github.ref == 'refs/heads/next') && github.actor == github.repository_owner
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+      - name: Create and push tag
+        run: python scripts/release_tag.py --tag "${{ inputs.tag }}"
+      - name: Write release tag artifact
+        run: echo "${{ inputs.tag }}" > tag.txt
+      - name: Upload release tag artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: release-pypi-tag
+          path: tag.txt

gabion-0.1.5/.github/workflows/release-testpypi.yml

@@ -0,0 +1,92 @@
+name: release-testpypi
+on:
+  push:
+    tags:
+      - "test-v*"
+  workflow_run:
+    workflows: ["auto-test-tag"]
+    types: [completed]
+permissions:
+  contents: read
+  actions: read
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    if: >
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/test-v')) ||
+      (github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success' &&
+        (github.event.workflow_run.actor.login == github.repository_owner ||
+          github.event.workflow_run.actor.login == 'github-actions[bot]'))
+    environment: testpypi
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+      - name: Download tag artifact
+        if: github.event_name == 'workflow_run'
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: auto-test-tag
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path: artifacts/auto-test-tag
+      - name: Resolve test tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "push" ]; then
+            echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ ! -f artifacts/auto-test-tag/tag.txt ]; then
+            echo "No tag artifact found; skipping."
+            echo "tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          TAG="$(cat artifacts/auto-test-tag/tag.txt)"
+          if [ -z "$TAG" ]; then
+            echo "Empty tag; skipping."
+            echo "tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+      - name: Persist test tag
+        if: steps.tag.outputs.tag != ''
+        run: |
+          mkdir -p artifacts/release-testpypi
+          echo "${{ steps.tag.outputs.tag }}" > artifacts/release-testpypi/tag.txt
+      - name: Upload test tag artifact
+        if: steps.tag.outputs.tag != ''
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: release-testpypi-tag
+          path: artifacts/release-testpypi/tag.txt
+      - name: Ensure tag is on main/next
+        if: steps.tag.outputs.tag != ''
+        run: python scripts/release_verify_test_tag.py --tag "${{ steps.tag.outputs.tag }}"
+      - name: Set version from test tag
+        if: steps.tag.outputs.tag != ''
+        run: python scripts/release_set_test_version.py --tag "${{ steps.tag.outputs.tag }}"
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        if: steps.tag.outputs.tag != ''
+        with:
+          python-version: "3.11"
+      - name: Build
+        if: steps.tag.outputs.tag != ''
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+          python -m build
+      - name: Verify dist metadata
+        if: steps.tag.outputs.tag != ''
+        run: |
+          python -m pip install --upgrade twine pkginfo
+          python -m twine check dist/*
+      - name: Publish to TestPyPI
+        if: steps.tag.outputs.tag != ''
+        uses: pypa/gh-action-pypi-publish@03f86fee9ac21f854951f5c6e2a02c2a1324aec7
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          verify-metadata: false

{gabion-0.1.0 → gabion-0.1.5}/.gitignore

@@ -7,5 +7,6 @@ dist/
 venv/
 .env
 .pytest_cache/
+.coverage
 artifacts/*
 !artifacts/.gitkeep

{gabion-0.1.0 → gabion-0.1.5}/AGENTS.md

@@ -1,5 +1,5 @@
 ---
-doc_revision: 9
+doc_revision: 12
 reader_reintern: "Reader-only: re-intern if doc_revision changed since you last read this doc."
 doc_id: agents
 doc_role: agent
@@ -13,6 +13,11 @@ doc_requires:
   - CONTRIBUTING.md
   - POLICY_SEED.md
   - glossary.md
+doc_reviewed_as_of:
+  README.md: 58
+  CONTRIBUTING.md: 69
+  POLICY_SEED.md: 28
+  glossary.md: 13
 doc_change_protocol: "POLICY_SEED.md §6"
 doc_invariants:
   - read_policy_glossary_first
@@ -62,5 +67,6 @@ Semantic correctness is governed by `glossary.md` (co-equal contract).
 ## Doc hygiene
 - Markdown docs include a YAML front-matter block with `doc_revision`.
 - Bump `doc_revision` for conceptual changes.
+- Record convergence in `doc_reviewed_as_of` (must match dependency revisions).
 
 If unsure, prefer refusal over unsafe compliance.

{gabion-0.1.0 → gabion-0.1.5}/CONTRIBUTING.md

@@ -1,5 +1,5 @@
 ---
-doc_revision: 55
+doc_revision: 69
 reader_reintern: "Reader-only: re-intern if doc_revision changed since you last read this doc."
 doc_id: contributing
 doc_role: guide
@@ -14,6 +14,13 @@ doc_requires:
   - AGENTS.md
   - POLICY_SEED.md
   - glossary.md
+  - docs/coverage_semantics.md
+doc_reviewed_as_of:
+  README.md: 58
+  AGENTS.md: 12
+  POLICY_SEED.md: 28
+  glossary.md: 13
+  docs/coverage_semantics.md: 6
 doc_change_protocol: "POLICY_SEED.md §6"
 doc_invariants:
   - policy_glossary_handshake
@@ -66,9 +73,16 @@ Tier-3 bundles must be documented with `# dataflow-bundle:` or reified.
 
 ## Branching model (normative)
 - Routine work goes to `stage`; CI runs on every `stage` push and must be green.
+- CI does not run on `main` pushes; PRs to `main` are for review and status checks.
 - `main` is protected and receives changes via PRs from `stage`.
-- Merges to `main` are regular merge commits (no squash).
+- Merges to `main` are regular merge commits (no squash or rebase).
 - `stage` accumulates changes and may include merge commits from `main`.
+- `next` mirrors `main` (no unique commits) and is updated after `main` merges.
+- `release` mirrors `next` (no unique commits) and is updated only after `test-v*` succeeds.
+- Test release tags are created via the `release-tag` workflow on `next`.
+- Release tags are created via the `release-tag` workflow on `release` (no manual tags).
+- `next` and `release` are automation-only branches. Human pushes are forbidden.
+  The `mirror-next` and `promote-release` workflows update them.
 
 ## Current analysis coverage (non-binding)
 These describe current coverage so contributors keep changes aligned:
@@ -176,6 +190,19 @@ To bypass hooks for a one-off command:
 GABION_SKIP_HOOKS=1 git commit
 ```
 
+## Locked dependencies
+Dependencies are locked in `requirements.lock` (generated via `uv`).
+Install the locked set and the editable package:
+```
+mise exec -- uv pip sync requirements.lock
+mise exec -- uv pip install -e .
+```
+CI creates an explicit venv and installs the lock into it.
+Regenerate the lockfile (after updating dependencies):
+```
+uv pip compile pyproject.toml --extra dev -o requirements.lock
+```
+
 ## Editor integration (optional)
 The VS Code extension stub lives in `extensions/vscode` and launches the
 Gabion LSP server over stdio. It is a thin wrapper only.
@@ -189,15 +216,16 @@ mise exec -- python scripts/lsp_smoke_test.py --root .
 LSP smoke test (pytest) requires `pygls` to be installed. It will be skipped
 automatically if the dependency is missing.
 
-Install pytest (once):
+Run tests:
 ```
-mise exec -- python -m pip install pytest
+mise exec -- pytest
 ```
 
-Run tests:
+Run coverage (advisory):
 ```
-mise exec -- pytest
+mise exec -- python -m pytest --cov=src/gabion --cov-report=term-missing
 ```
+Coverage meaning is defined in `docs/coverage_semantics.md`.
 
 Run tests with durable logs:
 ```