From dccd8dcf3a4d482ec765388c18cfce3f38acffa9 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Fri, 2 Oct 2026 17:41:00 +0200 Subject: [PATCH] Answer the prose review's second round and the product-owner review's second --- AGENTS.md | 4 ++-- README.md | 22 +++++++++++----------- todo.md | 7 ++++--- 3 files changed, 17 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f3ab460..1501d2f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -143,7 +143,7 @@ Per chunk: result exists for the commit under review, or when the diff since that result cannot affect it (docs-only) — re-run only what its own findings or fixes invalidate. 3. Merge the PR (standing authorization, this repo only, granted by the maintainer through the - `0.2.0` release), delete the chunk's items from `todo.md` — what a consumer sees of it is + `0.2.0` release), delete the chunk's items from `todo.md` — what a consumer sees of them is reworded for them into `CHANGELOG.md`'s `## Unreleased` — report, stop. Reserved for the maintainer whatever any rule here says: changing `version` in `package.json` (a @@ -172,7 +172,7 @@ The verdict lands in `docs/decisions.md`. ### Findings, numbers and empty releases -- A finding inside the chunk's items is fixed in the chunk. Outside it, a new `todo.md` item, always +- A finding inside the chunk's items is fixed in the chunk. Outside them, a new `todo.md` item, always in a release, weighed against every item on that release by the personas and `docs/decisions.md` §Plain markdown is a flavour of the grammar through §Names stay text — an item it outweighs moves later. A weighing no entry decides is asked as a gap. diff --git a/README.md b/README.md index 33a9ad1..2341e7a 100644 --- a/README.md +++ b/README.md @@ -38,8 +38,8 @@ The most useful ADF conversion library available, by these goals in priority ord ## Audience Application developers embedding the library, in four personas. All four rely on the guarantees -below and on `code` being a closed list; none may rely on an error message's wording, which is -free text. +below and on an error's `code` being a closed list; none may rely on an error message's wording, +which is free text. - **Viewer/editor app** — shows a document, lets a human edit, posts it back. Relies on the round-trip holding for whatever the site's editor wrote, unknown node types included, and on a @@ -70,8 +70,8 @@ if (result.ok) { ``` Serves Goals 1, 2 and 7. Pure functions, each taking a whole document and returning a whole -result; no I/O, no configuration. Every conversion goes through ADF, so `markdownToHtml` keeps -exactly what ADF holds. +result; no I/O, no configuration. `markdownToHtml` and `htmlToMarkdown` convert through ADF, so +they drop whatever ADF cannot hold. ```ts adfToMarkdown(doc: AdfDocument): Result @@ -83,8 +83,8 @@ plainMarkdownToAdf(markdown: string): Result adfToHtml(doc: AdfDocument): Result // 0.2.0 htmlToAdf(html: string): Result // 0.2.0 -markdownToHtml(markdown: string): Result // 0.2.0, via ADF -htmlToMarkdown(html: string): Result // 0.2.0, via ADF +markdownToHtml(markdown: string): Result // 0.2.0 +htmlToMarkdown(html: string): Result // 0.2.0 ``` `Result` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws. @@ -201,9 +201,9 @@ Serves Goals 1, 3 and 4. - `markdownToAdf(adfToMarkdown(doc))` equals `doc` — unknown node types included, carried opaquely ([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#unknown-nodes-ride-the-carry)). -- Markdown means what the CommonMark spec says — and, at `0.2.0`, well-formed HTML what the HTML - standard parses — both in what this library reads and in what a conforming parser reads back - from its output; the bullets below name every exception. +- Markdown this library reads, and markdown it writes, means what the CommonMark spec says; from + `0.2.0`, well-formed HTML means what the HTML standard says, read or written. The bullets below + name every exception. - Plain CommonMark is valid input to `markdownToAdf` apart from the raw HTML `unmappable-html` names, with three carve-outs — literal text matching directive, pipe-table or strikethrough syntax is claimed (escapable — `spec/flavour.md`) — and one gap: a CommonMark image fits only as @@ -242,7 +242,7 @@ Serves Goals 1, 3 and 4. ## The package Serves Goal 7. ESM only, no runtime dependencies, public npm. Built JavaScript with `.d.ts` -beside it. Pure ECMAScript at an ES2022 baseline, reaching for no host API; the test suite runs under Node, -Deno and Bun, and a headless Firefox converts the corpus through the built entrypoint. +beside it. Pure ECMAScript at an ES2022 baseline, reaching for no host API; the test suite runs +under Node, Deno and Bun, and a headless Firefox converts the corpus through the built entrypoint. Contract: [`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#any-es2022-engine), §Any ES2022 engine to §Public on npm. diff --git a/todo.md b/todo.md index c017739..4424c54 100644 --- a/todo.md +++ b/todo.md @@ -65,9 +65,10 @@ `description` naming both, the lossy pair, and the flavours it writes and reads by name — GitHub Flavored Markdown's alerts and task lists, Obsidian Flavored Markdown's callouts — so a search for either finds the package. -- **44 — Delete `AGENTS.md` §7's empty-release bullet, leaving the maintainer's global working loop - to rule it.** "An earliest release with no items left and nothing shipped toward it is planned as - the chunk" restates that loop, in a sentence its own prose rules ban. +- **44 — Cut `AGENTS.md` §7's empty-release bullet to what the maintainer's global working loop + leaves open.** The bullet restates that loop's rule for an empty release, in a sentence + `~/.claude/CLAUDE.md` → "Prose" bans; keep only its weighing by the personas and + `docs/decisions.md`, which the global loop does not hold. ## 0.3.0