Answer prose round 1: 0 🔴, 6 🟡 (0 misread); say each pair's use once in the module docstring, name what the changelog entry keeps, and make item 391 stand alone

This commit is contained in:
2026-11-16 13:16:50 +01:00
parent bac9cf9756
commit f2b7eb7fd2
4 changed files with 12 additions and 15 deletions
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased
- A tool can now convert ADF to markdown and back without losing anything Jira stores. `adf_codec.convert` has `markdown_to_adf_lossless`, `adf_to_markdown_lossless` and `adfs_to_markdown_lossless`, which keep every block's `localId` and the empty paragraphs Jira uses for spacing, so a Jira or Confluence document read and saved back unedited comes back identical. The portable functions stay for new text and for markdown shown to a person. No tool uses the lossless functions yet.
- `adf_codec.convert` can now convert ADF to markdown and back without losing a block's `localId` or the empty paragraphs Jira uses for spacing, so a Jira or Confluence document read and saved back unedited comes back identical: `markdown_to_adf_lossless`, `adf_to_markdown_lossless` and `adfs_to_markdown_lossless`. No tool calls them yet.
- A config whose `plan` names a Jira epic must now set `jira-score-formula` and `jira-score-bar`, and fails to load without them. `todo-item add` scores the item by them, refuses one under the bar unless it is exempt, and ranks the new issue among the issues the loop filed: questions first, then security findings, then by score. A person's issues keep their rank.
- `todo-item edit` and `move` work on a plan kept in a Jira epic. They change only an issue the loop filed, and never a link. Of an issue a person filed, `edit` sets only the scores, and posts the new `--comment` on the issue to tell the team why; a plan in a file takes the flag and keeps no comment.
- A release someone else cut while it still held plan items no longer stops the loop: those items count as the next release's, `chunk-preflight` tells the worker to move them there, and `loop-claude` routes on them. Where the plan names no later release and `todo.md` named none since the cut, the loop still asks which release they belong to.
+8 -10
View File
@@ -4,7 +4,7 @@ It runs @larvit/adf-codec, a Node package, in a throwaway container that holds n
adf-codec has two pairs of calls, and each function here names the one it runs:
- The lossless pair, `*_lossless`, for a document that already exists in Jira or Confluence and is edited and saved back. It keeps each block's localId and the empty paragraphs Jira uses for spacing, so a document read and saved unedited comes back identical.
- The portable pair, with no suffix, for new text written from scratch, and for markdown shown to a person. It drops both, so saving a document that exists changes it.
- The portable pair, with no suffix, for new text written from scratch, and for markdown shown to a person. It drops the localId and the empty paragraphs, so saving a document that exists changes it.
"""
import contextlib
import dataclasses
@@ -35,7 +35,7 @@ class Ran:
err: str
# Runs the shim in the given mode (`to-adf`, `to-markdown` or either with `-lossless` after it) on a text, or fails to run it.
# Runs the shim in the given mode (`to-adf`, `to-markdown`, `to-adf-lossless` or `to-markdown-lossless`) on a text, or fails to run it.
Run = typing.Callable[[str, str], Ran | Failure]
# Runs a docker command line on a text, in at most the given seconds, or fails to run it.
Docker = typing.Callable[[list[str], str, int], Ran | Failure]
@@ -190,32 +190,30 @@ def one_markdown(texts: list[str] | Refused | Failure) -> str | Failure:
def markdown_to_adf(markdown: str, run: Run = container_run) -> dict[str, typing.Any] | Failure:
"""The ADF document for new markdown, by the portable pair: for text written from scratch. It can't carry a document that exists back unchanged; use markdown_to_adf_lossless."""
"""The ADF document for the markdown, by the portable pair."""
return to_adf("to-adf", markdown, run)
def markdown_to_adf_lossless(markdown: str, run: Run = container_run) -> dict[str, typing.Any] | Failure:
"""The ADF document for markdown that adf_to_markdown_lossless or adfs_to_markdown_lossless wrote, by the lossless pair: for saving an existing Jira or Confluence document back. Unedited, it gives back the document that was read."""
"""The ADF document for the markdown, by the lossless pair."""
return to_adf("to-adf-lossless", markdown, run)
def adfs_to_markdown(documents: list[dict[str, typing.Any]], run: Run = container_run) -> list[str] | Refused | Failure:
"""The markdown for each ADF document, in their order, by the portable pair, from one container run, so a caller with many documents pays one container start.
For markdown shown to a person; the text can't be saved back without changing the document, so use adfs_to_markdown_lossless to edit one."""
"""The markdown for each ADF document, in their order, by the portable pair, from one container run, so a caller with many documents pays one container start."""
return to_markdowns("to-markdown", documents, run)
def adfs_to_markdown_lossless(documents: list[dict[str, typing.Any]], run: Run = container_run) -> list[str] | Refused | Failure:
"""The markdown for each ADF document, in their order, by the lossless pair, from one container run: for documents that exist in Jira or Confluence and are edited and saved back with markdown_to_adf_lossless."""
"""The markdown for each ADF document, in their order, by the lossless pair, from one container run."""
return to_markdowns("to-markdown-lossless", documents, run)
def adf_to_markdown(document: dict[str, typing.Any], run: Run = container_run) -> str | Failure:
"""The markdown for the ADF document, by the portable pair: for showing it to a person, not for saving it back."""
"""The markdown for the ADF document, by the portable pair."""
return one_markdown(adfs_to_markdown([document], run))
def adf_to_markdown_lossless(document: dict[str, typing.Any], run: Run = container_run) -> str | Failure:
"""The markdown for the ADF document, by the lossless pair: for editing it and saving it back with markdown_to_adf_lossless."""
"""The markdown for the ADF document, by the lossless pair."""
return one_markdown(adfs_to_markdown_lossless([document], run))
+1 -2
View File
@@ -1,8 +1,7 @@
// Converts between markdown and ADF with @larvit/adf-codec. The mode is the one argument:
// to-adf stdin is markdown, stdout is the ADF document as JSON
// to-markdown stdin is a JSON array of ADF documents, stdout a JSON array of their markdown texts, in their order
// The portable calls behind those two drop each block's localId and empty paragraphs. The same two modes with the suffix
// -lossless, to-adf-lossless and to-markdown-lossless, call adf-codec's lossless pair, which keeps both.
// to-adf-lossless, to-markdown-lossless the same, through adf-codec's lossless pair in place of its portable pair
// Exit 0: stdout holds the answer. Exit 2: adf-codec refused the input, and stdout holds {"error": {code, message, path, position?}},
// with "index", the refused document's place in the array, beside "error" in to-markdown.
// Exit 1: the shim could not run, and stderr says why.
+2 -2
View File
@@ -86,9 +86,9 @@ The config key for the parallel limit is a syntax users write, so a panel seated
### 391. Read and write a Jira epic issue's description and a Confluence record page through the lossless pair, so saving an unedited document leaves it unchanged.
Follows item 390. `plan_store/jira_epic.py` reads an issue's description and writes it back on an edit, and `record_store/confluence_page.py` reads a page and saves it back; both use the portable pair, which drops each block's `localId` and the empty paragraphs Jira uses for spacing. Use `adfs_to_markdown_lossless` and `markdown_to_adf_lossless` where a tool reads a document and writes it back. `record_store/jira_description.py` only reads, to show a person: it stays on the portable pair.
`plan_store/jira_epic.py` reads an issue's description and writes it back on an edit, and `record_store/confluence_page.py` reads a page and saves it back; both use the portable pair, which drops each block's `localId` and the empty paragraphs Jira uses for spacing. `record_store/jira_description.py` only reads, to show a person: it stays on the portable pair.
Open before building: the lossless markdown is less readable than the portable one (upstream larvit/adf-codec#185), and agents and the judge read the plan's details from it, so the item must show how a detail stays readable, perhaps by reading portable and writing lossless only on a document an edit changes. Test that an unedited issue and page save back identical. Filed for 0.12.0 because R is above 5 and the item ships alone; the release is the human's call.
Open before building: the lossless markdown is less readable than the portable one (upstream larvit/adf-codec#185), and agents and the judge read the plan's details from it. Decide how a detail stays readable, for example by reading lossless and showing a person a portable view. Test that an unedited issue and page save back identical. The item ships alone because its R is above 5.
### 319. Start a fresh session with a brief of the chunk when a rung step changes the worker's model, in place of resuming the old session.