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

logseq_matryca_parser-1.6.0/.github/ISSUE_TEMPLATE/clean_architecture.yml

@@ -0,0 +1,61 @@
+name: Clean Architecture slice
+description: Structural refactor or layer-boundary work (Uncle Bob contract)
+title: "refactor: "
+labels:
+  - architecture
+  - clean-code
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for SRP/OCP/ISP/DIP slices. SSOT: [CLEAN_CODE_ARCHITECTURE.md](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/CLEAN_CODE_ARCHITECTURE.md)
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Operator- or maintainer-visible issue in one paragraph
+    validations:
+      required: true
+  - type: textarea
+    id: lens
+    attributes:
+      label: Clean Architecture lens
+      description: "Table: Ring | SOLID violation | dependency-rule note"
+      value: |
+        | Ring | SOLID | Dependency rule |
+        |------|-------|-----------------|
+        | | | |
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Minimal markdown fixture, Python probe, or import-graph note
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual
+      description: Precise strings, counts, or module boundaries
+    validations:
+      required: true
+  - type: textarea
+    id: fix
+    attributes:
+      label: Suggested fix
+      description: Stay inside the correct ring; no drive-by refactors
+    validations:
+      required: true
+  - type: textarea
+    id: dod
+    attributes:
+      label: Definition of Done
+      value: |
+        - [ ] `make all` passes (Ruff, Mypy, pytest ≥80% coverage)
+        - [ ] `make vendor-name-check` passes
+        - [ ] `CHANGELOG.md` updated if operator-visible
+        - [ ] `docs/quality/CLEAN_ARCH_BACKLOG.md` updated if DEBT item closed
+    validations:
+      required: true

{logseq_matryca_parser-1.4.1 → logseq_matryca_parser-1.6.0}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Clean Architecture epic (v1.6)
+    url: https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/quality/GITHUB_CLEAN_ARCH_ROADMAP.md
+    about: Milestone, project board, and phase issues for Uncle Bob v1.6 work
   - name: Security vulnerability
     url: https://github.com/MarcoPorcellato/logseq-matryca-parser/security/policy
     about: Report a security issue privately — do not open a public issue

logseq_matryca_parser-1.6.0/.github/clean_arch_issue_numbers.txt

@@ -0,0 +1,7 @@
+milestone=2
+EPIC=78
+PHASE0=79
+PHASE1=80
+PHASE3A=81
+PHASE3B=82
+PHASE4=83

{logseq_matryca_parser-1.4.1 → logseq_matryca_parser-1.6.0}/.github/labels.yml

@@ -36,3 +36,11 @@
 - name: forge
   color: bfd4f2
   description: FORGE exporters and visitors
+
+- name: clean-code
+  color: "0e8a16"
+  description: Clean Architecture / SOLID slice — Uncle Bob contract
+
+- name: architecture
+  color: "5319e7"
+  description: Layer boundaries, dependency rule, structural refactor

