Obsidian lint - readability gate for vault notes
Operator rule (2026-10-15): mangled notes are unreadable in Obsidian. Raw
Killchain/JSON dumps, double-encoded transcriptions, and escape walls filed as
prose are defects, not evidence.
When to run
- After ANY note is written under
targets/<eng>/ by an agent, lane, or sync
(especially FIND reports and anything transcribed from web/PDF/other reports).
- Before close-out / FIND registration (pairs with the evidence skill's
registration law).
Command
python3 scripts/obsidian-lint.py targets/<eng>
Exit 0 = clean; exit 1 lists every violation. Scope it narrower
(targets/<eng>/Vulns) for a quick gate.
What it catches
- Literal
\n mid-text - the #1 mangle: JSON/killchain dumps pasted as
prose. ANY occurrence outside code fences fails.
- Transcription artifacts - mojibake (double-encoded UTF-8), un-rendered
HTML entities, markdown glued mid-line (
text## Heading), invisible
characters (BOM/zero-width), unbalanced code fences (truncated transcription).
- Non-ASCII typography - em/en-dashes, smart quotes, ellipsis, nbsp
(repo rule: ASCII
- and ' instead).
- CRLF - Windows line endings (NOTE: Python
write_text/text-mode on this
box emits CRLF; write bytes or normalize - the lint will catch yours too).
- Wall lines - unbroken 400+ char lines outside code fences (split into
sections); table rows and list items exempt, fenced URLs/payloads exempt.
- Mid-sentence hard wraps - textwrap-style repair damage (a long line not
ending a sentence followed by a lowercase continuation) and hyphen-split
tokens (
X-Amz- / Security-Token).
- Glued fences - a closing fence carrying prose on the same line
(
EXPECTED OUTCOME: ...); this shape also HIDES content from the
fence-stripper, so it can mask lane references inside broken blocks.
- FIND-*.md shape - YAML frontmatter with title/type/severity/status/
date_created required; a file starting
## FIND- is a Killchain dump, not
a report - convert before filing.
evidence/ subdirs are skipped: they are verbatim lane captures, never
prose-normalized.
Fix law
Fix the FILE, never the lint: re-transcribe with correct encoding, unwrap
escapes to real newlines, split walls into sections, add frontmatter. Do not
wrap mangled content in code fences to silence the gate - fences are for
commands and payloads only.
Bounty-report law (FIND files are company-facing, operator 2026-10-15)
The bug bounty company does not care about our internal machinery. A FIND
report body must read like a normal, compact vulnerability report:
- NO lane names (laneA..laneZ, laneM etc.), NO agent/session handles, NO
agent-reports/ paths inside the PROSE. Evidence pointers belong in the
frontmatter sources: block or one Evidence section at the end - never
woven through the narrative.
- NO irrelevant dates (test-session timestamps, run dates that add nothing).
Keep only verification dates that change the reader's understanding
(e.g. "re-verified after the 2026-10-13 patch").
- Compact structure: Summary, Preconditions, Reproduction (numbered,
copy-pasteable), Impact, What-is-NOT-possible (negative controls),
Remediation, References. No meta-sections about our process.
- Perfect markdown (the reason this lint exists): no weird wrapping, no
weird new lines, no broken structure.
Lint enforces this: lane<X> / agent-reports tokens in a FIND body are
flagged. When flagged, rewrite the sentence without the internal reference
(keep the fact, drop the machinery).
Repair discipline (hard, learned 2026-10-15)
Never bulk-rewrite notes with scripted reflow (textwrap/join loops): it
shatters code fences, hyphen-splits tokens and collapses frontmatter.
Repair ONE file at a time: read it, patch the specific broken lines with
targeted edits, verify by reading it back, THEN move to the next file.
Lint after each file. Test a repair pipeline on ONE finding and verify it
visually before running anything on the whole tree - a broken repair script
applied everywhere multiplies the damage across every note.
Rewrite mechanics (the file tools enforce read-before-write): a partial read
(offset/limit, or an offset past end-of-file) marks the file as not-fully-read
and a full overwrite is refused. Read EVERY page of the file before rewriting
it, or patch the specific lines instead of rewriting. sed for exact-token
swaps (single words, paths) is safe; sed never reflows lines.
1---2name: obsidian-lint3description: "Use when notes are written into the vault (findings, reports, transcriptions, syncs from VMshare/lanes) or before close-out: run scripts/obsidian-lint.py to catch mangled text before the operator reads it in Obsidian."4metadata:5 source: https://skillmd.com/skills/encod3d-sec/obsidian-lint6 hermes:7 version: 18 author: seat9 license: MIT10 tags: [obsidian, vault, quality, lint]11 related_skills: [evidence, close-out]12---1314# Obsidian lint - readability gate for vault notes1516Operator rule (2026-10-15): mangled notes are unreadable in Obsidian. Raw17Killchain/JSON dumps, double-encoded transcriptions, and escape walls filed as18prose are defects, not evidence.1920## When to run2122- After ANY note is written under `targets/<eng>/` by an agent, lane, or sync23 (especially FIND reports and anything transcribed from web/PDF/other reports).24- Before close-out / FIND registration (pairs with the evidence skill's25 registration law).2627## Command2829 python3 scripts/obsidian-lint.py targets/<eng>3031Exit 0 = clean; exit 1 lists every violation. Scope it narrower32(`targets/<eng>/Vulns`) for a quick gate.3334## What it catches35361. **Literal `\n` mid-text** - the #1 mangle: JSON/killchain dumps pasted as37 prose. ANY occurrence outside code fences fails.382. **Transcription artifacts** - mojibake (double-encoded UTF-8), un-rendered39 HTML entities, markdown glued mid-line (`text## Heading`), invisible40 characters (BOM/zero-width), unbalanced code fences (truncated transcription).413. **Non-ASCII typography** - em/en-dashes, smart quotes, ellipsis, nbsp42 (repo rule: ASCII ` - ` and `'` instead).434. **CRLF** - Windows line endings (NOTE: Python `write_text`/text-mode on this44 box emits CRLF; write bytes or normalize - the lint will catch yours too).455. **Wall lines** - unbroken 400+ char lines outside code fences (split into46 sections); table rows and list items exempt, fenced URLs/payloads exempt.476. **Mid-sentence hard wraps** - textwrap-style repair damage (a long line not48 ending a sentence followed by a lowercase continuation) and hyphen-split49 tokens (`X-Amz-` / `Security-Token`).507. **Glued fences** - a closing fence carrying prose on the same line51 (````EXPECTED OUTCOME: ...````); this shape also HIDES content from the52 fence-stripper, so it can mask lane references inside broken blocks.538. **FIND-*.md shape** - YAML frontmatter with title/type/severity/status/54 date_created required; a file starting `## FIND-` is a Killchain dump, not55 a report - convert before filing.5657`evidence/` subdirs are skipped: they are verbatim lane captures, never58prose-normalized.5960## Fix law6162Fix the FILE, never the lint: re-transcribe with correct encoding, unwrap63escapes to real newlines, split walls into sections, add frontmatter. Do not64wrap mangled content in code fences to silence the gate - fences are for65commands and payloads only.6667## Bounty-report law (FIND files are company-facing, operator 2026-10-15)6869The bug bounty company does not care about our internal machinery. A FIND70report body must read like a normal, compact vulnerability report:7172- NO lane names (laneA..laneZ, laneM etc.), NO agent/session handles, NO73 `agent-reports/` paths inside the PROSE. Evidence pointers belong in the74 frontmatter `sources:` block or one Evidence section at the end - never75 woven through the narrative.76- NO irrelevant dates (test-session timestamps, run dates that add nothing).77 Keep only verification dates that change the reader's understanding78 (e.g. "re-verified after the 2026-10-13 patch").79- Compact structure: Summary, Preconditions, Reproduction (numbered,80 copy-pasteable), Impact, What-is-NOT-possible (negative controls),81 Remediation, References. No meta-sections about our process.82- Perfect markdown (the reason this lint exists): no weird wrapping, no83 weird new lines, no broken structure.8485Lint enforces this: `lane<X>` / `agent-reports` tokens in a FIND body are86flagged. When flagged, rewrite the sentence without the internal reference87(keep the fact, drop the machinery).8889## Repair discipline (hard, learned 2026-10-15)9091Never bulk-rewrite notes with scripted reflow (textwrap/join loops): it92shatters code fences, hyphen-splits tokens and collapses frontmatter.93Repair ONE file at a time: read it, patch the specific broken lines with94targeted edits, verify by reading it back, THEN move to the next file.95Lint after each file. Test a repair pipeline on ONE finding and verify it96visually before running anything on the whole tree - a broken repair script97applied everywhere multiplies the damage across every note.9899Rewrite mechanics (the file tools enforce read-before-write): a partial read100(offset/limit, or an offset past end-of-file) marks the file as not-fully-read101and a full overwrite is refused. Read EVERY page of the file before rewriting102it, or patch the specific lines instead of rewriting. sed for exact-token103swaps (single words, paths) is safe; sed never reflows lines.