fix(injector): use h2 heading and backticks in managed block

[AlexanderWillner]

Summary

• Change managed block heading from # (h1) to ## (h2) to avoid breaking document heading hierarchy in AGENTS.md/CLAUDE.md files that already have an h1 title
• Change 'ocr init' to `ocr init` for consistent markdown inline code formatting

Context

Found via OCR code review: the injected block in packages/cli/src/lib/injector.ts uses # Open Code Review Instructions which creates a second h1 heading in files that already have one. All other sections in typical AGENTS.md files use ## (h2). This affects markdown renderers and TOC generators.

Additionally, the CLI command reference uses single quotes instead of backticks, inconsistent with standard markdown conventions for inline code.

Changes

• packages/cli/src/lib/injector.ts: Two fixes in OCR_INSTRUCTION_BLOCK constant:
  • Line 8: # → ##
  • Line 24: 'ocr init' → \`ocr init\`

[spencermarx]

Thanks for raising @AlexanderWillner ! Will take a look 🙏

[spencermarx]

Code Review: PR #26 — fix(injector): use h2 heading and backticks in managed block

Date: 2026-04-07
Reviewers: @principal-1, @Quality-1, @ai-1, @ephemeral-1
Mode: Full (with discourse)

---

Verdict

APPROVE

The PR correctly fixes two formatting defects in the OCR managed block template. The h2 heading and backtick formatting changes are both correct and well-scoped. No blockers identified — the two should-fix items are pre-existing gaps surfaced by this change, not regressions introduced by it.

---

Blockers

None.

---

Should Fix

1. Update repo's own CLAUDE.md and AGENTS.md to reflect the fixed template

Flagged by: @principal-1, @Quality-1, @ai-1, @ephemeral-1
Location: CLAUDE.md:27-44, AGENTS.md:25-43

The repo's own CLAUDE.md and AGENTS.md files still contain the old # Open Code Review Instructions (h1) and single-quoted 'ocr init'. Since this repo serves as the canonical reference project for OCR, the injected blocks should reflect the corrected template.

Recommended action: Run ocr init (or ocr update --inject) after merging to regenerate the managed blocks, and commit the updated files. Alternatively, include the updated files in this PR.

2. Add test coverage for injector.ts

Flagged by: @principal-1, @Quality-1, @ai-1, @ephemeral-1
Location: packages/cli/src/lib/injector.ts (no corresponding test file)

The OCR_INSTRUCTION_BLOCK constant and injection functions have zero automated test coverage. The very regression this PR fixes (wrong heading level) would have been caught by a simple string assertion test. Given that this template is injected into every consumer project at ocr init time, the cost of content regressions is unusually high.

Recommended action: Add packages/cli/src/lib/__tests__/injector.test.ts covering: heading level assertion (## not #), backtick formatting assertion, fresh inject, re-inject idempotency, and hasOcrInstructions detection. This is a pre-existing gap — not a blocker for this PR, but strongly recommended as a follow-up.

---

Suggestions

AI Workspace Conventions

• "OpenSpec managed block still uses h1 (# OpenSpec Instructions) while OCR is now h2. Consider coordinating with OpenSpec to align both blocks on h2, so all managed blocks are subordinate to the host file's document-level structure." — @ai-1, @ephemeral-1, @principal-1
• "OpenSpec's managed block uses single-quoted 'openspec update' while OCR now uses backtick-quoted `ocr init`. File a companion issue to align formatting." — @ephemeral-1

Content & Tone

• "The keep-alive instruction could be more directive: 'Do not remove or modify this managed block. It is managed by ocr init and will be refreshed automatically.' This would be harder for an agentic AI to rationalize removing." — @ai-1

Future Improvements

• "Consider embedding a content hash or format version in the HTML comment markers (e.g., <!-- OCR:START v2 -->) to enable drift detection by ocr doctor." — @principal-1

---

What's Working Well

• "The template literal escaping is correct: backticks are properly escaped — no syntax errors introduced." — @Quality-1, @ai-1
• "The PR is appropriately small and non-disruptive. Changing a string constant in a single file is the right level of intervention for a cosmetic fix." — @principal-1
• "The injectOcrInstructions function's replace-on-reinject semantics mean the fix is fully self-healing for any project that runs ocr update." — @principal-1
• "The h2 choice is correct. SKILL.md itself uses h2 for its structural headings — internally consistent." — @ai-1
• "The managed block template is well-structured for AI comprehension. The three-section pattern — when to activate, what to do, why the block exists — is exactly the right format for CLAUDE.md instruction blocks." — @ephemeral-1
• "The template injection model using HTML comment markers is sound — invisible in rendered markdown, unambiguous for regex extraction." — @ephemeral-1

---

Consensus & Dissent

Topic: Stale repo files

Reviewers: @principal-1, @Quality-1, @ai-1, @ephemeral-1

Reviewer	Position
@principal-1	"The repo itself ships with the very bug it's fixing" (Medium)
@Quality-1	"Inconsistency means injector and checked-in output diverge" (Medium)
@ai-1	"AI assistants will see the old formatting" (Low)
@ephemeral-1	"Creates a brief inconsistency period" (Info)

Consensus: All agree files should be updated. Severity ranges from Medium to Info — classified as Should Fix given this repo's canonical reference role.

Topic: OpenSpec heading asymmetry

Reviewers: @principal-1, @ai-1, @ephemeral-1

Reviewer	Position
@ai-1	"AI tools may give OCR instructions lower parsing weight at h2 vs OpenSpec at h1"
@ephemeral-1	"Cursor and Windsurf show more sensitivity to heading hierarchy"
@principal-1	"Creates structural inconsistency between the two managed-block systems"

Consensus: All agree h2 is correct for OCR; the asymmetry is an out-of-scope follow-up for OpenSpec.

---

Clarifying Questions

Every question below was raised by a reviewer. Please address each.

From @principal-1

• "Is there a policy about whether the repo's own CLAUDE.md/AGENTS.md should be manually updated when the injector template changes, or is ocr update --inject run as part of the release process?"
• "Is the heading-level inconsistency with OpenSpec's # OpenSpec Instructions intentional?"

From @Quality-1

• "The commit message is fix(injector): use h2 heading and backticks in managed block — was the intent to also update the checked-in CLAUDE.md/AGENTS.md in this PR?"

From @ai-1

• "Does ocr update also call injectIntoProjectFiles? If so, should the PR description call that out?"
• "Is there a defined convention for whether managed blocks should appear at the top or bottom of target files?"

From @ephemeral-1

• "Is there an ocr update command separate from ocr init? Which is the intended idempotent re-injection command?"
• "Is there a canonical heading convention for managed blocks injected into CLAUDE.md/AGENTS.md across all tools in this ecosystem?"

---

Individual Reviews

Full reviews available in session directory:

Reviewer	Blockers	Should Fix	Suggestions	File
@principal-1	0	2	2	rounds/round-1/reviews/principal-1.md
@Quality-1	0	2	1	rounds/round-1/reviews/quality-1.md
@ai-1	0	2	2	rounds/round-1/reviews/ai-1.md
@ephemeral-1	0	1	3	rounds/round-1/reviews/ephemeral-1.md

Session: .ocr/sessions/2026-04-07-pr-AlexanderWillner-26/
Discourse: rounds/round-1/discourse.md

[spencermarx]

Hi @AlexanderWillner — thanks for this fix! I ran an OCR review on the PR and pushed one follow-up commit (3e4d01f) directly to your branch to address the should-fix items the reviewers raised. Hope that's okay; happy to revert if you'd prefer to handle them yourself.

What was added:

1. Test coverage for injector.ts — packages/cli/src/lib/__tests__/injector.test.ts with 11 tests. The reviewers' point was that the very regression your PR fixes (h1 vs h2) would have been caught by a string assertion, and since this template is injected into every consumer project at ocr init time, content regressions are unusually expensive. The new tests cover:

   • Content guards: h2 heading (regex-anchored to prevent the # regression), backtick formatting around `ocr init`, marker presence
   • injectOcrInstructions: fresh inject, append-while-preserving-existing-content, idempotent re-inject, stale-block replacement
   • injectIntoProjectFiles: dual-file injection into both AGENTS.md and CLAUDE.md
   • hasOcrInstructions: missing file, missing markers, present markers

2. Regenerated this repo's own CLAUDE.md and AGENTS.md — All four reviewers flagged that this repo (the canonical reference project for OCR) still shipped the old # Open Code Review Instructions (h1) and single-quoted 'ocr init' in its checked-in managed blocks. Now updated to match your corrected template.

3. Harmonized OpenSpec and Code Conventions headings to h2 — The reviewers also noted in a "consensus & dissent" section that the OpenSpec managed block was at h1 while OCR was now at h2, creating structural asymmetry. Bringing all top-level blocks in these files to h2 keeps the hierarchy consistent.

Verification: npx nx test cli passes all suites including the new 11 injector tests.

[spencermarx]

Great work @AlexanderWillner. My latest comment explains the couple additions made. We're good to go on merge here 👍