Skip to content

fix(review): make repo-doc refresh diff-aware and preserve manual edits #3004

Description

@JSONbored

Context

Part of the repo-specific CLAUDE.md/AGENT.md generation roadmap. The scheduled/on-demand refresh issue re-runs generation on an interval; without this issue, each refresh would wholesale-regenerate and overwrite the target file, clobbering any hand-edits a maintainer made to the previously-generated content after merging it. This issue makes refresh incremental: it diffs newly generated content against the current file, preserves sections the operator has clearly hand-edited, and proposes only the meaningfully changed portions.

Goal

Make refresh diff-aware so operator hand-edits to a previously generated file survive subsequent automated refreshes.

Requirements

  • Generated files carry a clear generated-content marker block (start/end markers) demarcating the portion this engine owns versus content outside the markers, which is treated as permanently manual and never touched by refresh.
  • Refresh recomputes only the marked, generated section from the current repo profile and leaves everything outside the markers untouched, byte-for-byte.
  • If the marker block itself has been manually altered or removed, refresh fails closed (skips the automated PR and flags for manual review) rather than guessing at intent.
  • Diffing logic is shared with the no-meaningful-change short-circuit from the scheduled-refresh issue so the two do not implement divergent diff semantics.
  • Works for both CLAUDE.md/AGENT.md and any generated skill files.

Deliverables

  • Generated-content marker convention defined and applied by the generation engine
  • Refresh path that recomputes only the marked section and leaves manual content untouched, with a test asserting byte-for-byte preservation outside the markers
  • Fail-closed handling for a missing/altered marker block, with test coverage
  • Shared diff utility reused by both this issue and the scheduled-refresh no-meaningful-change check

Expected outcomes

  • An operator's hand-edits outside the generated-content markers survive an arbitrary number of subsequent automated refreshes
  • A file whose marker block was manually removed never receives a silent automated overwrite

Part of the repo-doc generation roadmap: #2993

Metadata

Metadata

Assignees

Labels

maintainer-onlyOwner-only work — yields no Gittensor points.

Projects

Status
Done

Relationships

None yet

Development

No branches or pull requests

Issue actions