logseq-matryca-parser 1.6.0__tar.gz → 1.7.0__tar.gz

{logseq_matryca_parser-1.6.0 → logseq_matryca_parser-1.7.0}/.cursorignore

@@ -1,5 +1,5 @@
 # .cursorignore
-# (Nota: Cursor ignora già automaticamente tutto ciò che è nel .gitignore)
+# Note: Cursor already ignores everything listed in .gitignore.
 
 # =========================
 # Python & Virtual Environments
@@ -27,10 +27,10 @@ build/
 *.egg-info/
 
 # =========================
-# Lockfiles (Letali per il Codebase Indexing)
+# Lockfiles (harmful to codebase indexing)
 # =========================
-# I lockfile devono stare su Git, ma l'IA non deve MAI leggerli,
-# sono solo un muro di versioni incomprensibili.
+# Lockfiles belong in Git, but the AI should never read them because they are
+# only a wall of dependency versions with no useful semantic context.
 poetry.lock
 uv.lock
 package-lock.json
@@ -38,36 +38,36 @@ yarn.lock
 pnpm-lock.yaml
 
 # =========================
-# Output AI e Report (Evitare loop di contesto)
+# AI Outputs and Reports (avoid context loops)
 # =========================
-# Se committi per sbaglio un output, non vogliamo che Cursor lo studi.
+# If an output is committed accidentally, keep it out of the code index.
 repomix-output.*
 output_langchain/
 mappa_cervello.html
 
 # =========================
-# Dati di Test e Fixtures Mock
+# Test Data and Mock Fixtures
 # =========================
