A comment on a whole document is a blunt instrument when what you mean is "this paragraph is wrong". For markdown artifacts, Kythene lets you review block by block - and the feedback survives the next version.
Flag a block, thread on it
Open a markdown artifact in the app and each addressable block - heading, paragraph, list item, quote, code block, table - can carry:
- a status, and
- a comment thread.
The five statuses:
| Status | Means |
|---|---|
| needs review | look at this again |
| needs work | changes required |
| done | the needed action is complete |
| approved | signed off |
| reject / remove | this block should go |
Each flag records whether it was set by a human or by an instance, so a document reviewed by an agent is distinguishable at a glance from one a person went through.
Why it survives a re-publish
Every block gets an anchor derived from its own content - a hash of the normalised text, plus which occurrence it is when identical blocks repeat. The anchor is a pure function of what the block says, so it's stable across re-ordering and unchanged by edits elsewhere in the document.
The practical consequence: publish a new version with three paragraphs rewritten and the feedback on the other forty still points at the right paragraphs. Feedback on a block that did change is automatically flipped back to needs review, because a comment about text that no longer exists shouldn't read as settled.
This is the bit that makes iterative review with an AI actually work. Your instance rewrites the document, and the reviewer sees exactly which of their points are still open, rather than a fresh document with all the context gone.
And when a block is rewritten so completely that nothing matches - the "you were right, here's the new version" case - its thread isn't dropped either. It moves to a Rewritten since section on the document, still carrying the text it originally referred to, so you can see your point was acted on and close it or reply. The case where the feedback matters most is the one that used to vanish.
How it fits the loop
"Publish v2 of the spec - I've addressed the three blocks marked needs work."
"Check the spec for open block feedback and fix the ones marked needs work."
An instance can read the open flags, act on them, and push a new version. The blocks it fixed change, so their old feedback is re-raised for the human to confirm; the blocks it didn't touch keep whatever status they had.
From the CLI:
kythe review <collection-id> --artifact <artifact-id> --block "the exact block text" --status needs_work --comment "this contradicts the retry policy"The block can be named by its anchor or by quoting its text.
Access
There's no separate permission to manage. Block feedback resolves through the artifact itself, so anyone who can see the artifact can read its feedback, and anyone who can comment on the work can flag a block - guests on a share code included.