logseq_matryca_parser-1.6.0/.github/scripts/create_clean_arch_issues.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# Bootstrap Clean Architecture v1.6 milestone, epic, and phase issues.
+# Run from repo root: bash .github/scripts/create_clean_arch_issues.sh
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT"
+
+REPO="${GITHUB_REPOSITORY:-MarcoPorcellato/logseq-matryca-parser}"
+MILESTONE_TITLE="v1.6 — Clean Architecture & Code Quality"
+OUT="$ROOT/.github/clean_arch_issue_numbers.txt"
+: > "$OUT"
+
+milestone_number() {
+  gh api "repos/${REPO}/milestones" --paginate \
+    --jq ".[] | select(.title==\"${MILESTONE_TITLE}\") | .number" | head -1
+}
+
+ensure_milestone() {
+  local num
+  num=$(milestone_number || true)
+  if [[ -n "${num}" ]]; then
+    echo "Milestone exists: #${num} (${MILESTONE_TITLE})"
+    echo "milestone=${num}" >> "$OUT"
+    return
+  fi
+  num=$(gh api "repos/${REPO}/milestones" -f title="${MILESTONE_TITLE}" \
+    -f description="Uncle Bob rings, layer CI, KINETIC/SYNAPSE SRP-OCP slices. SSOT: docs/CLEAN_CODE_ARCHITECTURE.md. Target: v1.6.0." \
+    --jq '.number')
+  echo "Created milestone #${num}: ${MILESTONE_TITLE}"
+  echo "milestone=${num}" >> "$OUT"
+}
+
+create_issue() {
+  local id="$1"
+  local title="$2"
+  local labels="$3"
+  local body_file="$4"
+  local url
+  url=$(gh issue create --title "$title" --label "$labels" --body-file "$body_file")
+  local num="${url##*/}"
+  local ms
+  ms=$(milestone_number)
+  if [[ -n "${ms}" ]]; then
+    gh api -X PATCH "repos/${REPO}/issues/${num}" -f milestone="${ms}" >/dev/null
+  fi
+  echo "$id=${num}" >> "$OUT"
+  echo "Created ${id} -> #${num}"
+}
+
+BODY_DIR=$(mktemp -d)
+trap 'rm -rf "$BODY_DIR"' EXIT
+
+ensure_milestone
+
+# Epic
+cat > "$BODY_DIR/epic.md" <<'EOF'
+## Goal
+
+Ship the v1.6 Clean Architecture contract: SSOT documentation, import-boundary CI, KINETIC export extraction, SYNAPSE embed OCP, graph ISP public API, and a KINETIC command slice.
+
+## Clean Architecture lens
+
+| Ring | Modules touched |
+|------|-----------------|
+| Entities | `logos_core` (unchanged in v1) |
+| Use cases | `graph`, `logos_parser` (no FSM refactor) |
+| Adapters | `synapse`, `forge`, `kinetic_export` |
+| Drivers | `kinetic`, `kinetic_commands` |
+
+## Phases (child issues)
+
+Update checkboxes when each phase merges:
+
+- [ ] Phase 0 — docs SSOT + layer CI + vendor-name-check
+- [ ] Phase 1 — `kinetic_export.py` (DEBT-005)
+- [ ] Phase 2 — SYNAPSE embed OCP (DEBT-006) — #70
+- [ ] Phase 3 — `iter_attached_nodes()` + `kinetic_commands.py`
+- [ ] Phase 4 — hardening + v1 closure
+
+## SSOT
+
+- [`docs/CLEAN_CODE_ARCHITECTURE.md`](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/CLEAN_CODE_ARCHITECTURE.md)
+- [`docs/quality/CLEAN_ARCH_BACKLOG.md`](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/quality/CLEAN_ARCH_BACKLOG.md)
+- [`docs/quality/GITHUB_CLEAN_ARCH_ROADMAP.md`](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/quality/GITHUB_CLEAN_ARCH_ROADMAP.md)
+
+## Out of scope (v2 epic)
+
+- `logos_parser.py` split (1439 lines, CRITICAL hub — do not refactor in v1.6)
+- Hexagonal `domain/ports.py`
+- Vendor AST indexer in CI (Ghost Tooling policy)
+
+## Definition of Done
+
+- [ ] All phase issues closed
+- [ ] `make all` green on `main`
+- [ ] `CHANGELOG.md` ready for v1.6.0
+- [ ] Milestone closed after tag `v1.6.0`
+EOF
+create_issue "EPIC" "Epic: Clean Architecture v1.6 — documentation, layer CI, and SRP/OCP slices" "architecture,enhancement" "$BODY_DIR/epic.md"
+
+# Phase 0
+cat > "$BODY_DIR/phase0.md" <<'EOF'
+## Problem
+
+Contributors lack a single Uncle Bob SSOT, automated layer-boundary tests, and a vendor-free code-audit runbook. Two small DIP/SRP slices are already implemented locally but not tracked on `main`.
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Drivers / use cases | SRP, DIP | Public graph API for watcher; remove dead kinetic helper |
+| CI (tests) | — | Inner rings must not import frameworks |
+
+## Deliverables
+
+- [ ] `docs/CLEAN_CODE_ARCHITECTURE.md` — rings, SOLID, module map
+- [ ] `tests/test_layer_boundary.py` — import-boundary gate
+- [ ] `scripts/check_vendor_free_docs.sh` + `make vendor-name-check`
+- [ ] `docs/internal/LOCAL_CODE_STUDY.md` — maintainer runbook (generic terminology)
+- [ ] Public `LogseqGraph.is_tracked_markdown_path()` (closes #68)
+- [ ] Remove dead `_parse_graph` from `kinetic.py` (closes #67)
+
+## Reproduction
+
+```bash
+uv run pytest tests/test_layer_boundary.py -q
+make vendor-name-check
+```
+
+## Expected vs actual
+
+- **Expected:** `make all` passes; zero vendor tool names in public docs.
+- **Actual (pre-merge):** slices exist only in working tree.
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] PR body: `Fixes #67`, `Fixes #68`, links epic
+EOF
+create_issue "PHASE0" "docs: Clean Architecture SSOT, layer CI, and code-audit runbook" "architecture,clean-code,documentation" "$BODY_DIR/phase0.md"
+
+# Phase 1
+cat > "$BODY_DIR/phase1.md" <<'EOF'
+## Problem
+
+`kinetic.py` mixes Typer wiring with five `_export_*` handlers (~700 lines). Export formats cannot be extended without editing the driver module (SRP / OCP violation).
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Drivers | SRP, OCP | `kinetic.py` orchestrates; `kinetic_export.py` owns format handlers |
+| Adapters | — | Handlers may call `forge`, `synapse` via public APIs |
+
+## Suggested fix
+
+1. Create `src/logseq_matryca_parser/kinetic_export.py`
+2. Move `_export_json`, `_export_markdown`, `_export_obsidian`, `_export_langchain`, etc.
+3. Registry or dispatcher in `kinetic.export()` — no behavior change
+4. Extend `tests/test_layer_boundary.py` for the new module
+
+## Reproduction
+
+```bash
+uv run matryca-parse export --help
+make check
+```
+
+## Expected vs actual
+
+- **Expected:** identical CLI output and exit codes; `kinetic.py` shrinks materially.
+- **Actual:** all export logic inline in `kinetic.py`.
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] `tests/test_kinetic.py` unchanged behavior
+- [ ] `docs/quality/CLEAN_ARCH_BACKLOG.md` — DEBT-005 closed
+- [ ] `CHANGELOG.md` if operator-visible
+
+**Tracking:** DEBT-005
+EOF
+create_issue "PHASE1" "refactor(kinetic): extract export handlers to kinetic_export.py (SRP)" "architecture,clean-code,cli,enhancement" "$BODY_DIR/phase1.md"
+
+# Phase 3a — iter_attached_nodes
+cat > "$BODY_DIR/phase3a.md" <<'EOF'
+## Problem
+
+`LogseqGraph._iter_attached_nodes()` is private but is the correct ISP surface for consumers that must skip orphan ghost nodes. Callers risk using `graph.pages` or `_node_registry` directly.
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Use cases | ISP | Public iterator; private implementation unchanged |
+| Adapters | DIP | `agent_read`, LENS, SYNAPSE should prefer public API |
+
+## Suggested fix
+
+- Add `LogseqGraph.iter_attached_nodes() -> Iterator[LogseqNode]` (public)
+- Delegate from existing private method
+- Deprecation comment on leaky patterns in docstring only
+
+## Reproduction
+
+```python
+from logseq_matryca_parser.graph import LogseqGraph
+g = LogseqGraph.load_directory("path/to/vault")
+list(g.iter_attached_nodes())
+```
+
+## Definition of Done
+
+- [ ] Public method documented in `CLEAN_CODE_ARCHITECTURE.md` module map
+- [ ] `make all` passes
+- [ ] No new `graph.pages` iteration in drivers without `iter_canonical_pages()`
+EOF
+create_issue "PHASE3A" "refactor(graph): public iter_attached_nodes() (ISP)" "architecture,clean-code,enhancement" "$BODY_DIR/phase3a.md"
+
+# Phase 3b — kinetic_commands
+cat > "$BODY_DIR/phase3b.md" <<'EOF'
+## Problem
+
+After Phase 1 export extraction, `kinetic.py` still hosts many Typer subcommands (scan, visualize, agent-write, demo). The driver module remains above the ~550-line SRP threshold.
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Drivers | SRP | `kinetic.py` = app factory + shared helpers; `kinetic_commands.py` = command handlers |
+
+## Suggested fix
+
+- Extract command groups to `kinetic_commands.py`
+- `kinetic.py` registers commands via imports
+- Extend `tests/test_layer_boundary.py` if needed
+
+## Related
+
+- #61 — replace production `assert` in `agent_write` (include in same PR if still present)
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] `tests/test_kinetic.py` green
+- [ ] `kinetic.py` line count ≤ 550 post-extraction
+EOF
+create_issue "PHASE3B" "refactor(kinetic): extract subcommands to kinetic_commands.py (SRP)" "architecture,clean-code,cli,enhancement" "$BODY_DIR/phase3b.md"
+
+# Phase 4
+cat > "$BODY_DIR/phase4.md" <<'EOF'
+## Problem
+
+v1.6 documentation and backlog need final cross-links; epic checklist must close; README/COOKBOOK should point to the Uncle Bob SSOT.
+
+## Deliverables
+
+- [ ] README + COOKBOOK links to `docs/CLEAN_CODE_ARCHITECTURE.md`
+- [ ] `docs/quality/CLEAN_ARCH_BACKLOG.md` — v1 structural items marked complete
+- [ ] Close epic issue
+- [ ] `CHANGELOG.md` release notes draft for v1.6.0 (no autonomous tag)
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] Epic checklist complete
+- [ ] Milestone ready to close after release tag
+EOF
+create_issue "PHASE4" "chore: Clean Architecture v1 hardening + README/COOKBOOK links" "architecture,clean-code,documentation" "$BODY_DIR/phase4.md"
+
+echo ""
+echo "=== Issue numbers written to ${OUT} ==="
+cat "$OUT"
+echo ""
+echo "Next: assign milestone to existing #70, #71, #61 via gh issue edit"
+echo "Create GitHub Project: gh project create --title 'Logseq Parser — Clean Architecture v1.6' --owner MarcoPorcellato"

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

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Added
+
+- **Clean Architecture SSOT** — [`docs/CLEAN_CODE_ARCHITECTURE.md`](docs/CLEAN_CODE_ARCHITECTURE.md) maps Uncle Bob rings, SOLID, and module maps; quality index in [`docs/quality/`](docs/quality/) (backlog, GitHub roadmap, July 2026 triage).
+- **`kinetic_export.py`** — KINETIC format handlers extracted from `kinetic.py` (DEBT-005 / [#80](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/80)).
+- **`kinetic_commands.py`** — `scan`, `visualize`, `demo`, `append`, `agent-read`, and `agent-write` subcommands (SRP slice / [#82](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/82)).
+- **`synapse_embed.py`** — `BlockEmbedExpander` / `PageEmbedExpander` strategy pattern for embed expansion (DEBT-006 / [#70](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/70)).
+- **`LogseqGraph.iter_attached_nodes()`** — public ISP iterator skipping orphan ghost registry entries ([#81](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/81)).
+- **Layer boundary CI** — `tests/test_layer_boundary.py` forbids framework imports in entities/use cases, adapter→driver leaks, and Typer/Rich in `kinetic_export.py`.
+- **`make vendor-name-check`** — Ghost Tooling gate for vendor-free public documentation.
+- **Maintainer local code audit runbook** — [`docs/internal/LOCAL_CODE_STUDY.md`](docs/internal/LOCAL_CODE_STUDY.md).
+- **GitHub issue template** — `.github/ISSUE_TEMPLATE/clean_architecture.yml` for Uncle Bob slices; bootstrap script `.github/scripts/create_clean_arch_issues.sh`.
+
+### Changed
+
+- **`kinetic.py`** — slim Typer app factory (~230 lines): `export` orchestration + shared CLI helpers; subcommands in `kinetic_commands.py`.
+- **`LogseqGraph.is_tracked_markdown_path()`** — public DIP surface for watcher path checks ([#68](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/68)).
+- **KINETIC** — removed dead `_parse_graph` helper ([#67](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/67)).
+- **Ghost Tooling** — vendor AST indexer names removed from public docs; unified on **local code audit** / **graph-based code study** terminology.
+- **Contributor docs** — [`README.md`](README.md), [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/COOKBOOK.md`](docs/COOKBOOK.md), [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md), and [`CONTRIBUTING.md`](CONTRIBUTING.md) updated for v1.6.0 and **456** pytest cases.
+
+### Meta (contributor tracking)
+
+- **Clean Architecture epic** — [#78](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/78) (phases [#79](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/79)–[#83](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/83)).
+- **Contributor waves 3–5** — issues [#59](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/59)–[#73](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/73) filed from local code study; agent rule [`.cursor/rules/07-clean-architecture-audit.mdc`](.cursor/rules/07-clean-architecture-audit.mdc).
+
+## [1.5.0] - 2026-06-29
+
+### Added
+
+- **CLI** — `matryca-parse scan --broken-refs` reports unresolved `((uuid))` block references in a Rich table and exits with status 1 when any are found ([#29](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/29), [#77](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/77)).
+
+### Changed
+
+- **Contributor docs** — [`README.md`](README.md), [`docs/COOKBOOK.md`](docs/COOKBOOK.md), [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md), and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) document the new scan flag and **451** pytest cases.
+
+## [1.4.2] - 2026-06-29
+
+### Fixed
+
+- **agent-write** — `append_child_to_node` normalizes source files missing a trailing newline before line splice, preventing new bullets from being appended onto the last line ([#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72), [#74](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/74)).
+- **SYNAPSE** — cyclic `{{embed [[Page]]}}` chains no longer duplicate parent literal text; page embed expansion tracks an immutable host-page chain seeded from `to_context_enriched_chunks` ([#65](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/65), [#75](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/75)).
+- **agent-write** — `SessionAliasRegistry.load_from_disk` tolerates empty, malformed, or legacy-wrapped X-Ray JSON; KINETIC exits with a clear message instead of a traceback ([#60](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/60), [#76](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/76)).
+
+### Added
+
+- **Test coverage (wave 2)** — Community contribution ([#58](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/58), maintainer #43): **65** new pytest cases for `detect_tab_size_from_markdown`, graph link/backlink helpers, SYNAPSE embedding strip + metadata schema, FORGE Markdown/JSON visitors, LENS node classification, `extract_changelog` CLI, `LogseqConfigReader` timestamps, and KINETIC `agent-write` validation errors. Closes [#20](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/20), [#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52).
+- **Regression tests** — Seven new cases for newline splice, cyclic page embed, and malformed X-Ray state (issues [#73](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/73), [#65](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/65), [#60](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/60)); suite total **450** pytest.
+
+### Changed
+
+- **Contributor docs** — [`README.md`](README.md), [`docs/README.md`](docs/README.md), [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) harmonized for **v1.4.2** (test count, supported versions, agent-write / SYNAPSE behavior notes).
+
 ## [1.4.1] - 2026-06-24
 
 ### Added

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

@@ -13,15 +13,18 @@ To maintain the architectural integrity of the project, please follow the guidel
 User-facing behavior is documented in:
 
 - [`README.md`](README.md) — overview, quickstart, and feature matrix
+- [`docs/CLEAN_CODE_ARCHITECTURE.md`](docs/CLEAN_CODE_ARCHITECTURE.md) — Clean Code & Clean Architecture (rings, SOLID, layer boundaries)
 - [`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.4.1**) and **Unreleased** changes (Keep a Changelog)
+- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.6.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/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)).
@@ -52,6 +55,25 @@ Tier 1 tasks are **test-only** — no parser changes, ideal for learning `CliRun
 
 ---
 
+## Code quality (Clean Code & Clean Architecture)
+
+The project applies **Robert C. Martin's** *Clean Architecture* (dependency rule, inward dependencies) and *Clean Code* (SRP, meaningful names, tests as specification) across `src/logseq_matryca_parser/`.
+
+| Practice | Where it shows up |
+|----------|-------------------|
+| **Dependency Rule** | Entities + use cases must not import Typer, Rich, or optional AI/viz frameworks — `tests/test_layer_boundary.py` |
+| **Fat modules, thin edges** | Parse/index in `graph` / `logos_parser`; KINETIC and adapters delegate |
+| **Public graph API** | `iter_canonical_pages()`, `page_for_node()`, `iter_attached_nodes()`, `is_tracked_markdown_path()` |
+| **Tests as spec** | pytest + `tmp_path` vaults; `make all` gate |
+
+**SSOT:** [`docs/CLEAN_CODE_ARCHITECTURE.md`](docs/CLEAN_CODE_ARCHITECTURE.md) · audit backlog: [`docs/quality/CLEAN_ARCH_BACKLOG.md`](docs/quality/CLEAN_ARCH_BACKLOG.md) · Cursor rule: [`.cursor/rules/08-clean-code-architecture.mdc`](.cursor/rules/08-clean-code-architecture.mdc).
+
+**Good first issues (Clean Architecture — Tier 4):** [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) § Tier 4 (label `clean-code`).
+
+**Ghost Tooling:** do not name vendor AST indexers in issues or PRs; maintainers may use local graph-based code audit per [`docs/internal/LOCAL_CODE_STUDY.md`](docs/internal/LOCAL_CODE_STUDY.md). Run `make vendor-name-check` before docs PRs.
+
+---
+
 ## 🏛️ Architectural Philosophy
 
 Before writing any code, please understand our core principles:
@@ -124,7 +146,7 @@ CI runs the same commands as your local environment: `uv sync --all-extras`, the
 make all
 ```
 
-As of **v1.4.1**, `make test` runs **378** pytest cases with **≥80%** line coverage on `src/logseq_matryca_parser` (currently ~**90%**). 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.
+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.
 
 Or run each step individually:
 

{logseq_matryca_parser-1.4.1 → logseq_matryca_parser-1.6.0}/Makefile

@@ -1,6 +1,6 @@
-.PHONY: all lint check test build
+.PHONY: all lint check test build vendor-name-check
 
-all: lint check test
+all: lint check vendor-name-check test
 
 lint:
 	uv run ruff check . --fix
@@ -8,6 +8,9 @@ lint:
 check:
 	uv run mypy src/ tests/ examples/
 
+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/
 

{logseq_matryca_parser-1.4.1 → logseq_matryca_parser-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.4.1
+Version: 1.6.0
 Summary: The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai.
 Project-URL: Homepage, https://github.com/MarcoPorcellato/logseq-matryca-parser
 Project-URL: Repository, https://github.com/MarcoPorcellato/logseq-matryca-parser
@@ -53,7 +53,7 @@ Description-Content-Type: text/markdown
 [![Status: Stable](https://img.shields.io/badge/Status-Stable-22c55e.svg?style=flat-square)](#)
 ![Origin: Matryca.ai](https://img.shields.io/badge/Origin-Matryca.ai-gold?style=for-the-badge)
 
-**v1.4.1** — Test-hardening patch: **378 tests** (+107), community coverage for parser helpers, CLI agents, FORGE visitors, and wave-2 good-first issues ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) — no production API changes (see [CHANGELOG](CHANGELOG.md)).
+**v1.6.0** — Clean Architecture slices (`kinetic_export`, `synapse_embed`, layer CI), public `iter_attached_nodes()` / `is_tracked_markdown_path()`. **456 tests**. See [CHANGELOG](CHANGELOG.md).
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -63,7 +63,7 @@ Description-Content-Type: text/markdown
 
 [👉 **TRY THE LIVE INTERACTIVE DEMO**](https://MarcoPorcellato.github.io/logseq-matryca-parser/)
 
-[📘 **ARCHITECTURE**](docs/ARCHITECTURE.md) · [AST Primer](docs/logseq_ast_primer.md) · [Cookbook](docs/COOKBOOK.md) · [Good first issues](docs/GOOD_FIRST_ISSUES.md) · [Docs index](docs/README.md) · [CodeQL](docs/CODEQL.md) · [Changelog](CHANGELOG.md) · [Release process](docs/RELEASE_PROCESS.md)
+[📘 **ARCHITECTURE**](docs/ARCHITECTURE.md) · [Clean Architecture SSOT](docs/CLEAN_CODE_ARCHITECTURE.md) · [AST Primer](docs/logseq_ast_primer.md) · [Cookbook](docs/COOKBOOK.md) · [Good first issues](docs/GOOD_FIRST_ISSUES.md) · [Docs index](docs/README.md) · [CodeQL](docs/CODEQL.md) · [Changelog](CHANGELOG.md) · [Release process](docs/RELEASE_PROCESS.md)
 
 </div>
 
@@ -147,6 +147,43 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
+## ⚡ Release highlights (v1.6.0)
+
+Minor release — Clean Architecture v1 structural slices and documentation SSOT. **No intentional breaking changes** to default CLI behavior or stable package exports.
+
+| Area | Change |
+| :--- | :--- |
+| **KINETIC (SRP)** | `kinetic_export.py` (format handlers) + `kinetic_commands.py` (subcommands); `kinetic.py` is a ~230-line app factory ([#80](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/80), [#82](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/82)). |
+| **SYNAPSE (OCP)** | `synapse_embed.py` — `BlockEmbedExpander` / `PageEmbedExpander` strategy ([#70](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/70)). |
+| **Graph (ISP/DIP)** | Public `iter_attached_nodes()` and `is_tracked_markdown_path()` ([#81](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/81), [#68](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/68)). |
+| **Quality gates** | `tests/test_layer_boundary.py` + `make vendor-name-check`; SSOT [`docs/CLEAN_CODE_ARCHITECTURE.md`](docs/CLEAN_CODE_ARCHITECTURE.md). |
+| **Test suite** | **456** pytest cases (**+5** vs v1.5.0). |
+
+---
+
+## ⚡ Release highlights (v1.5.0)
+
+Minor release — CLI vault hygiene for broken block references. **No intentional breaking changes** to default `scan` behavior (`--broken-refs` is opt-in).
+
+| Area | Change |
+| :--- | :--- |
+| **KINETIC `scan`** | New `--broken-refs` flag prints unresolved `((uuid))` refs in a Rich table and exits `1` for CI pipelines ([#77](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/77)). |
+| **Test suite** | **451** pytest cases (**+1** vs v1.4.2). |
+
+---
+
+## ⚡ Release highlights (v1.4.2)
+
+Patch release — agent-write and SYNAPSE correctness fixes. **No intentional breaking changes** to public APIs.
+
+| Area | Change |
+| :--- | :--- |
+| **agent-write** | Headless splice normalizes files missing a final newline; corrupt `.matryca_xray_state.json` yields a controlled CLI exit ([#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72), [#60](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/60)). |
+| **SYNAPSE RAG** | Cyclic `{{embed [[Page]]}}` chains truncate at the re-entrant edge without duplicating parent literal text ([#65](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/65)). |
+| **Test suite** | **450** pytest cases (**+72** vs v1.4.1): wave 2 community coverage ([#58](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/58)) plus regression tests for the three fixes. |
+
+---
+
 ## ⚡ Release highlights (v1.4.1)
 
 Patch release — contributor test coverage and onboarding refresh. **No intentional changes** to parser, graph, or CLI runtime behavior.
@@ -330,7 +367,7 @@ matryca-parse agent-read /path/to/graph --tag idea
 matryca-parse agent-write /path/to/graph --alias 0 --content "Follow-up from the agent"
 ```
 
-For graph hygiene, **`LogseqGraph.get_broken_references()`** flags nodes whose `((uuid))` block refs point at missing registry targets—structural linting, not regex guessing.
+For graph hygiene, **`LogseqGraph.get_broken_references()`** flags nodes whose `((uuid))` block refs point at missing registry targets—structural linting, not regex guessing. From the CLI: `matryca-parse scan /path/to/graph --broken-refs` (exit `1` when broken refs exist).
 
 ---
 
@@ -348,7 +385,7 @@ For graph hygiene, **`LogseqGraph.get_broken_references()`** flags nodes whose `
 | **Agent-Native Printing Press** | [`agent_press.py`](src/logseq_matryca_parser/agent_press.py): **`SessionAliasRegistry`** maps session aliases ↔ block UUIDs; **`to_xray_markdown`** emits token-minimal outline text for autonomous agents (`matryca-parse agent-read`). |
 | **Native Markdown Serialization** | [`logseq_markdown.py`](src/logseq_matryca_parser/logseq_markdown.py) + [`logseq_paths.py`](src/logseq_matryca_parser/logseq_paths.py): rebuild and write Logseq-compliant markdown from an AST—page header preserves **YAML `---` or native `key::`** by source format, block properties at **parent whitespace + 2 spaces** (including bullet-list `tags::`), `:LOGBOOK:` drawers, and namespace titles via **`___`** pathing rules. |
 | **Headless Write Engine** | [`agent_writer.py`](src/logseq_matryca_parser/agent_writer.py): **`append_child_to_node`** splices child bullets into on-disk Markdown from AST topology; **`serialize_logseq_page`** / **`write_logseq_page`** emit full pages; **`matryca-parse agent-write`** resolves aliases via **`.matryca_xray_state.json`**. |
-| **AST Linters** | **`LogseqGraph.get_broken_references()`** returns originating nodes when `block_refs` target UUIDs absent from the global registry. |
+| **AST Linters** | **`LogseqGraph.get_broken_references()`** returns originating nodes when `block_refs` target UUIDs absent from the global registry; **`matryca-parse scan --broken-refs`** exposes the same check from KINETIC (v1.5.0). |
 | **Sovereign AI** | 100% Local. Zero telemetry. Private by design. |
 
 ### Data model — `LogseqNode` task fields
@@ -373,7 +410,7 @@ Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `
 ## 🛠️ Quickstart
 
 ```bash
-# Install from PyPI (latest: v1.4.1)
+# Install from PyPI (latest: v1.6.0)
 uv pip install logseq-matryca-parser
 
 # Optional: filesystem watcher for live incremental graph updates