chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping)

.pre-commit-config.yaml

@@ -6,11 +6,13 @@
 exclude: "^(docs/plans/|docs/research/|han-reporting/skills/html-summary/assets/)"
 
 repos:
-  # Prettier owns formatting for JSON, YAML, and JS at 120 columns. Markdown is
-  # deliberately excluded in .prettierignore: agents read skills and reference
-  # files as raw source, and Prettier's list renumbering and code-span trimming
-  # change what those files say. Running the local devDependency keeps Prettier's
-  # version in package.json only, not duplicated in a hook mirror.
+  # Prettier owns formatting for Markdown, JSON, YAML, and JS at 120 columns.
+  # Markdown runs with proseWrap: preserve and embeddedLanguageFormatting off (see
+  # .prettierrc.json). Agents read skills and reference files as raw source, so the
+  # source is kept robust to the two normalizations Prettier cannot turn off —
+  # ordered-list renumbering and inline code-span trimming — and Prettier then
+  # leaves what those files say unchanged. Running the local devDependency keeps
+  # Prettier's version in package.json only, not duplicated in a hook mirror.
   # It runs first so the hygiene fixers below never fight it.
   - repo: local
     hooks:

.prettierignore

@@ -1,14 +1,12 @@
 # Markdown is the product, not just prose about it: skills, agents, and reference
 # files are read as raw source by agents, so a transform that renders the same can
 # still change what an agent is told to do. Prettier has two such transforms that
-# cannot be turned off, because they are core CommonMark normalizations:
-#   * It renumbers ordered lists, while the prose cross-references to those steps
-#     ("see Step 6") stay put and end up pointing at the wrong ones.
-#   * It strips the spaces inside inline code spans, so a heading spec written as
-#     ` — ` becomes `—` next to prose that still says "with surrounding spaces".
-# Both survive proseWrap: preserve and embeddedLanguageFormatting: off, so there is
-# no configuration that formats this repo's Markdown without corrupting it.
-*.md
+# cannot be turned off, because they are core CommonMark normalizations: it
+# renumbers ordered lists, and it strips the padding spaces inside inline code
+# spans. The source is kept robust to both (ordered lists are already sequential,
+# and no prose wraps a padded spec like ` — ` in backticks), so proseWrap: preserve
+# plus embeddedLanguageFormatting: off formats this repo's Markdown without
+# corrupting it. Keep it that way when editing.
 
 # Static historical artifacts: left as written.
 docs/plans/
@@ -17,6 +15,11 @@ docs/research/
 # Vendored third-party assets: checked in verbatim, never reformat.
 han-reporting/skills/html-summary/assets/
 
+# A schematic HTML sketch, not real HTML: Prettier hard-errors trying to parse it.
+# The prek hook never hands it over (it filters to markdown, JSON, YAML, and JS),
+# but ignore it here too so a direct `prettier .` stays green.
+han-reporting/skills/html-summary/references/html-template.html
+
 # Dependencies and generated files.
 node_modules/
 package-lock.json

.prettierrc.json

@@ -1,3 +1,5 @@
 {
-  "printWidth": 120
+  "printWidth": 120,
+  "proseWrap": "preserve",
+  "embeddedLanguageFormatting": "off"
 }

han-atlassian/skills/markdown-to-confluence/SKILL.md

@@ -135,7 +135,7 @@ draft-vs-published.
   changes local only.
 
 **Diagram note:** Markdown produced by Han's documentation skills emits Mermaid
-diagrams in fenced ```mermaid``` code blocks. Confluence does not render Mermaid
+diagrams in fenced `mermaid` code blocks. Confluence does not render Mermaid
 natively without a Mermaid macro, so these blocks publish as code, not rendered
 diagrams. Leave them intact — do not silently strip them — and tell the user the
 diagrams posted as Mermaid source, in case their space has a macro that renders

han-coding/skills/code-overview/references/overview-template.md

@@ -52,7 +52,7 @@ remove the guidance comments, and keep the section order exactly as written.
 
 ## Code mode — explaining code as it is now
 
-```markdown
+````markdown
 # Code Overview: {short name of the target}
 
 {Intro paragraph: one or two sentences naming what code is being examined — the
@@ -98,13 +98,13 @@ read as how the code delivers on the why above.}
 
 {The concrete entry points — the specific files or components — the reader
 would open first to begin working, with one line each on what each is for.}
-```
+````
 
 ---
 
 ## PR mode — explaining a set of changes
 
