Problem and missing tool
Agents need a safe signer-authorized native block editing operation. Current exposed document updates replace Markdown bodies. Multiline evidence paragraphs can be split/reparented even when block identity comments are preserved. This blocks evidence cleanup in the User Story Maps project.
Owner: Eric Vicenti, assigned at Horacio's request. No fix is claimed. The HM protocol has native editing primitives; the missing piece is a tested authenticated agent interface connecting native changes to an authorized signer.
Reproduction — disposable fixture only
Read the native tree of the original generated snapshot. Do not reproduce destructively on this document or original design sources.
Create a fixture with the same shape: nested lists containing Paragraph blocks with multiline literal code, a leading bold structural label and a source-link annotation. Eight paragraphs in this example have multiline code. Capture native IDs, types, tree/order, text, annotations, URLs and metadata.
Read Markdown, remove only generated prefixes such as Paragraph, Heading and Code, and preserve every identity comment, indentation and link. Submit a full-body Markdown document update.
Compare native JSON after publication with the intended prefix-only transformation.
Actual versus expected
The affected published version has 134 native blocks versus 50 originally: 84 additional IDs, zero missing original IDs. Original URL targets and their multiplicities remain in the native tree; metadata is unchanged. However, text and source-link associations were split/reparented. Block ID JJVioR2a, for example, originally held the full exclusiveAnnotationProperties code example and source annotation; afterward it held only its opening line and no annotations.
Expected: remove only the prefix and its bold annotation, shifting remaining annotation offsets. Preserve all native IDs, types, hierarchy/order, evidence text, URL occurrences and metadata. A label cleanup must not add blocks or move content.
Suggested solution
Expose an authenticated native document-change tool backed by an available authorized signer, with capability checks, expected base version, stale-version rejection, dry-run native diff and committed-version receipt.
Support native replaceBlock/moveBlock/deleteBlock operations rather than Markdown round trips. Validate annotation offsets and preserve untouched blocks. The investigation found PrepareDocumentChange and SDK publication primitives but no tested end-to-end signer bridge in the exposed agent tools.
Add regression tests for multiline code inside Paragraph blocks, nested evidence lists and mixed annotations. Make Markdown updates lossless for supported structures or reject unsafe structural transformations before publication.
Repair the affected generated snapshot using its original native tree plus the intended prefix-only edit. Re-read the current head; restore original text/annotations and parent/order, move retained blocks out of introduced parents as required, then delete exactly the 84 introduced blocks. Preserve the original 50 IDs. Do not blindly reimport the Markdown backup.
Verify that repair before resuming the remaining snapshot cleanup. Do not edit original design sources, schemas or review decisions.
Acceptance criteria
An agent can preview and publish an authorized native edit with an expected base version; stale and unauthorized edits fail safely.
Prefix-only edits preserve IDs/types/tree/order, evidence, URLs and metadata, with correctly shifted annotations.
The reproduction fixture acquires no extra blocks, including all eight multiline evidence paragraphs.
The affected snapshot is restored to the intended 50-block tree and verified at the committed version.
Remaining generated snapshots can be cleaned and read back without structural drift; original source documents remain unchanged.
Incident scope and repair artifacts
The final scan covered 188 generated documents: 2,636 labels across 142 documents. Six cleanups removed 131 labels with successful checks. The seventh removed 43 labels but failed structural verification. Bulk edits stopped, leaving 2,462 labels in 135 documents. These are incident-time counts, not a fresh scan.
Clerk retained original/current native JSON, native diff and an unpublished repair target in its memory directory story-maps/implementation/presentation-cleanup/. These are internal artifacts, not shared attachments. The version-pinned public documents above provide reproducible evidence. The target preserves the original 50-block tree while removing exactly 43 labels (16 Heading, 19 Paragraph, eight Code) and shifting annotations. No repair has been published.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime