Frank
a5fe045b58
Structural repair: - 13 pages were the same document twice (each exactly 2x its HEAD size), a second frontmatter block whose closing fence had been glued onto a body line by a frontmatter rewrite that re-read its own output. Un-doubled by cutting at the second frontmatter and keeping the copy whose body is a superset; the orphan census reports 0 lost tokens against HEAD. - log.md: one entry per date, bare `## YYYY-MM-DD` headings, newest first — 66 dated headings merged into 34, titles demoted to bold leads, every content line verified present. The file had been descending at the head and ascending at the tail. Ownership moves: - New `LLM/frank-medium.md` is the locator for the retired Dankserver endpoint: era windows quoted from each era page's own banner, no numbers restated, and the two unresolved date conflicts recorded instead of silently resolved. `frank-archon.md` links to it instead of restating the pre-rename window. - The four Pipeline-Parallelism stubs (frontmatter only, no body) are gone; `Multi-Node Runtimes.md` owns runtime construction, launch, mixed-vendor verdicts and cross-split spec decode, and the four links that pointed at the stubs were repointed at it or at the drafter page. - Authentik's three stub pages fold into `Authentik.md`, with the process detail and the outpost reference split out so the parent stays under the length hint. Verified corrections (host census + live probe, 2026-10-19): - The MXFP4 checkpoint two pages called the "on-disk rollback" is gone: /home/dank/models/ holds StillDeadcode, rad and tpl.jinja. Stated once, on the era page that owns that payload; the swap page now links to it. - frank-medium-radiance-mxfp4: the 4.24/7 accept rate belongs to the DFlash2 arm measured on the FP8 target, not to the MXFP4 era; the 3-family soak run census is kept once (155 requests) instead of twice (~120 and 155). - Fleet shapes re-confirmed against the live endpoints before touching any page: 3x200000 fp8 KV, 2x200704, 2x262144. Index rows are regenerated, not hand-carved. Net -1,849 vault lines.
115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
---
|
|
type: reference
|
|
title: Agent Docs and Edits
|
|
description: "Two self-inflicted doc damage classes from parallel agent edits, with the audit checks and recovery order for each."
|
|
tags: [agents, docs, markdown, hashline, edit-recovery]
|
|
timestamp: 2026-10-18T00:00:00Z
|
|
---
|
|
|
|
# Agent Docs and Edits
|
|
|
|
## Doc-structure audit (after parallel agent edits)
|
|
|
|
Use after one or more subagents have edited markdown docs (OKF/Obsidian
|
|
vault with `---` frontmatter), before committing. Link checkers and
|
|
completeness seams validate *references*, not *structure* — agents reliably
|
|
produce structurally broken markdown that still links cleanly.
|
|
|
|
Damage catalogue:
|
|
|
|
1. Banner/prose prepended **above** the opening `---` → the frontmatter is
|
|
no longer frontmatter (title/tags/description become body text).
|
|
2. A rewrite **appended** instead of merged → duplicate headings and a stray
|
|
second `---` mid-file.
|
|
3. Literal model artifacts in the body: `<|channel>}<tool_call|>...`,
|
|
`+- `, `- - `.
|
|
4. Wrapped bullets re-emitted with a `- ` prefix on every physical line.
|
|
5. Line-range replacement that dropped a sentence tail → dangling fragment,
|
|
often mid-parenthesis.
|
|
|
|
Checks (fast, run all):
|
|
|
|
```bash
|
|
head -3 <file> # must be `---` if the page has frontmatter
|
|
grep -c '^---$' <file> # exactly 2 (opener + closer)
|
|
grep -n '^## ' <file> | sort -t: -k2 | uniq -f1 -d # duplicate sections
|
|
grep -rnE '^\+- |^- - |<\|' <files> # artifacts
|
|
python3 scripts/check-vault-links.py <vault-dir>
|
|
./tests/run.sh # docs completeness seam etc.
|
|
```
|
|
|
|
Repair order (matters):
|
|
|
|
1. If the file was destroyed rather than edited: stash the agent version to
|
|
`.AGENTTRASH/<YYYYMMDD-topic>/`, then `git checkout HEAD -- <file>` and
|
|
re-apply only the intended changes by hand.
|
|
2. If it merely duplicated: **salvage unique content first** — cut the
|
|
one-of-a-kind section, paste it into the copy you keep, THEN delete the
|
|
duplicate ranges. Never delete first.
|
|
3. Re-add missing sentence tails (insert before the orphaned fragment),
|
|
keeping list continuation lines indented.
|
|
4. Re-run all checks above.
|
|
|
|
Gotchas: agents can write AFTER they appear finished (job settles, file
|
|
changes) — re-verify structure after the last background job reports, not
|
|
before. Editing an agent's already-damaged file with fresh line numbers is
|
|
safe, but its snapshot tag changes on every edit — re-read before each
|
|
subsequent edit. `.AGENTTRASH/` is gitignored (`.gitignore:25`), so NEW trash
|
|
stays local — but do not read that as "the repo has none of it": on 2026-10-18
|
|
`git ls-files | grep -c AGENTTRASH` returns **37** tracked paths
|
|
(`.AGENTTRASH/`, `scripts/.AGENTTRASH/`, `dankserver/.AGENTTRASH/`,
|
|
`tests/.AGENTTRASH/`), because gitignore never untracks what was committed
|
|
before the rule. Trash is a temporary hold, not an archive.
|
|
|
|
## Hashline edit recovery
|
|
|
|
Failure mode: multi-op edits resolve every `PUT N.=M:` / `CUT N.=M:` index
|
|
against the **original** file numbering, and the post-apply diff view
|
|
**elides lines** (it shows an anchor window, not the whole file). Two traps
|
|
follow:
|
|
|
|
1. A second edit call built from a diff-view snapshot uses line numbers from
|
|
a *partial* view. Lines outside the window are invisible but still
|
|
counted.
|
|
2. If the first apply was itself wrong, the file shifted. The diff view
|
|
tells you the damage, but not the true offsets.
|
|
|
|
Result: the repair pastes fresh text **beside** stale text instead of over
|
|
it.
|
|
|
|
Procedure:
|
|
|
|
1. **Never carry line numbers across calls.** Re-read the target range for a
|
|
fresh tag before every subsequent edit. A read is cheap; a duplicated
|
|
paragraph costs a commit and a revert.
|
|
2. **One op per call when the previous apply was imperfect.** Fixed offsets
|
|
are only trustworthy when every preceding apply landed exactly as
|
|
specified.
|
|
3. **Re-read after every apply**, and verify the whole affected region — the
|
|
diff view is a sample, not proof. Check the *boundaries*: the line before
|
|
the edit and the line after it. Damage shows up as a repeated sentence
|
|
straddling the seam.
|
|
4. **Repair by CUT, not by re-PUT.** Once you know the exact stale lines
|
|
from a fresh read, delete them. Do not try to PUT a corrected superset
|
|
over a range whose extent you are guessing at.
|
|
5. Verify with a content assertion, not a diff review: `grep -c` for the
|
|
duplicated sentence, plus a syntax/compile check on any touched script.
|
|
|
|
Same rule for any imperative `edit` tool with an old/new match: the matched
|
|
text must be the **entire** text being replaced. Matching a bare fragment
|
|
inside a paragraph splices the replacement into the middle of the sentence
|
|
and silently corrupts the file. Re-read the file afterwards to confirm.
|
|
|
|
### Anchored in-page links
|
|
|
|
Renaming a Markdown heading breaks `[[#Old Heading]]` anchors. When a
|
|
section is retitled, grep for the old heading text and fix every anchor in
|
|
the same pass — doc link-checkers frequently do not validate `#fragment`
|
|
targets, so a green suite will not catch a dangling one.
|
|
|
|
## Related
|
|
|
|
- [[OMP Harness]] — the session context these repairs protect
|
|
- [[Command Center Dotfiles]] — the repo these edits commit to
|
|
- [[Testing Policy]] — the seams that catch broken vault structure
|