logseq-matryca-parser 1.4.0__tar.gz → 1.4.2__tar.gz

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Contributor issues (wave 3)** — Six new issues from local code study ([#59](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/59)–[#64](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/64)): LENS ghost wikilink nodes, corrupt X-Ray state handling, `agent_write` assert guard, and paired good-first tests.
+- **Contributor issues (wave 4)** — Seven issues from Clean Architecture code study ([#65](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/65)–[#71](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/71)): SYNAPSE cyclic embed duplication, unresolved embed semantics, kinetic dead code, graph watcher DIP, English DX messages, OCP embed refactor, and parametrized SYNAPSE tests. Agent rule: [`.cursor/rules/07-clean-architecture-audit.mdc`](.cursor/rules/07-clean-architecture-audit.mdc).
+- **Contributor issues (wave 5)** — [#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72) / [#73](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/73): `append_child_to_node` corrupts Markdown when the source file lacks a trailing newline (agent-write data loss).
+
+## [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
+
+- **Test coverage (wave 1)** — Community contribution ([#42](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/42)): **107** new pytest cases (**378** total) across parser helpers (`normalize_logseq_timestamp`, `clean_node_content`), `logseq_paths` fallbacks, exception hierarchy, `extract_changelog` release script, KINETIC per-command `--help`, `agent-read --query`, and direct `ObsidianForgeVisitor` tests. New modules: `tests/test_exceptions.py`, `tests/test_extract_changelog.py`. Closes [#21](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/21)–[#24](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/24), [#27](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/27), [#30](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/30)–[#32](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/32).
+- **Good first issues (wave 2)** — Ten new contributor tasks ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) indexed as GFI-17–GFI-26 in [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md); wave-1 GFI items marked complete.
+
+### 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.1** (test count, issue index range, supported versions).
+
 ## [1.4.0] - 2026-06-23
 
 ### Added

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/CONTRIBUTING.md

@@ -15,7 +15,7 @@ User-facing behavior is documented in:
 - [`README.md`](README.md) — overview, quickstart, and feature matrix
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — LOGOS, SYNAPSE, `LogseqGraph`, agents, and data flow
 - [`docs/logseq_ast_primer.md`](docs/logseq_ast_primer.md) — Logseq Spatial Markdown domain rules
-- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.4.0**) and **Unreleased** changes (Keep a Changelog)
+- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.4.2**) 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
@@ -44,7 +44,7 @@ New to the codebase? Start here:
 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`.
 4. **Branch** using `feat/…`, `test/…`, or `docs/…` naming (see workflow below).
-5. **Submit** a PR that links the issue (`Fixes #123`).
+5. **Submit** one PR per issue, branched from `main` (`Fixes #123`).
 
 Tier 1 tasks are **test-only** — no parser changes, ideal for learning `CliRunner` and pytest patterns in `tests/`. Tier 2 is documentation. Tier 3 adds small CLI or FORGE features with explicit acceptance criteria.
 
@@ -124,6 +124,8 @@ CI runs the same commands as your local environment: `uv sync --all-extras`, the
 make all
 ```
 
+As of **v1.4.2**, `make test` runs **450** pytest cases with **≥80%** line coverage on `src/logseq_matryca_parser` (currently ~**91%**). 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:
 
 ```bash
@@ -150,9 +152,9 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/). Your com
 
 ### 6. Submit a Pull Request (PR)
 
-- Push your branch and open a PR against the `main` branch.
+- Push your branch and open a PR against the `main` branch (**one issue per PR**).
 - Describe why the change is needed.
-- Link the relevant Issue (e.g., `Fixes #123`).
+- Link the relevant Issue (e.g., `Fixes #123`). **One issue per PR** — do not stack multiple issues on a single branch.
 - Ensure all GitHub Actions (CI) checks pass.
 
 ---

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.4.0
+Version: 1.4.2
 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.0** — Robustness & graph-integrity release: 31 bug-hunt fixes, canonical page iteration, case-insensitive tag/search, live watcher delete/move, SYNAPSE embed safety (see [CHANGELOG](CHANGELOG.md)) — **271 tests**.
+**v1.4.2** — Bugfix patch: agent-write splice safety, SYNAPSE cyclic embed truncation, resilient X-Ray state reload ([#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72), [#65](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/65), [#60](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/60)). **450 tests** (wave 1 + wave 2 + regression suite). See [CHANGELOG](CHANGELOG.md).
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -147,6 +147,30 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
+## ⚡ 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.
+
+| Area | Change |
+| :--- | :--- |
+| **Test suite** | **378** pytest cases (**+107** vs v1.4.0): `normalize_logseq_timestamp`, `clean_node_content`, `logseq_paths` fallbacks, exception hierarchy, `extract_changelog` script, KINETIC `--help`, `agent-read --query`, direct `ObsidianForgeVisitor` tests ([#42](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/42)). |
+| **New test modules** | `tests/test_exceptions.py`, `tests/test_extract_changelog.py`. |
+| **Contributor index** | [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) wave 2 ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)); wave-1 items marked complete. |
+
+---
+
 ## ⚡ Release highlights (v1.4.0)
 
 Minor release — graph integrity, export hygiene, and parser hardening from the local static-analysis bug hunt (waves 1–8). No intentional breaking changes to default parse behavior.
@@ -361,7 +385,7 @@ Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `
 ## 🛠️ Quickstart
 
 ```bash
-# Install from PyPI (latest: v1.4.0)
+# Install from PyPI (latest: v1.4.2)
 uv pip install logseq-matryca-parser
 
 # Optional: filesystem watcher for live incremental graph updates
@@ -458,7 +482,7 @@ We welcome issues, pull requests, and constructive feedback.
 
 | Resource | Link |
 | :--- | :--- |
-| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
+| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) |
 | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, PR workflow |
 | **Cookbook** | [docs/COOKBOOK.md](docs/COOKBOOK.md) — integration recipes (Synapse, graph query, watcher) |
 | **Documentation index** | [docs/README.md](docs/README.md) — active vs historical docs |

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/README.md

@@ -12,7 +12,7 @@
 [![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.0** — Robustness & graph-integrity release: 31 bug-hunt fixes, canonical page iteration, case-insensitive tag/search, live watcher delete/move, SYNAPSE embed safety (see [CHANGELOG](CHANGELOG.md)) — **271 tests**.
+**v1.4.2** — Bugfix patch: agent-write splice safety, SYNAPSE cyclic embed truncation, resilient X-Ray state reload ([#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72), [#65](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/65), [#60](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/60)). **450 tests** (wave 1 + wave 2 + regression suite). See [CHANGELOG](CHANGELOG.md).
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -106,6 +106,30 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
+## ⚡ 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.
+
+| Area | Change |
+| :--- | :--- |
+| **Test suite** | **378** pytest cases (**+107** vs v1.4.0): `normalize_logseq_timestamp`, `clean_node_content`, `logseq_paths` fallbacks, exception hierarchy, `extract_changelog` script, KINETIC `--help`, `agent-read --query`, direct `ObsidianForgeVisitor` tests ([#42](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/42)). |
+| **New test modules** | `tests/test_exceptions.py`, `tests/test_extract_changelog.py`. |
+| **Contributor index** | [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) wave 2 ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)); wave-1 items marked complete. |
+
+---
+
 ## ⚡ Release highlights (v1.4.0)
 
 Minor release — graph integrity, export hygiene, and parser hardening from the local static-analysis bug hunt (waves 1–8). No intentional breaking changes to default parse behavior.
@@ -320,7 +344,7 @@ Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `
 ## 🛠️ Quickstart
 
 ```bash
-# Install from PyPI (latest: v1.4.0)
+# Install from PyPI (latest: v1.4.2)
 uv pip install logseq-matryca-parser
 
 # Optional: filesystem watcher for live incremental graph updates
@@ -417,7 +441,7 @@ We welcome issues, pull requests, and constructive feedback.
 
 | Resource | Link |
 | :--- | :--- |
-| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
+| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) |
 | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, PR workflow |
 | **Cookbook** | [docs/COOKBOOK.md](docs/COOKBOOK.md) — integration recipes (Synapse, graph query, watcher) |
 | **Documentation index** | [docs/README.md](docs/README.md) — active vs historical docs |

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/SECURITY.md

@@ -6,8 +6,8 @@ Security fixes are provided **only for the latest released version** on [PyPI](h
 
 | Version | Supported |
 | ------- | --------- |
-| **1.4.0** (latest) | Yes |
-| Older releases | No |
+| **1.4.2** (latest) | Yes |
+| 1.4.1 and older | No |
 
 We recommend always running the current release and upgrading promptly when a security advisory is published.
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/docs/ARCHITECTURE.md

@@ -270,7 +270,7 @@ Beyond flat `Document` emission, **`to_context_enriched_chunks`** targets **vect
 
 1. **Breadcrumbs.** [`_build_breadcrumbs`](../src/logseq_matryca_parser/synapse.py) walks the owning `LogseqPage` and the node’s UUID `path` so the chunk’s visible text carries **human-readable lineage** (page title + ancestor outline), not just an opaque `parent_id`.
 
-2. **Recursive macro / embed expansion.** [`_expand_macros_and_embeds`](../src/logseq_matryca_parser/synapse.py) operates on **`node.content`** (not `clean_text`) so tokens hidden from embeddings—such as `((uuid))` inside `{{embed ((uuid))}}`—remain visible to the scanner. It expands **`{{embed ((uuid))}}`** by inlining the target block’s content (with **per-UUID cycle detection**) and **`{{embed [[Page]]}}`** by inlining page bodies via **`LogseqGraph.get_page`** (case-insensitive, with **per-title cycle detection**). Unresolved embed targets yield **empty replacement** instead of hanging the export pipeline (v1.4.0).
+2. **Recursive macro / embed expansion.** [`_expand_macros_and_embeds`](../src/logseq_matryca_parser/synapse.py) operates on **`node.content`** (not `clean_text`) so tokens hidden from embeddings—such as `((uuid))` inside `{{embed ((uuid))}}`—remain visible to the scanner. It expands **`{{embed ((uuid))}}`** by inlining the target block’s content (with **per-UUID cycle detection**) and **`{{embed [[Page]]}}`** by inlining page bodies via **`LogseqGraph.get_page`** (case-insensitive, with **per-title embed-chain detection** — the host page title seeds an immutable chain so inter-page cycles truncate at the re-entrant edge instead of re-inlining parent literals). Unresolved embed targets yield **empty replacement** instead of hanging the export pipeline (v1.4.0).
 
 3. **Org-mode-style property inheritance.** Metadata includes **`effective_properties`**: the merge produced by [`LogseqGraph.get_effective_properties`](../src/logseq_matryca_parser/graph.py) — **page frontmatter first**, then each ancestor on `node.path` **top-down**, with deeper `LogseqNode.properties` **overriding** shallower keys. Downstream filters can therefore key off inherited `type::`, `status::`, etc., without re-walking the outline at query time.
 
@@ -288,7 +288,7 @@ In the **LLM OS** metaphor, **LOGOS** is the **read path** into the hierarchical
 
 1. **Weekly append sandbox (`logseq_agent_write`).** A **deterministic**, **configuration-aware** channel that **dynamically reads `config.edn`** (for example **`:journal/page-title-format`**) so filenames and titles align with the vault’s own conventions. Writes use **`open(..., mode="a")`** **append-only** I/O — agents **append** new block material **after** existing bytes; they do **not** rewrite, merge, or re-indent prior content. Surfaced through the **`append`** command in **KINETIC**.
 
-2. **Headless Markdown splicer (`append_child_to_node`).** For **in-place graph mutation** under an existing parent block, the engine resolves `target_uuid` via `LogseqGraph.get_node_by_uuid`, walks to the **deepest last descendant** to obtain a **1-based `line_end` insertion index**, and computes child indentation as **`(target_node.indent_level + 1) × graph.tab_size`** spaces before the `- {content}` bullet prefix. The raw file is split into lines, the new row is inserted at that index, and the result is flushed through a **same-directory `tempfile.mkstemp` + `os.replace`** — an atomic swap that avoids torn reads during concurrent tooling. **KINETIC** exposes this as **`matryca-parse agent-write`**, resolving parent blocks by **`--alias`** (from the X-Ray state file) or **`--target-uuid`**.
+2. **Headless Markdown splicer (`append_child_to_node`).** For **in-place graph mutation** under an existing parent block, the engine resolves `target_uuid` via `LogseqGraph.get_node_by_uuid`, walks to the **deepest last descendant** to obtain a **1-based `line_end` insertion index**, and computes child indentation as **`(target_node.indent_level + 1) × graph.tab_size`** spaces before the `- {content}` bullet prefix. The raw file is split into lines (normalizing a missing final newline first so the last logical row is not concatenated with the splice), the new row is inserted at that index, and the result is flushed through a **same-directory `tempfile.mkstemp` + `os.replace`** — an atomic swap that avoids torn reads during concurrent tooling. **KINETIC** exposes this as **`matryca-parse agent-write`**, resolving parent blocks by **`--alias`** (from the X-Ray state file) or **`--target-uuid`**.
 
 Both paths keep **existing topology intact** relative to their contract: append-only journaling never truncates prior bytes; the splicer only inserts one new child line at an AST-derived coordinate so a subsequent **LOGOS** parse remains deterministic.
 
@@ -374,7 +374,7 @@ Human-facing RAG (SYNAPSE enriched chunks, breadcrumbs, inherited properties) op
 
 #### Stateful session registry (`.matryca_xray_state.json`)
 
-X-Ray is designed for **stateless LLM toolchains**: each `agent-read` invocation is a fresh process, yet agents must still **write back** to blocks they only saw as `[n]` tokens. After **`generate_aliases`**, **KINETIC** persists the alias map to **`<graph_root>/.matryca_xray_state.json`** via **`SessionAliasRegistry.save_to_disk`**. A later **`matryca-parse agent-write --alias N`** loads that JSON with **`load_from_disk`**, resolves `N → uuid`, and hands off to **`append_child_to_node`**. The read/write pair therefore composes as **two independent CLI exits** without stuffing UUIDs into the model context — the filesystem holds session continuity.
+X-Ray is designed for **stateless LLM toolchains**: each `agent-read` invocation is a fresh process, yet agents must still **write back** to blocks they only saw as `[n]` tokens. After **`generate_aliases`**, **KINETIC** persists the alias map to **`<graph_root>/.matryca_xray_state.json`** via **`SessionAliasRegistry.save_to_disk`**. A later **`matryca-parse agent-write --alias N`** loads that JSON with **`load_from_disk`**, resolves `N → uuid`, and hands off to **`append_child_to_node`**. Malformed or empty state files yield a controlled CLI exit (empty registry for whitespace-only files; **`SessionAliasRegistryError`** for invalid JSON) rather than an uncaught traceback. The read/write pair therefore composes as **two independent CLI exits** without stuffing UUIDs into the model context — the filesystem holds session continuity.
 
 #### Session alias mechanics (`SessionAliasRegistry`)
 
@@ -557,7 +557,11 @@ Recursive and character-budget chunkers assume **approximately flat prose**. Log
 | :--- | :--- |
 | [`logseq_ast_primer.md`](logseq_ast_primer.md) | Before touching parser or serialization behavior |
 | [`COOKBOOK.md`](COOKBOOK.md) | Integration examples (Synapse, `LogseqGraph`, watcher) |
-| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | Picking a first PR ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
-| [`README.md`](README.md) | Documentation index (active vs historical) |
-| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | `uv` setup, `make all`, PR checklist |
+| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | Picking a first PR ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)); wave 1 tests landed in **v1.4.1**, wave 2 + bugfix regressions in **v1.4.2** |
+| [`README.md`](README.md) | Project overview and quickstart |
+| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | `uv` setup, `make all` (**450** pytest, ~**91%** coverage), PR checklist |
 | [`design-docs/README.md`](design-docs/README.md) | Warning before using historical DDD blueprints |
+
+### Quality gate (v1.4.2)
+
+Local and CI parity: `uv sync --all-extras` → `make lint` → `make check` → `make test`. The test gate enforces **≥80%** coverage on `src/logseq_matryca_parser` with **450** pytest cases as of **v1.4.2** (community wave 2 via [#58](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/58) plus agent-write / SYNAPSE regression tests). Dedicated modules: `tests/test_exceptions.py`, `tests/test_extract_changelog.py` — see [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) § Test suite.

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/docs/BUG_HUNT_REPORT.md

@@ -5,7 +5,9 @@
 **Strumenti:** analisi statica locale (graph-based), `make all`, `scripts/debug_pre_release.py`, probe Python ad hoc  
 **Riferimenti architetturali:** [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) (R. C. Martin), [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
-> **Stato risoluzione (2026-06-23):** tutti i **BUG-001…031** e le limitazioni **LIM-001/002** sono stati affrontati nel codice (vedi `CHANGELOG.md` `[Unreleased]`). **DEBT-001** (`iter_canonical_pages`, `page_for_node`) è implementato; debito architetturale residuo (SRP su `kinetic.py`, OCP embed strategy) resta backlog non bloccante.
+> **Stato risoluzione (2026-06-23):** tutti i **BUG-001…031** e le limitazioni **LIM-001/002** sono stati affrontati nel codice (vedi `CHANGELOG.md` **v1.4.0**). **DEBT-001** (`iter_canonical_pages`, `page_for_node`) è implementato; debito architetturale residuo (SRP su `kinetic.py`, OCP embed strategy) resta backlog non bloccante.
+>
+> **Aggiornamento test (2026-06-24, v1.4.1):** GFI-04 (`logseq_paths` fallback), GFI-14 (`normalize_logseq_timestamp`), GFI-03/05/06/09/12/13 e suite totale **378** pytest — vedi `CHANGELOG.md` **v1.4.1**.
 
 ---
 
@@ -13,8 +15,8 @@
 
 | Metrica | Esito |
 | :--- | :--- |
-| `make all` (Ruff + Mypy + 271 pytest) | **PASS** |
-| Coverage | **89.25%** (soglia 80%) |
+| `make all` (Ruff + Mypy + 378 pytest) | **PASS** |
+| Coverage | **90.18%** (soglia 80%; **378** pytest, v1.4.1) |
 | Round-trip corpus (`debug_pre_release.py`) | **19/19 OK** |
 | analisi statica `check` (cicli IMPORTS) | **0 cicli** |
 | analisi statica index | `logseq-matryca-parser` — 1074 embeddings, commit `7d3f77b` |
@@ -35,6 +37,10 @@ Nonostante la suite verde, l’analisi guidata da analisi statica e da probe run
 
 **Wave 8 (2026-06-23):** +6 bug via analisi statica `query(resolve_relative_page_link)`, `query(agent_press)`, probe backlink/namespace/tag case, `_export_json`, `resolve_asset_path` — chiusura mappatura moduli core.
 
+**Wave 9–10 (2026-06-29):** issue GitHub [#59](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/59)–[#71](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/71) — LENS ghost wikilinks, X-Ray state corrupto, SYNAPSE cyclic embed / unresolved semantics, kinetic dead code, watcher DIP, DX inglese, OCP embed refactor. Vedi `CHANGELOG.md` [Unreleased].
+
+**Wave 11 (2026-06-29):** [#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72) — `append_child_to_node` corrompe il Markdown quando l'ultima riga del file sorgente **non** termina con `\n` (splice sulla stessa riga → outline corrotto dopo `agent-write`). Probe: `impact(append_child_to_node)` → CLI `agent_write`. Paired test issue [#73](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/73).
+
 ---
 
 ## 2. Metodologia (Clean Architecture lens)
@@ -855,7 +861,7 @@ page_title_to_relative_path('') → PosixPath('untitled.md')
 write_logseq_page(page, dest) → scrive su pages/untitled.md (non crash)
 ```
 
-Comportamento diverso dalla nota precedente (non più `Errno 21` su path vuoto grazie al fallback `untitled.md`). Resta ambiguo per vault reali. Copertura test assente (GFI-04).
+Comportamento diverso dalla nota precedente (non più `Errno 21` su path vuoto grazie al fallback `untitled.md`). Resta ambiguo per vault reali. **Copertura:** GFI-04 chiuso in **v1.4.1** (`tests/test_logseq_paths.py`).
 
 ---
 
@@ -871,7 +877,7 @@ Valutazione secondo i principi di R. C. Martin, senza implicare che il codice si
 | **ISP** | Adapter SYNAPSE accede a `graph._page_for_node` (privato) | `synapse.py` L222 | Esporre `graph.page_for_node()` pubblico o protocol `GraphLookup`. |
 | **DIP** | Import lazy `logseq_paths` dentro metodo entity | `logos_core.py` L144 | Accettabile per evitare cicli; alternativa: spostare `resolve_asset_path` in use case layer. |
 | **Boundaries** | `assert bm is not None` in produzione | `synapse.py` L171, L190 | Sostituire con guard espliciti (Clean Code: fail fast leggibile, no assert in `-O`). |
-| **Error handling** | `except ValueError: pass` in normalizzazione timestamp | `logos_parser.py` L500 | Accettabile come fallback chain; aggiungere test GFI-14. |
+| **Error handling** | `except ValueError: pass` in normalizzazione timestamp | `logos_parser.py` L500 | Accettabile come fallback chain; **GFI-14 chiuso in v1.4.1** (`tests/test_logos_parser.py`). |
 | **ISP / encapsulation** | Consumer iterano `graph.pages.values()` raw | `kinetic.py`, `graph.py` | `iter_canonical_pages()` — DEBT-001; radice di BUG-002/006/007. |
 | **Use case completeness** | Nessun ramo *delete* in invalidazione incrementale | `graph.py` L641 | BUG-005; watcher senza delete/move — BUG-014 |
 
@@ -895,7 +901,7 @@ Linee non coperte con **alto rischio funzionale** (non solo numeri):
 | `logseq_markdown.py` | round-trip 4-space indent | **Alto** — BUG-021 |
 | `graph.py` | ghost nodes in search/query/agent-read | **Alto** — BUG-022 (con BUG-010) |
 | `kinetic.py` | `_export_langchain_enriched` alias dupes | **Alto** — BUG-006 |
-| `logseq_paths.py` | titolo vuoto, fallback graph root | **Basso** — GFI-04 |
+| `logseq_paths.py` | titolo vuoto, fallback graph root | **Risolto (v1.4.1)** — GFI-04 |
 
 ---
 
@@ -919,7 +925,7 @@ Linee non coperte con **alto rischio funzionale** (non solo numeri):
 | P3 | BUG-004 | Decisione ISO vs `%W` + doc/test | 1 h |
 | P4 | BUG-008, BUG-009, BUG-015, BUG-018–020, BUG-024–025, BUG-028–031 | case/`#`/namespace; export dup; asset path | backlog |
 | P5 | Debito | `graph.page_for_node` pubblico; rimuovere `assert` | 2 h |
-| P6 | Coverage | Chiudere GFI-01, GFI-02, GFI-14 | backlog |
+| P6 | Coverage | Chiudere GFI-01, GFI-02; wave 2 ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) | backlog |
 
 Dopo ogni fix: `make all` + `refresh dell'indice locale` + `impact` sul simbolo modificato.
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/docs/CODEQL.md

@@ -1,6 +1,6 @@
 # CodeQL code scanning
 
-**Logseq Matryca Parser** (v1.4.0+) uses **GitHub CodeQL default setup** for static analysis (SAST) on Python.
+**Logseq Matryca Parser** (v1.4.2+) uses **GitHub CodeQL default setup** for static analysis (SAST) on Python.
 
 ## Why there is no `codeql.yml` workflow
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/docs/COOKBOOK.md

@@ -127,7 +127,28 @@ if broken:
         print("broken ref in", node.clean_text)
 ```
 
-**CLI tip:** run `matryca-parse export` after `load_directory` — KINETIC scans canonical pages internally (v1.4.0).
+**CLI tip:** run `matryca-parse export` after `load_directory` — KINETIC scans canonical pages internally (since v1.4.0).
+
+---
+
+## Recipe 6 — Contributor test patterns
+
+Pick a scoped task from [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) (wave 2: [#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)), then mirror nearby tests:
+
+```bash
+uv sync --all-extras
+make all   # 378 pytest cases, ≥80% coverage gate
+```
+
+| Pattern | Example module | Test file |
+| :--- | :--- | :--- |
+| Pure helper | `normalize_logseq_timestamp` | `tests/test_logos_parser.py` |
+| CLI `--help` / errors | `kinetic.py` | `tests/test_kinetic.py` |
+| FORGE visitor | `ObsidianForgeVisitor` | `tests/test_forge.py` |
+| Release script | `scripts/extract_changelog.py` | `tests/test_extract_changelog.py` |
+| Exception hierarchy | `exceptions.py` | `tests/test_exceptions.py` |
+
+Test-only PRs should not change runtime behavior — update `CHANGELOG.md` under `[Unreleased]` only when user-visible behavior changes.
 
 ---
 

logseq_matryca_parser-1.4.2/docs/GOOD_FIRST_ISSUES.md

@@ -0,0 +1,130 @@
+# Good First Issues
+
+Welcome! These tasks are scoped for a **first pull request** — mostly tests and documentation, with a few small CLI/FORGE features. Each has clear acceptance criteria and avoids changes to `logos_core.py` without prior design discussion.
+
+**Before you start:**
+
+1. Read [`CONTRIBUTING.md`](../CONTRIBUTING.md), [`ARCHITECTURE.md`](ARCHITECTURE.md) (skim the module map), and [`logseq_ast_primer.md`](logseq_ast_primer.md) if you touch parsing.
+2. Run `uv sync --all-extras` then `make all` to confirm a green baseline.
+3. Comment on the GitHub issue you want to claim so we avoid duplicate work.
+4. Open **one PR per issue**, branched from `main` (`Fixes #NNN`).
+
+Integrators may prefer [`COOKBOOK.md`](COOKBOOK.md) for copy-paste recipes before picking a code task.
+
+Filter open good-first issues on GitHub: [good first issue label](https://github.com/MarcoPorcellato/logseq-matryca-parser/labels/good%20first%20issue).
+
+---
+
+## Tier 1 — Tests only (~1–3 hours)
+
+Ideal first PR: no production code changes, copy patterns from nearby tests.
+
+| ID | Title | Skills | Issue |
+| :--- | :--- | :--- | :--- |
+| GFI-01 | `test(kinetic): add CLI error-path coverage for missing graph and optional deps` | pytest, Typer | [#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19) |
+| GFI-02 | `test(kinetic): cover agent-write validation errors` | pytest, CLI | [#20](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/20) ✅ |
+| GFI-03 | `test: add dedicated tests for exception hierarchy` | pytest | [#21](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/21) ✅ |
+| GFI-04 | `test(logseq_paths): cover empty title and fallback graph-root derivation` | pytest | [#22](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/22) ✅ |
+| GFI-05 | `test: add unit tests for extract_changelog release helper` | pytest | [#23](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/23) ✅ |
+| GFI-06 | `test(agent): add CLI test for agent-read --query filter` | pytest, CLI | [#24](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/24) ✅ |
+| GFI-17 | `test(logseq_markdown): unit tests for detect_tab_size_from_markdown` | pytest | [#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43) ✅ |
+| GFI-18 | `test(synapse): table-driven tests for _strip_markdown_for_embedding` | pytest | [#44](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/44) ✅ |
+| GFI-19 | `test(graph): unit tests for _normalize_relative_link_target helper` | pytest | [#45](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/45) ✅ |
+| GFI-20 | `test(extract_changelog): cover main() CLI exit codes and stdout` | pytest | [#47](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/47) ✅ |
+| GFI-21 | `test(agent_writer): cover LogseqConfigReader format_timestamp and config fallback` | pytest, CLI | [#48](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/48) ✅ |
+| GFI-22 | `test(lens): classify journal and project nodes in GraphVisualizer` | pytest | [#49](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/49) ✅ |
+| GFI-23 | `test(graph): unit tests for backlink alias token helpers` | pytest | [#50](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/50) ✅ |
+| GFI-24 | `test(synapse): direct build_synapse_metadata schema coverage` | pytest | [#51](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/51) ✅ |
+| GFI-27 | `test(lens): regression test for unresolved wikilink ghost nodes` | pytest | [#62](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/62) |
+| GFI-28 | `test(agent_press): cover malformed SessionAliasRegistry JSON on load` | pytest, CLI | [#63](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/63) |
+| GFI-31 | `test(synapse): table-driven embed expansion edge cases` | pytest | [#71](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/71) |
+| GFI-34 | `test(agent_writer): append_child without trailing source newline` | pytest, CLI | [#73](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/73) |
+
+---
+
+## Tier 2 — Documentation & DX (~2–4 hours)
+
+| ID | Title | Skills | Issue |
+| :--- | :--- | :--- | :--- |
+| GFI-07 | `docs: add examples cookbook for common integration recipes` | Markdown, Python snippets | [#25](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/25) *(initial [`COOKBOOK.md`](COOKBOOK.md) landed — extend or polish)* |
+| GFI-08 | `docs: add docs/README.md index warning about historical design-docs` | Markdown | [#26](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/26) *(index exists — verify links and `design-docs/README.md`)* |
+| GFI-09 | `test(kinetic): assert per-command --help renders without error` | pytest, Typer | [#27](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/27) ✅ |
+| GFI-10 | `docs(examples): translate run_demo.py comments to English and align with package imports` | Python, docs | [#28](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/28) *(done in repo — close if satisfied)* |
+
+---
+
+## Tier 3 — Small bounded features (~3–6 hours)
+
+| ID | Title | Skills | Issue |
+| :--- | :--- | :--- | :--- |
+| GFI-11 | `feat(cli): add scan --broken-refs flag using LogseqGraph.get_broken_references()` | Typer, graph API | [#29](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/29) |
+| GFI-12 | `test(forge): add direct ObsidianForgeVisitor visitor tests` | pytest, FORGE | [#30](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/30) ✅ |
+| GFI-13 | `test(parser): table-driven tests for clean_node_content helper` | pytest | [#31](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/31) ✅ |
+| GFI-14 | `test(parser): unit tests for normalize_logseq_timestamp edge inputs` | pytest | [#32](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/32) ✅ |
+| GFI-25 | `test(forge): direct MarkdownForgeVisitor property and id filtering` | pytest, FORGE | [#46](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/46) ✅ |
+| GFI-26 | `test(forge): direct JSONForgeVisitor nested stack behavior` | pytest, FORGE | [#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52) ✅ |
+| GFI-29 | `fix(lens): skip ghost page nodes for unresolved wikilinks` | pytest, LENS | [#59](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/59) |
+| GFI-30 | `fix(agent): handle corrupt X-Ray state files without crashing agent-write` | pytest, CLI | [#60](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/60) |
+| GFI-32 | `chore(synapse): replace Italian ImportError strings with English DX messages` | docs, SYNAPSE | [#69](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/69) |
+| GFI-35 | `fix(agent_writer): append_child corrupts files missing trailing newline` | pytest, CLI | [#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72) |
+
+---
+
+## Mentor issues (slightly larger)
+
+| ID | Title | Note | Issue |
+| :--- | :--- | :--- | :--- |
+| GFI-15 | `feat(forge): add minimal CSV exporter` | Follow existing JSON visitor pattern in `forge.py` | [#33](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/33) |
+| GFI-16 | `docs: RFC Ollama one-click local RAG` | Design-only RFC; implementation in follow-up issues | [#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34) *(draft at [`rfc/OLLAMA_RAG.md`](rfc/OLLAMA_RAG.md))* |
+| GFI-33 | `refactor(synapse): extract embed-expansion strategy (OCP)` | Mentor — strategy pattern | [#70](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/70) |
+
+---
+
+## Recommended starter pack (wave 3)
+
+From local code study (waves 9–10) — tests and small fixes with clear repros:
+
+| Priority | ID | Why |
+| :---: | :--- | :--- |
+| 1 | GFI-31 ([#71](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/71)) | SYNAPSE embed table tests — pairs with #65/#66 |
+| 2 | GFI-28 ([#63](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/63)) | JSON fixtures for agent session state |
+| 3 | GFI-27 ([#62](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/62)) | Single-file LENS regression |
+| 4 | GFI-32 ([#69](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/69)) | Small English DX fix in `synapse.py` |
+| 5 | GFI-01 ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)) | CLI error-path coverage still open |
+
+**Bugs (maintainer / mentor):** [#65](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/65) cyclic embed duplication, [#59](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/59) LENS ghosts, [#60](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/60) corrupt X-Ray state, [#72](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/72) agent-write newline splice.
+
+Wave 2 (GFI-17–GFI-26, GFI-02) is **complete** ([#58](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/58)).
+
+---
+
+## Test suite (v1.4.2+)
+
+| Module | Test file |
+| :--- | :--- |
+| Parser (LOGOS) | `tests/test_logos_parser.py` |
+| Graph & watcher | `tests/test_graph.py` |
+| SYNAPSE adapters | `tests/test_synapse.py` |
+| FORGE exporters | `tests/test_forge.py` |
+| KINETIC CLI | `tests/test_kinetic.py` |
+| Agent read/write | `tests/test_agent_press.py`, `tests/test_agent_writer.py` |
+| Paths & markdown | `tests/test_logseq_paths.py`, `tests/test_logseq_markdown.py` |
+| Release helpers | `tests/test_extract_changelog.py`, `tests/test_package_version.py` |
+| Exceptions | `tests/test_exceptions.py` |
+
+Run the full gate: `make all` (**450** pytest cases after wave 2 + bugfix regressions).
+
+## Out of scope for a first PR
+
+- Changes to Pydantic models in `logos_core.py` (open a design issue first).
+- Desktop GUI ([#3](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)) — multi-sprint epic.
+- Bulk mldoc parity work in `logos_parser.py` — high regression risk.
+- Obsidian namespace path alignment — cross-tool behavior, needs design.
+
+---
+
+## Definition of Done (all tiers)
+
+- [ ] `make all` passes locally (Ruff, Mypy, Pytest ≥80% coverage).
+- [ ] PR links the GitHub issue and describes the change briefly.
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` **only** for user-visible behavior changes.

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/docs/README.md

@@ -8,8 +8,8 @@ Use this page to find **active** documentation. Files under [`design-docs/`](des
 | :--- | :--- | :--- |
 | [`ARCHITECTURE.md`](ARCHITECTURE.md) | Contributors, integrators | LOGOS, SYNAPSE, `LogseqGraph`, agents, data flow |
 | [`logseq_ast_primer.md`](logseq_ast_primer.md) | Parser contributors | Logseq Spatial Markdown domain rules |
-| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | New contributors | Curated starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
-| [`COOKBOOK.md`](COOKBOOK.md) | Integrators | Copy-paste recipes (Synapse, graph query, watcher, agents) |
+| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | New contributors | Curated starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52); wave 1 in **v1.4.1**, wave 2 + bugfix tests in **v1.4.2**) |
+| [`COOKBOOK.md`](COOKBOOK.md) | Integrators | Copy-paste recipes (Synapse, graph query, watcher, agents, contributor test patterns) |
 | [`RELEASE_PROCESS.md`](RELEASE_PROCESS.md) | Maintainers | Semver, tag, and PyPI publish checklist |
 | [`CODEQL.md`](CODEQL.md) | Maintainers | CodeQL default setup notes |
 | [`BUG_HUNT_REPORT.md`](BUG_HUNT_REPORT.md) | Maintainers, contributors | Local static analysis bug audit (Clean Architecture lens, runtime evidence) |

logseq_matryca_parser-1.4.2/docs/design-docs/README.md

@@ -0,0 +1,13 @@
+> ⚠️ **Notice:** For the active documentation index, please refer to the main [README.md](../../README.md).
+
+# Historical design documents
+
+For contributors: These files are Document-Driven Development blueprints from the initial Logos Protocol scaffolding. They explain design intent and mldoc parity research — they are not the live implementation contract.
+
+For current architecture and APIs, use:
+
+* [ARCHITECTURE.md](../ARCHITECTURE.md) — active system design
+* [logseq_ast_primer.md](../logseq_ast_primer.md) — Logseq Spatial Markdown domain rules
+* [README.md](../../README.md) — documentation index
+
+Each file in this folder includes the same historical banner at the top. When implementing parser behavior, prefer tests in tests/test_logos_parser.py and OFFICIAL_MLDOC_SPECS.md as reference, then confirm against the running code in src/logseq_matryca_parser/.

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.2}/docs/logseq_ast_primer.md

@@ -215,7 +215,7 @@ If you feed Logseq Markdown into `RecursiveCharacterTextSplitter` (LangChain) or
 
 The **Logos Protocol** solves this by walking the AST deterministically, isolating properties, shielding dead-zone literals, and using the `SYNAPSE` adapter to export native LangChain `Document` or LlamaIndex `TextNode` objects. Every generated object retains its exact hierarchical lineage in the metadata, feeding your local LLM perfectly structured data.
 
-For vault-wide navigation (aliases, backlinks, namespace shadowing, assets), load the graph with **`LogseqGraph`** — see the [README](../README.md) and [CHANGELOG](../CHANGELOG.md) (graph parity from **v1.2.0**; **v1.3.0** adds watcher debounce, `strict_refs`, public API exports, and LlamaIndex spatial relationships; **v1.4.0** adds canonical page iteration, case-insensitive tag/search, watcher delete/move handling, and SYNAPSE embed safety).
+For vault-wide navigation (aliases, backlinks, namespace shadowing, assets), load the graph with **`LogseqGraph`** — see the [README](../README.md) and [CHANGELOG](../CHANGELOG.md) (graph parity from **v1.2.0**; **v1.3.0** adds watcher debounce, `strict_refs`, public API exports, and LlamaIndex spatial relationships; **v1.4.0** adds canonical page iteration, case-insensitive tag/search, watcher delete/move handling, and SYNAPSE embed safety; **v1.4.1** adds community test coverage for parser helpers, CLI agents, and FORGE visitors — **378** pytest cases, no runtime API changes).
 
 ---
 

logseq_matryca_parser-1.4.2/metrics/index.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "partition": "calendar_quarter",
+  "quarters": [
+    "2026-Q2"
+  ],
+  "legacy_migrated": true,
+  "updated_at": "2026-06-29"
+}