logseq-matryca-parser 1.8.0__tar.gz → 1.8.2__tar.gz

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/.github/dependabot.yml

@@ -5,9 +5,13 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
 
   # Keep GitHub Actions current (reads .github/workflows/ci.yml).
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7

logseq_matryca_parser-1.8.2/.github/workflows/ci.yml

@@ -0,0 +1,150 @@
+name: Logos Protocol CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality (Python 3.12)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout without credentials
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.11.7"
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync locked dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Lint
+        run: make lint
+
+      - name: Type check
+        run: make check
+
+      - name: Validate repository policy
+        run: make vendor-name-check
+
+      - name: Validate documentation
+        run: make docs-check
+
+      - name: Verify checkout unchanged
+        run: make verify-clean
+
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-15, windows-2025]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout without credentials
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.11.7"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Sync locked dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Run complete test suite
+        run: >-
+          uv run pytest
+          --cov=src/logseq_matryca_parser
+          --cov-report=term-missing
+          --cov-fail-under=80
+          -v tests/
+
+  dependency-audit:
+    name: Production dependency audit
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Checkout without credentials
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.11.7"
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync locked dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Export every production dependency
+        run: >-
+          uv export
+          --all-extras
+          --no-dev
+          --no-emit-workspace
+          --output-file "${{ runner.temp }}/requirements-audit.txt"
+
+      - name: Audit exported dependencies
+        run: uv run pip-audit --no-deps --disable-pip -r "${{ runner.temp }}/requirements-audit.txt"
+
+  package-contract:
+    name: Wheel and source distribution contract
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Checkout without credentials
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.11.7"
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync locked dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Build wheel and source distribution
+        run: uv build --out-dir dist-contract
+
+      - name: Verify wheel metadata and PEP 561 marker
+        run: uv run python scripts/check_wheel_contract.py dist-contract/*.whl
+
+      - name: Validate distribution metadata
+        run: uvx --from twine==6.2.0 twine check dist-contract/*
+
+      - name: Verify downstream typing from the wheel
+        run: |
+          uv venv "${{ runner.temp }}/typing-venv"
+          uv pip install --python "${{ runner.temp }}/typing-venv/bin/python" mypy==1.20.2 dist-contract/*.whl
+          cd "${{ runner.temp }}"
+          "${{ runner.temp }}/typing-venv/bin/python" -m mypy --strict "${{ github.workspace }}/tests/typing_samples/public_api.py"

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/.github/workflows/daily-metrics.yml

@@ -19,16 +19,19 @@ env:
 jobs:
   save-metrics:
     if: github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     permissions:
       contents: write
     steps:
       - name: Checkout trusted default branch
+        # zizmor: ignore[artipacked] -- this trusted main-only job must push metrics.
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: main
           fetch-depth: 0
           token: ${{ github.token }}
+          persist-credentials: true
 
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0

logseq_matryca_parser-1.8.2/.github/workflows/dependency-hygiene.yml

@@ -0,0 +1,37 @@
+name: Dependency Hygiene Audit
+
+on:
+  schedule:
+    - cron: "23 4 1 * *"
+  workflow_dispatch:
+
+concurrency:
+  group: dependency-hygiene-${{ github.repository }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  deptry:
+    name: Check dependency declarations
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - name: Checkout without credentials
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned uv without a shared cache
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.11.7"
+          python-version: "3.12"
+          enable-cache: false
+
+      - name: Sync locked project environment
+        run: uv sync --locked --all-extras
+
+      - name: Check dependency declarations
+        run: uv run --with deptry==0.25.1 deptry . --github-output

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/.github/workflows/dependency-review.yml

@@ -13,7 +13,8 @@ concurrency:
 jobs:
   dependency-review:
     name: Block newly introduced vulnerable dependencies
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     steps:
       - name: Checkout dependency manifests
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/.github/workflows/parser-adversarial.yml

@@ -14,21 +14,24 @@ permissions:
 
 jobs:
   bounded-generated-assurance:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 10
 
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
+          version: "0.11.7"
           python-version: "3.12"
           enable-cache: true
 
       - name: Sync dependencies
-        run: uv sync --all-extras
+        run: uv sync --locked --all-extras
 
       - name: Run bounded broad profile
         run: uv run python -m tests.parser_assurance.adversarial --profile broad

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/.github/workflows/pypi_publish.yml

@@ -15,7 +15,8 @@ permissions:
 jobs:
   pre-flight:
     name: Pre-flight checks (Python ${{ matrix.python-version }})
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -23,21 +24,23 @@ jobs:
     steps:
       - name: Checkout exact tag
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version: "0.11.7"
           python-version: ${{ matrix.python-version }}
-          enable-cache: true
+          enable-cache: false
 
       - name: Sync locked dependencies
         run: uv sync --locked --all-extras
 
       - name: Audit production dependencies
         run: |
-          uv export --no-dev --no-emit-workspace --no-hashes -o "${{ runner.temp }}/requirements-audit.txt"
-          uv run pip-audit -r "${{ runner.temp }}/requirements-audit.txt"
+          uv export --all-extras --no-dev --no-emit-workspace -o "${{ runner.temp }}/requirements-audit.txt"
+          uv run pip-audit --no-deps --disable-pip -r "${{ runner.temp }}/requirements-audit.txt"
 
       - name: Run full quality gate
         run: make all
@@ -48,7 +51,8 @@ jobs:
   build:
     name: Build immutable release bundle
     needs: pre-flight
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
     permissions:
       contents: read
       id-token: write
@@ -58,13 +62,14 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version: "0.11.7"
           python-version: "3.12"
-          enable-cache: true
+          enable-cache: false
 
       - name: Sync locked dependencies
         run: uv sync --locked --all-extras
@@ -115,7 +120,7 @@ jobs:
             | sha256sum --check -
 
       - name: Attest release artifact provenance
-        uses: actions/attest@508db95dd578ae2727ebd6217d5ba78e4fbda05d # v4.2.1
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-path: |
             release-bundle/dist/*
@@ -124,7 +129,7 @@ jobs:
             release-bundle/SHA256SUMS
 
       - name: Bind the production SBOM to the distributions
-        uses: actions/attest@508db95dd578ae2727ebd6217d5ba78e4fbda05d # v4.2.1
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-path: release-bundle/dist/*
           sbom-path: release-bundle/SBOM.cdx.json
@@ -154,7 +159,8 @@ jobs:
   publish:
     name: Publish exact distributions to PyPI
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     environment:
       name: pypi
       url: https://pypi.org/p/logseq-matryca-parser
@@ -182,7 +188,8 @@ jobs:
   github-release:
     name: Publish GitHub Release from exact distributions
     needs: publish
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     permissions:
       contents: write
     steps:
@@ -199,15 +206,16 @@ jobs:
             | sha256sum --check -
 
       - name: Create GitHub Release with verified artifacts
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
-        with:
-          tag_name: ${{ github.ref_name }}
-          name: ${{ github.ref_name }}
-          body_path: release-bundle/RELEASE_NOTES.md
-          files: |
-            release-bundle/dist/*
-            release-bundle/SBOM.cdx.json
-            release-bundle/DEPENDENCY_LICENSES.json
-            release-bundle/SHA256SUMS
-          generate_release_notes: false
-          make_latest: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            release-bundle/dist/* \
+            release-bundle/SBOM.cdx.json \
+            release-bundle/DEPENDENCY_LICENSES.json \
+            release-bundle/SHA256SUMS \
+            --repo "$GITHUB_REPOSITORY" \
+            --verify-tag \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file release-bundle/RELEASE_NOTES.md \
+            --latest

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/.github/workflows/scorecard.yml

@@ -11,7 +11,8 @@ permissions: read-all
 jobs:
   analysis:
     name: Scorecard analysis
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     permissions:
       contents: read
       security-events: write
@@ -38,6 +39,6 @@ jobs:
           if-no-files-found: error
 
       - name: Publish findings to code scanning
-        uses: github/codeql-action/upload-sarif@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4.37.4
+        uses: github/codeql-action/upload-sarif@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           sarif_file: results.sarif

logseq_matryca_parser-1.8.2/.github/workflows/workflow-analysis.yml

@@ -0,0 +1,59 @@
+name: Workflow Static Analysis
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - ".github/workflows/**"
+      - ".github/dependabot.yml"
+      - ".pre-commit-config.yaml"
+      - "zizmor.yml"
+  pull_request:
+    paths:
+      - ".github/workflows/**"
+      - ".github/dependabot.yml"
+      - ".pre-commit-config.yaml"
+      - "zizmor.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  workflow-analysis:
+    name: Validate workflow semantics and security
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - name: Checkout without credentials
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned uv without a shared cache
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.11.7"
+          python-version: "3.12"
+          enable-cache: false
+
+      - name: Install checksum-verified actionlint 1.7.12
+        run: |
+          archive="${RUNNER_TEMP}/actionlint_1.7.12_linux_amd64.tar.gz"
+          curl --proto '=https' --tlsv1.2 --fail --location --silent --show-error \
+            --output "$archive" \
+            https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz
+          echo "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8  $archive" \
+            | sha256sum --check --strict
+          tar --extract --gzip --file "$archive" --directory "$RUNNER_TEMP" actionlint
+
+      - name: Validate workflow semantics
+        run: |
+          "$RUNNER_TEMP/actionlint" -color
+
+      - name: Audit workflow security
+        run: uvx --from zizmor==1.29.0 zizmor --strict-collection --format=github .

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/.pre-commit-config.yaml

@@ -1,4 +1,8 @@
 repos:
+-   repo: https://github.com/rhysd/actionlint
+    rev: 914e7df21a07ef503a81201c76d2b11c789d3fca  # v1.7.12
+    hooks:
+    -   id: actionlint
 -   repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.12
     hooks:

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/AGENTS.md

@@ -31,6 +31,8 @@ backlinks, exports, visualizations, and AI chunks are derived views.
   [`docs/reference/API_STABILITY.md`](docs/reference/API_STABILITY.md).
 - For architecture and ownership boundaries, use
   [`docs/CLEAN_CODE_ARCHITECTURE.md`](docs/CLEAN_CODE_ARCHITECTURE.md).
+- For pull-request, scheduled, settings-managed, and release checks, use
+  [`docs/CI_ASSURANCE.md`](docs/CI_ASSURANCE.md).
 - For the maintained machine-readable knowledge map, use
   [`docs/index.md`](docs/index.md).
 - For historical release capabilities, use
@@ -66,7 +68,7 @@ Protocol integrations remain optional and deferred under
 ## Repository working contract
 
 ```bash
-uv sync --all-extras
+uv sync --locked --all-extras
 make all
 make vendor-name-check
 ```

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.2] - 2026-08-30
+
+### Changed
+
+- **Native cross-platform GitHub assurance** — replace the public-repository
+  receipt-routing experiment with SHA-pinned GitHub-hosted quality, packaging,
+  dependency, CodeQL, Linux, macOS, and Windows checks. Local maintainer
+  guidance now treats hosted Actions as the authoritative public CI path (#194).
+- **Cookbook guidance** — add corrected broken-block-reference and LENS
+  visualization recipes, including their CLI outcome and optional dependency
+  boundaries (#195).
+- **Graph loader path-type acceptance** — `LogseqGraph.load_directory` accepts
+  `graph_path` as either `Path` or `str`, normalizes with
+  `Path(graph_path).expanduser().resolve()`, and preserves strict-mode defaults
+  (#197).
+
+### Fixed
+
+- **Windows assurance portability** — open local-assurance inputs in binary
+  mode so CRLF files retain their measured byte length, use platform-neutral
+  byte and path fixtures, preserve POSIX permission assertions only where the
+  operating system provides those semantics, and fold CLI diagnostic
+  identifiers instead of replacing their final characters with an ellipsis
+  (#194).
+- **Optional AI dependency guidance** — use one consistent message when AI
+  export dependencies are unavailable: `uv sync --extra ai` (#196).
+
+## [1.8.1] - 2026-08-25
+
+### Security
+
+- **Stable NLTK supply-chain source (#186)** — the optional AI and development
+  dependency graph now constrains NLTK to the patched PyPI release line at
+  `>=3.10.3`, replacing the mutable `v3.10.0-rc1` VCS tag declaration. The
+  lightweight base installation remains unchanged.
+
+### Added
+
+- **Reproducible runtime evidence foundation (#111)** — add a deterministic,
+  offline synthetic-vault generator and a source-free measurement runner for
+  parser, cold-load, reload, search, and optional SYNAPSE scenarios. The runner
+  records semantic validity and bounded runtime observations outside the
+  default CI gate. It establishes a measurement protocol, not vault-scale
+  budgets or a universal performance claim; #111 remains open.
+
+### Changed
+
+- **Private lexical-state extraction (#108 M9)** — move YAML, code, query,
+  drawer, frontmatter, and block-property eligibility transitions into a
+  private standard-library-only state object. `StackMachineParser.parse()`
+  retains line classification, reduction, AST construction, identities,
+  semantic enrichment, and public behavior. The broader #108 epic remains
+  open.
+
+### Fixed
+
+- **Coherent incremental graph mutations (#103)** — reloads, deletions, and
+  filesystem moves now publish page routing, node and backlink registries, and
+  collision diagnostics as one coherent graph snapshot. Conflicting title or
+  alias participants can recover deterministically, bounded writes serialize
+  their source read and reload transaction, and watcher callbacks observe the
+  published state in order. Stable public APIs remain unchanged.
+- **Pathological nested outlines (#87)** — parse and file-entrypoint traversal
+  now remain iterative for a 1024-level valid outline, while parser-owned tree
+  construction avoids quadratic immutable-ancestor copies. Derived metadata is
+  refreshed once after tree construction instead of repeatedly across mutable
+  soft-break ancestors, and parser registries are rebuilt from the exact final
+  nodes returned by parse and file entry points. Strict reference validation is
+  confined to the current page. Tree order, parent and left relationships,
+  source paths, semantic snapshots, and the stable public API are preserved.
+  Deterministic tests bound refresh growth; local timing observations remain
+  diagnostic only and do not add a vault-scale performance claim.
+- **Bounded local-assurance timeout cleanup (#188)** — a timed-out isolated
+  assurance worker is terminated and joined before its result queue is closed,
+  preventing queue-thread cleanup from extending the bounded failure path.
+
+### Tests
+
+- Expand privacy-safe local-assurance regression coverage across traversal and
+  byte limits, guarded reads, parser aggregation, report validation, denied
+  network entry points, worker lifecycle, and failure cleanup without exposing
+  vault content or weakening the repository coverage floor.
+
 ## [1.8.0] - 2026-08-20
 
 ### Tests

{logseq_matryca_parser-1.8.0 → logseq_matryca_parser-1.8.2}/CONTRIBUTING.md

@@ -17,8 +17,9 @@ User-facing behavior is documented in:
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — LOGOS, SYNAPSE, `LogseqGraph`, agents, and data flow
 - [`docs/internal/LOCAL_CODE_STUDY.md`](docs/internal/LOCAL_CODE_STUDY.md) — maintainer local code audit runbook (not for public issues/CHANGELOG)
 - [`docs/logseq_ast_primer.md`](docs/logseq_ast_primer.md) — Logseq Spatial Markdown domain rules
-- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.8.0**) and **Unreleased** changes (Keep a Changelog)
+- [`CHANGELOG.md`](CHANGELOG.md) — release candidate **1.8.2**, latest published release **1.8.1**, and **Unreleased** changes (Keep a Changelog)
 - [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) — version bump, tag, and PyPI publish checklist
+- [`docs/CI_ASSURANCE.md`](docs/CI_ASSURANCE.md) — pull-request, scheduled, settings-managed, and release checks
 - [`docs/CODEQL.md`](docs/CODEQL.md) — CodeQL default setup (no custom `codeql.yml`)
 - [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) — curated starter tasks for new contributors
 - [`docs/COOKBOOK.md`](docs/COOKBOOK.md) — integration recipes (Synapse, graph query, watcher)
@@ -80,7 +81,7 @@ New to the codebase? Start here:
 
 1. **Pick a task** from [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) (label: `good first issue` on GitHub).
 2. **Comment on the issue** so others know you are working on it.
-3. **Set up** with `uv sync --all-extras` and confirm `make all` is green on `main`.
+3. **Set up** with `uv sync --locked --all-extras` and confirm `make all` is green on `main`.
 4. **Branch** using `feat/…`, `test/…`, or `docs/…` naming (see workflow below).
 5. **Submit** one PR per issue, branched from `main` (`Fixes #123`).