-```markdown
+````markdown
 # Change Overview: {short name of the pull request or branch}
 
 {Intro paragraph: one or two sentences naming what is being examined — which
@@ -160,4 +160,4 @@ quality or risk judgment; that is code-review's job, not this skill's. -->
 {The concrete entry points — the specific files or components — where the
 change is densest or most interconnected, with one line each on why a reviewer
 should slow down there.}
-```
+````

han-coding/skills/coding-standard/SKILL.md

@@ -109,8 +109,8 @@ When converting an existing document into a coding standard:
 
 1. Read the source document
 2. Map sections to coding standard sections using the mapping at [adr-conversion-mapping.md](./references/adr-conversion-mapping.md)
-4. **If the source document is fully subsumed:** delete it and update references (search `CLAUDE.md`, `AGENTS.md`, and other markdown files)
-5. **If the source document retains useful content:** add a link to the new coding standard in the source document and remove migrated sections
+3. **If the source document is fully subsumed:** delete it and update references (search `CLAUDE.md`, `AGENTS.md`, and other markdown files)
+4. **If the source document retains useful content:** add a link to the new coding standard in the source document and remove migrated sections
 
 ## Step 6: Write the Coding Standard
 

han-core/agents/readability-editor.md

@@ -17,7 +17,7 @@ You will receive the path to a draft file (or the draft text inline) and the sha
 
 You rewrite **prose regions only**. Leave these byte-for-byte unchanged:
 
