perf(lint): read frontmatter in-process, first part of CC-636 (Windows test-doctor.sh cost)

[screenleon]

Summary

• Record CC-636: on native Windows every test-doctor.sh case that runs the real doctor.sh costs about 45 s (samples 46/81/43/44 s; the file has 93 cases), so it cannot be run locally within the tool limit.
• First part of the fix: tools/lint/lint-frontmatter.sh read each file with sed, grep, awk and a pipeline; it now reads the first line, the fences and the frontmatter in one in-process pass. doctor.sh runs this lint on every invocation.
• A trailing CR is dropped per line, so a CRLF file is validated like an LF one on every platform (before: skipped on Linux, validated on native Windows). Two CRLF cases and a trailing-space-fence case pin it.
• CC-636 stays active: requirement 2 (cache host.yaml scalar reads) and 3 (check_detached_runs cost) are not done.

Evidence (one machine, single measurements, noisy)

• Lint run on this checkout: about 8 s to about 1 s; output byte-identical (stdout, stderr, rc).
• test-lint-frontmatter.sh: 70 passed in 51 s before; 75 passed in 28 s after.
• doctor-grok-authed-via-xai-env case: 33-47 s before, 27 s after. The rest of the cost is still in doctor.
• Differential run old vs new on about 40 edge files (empty, no trailing newline, fences with spaces, mid-body fence, NUL byte, CRLF): identical except CRLF (now validated) and a lone CR line.
• Mutation checks: dropping the CR stripping fails crlf-invalid-frontmatter-fails; collecting body lines fails body-after-closing-fence-not-validated.
• validate.sh BACKLOG.md, planning consistency, lint-test-docstrings.sh: pass.

Gate and review

• Full pr-gate: NOT run (not feasible on this host); no gate result artifact.
• Five reviewers ran individually as subagents (same model family as the author): critic, qa-tester, security, risk, architecture. All approve or advise; risk and security raised the CRLF false pass, fixed in the second commit.
• Known gaps: the unreadable-file branch is untested (cannot be set up on NTFS); a file with a single fence is read to its end (about 3.6 s for 20,000 lines, agent/command/skill files are small); shellcheck is not installed here and lint-doc-wikilinks.sh is too slow to run locally, so both rely on CI; the full test-doctor.sh was not run.
• Permanent test admissions: five cases added to tests/shell/test-lint-frontmatter.sh (an existing suite), all for the rewritten in-process reader.
  • body-after-closing-fence-not-validated and closing-fence-without-trailing-newline: stable supported boundary (where frontmatter ends), high-impact regression (a wrong boundary validates the body or rejects a valid file), implementation-independent observable (lint exit status), low maintenance, direct contract; each was killed by a plausible wrong implementation.
  • crlf-invalid-frontmatter-fails and crlf-valid-frontmatter-passes: the review found that skipping CRLF files makes doctor report invalid frontmatter as passed; same criteria, mutation-checked (removing the CR stripping fails the first).
  • fences-with-trailing-spaces: pins the [[:space:]]* fence rule the old grep and awk had; cheap and observable by exit status.

🤖 Generated with Claude Code

https://claude.ai/code/session_011c6rVDk6zyfgLPEfbVrZi9