-# Se hai dei file Markdown o JSON enormi che usi solo per testare il parser,
-# a Git servono, ma all'IA confondono solo le idee.
+# Large Markdown or JSON fixtures may belong in Git for parser tests, but they
+# should not consume indexing context.
 tests/fixtures/*.json
 tests/fixtures/*.edn
 tests/fixtures/*.md
 *.csv
 
 # =========================
-# Assets Vettoriali
+# Vector Assets
 # =========================
-# Le immagini PNG/JPG Cursor le ignora da solo, ma gli SVG sono file di testo!
-# Se l'IA legge un SVG, legge migliaia di coordinate matematiche inutili.
+# PNG and JPG files are ignored automatically, while SVG files are text and can
+# add thousands of irrelevant coordinate values to the index.
 *.svg
 
 # =========================
-# File di Configurazione Editor
+# Editor Configuration Files
 # =========================
 .vscode/
 .idea/
 .clinerules
 
-# Esclude lo storico delle metriche per preservare il contesto LLM
-metrics/history.json
+# Exclude historical metrics to preserve LLM context.
+metrics/history.json

{logseq_matryca_parser-1.6.0 → logseq_matryca_parser-1.7.0}/.github/dependabot.yml

@@ -1,12 +1,12 @@
 version: 2
 updates:
-  # Mantiene aggiornate le dipendenze Python (legge il pyproject.toml)
+  # Keep Python dependencies current (reads pyproject.toml).
   - package-ecosystem: "pip"
     directory: "/"
     schedule:
       interval: "weekly"
 
-  # Mantiene aggiornate le GitHub Actions (legge il tuo .github/workflows/ci.yml)
+  # Keep GitHub Actions current (reads .github/workflows/ci.yml).
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

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

@@ -0,0 +1,83 @@
+name: Logos Protocol CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.12", "3.13" ]
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+
+    - name: Sync dependencies
+      run: uv sync --all-extras
+
+    - name: Audit 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"
+
+    - name: Lint
+      run: make lint
+
+    - name: Type check
+      run: make check
+
+    - name: Test
+      run: make test
+
+    - name: Documentation check (non-mutating)
+      run: make docs-check
+
+    - name: Verify checkout unchanged
+      run: make verify-clean
+
+  package-contract:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        python-version: "3.12"
+        enable-cache: true
+
+    - 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: Verify 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 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.6.0 → logseq_matryca_parser-1.7.0}/.github/workflows/daily-metrics.yml

@@ -2,8 +2,8 @@ name: Daily Metrics Saver
 
 on:
   schedule:
-    - cron: '0 3 * * *' # Gira ogni giorno alle 03:00 UTC
-  workflow_dispatch: # Permette l'avvio manuale con un click
+    - cron: '0 3 * * *' # Runs daily at 03:00 UTC.
+  workflow_dispatch: # Allows one-click manual runs.
 
 concurrency:
   group: daily-metrics-${{ github.repository }}
@@ -13,7 +13,7 @@ permissions:
   contents: write
 
 env:
-  # Forza l'ambiente di esecuzione su Node.js 24 per prevenire i warning di deprecazione di giugno 2026
+  # Force the Node.js 24 runtime to prevent the June 2026 deprecation warnings.
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
@@ -21,12 +21,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.12'
 

logseq_matryca_parser-1.7.0/.github/workflows/pypi_publish.yml

@@ -0,0 +1,153 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  pre-flight:
+    name: Pre-flight checks (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout exact tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - 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"
+
+      - name: Run full quality gate
+        run: make all
+
+      - name: Verify checkout unchanged
+        run: make verify-clean
+
+  build:
+    name: Build immutable release bundle
+    needs: pre-flight
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout exact tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync locked dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Verify tag, source, runtime, and release notes
+        run: |
+          uv run python scripts/check_release_contract.py \
+            --tag "${GITHUB_REF_NAME}" \
+            --notes-out release-bundle/RELEASE_NOTES.md
+
+      - name: Build wheel and source distribution once
+        run: uv build --out-dir release-bundle/dist
+
+      - name: Verify wheel and package metadata
+        run: |
+          wheel_count=0
+          for wheel in release-bundle/dist/*.whl; do
+            uv run python scripts/check_wheel_contract.py "$wheel"
+            wheel_count=$((wheel_count + 1))
+          done
+          test "$wheel_count" -eq 1
+          uvx --from twine==6.2.0 twine check release-bundle/dist/*
+
+      - name: Record and verify distribution digests
+        working-directory: release-bundle
+        run: |
+          sha256sum dist/* > SHA256SUMS
+          sha256sum --check SHA256SUMS
+
+      - name: Upload immutable release bundle
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release-bundle-${{ github.ref_name }}
+          path: release-bundle/
+          if-no-files-found: error
+          retention-days: 30
+          compression-level: 0
+
+  publish:
+    name: Publish exact distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/logseq-matryca-parser
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download immutable release bundle
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-bundle-${{ github.ref_name }}
+          path: release-bundle
+
+      - name: Verify distribution digests
+        working-directory: release-bundle
+        run: sha256sum --check SHA256SUMS
+
+      - name: Publish package distributions with OIDC attestations
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          packages-dir: release-bundle/dist/
+
+  github-release:
+    name: Publish GitHub Release from exact distributions
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download immutable release bundle
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-bundle-${{ github.ref_name }}
+          path: release-bundle
+
+      - name: Verify distribution digests
+        working-directory: release-bundle
+        run: sha256sum --check SHA256SUMS
+
+      - name: Create GitHub Release with verified artifacts
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          body_path: release-bundle/RELEASE_NOTES.md
+          files: |
+            release-bundle/dist/*
+            release-bundle/SHA256SUMS
+          generate_release_notes: false
+          make_latest: true

logseq_matryca_parser-1.7.0/AGENTS.md

@@ -0,0 +1,26 @@
+# Audit code — maintainer intelligence
+
+Maintainers may use **audit code** (local graph-based static analysis) to understand call chains, blast radius, and import cycles before structural work. **Do not** name specific third-party indexer products anywhere in this repository (issues, PRs, CHANGELOG, public docs, or agent config).
+
+## Always do
+
+- Run **impact analysis** before editing hub symbols (`StackMachineParser._refresh_node`, `_expand_macros_and_embeds_impl`, `LogseqGraph.load_directory`, `invalidate_and_reload_page`).
+- Use **query** / **context** for cross-module flows instead of guessing from grep alone.
+- Run `check(cycles)` — expect **0** import cycles in `src/`.
+- Run `make all` (and `make vendor-name-check`) after behavior or documentation changes.
+
+## Never do
+
+- NEVER add vendor AST indexers to CI, Dockerfiles, or `pyproject.toml`.
+- NEVER ignore **HIGH** or **CRITICAL** impact warnings on parser/graph hubs without explicit user approval.
+- NEVER commit tool-specific cache directories — use `.git/info/exclude` locally (Ghost Tooling policy).
+
+## SSOT
+
+| Document | Purpose |
+|----------|---------|
+| [`docs/CLEAN_CODE_ARCHITECTURE.md`](docs/CLEAN_CODE_ARCHITECTURE.md) | Uncle Bob rings, SOLID, public graph APIs |
+| [`docs/internal/LOCAL_CODE_STUDY.md`](docs/internal/LOCAL_CODE_STUDY.md) | Maintainer audit-code runbook (generic MCP surface) |
+| [`docs/internal/STATIC_ANALYSIS_POLICY.md`](docs/internal/STATIC_ANALYSIS_POLICY.md) | Ghost Tooling policy |
+
+When the maintainer instructs you to use audit code tooling, follow their workflow — do not document product names in artifacts.

{logseq_matryca_parser-1.6.0 → logseq_matryca_parser-1.7.0}/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-08-08
+
+Minor release — structured diagnostics, deterministic title-collision handling,
+arbitrary-depth parser refreshes, typed public APIs, vault-bound writer safety,
+and a governed English documentation system. **No intentional breaking changes**
+to stable package exports or default CLI behavior.
+
+### Added
+
+- **Verified immutable release pipeline** — tag, source, runtime, and changelog
+  contracts now fail closed before packaging; Python 3.12/3.13 pre-flight runs
+  the full quality and dependency-audit gates; wheel and sdist are built once,
+  checked with Twine, checksummed, published to PyPI with OIDC attestations, and
+  attached byte-for-byte to the GitHub Release
+  ([#105](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/105)).
+
+- **Structured diagnostic foundation** — stable immutable `Diagnostic`,
+  `DiagnosticCode`, and `DiagnosticSeverity` exports; deterministic
+  `collect_graph_diagnostics()` for broken block references; vault-relative
+  path enforcement; and pure JSON CLI output through `scan --diagnostics-json`
+  ([#110](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/110)).
+- **Graph title-collision contract** — permissive loading now exposes stable
+  diagnostics for derived-title, frontmatter-title, and alias collisions while
+  preserving the existing deterministic winner and no-ghost invariants;
+  `strict_title_collisions=True` raises `PageTitleCollisionError`, and KINETIC
+  renders all findings with `scan --diagnostics`
+  ([#102](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/102)).
+- **Documentation system guide** — [`docs/DOCUMENTATION_SYSTEM.md`](docs/DOCUMENTATION_SYSTEM.md) explains source authority, maintained versus historical surfaces, metadata, freshness, validation, the Matryca Knowledge projection workflow, and the repository's documentation evolution.
+- **Synapse RAG example** — [`examples/run_synapse_rag.py`](examples/run_synapse_rag.py) demonstrates all four `SynapseAdapter` methods (`to_langchain_documents`, `to_llamaindex_nodes`, `to_context_enriched_chunks`, `_expand_macros_and_embeds`) plus table-driven embed expansion edge cases.
+- **Embed expansion edge-case tests** — `TestEmbedExpansionEdgeCases` in [`tests/test_synapse.py`](tests/test_synapse.py) covers cycles, missing targets, and happy-path for both `{{embed [[Page]]}}` and `{{embed ((uuid))}}` (closes [#71](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/71)).
+- **Contributor onboarding (wave 4)** — ten new Good First Issues (GFI-39…GFI-48) filed on GitHub ([#88](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/88)–[#97](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/97)); index updated in [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md).
+
+### Changed
+
+- **Immutable workflow dependencies** — all release and CI actions are pinned to
+  reviewed commit SHAs with readable release comments; the former independent
+  GitHub and PyPI tag workflows are consolidated into one ordered release graph.
+
+- **Federated documentation profile** — aligned the maintained bundle with Matryca Knowledge `origin/main` at `7a3ebd8`, separating OKF lifecycle from Matryca classification and recording authority, freshness, provenance, and the still-pending private registry activation.
+- **Ghost Tooling** — removed remaining vendor indexer blocks from `AGENTS.md` / `CLAUDE.md`; maintainer guidance now uses **audit code** terminology only.
+- **Repository language** — translated the historical audit reports, design references, Logseq Read skill, maintainer configuration comments, parser warning, demo labels, and optional SYNAPSE dependency errors into English; contributor guidance now makes English the repository default ([#69](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/69)).
+- **Documentation quality tranche** — added `scripts/check_documentation.py`, source `docs/maintained.toml`, and focused tests; wired the deterministic, non-mutating `docs-check` into `make all` and CI. This implements the source-side MKQ-3 gate; MKQ-4 remains pending until private `okf_entry_points` and projection activation pass against the merged source commit.
+
+### Fixed
+
+- **Vault-bound writer and asset reads** — headless child writes now reject
+  external/untracked/symlink-swapped targets, verify target identity before
+  replacement, preserve permission and ownership metadata, expose typed safe
+  diagnostics and configurable limits, and support unified-diff dry runs;
+  `file://` and asset symlink reads are confined to the graph
+  ([#106](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/106)).
+- **Deep parser refreshes** — immutable node updates now rebuild the complete
+  active branch to the root at arbitrary nesting depth, preserving soft breaks,
+  properties, fenced code, queries, list properties, ordering, identity, and
+  parent/left relationships ([#113](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/113)).
+- **LENS topology** — unresolved wikilinks no longer create phantom page nodes when visualization uses a loaded `LogseqGraph`; valid page aliases and tags remain visible ([#59](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/59)).
+
+### Security
+
+- **Artifact lineage** — PyPI publication must succeed before the GitHub Release
+  is created, and every consumer re-verifies the SHA-256 manifest for the exact
+  distributions produced by the single build job.
+
 ## [1.6.0] - 2026-07-02
 
 Minor release — Clean Architecture v1 structural slices (SRP/OCP), new public graph APIs, layer-boundary CI, and documentation SSOT. **No intentional breaking changes** to existing `matryca-parse` CLI behavior or stable package exports.

logseq_matryca_parser-1.7.0/CLAUDE.md

@@ -0,0 +1,26 @@
+# Audit code — maintainer intelligence
+
+Maintainers may use **audit code** (local graph-based static analysis) to understand call chains, blast radius, and import cycles before structural work. **Do not** name specific third-party indexer products anywhere in this repository (issues, PRs, CHANGELOG, public docs, or agent config).
+
+## Always do
+
+- Run **impact analysis** before editing hub symbols (`StackMachineParser._refresh_node`, `_expand_macros_and_embeds_impl`, `LogseqGraph.load_directory`, `invalidate_and_reload_page`).
+- Use **query** / **context** for cross-module flows instead of guessing from grep alone.
+- Run `check(cycles)` — expect **0** import cycles in `src/`.
+- Run `make all` (and `make vendor-name-check`) after behavior or documentation changes.
+
+## Never do
+
+- NEVER add vendor AST indexers to CI, Dockerfiles, or `pyproject.toml`.
+- NEVER ignore **HIGH** or **CRITICAL** impact warnings on parser/graph hubs without explicit user approval.
+- NEVER commit tool-specific cache directories — use `.git/info/exclude` locally (Ghost Tooling policy).
+
+## SSOT
+
+| Document | Purpose |
+|----------|---------|
+| [`docs/CLEAN_CODE_ARCHITECTURE.md`](docs/CLEAN_CODE_ARCHITECTURE.md) | Uncle Bob rings, SOLID, public graph APIs |
+| [`docs/internal/LOCAL_CODE_STUDY.md`](docs/internal/LOCAL_CODE_STUDY.md) | Maintainer audit-code runbook (generic MCP surface) |
+| [`docs/internal/STATIC_ANALYSIS_POLICY.md`](docs/internal/STATIC_ANALYSIS_POLICY.md) | Ghost Tooling policy |
+
+When the maintainer instructs you to use audit code tooling, follow their workflow — do not document product names in artifacts.

{logseq_matryca_parser-1.6.0 → logseq_matryca_parser-1.7.0}/CONTRIBUTING.md

@@ -17,18 +17,32 @@ 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.6.0**) and **Unreleased** changes (Keep a Changelog)
+- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.7.0**) and **Unreleased** changes (Keep a Changelog)
 - [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) — version bump, tag, and PyPI publish checklist
 - [`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)
 - [`docs/README.md`](docs/README.md) — documentation index (active vs historical)
+- [`docs/DOCUMENTATION_SYSTEM.md`](docs/DOCUMENTATION_SYSTEM.md) — documentation authority, metadata, lifecycle, validation, and federation workflow
 - [`docs/rfc/OLLAMA_RAG.md`](docs/rfc/OLLAMA_RAG.md) — draft RFC for Ollama local RAG ([#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34))
 - [`docs/quality/`](docs/quality/) — architecture backlog, GitHub roadmap (v1.6), triage
 - [`docs/internal/STATIC_ANALYSIS_POLICY.md`](docs/internal/STATIC_ANALYSIS_POLICY.md) — Ghost Tooling policy (vendor-agnostic CI and public docs)
 
 When you add or change observable parser or graph behavior, update the relevant doc sections and add a bullet under **`## [Unreleased]`** in `CHANGELOG.md` (see [`.cursor/rules/05-auto-changelog.mdc`](.cursor/rules/05-auto-changelog.mdc)).
 
+For documentation changes, first classify the target as maintained, active,
+historical, or generated. Follow the metadata, freshness, supersession, and
+projection rules in [`docs/DOCUMENTATION_SYSTEM.md`](docs/DOCUMENTATION_SYSTEM.md).
+
+### Repository language
+
+Use English for documentation, changelog entries, issue and pull-request text,
+code comments, log messages, CLI help, and maintainer-facing configuration.
+Non-English text is appropriate only when it is the data under test, a quoted
+source title, or an intentionally localized runtime fixture. Generated repository
+packs are read-only snapshots: regenerate them from their source files instead of
+editing their embedded copies.
+
 ### Tooling policy
 
 CI and automation in this repository are limited to the core runtime and standard open-source linters (Ruff, Mypy, Pytest, CodeQL). Do not add third-party AST indexers, experimental analysis scripts, or custom MCP servers to the public tree, workflows, or `pyproject.toml`. See [`docs/internal/STATIC_ANALYSIS_POLICY.md`](docs/internal/STATIC_ANALYSIS_POLICY.md).
@@ -140,27 +154,38 @@ git checkout -b feat/add-html-exporter
 
 ### 4. Code Quality & Linting (Mandatory)
 
-CI runs the same commands as your local environment: `uv sync --all-extras`, then `make lint`, `make check`, and `make test`. Before committing, run the full gate:
+CI runs the same non-mutating checks as your local environment: `uv sync
+--all-extras`, then `make lint`, `make check`, `make test`, and
+`make docs-check`. It finishes with `make verify-clean` to prove that no quality
+step changed the submitted checkout. Before committing, run the full local gate:
 
 ```bash
 make all
 ```
 
-As of **v1.6.0**, `make all` runs **456** pytest cases with **≥80%** line coverage on `src/logseq_matryca_parser` (currently ~**91%**), plus `make vendor-name-check`. New contributors should mirror patterns in [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) and the module map in that file’s **Test suite** section.
+`make all` runs the current pytest suite with a **≥80%** line-coverage gate on
+`src/logseq_matryca_parser`, plus the vendor-neutral documentation check. Exact
+counts are intentionally not duplicated here; see the dated
+[repository audit](docs/REPOSITORY_STELLAR_ROADMAP_2026-08-06.md) for a verified
+snapshot. New contributors should mirror patterns in
+[`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md).
 
 Or run each step individually:
 
 ```bash
-make lint   # Ruff (with auto-fix)
-make check  # Mypy on src/, tests/, examples/
+make lint   # Ruff verification; never rewrites files
+make check  # Mypy on src/, tests/, examples/, and the documentation checker
 make test   # Pytest on tests/
 ```
 
+When you explicitly want Ruff to repair local lint findings, use
+`make lint-fix`, inspect the resulting diff, and rerun `make all`.
+
 Equivalent `uv run` invocations:
 
 ```bash
-uv run ruff check . --fix
-uv run mypy src/ tests/ examples/
+uv run ruff check .
+uv run mypy src/ tests/ examples/ scripts/check_documentation.py
 uv run pytest -v tests/
 ```
 

logseq_matryca_parser-1.7.0/Makefile

@@ -0,0 +1,31 @@
+.PHONY: all lint lint-fix check test build vendor-name-check docs-check verify-clean
+
+all: lint check vendor-name-check docs-check test
+
+lint:
+	uv run ruff check .
+
+lint-fix:
+	uv run ruff check . --fix
+
+check:
+	uv run mypy src/ tests/ examples/ scripts/check_documentation.py scripts/check_release_contract.py scripts/check_wheel_contract.py
+
+vendor-name-check:
+	bash scripts/check_vendor_free_docs.sh
+
+test:
+	uv run pytest --cov=src/logseq_matryca_parser --cov-report=term-missing --cov-fail-under=80 -v tests/
+
+docs-check:
+	uv run python scripts/check_documentation.py --root . --profile docs/maintained.toml --as-of-date $$(date -u +%F)
+
+verify-clean:
+	@status="$$(git status --porcelain)"; \
+	if [ -n "$$status" ]; then \
+		printf '%s\n' "$$status"; \
+		exit 1; \
+	fi
+
+build:
+	uv run python -m nuitka --standalone --onefile src/logseq_matryca_parser/kinetic.py