-- Content inside code fences (```` ``` ````) and inline code spans.
+- Content inside code fences and inline code spans.
 - Diagram bodies — the content of a Mermaid block or any other rendered diagram.
 - Rendered markup — an HTML report's tags, attributes, and class names.
 - Inline citation identifiers (`A1`, `V3`, `[F5]`, and the like) — their whole value is that they still resolve to their registry, so they survive your rewrite exactly.

han-core/skills/project-documentation/SKILL.md

@@ -58,14 +58,15 @@ Lead with behavior. These rules make the doc an overview first and a reference s
 4. **Reference is supporting detail.** Place schema, core types, constants, implementation notes, API bodies, and component listings under the `## Technical Reference` region, below the behavioral spine. Treat them as lookup material, not the document's main body.
 
 Apply to every section:
+
 5. **Absolute file paths** from repo root (e.g., `src/services/auth.ts`, not `./auth.ts`).
 6. **Prefer pointers over long code.** In Technical Reference, point to the file and function and include a short illustrative snippet only where the source is non-obvious. Do not reproduce long (10-30 line) source blocks; link to the source instead.
 7. **Code fence language identifiers** must match the project's actual languages (from Step 1).
 8. **Document constants and magic numbers** with their actual values in the Constants table.
 9. **Skip CONDITIONAL sections** from the template that don't apply. Don't include empty sections.
 10. **One plain-language description** in the title area summarizing what the feature does.
 11. **Separate backend and frontend content.** Use `### Backend` / `### Frontend` sub-headings for cross-cutting features; skip sub-headings for single-layer features.
-12. **Diagrams are Mermaid, not ASCII.** Render the Architecture diagram, any Primary Flow diagram, and the Component Hierarchy as Mermaid in a ```` ```mermaid ```` fence — `flowchart` for structure and trees, `sequenceDiagram` for actor-to-system exchanges. Label nodes with parts a reader recognizes and label edges with what passes between them. Keep each diagram to the parts that matter; a reader should grasp the shape at a glance.
+12. **Diagrams are Mermaid, not ASCII.** Render the Architecture diagram, any Primary Flow diagram, and the Component Hierarchy as Mermaid in a ` ```mermaid ` fence — `flowchart` for structure and trees, `sequenceDiagram` for actor-to-system exchanges. Label nodes with parts a reader recognizes and label edges with what passes between them. Keep each diagram to the parts that matter; a reader should grasp the shape at a glance.
 
 **Updating existing documents:** Read the entire existing document first and note all content sources (existing doc, content migrated from CLAUDE.md or other files, any other inputs). Preserve the existing structure; don't reorganize unless requested. Identify sections needing changes based on Step 2 exploration. Add new sections where the template suggests them. If the existing doc has no plain-language behavioral layer (no Summary, How It Works, or Primary Flows), add those sections at the top so the updated doc leads with behavior. Flag removals as provisional for the Content Audit (Step 6). Update code examples to match current source and update cross-references in both directions.
 
@@ -121,7 +122,7 @@ Fidelity wins: the standard governs how the content is said, never whether a req
 
 ## Step 10: Verification
 
-1. **Documentation file:** Follows template structure and leads with behavior (Summary, How It Works, Primary Flows appear before the `## Technical Reference` region), no `{placeholder}` values remain, absolute file paths, reference code is short snippets or file pointers rather than long source blocks, no empty CONDITIONAL sections, Mermaid diagrams are syntactically valid (open with ```` ```mermaid ````, declare a diagram type, and parse)
+1. **Documentation file:** Follows template structure and leads with behavior (Summary, How It Works, Primary Flows appear before the `## Technical Reference` region), no `{placeholder}` values remain, absolute file paths, reference code is short snippets or file pointers rather than long source blocks, no empty CONDITIONAL sections, Mermaid diagrams are syntactically valid (open with ` ```mermaid `, declare a diagram type, and parse)
 2. **Agent config file:** Reference correctly formatted, link path valid, placed in right section
 3. **Cross-references:** Links point to real files, related docs link back to new doc
 4. **IA review applied:** Step 7 edits were applied, or any skipped edits were surfaced to the user

han-github/skills/work-items-to-issues/references/issue-template.md

@@ -42,7 +42,7 @@ The format below is what `/plan-work-items` emits and what the publish pipeline
 
 These are the patterns the publish scripts grep for; violating them breaks the pipeline. The skill's Step 3 validation checks each invariant before publishing and proposes evidence-based repairs.
 
-- **Heading line** begins with `## ` followed by `<SYM-N>` (uppercase letters or digits, dash, digits), then ` — ` (em-dash with surrounding spaces), then the title.
+- **Heading line** begins with `## ` followed by `<SYM-N>` (uppercase letters or digits, dash, digits), then an em-dash with surrounding spaces, then the title.
 - **Heading rewrite.** After issue creation, `scripts/create-issues.sh` rewrites each heading in place to `## <SYM-N> (#NNN) — <title>`. The `(#NNN)` annotation is how `link-blockers.sh` resolves symbolic IDs to GitHub issue numbers, and how `create-issues.sh` knows to skip already-created slices on re-run. Both shapes — with and without `(#NNN)` — are valid input.
 - **Slice body** ends at the next `## ` heading or end of file.
 - **Screenshot URLs** use the exact path scheme `.github/issue-assets/<feature-slug>/<SYM-N>/<file>.png`, where `<feature-slug>` is the kebab-cased basename of the plan folder. The upload script extracts this path verbatim from the per-repo file and reads the slug back out of it, so the slug written into the URL is authoritative.

han-planning/skills/plan-a-feature/SKILL.md

@@ -223,10 +223,9 @@ After all review agents return, compile their findings. **Do not dump raw findin
    - On each affected `T#` entry in `artifacts/feature-technical-notes.md`, add this finding's ID to `Driven by findings:` and list affected spec sections under `Referenced in spec:`.
    - If a new decision was introduced, add an inline `([D#](artifacts/decision-log.md#...))` reference in the relevant section of `feature-specification.md` and list that section under the decision's `Referenced in spec:` field. Apply the same pattern for any new `T#` references.
 5. **"Mechanics leaking into spec" findings** — findings in this class usually resolve by rewriting the offending spec sentence behaviorally and either extracting the mechanic to a `T#` note (if load-bearing) or removing it entirely (if pure implementation or discoverable from code). Do not escalate these to the user unless the rewrite would change the feature's meaning.
-
-5a. **`YAGNI candidate` findings** — apply the YAGNI rule per [../../references/yagni-rule.md](../../references/yagni-rule.md). For each finding, three resolution paths exist: (a) cite the missing evidence (per the rule's evidence test) and keep the spec item — record the citation in the relevant `D#`'s `Evidence:` field and close the finding; (b) replace with the strictly simpler version that satisfies the same evidence — update the spec sentence and the related `D#`, list the larger version under that `D#`'s `Rejected alternatives:` with the reason "simpler version satisfies the same evidence"; (c) demote to the spec's `## Deferred (YAGNI)` section with the reopening trigger named, removing the inline behavior from the affected sections. Surface YAGNI deferrals to the user in Step 7's escalation pass so the user can override consciously, but do not require user input when evidence resolves the finding directly.
-6. **Escalate only what genuinely needs the user.** For findings that remain open, draft a recommended answer with rationale and alternatives, the same way Step 4 surfaces questions. Present them to the user together, organized by the decision they affect — not by which agent raised them.
-7. **Capture the user's answers** in the relevant `D#` entry in `artifacts/decision-log.md`, finish populating the `F#` entry (`Resolved by: user input`), update any dependent decisions or tech-notes, and keep all files' cross-refs in sync.
+6. **`YAGNI candidate` findings** — apply the YAGNI rule per [../../references/yagni-rule.md](../../references/yagni-rule.md). For each finding, three resolution paths exist: (a) cite the missing evidence (per the rule's evidence test) and keep the spec item — record the citation in the relevant `D#`'s `Evidence:` field and close the finding; (b) replace with the strictly simpler version that satisfies the same evidence — update the spec sentence and the related `D#`, list the larger version under that `D#`'s `Rejected alternatives:` with the reason "simpler version satisfies the same evidence"; (c) demote to the spec's `## Deferred (YAGNI)` section with the reopening trigger named, removing the inline behavior from the affected sections. Surface YAGNI deferrals to the user in Step 7's escalation pass so the user can override consciously, but do not require user input when evidence resolves the finding directly.
+7. **Escalate only what genuinely needs the user.** For findings that remain open, draft a recommended answer with rationale and alternatives, the same way Step 4 surfaces questions. Present them to the user together, organized by the decision they affect — not by which agent raised them.
+8. **Capture the user's answers** in the relevant `D#` entry in `artifacts/decision-log.md`, finish populating the `F#` entry (`Resolved by: user input`), update any dependent decisions or tech-notes, and keep all files' cross-refs in sync.
 
 ## Step 8: Project Manager Synthesis
 

han-planning/skills/plan-work-items/references/work-item-template.md

@@ -38,7 +38,7 @@ Each work item in `work-items.md` uses this template. Required fields appear in
 
 ## Format invariants
 
-- Heading line begins with `## ` followed by `<W-N>` (the prefix letters, a dash, then digits), then ` — ` (em-dash with surrounding spaces), then the title.
+- Heading line begins with `## ` followed by `<W-N>` (the prefix letters, a dash, then digits), then an em-dash with surrounding spaces, then the title.
 - A work item body ends at the next `## ` heading or end of file.
 - Design-reference paths are relative to the `work-items.md` file (e.g., `ui-designs/<file>.png` when the screenshots live in the plan folder). Never use an absolute path or a cross-repository URL.
 - The `**Depends on.**` line uses the literal bold marker, comma-separates dependencies, and ends with `.` (the trailing period is part of the format, not a sentence terminator).

han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md

@@ -11,7 +11,7 @@ Context injection commands use the `` !`command` `` syntax to execute a shell co
 
 Format: `` - label: !`command` ``
 
-Multiple commands per line: `` - Git user: !`git config user.name` (!`git config user.email`) ``
+Multiple commands per line: ``- Git user: !`git config user.name` (!`git config user.email`)``
 
 Many skills use this pattern: code-review skills, documentation skills, PR-description skills, investigation skills, project-discovery skills, and any skill whose steps need to know the current git state or project layout.
 

han-plugin-builder/skills/guidance/references/skill-building-guidance/script-execution-instructions.md

@@ -28,7 +28,7 @@ Each step has three elements:
 
 Fenced code blocks with comments as pseudocode are ambiguous:
 
-```markdown
+````markdown
 <!-- BAD — do not do this -->
     ```
     # generate a unique temp file path
@@ -40,7 +40,7 @@ Fenced code blocks with comments as pseudocode are ambiguous:
     # post the review
     scripts/post-pr-review.sh {args}
     ```
-```
+````
 
 Problems:
 

han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md

@@ -237,7 +237,7 @@ network calls and file writes are explicit in function names so callers know wha
 Three conventions are buried in a single paragraph. The model must parse sentence boundaries to separate them.
 
 **After (each convention as its own block):**
-```markdown
+````markdown
 ## Step 3: Apply Review Standards
 
 ### Error handling
@@ -273,7 +273,7 @@ Functions with network calls or file writes must name the side effect.
 // do this:  fetchPricing(), writeSummaryToFile()
 // not this: getPricing(), generateSummary()
 ```
-```
+````
 Each convention is independently parseable: heading, rule, example.
 
 ### Rule: Resolve variation at the point of use