WORK-593
ID:WORK-593Status:ready

Stamp-on-insert in the editor, and marking the reference pages

SPEC-134 phase 3, minus the validation rail. The feature exists after WORK-592; this is the part that gets it used.

Two pieces, both small:

Priority:mediumComplexity:simpleMilestone:v0.37.0Source:SPEC-134
claude/data-rune-custom-queries-h8qg72 View source

Criteria completion

Criteria completion: 0 of 5 (0%) checked; tracking started on Sep 22, no incremental history yet0%25%50%75%100%Sep 22Oct 11

Tracking started Sep 22 — check back for trends.

Branches 4
History 1
  1. 0fb6810
    Created (ready)by bjornolofandersson

Adoption is selective on purpose (D8)

Marking every snippet would make --check permanently noisy and train everyone to ignore it. Authors mark the references whose prose makes specific claims about the code beside them.

The selection is the work here, not the stamping — refrakt snippet review <page> does the mechanical part. Reading a page and deciding whether its paragraphs actually assert something about the slice is what this item is for.

The natural starting set is the pages WORK-590 migrated, since those are the invocations someone has just looked at closely — but migration and marking are different claims and must stay different commits.

The validation rail is not here

SPEC-134 phase 3 lists the editor validation rail alongside these two. That rail is WORK-395's, which is unmilestoned and outside this milestone. Stale markers reach their audience through the dev-server diagnostics WORK-575 shipped and through --check; the rail is an improvement on that, not a prerequisite for it.

Acceptance Criteria

  • The block editor stamps reviewed when inserting a snippet, file-ref or expand
  • A snippet inserted through the editor whose target has not changed does not immediately report stale
  • The reference pages whose prose makes specific claims about a quoted slice are marked, with the selection recorded rather than exhaustive
  • Marking is a separate commit from WORK-590's migration
  • --check runs clean across site/content after the marking pass

Approach

Stamp-on-insert reuses WORK-592's stamping path rather than recomputing a hash in the editor package — the normalization must not have two implementations.

For the marking pass, work page by page and write down why each page was or was not marked. That record is what stops the next person marking everything.

Blocked by

  • WORK-592 — the stamping path and the review CLI

Notes

If --check is noisy immediately after this lands, the remedy is unmarking pages, not loosening normalization. A marker that fires on a page whose prose did not actually depend on the slice is a selection error, and normalization is the wrong place to fix it.

References

  • SPEC-134 — phase 3, D8 (opt-in per invocation, never bulk)
  • WORK-592 — the stamping path
  • WORK-395 — the editor validation rail, out of scope here
  • WORK-575 — the dev-server diagnostics markers surface through today