qte77/enforcing-doc-hierarchy

Enforce Documentation Hierarchy

Scope: $ARGUMENTS

Audits documentation against the project's declared hierarchy, then aligns violations with user approval.

Phase 1: Discover

Read the project's hierarchy declaration. Look for (in order):

1. CONTRIBUTING.md — "Documentation Hierarchy" section (table or list)
2. AGENTS.md — "Key references" or "Information sources" section
3. README.md — "Documentation" section (links to authoritative docs)

Extract:

• Entry points: which docs are human vs agent entry points
• Authority map: which doc owns which content type
• Anti-redundancy rule: stated or implied (default: no duplication across docs)

If no hierarchy is declared, report that as the first finding and stop.

Phase 2: Audit

Detect violations across the scope. For each finding, record:

| Source File | Line | Type | Description | |-------------|------|------|-------------| | path | Lnn | type | what's wrong |

Violation Types

• broken-link: Reference target does not exist (moved, renamed, deleted, wrong case)
• duplicate: Same content (3+ lines) appears in both an authority doc and a dependent doc
• misplaced: Content is in the wrong doc per the discovered authority map, OR a doc in the hierarchy is not referenced by its parent
• lint-compat: HTML comments before frontmatter
• config-drift: Inline <!-- markdownlint-disable/enable --> for a rule already disabled in .markdownlint.json. These are dead code that causes false positives when the enable directive re-activates a globally-disabled rule
• unused-link-def: [key]: url link definition with no corresponding [text][key] or [key] reference in the file

Audit Procedure

1. Determine scope from $ARGUMENTS:

   • File: audit that file's outbound references and content placement
   • Directory: audit all .md files in that directory
   • full or empty: audit every .md file in the repo

2. Check links: For each [text](path) and @file reference, verify the target exists. Check case sensitivity.

3. Check duplicates: For each authority doc, search dependent docs for substantial repeated content (3+ lines or identical tables).

4. Check placement: For each doc, verify its content matches its declared authority. Flag content that belongs in a different doc per the authority map.

5. Check chain: Verify each doc in the hierarchy is referenced by at least one parent doc. Flag orphaned docs.

6. Run markdownlint (preferred) or manual lint check (fallback):

   a) If markdownlint-cli is available (npx markdownlint-cli --version succeeds): run it with the project config and parse output:

   npx markdownlint-cli -c .markdownlint.json <scope> 2>&1
   

   Map results to violation types: MD012 → double blanks (fix during align), MD053 → unused-link-def, MD022/MD058 → spacing issues from prior directive removal. Report rule ID + line + message.

   b) Fallback (no markdownlint available): read .markdownlint.json (or .markdownlintrc, .markdownlint.yaml) to get globally-disabled rules, then manually:

   • Flag files with HTML comments before frontmatter on line 1 (lint-compat)
   • Flag inline <!-- markdownlint-disable/enable MDXXX --> where MDXXX is already disabled in the config file (config-drift)
   • Grep for [key]: url definitions with no corresponding reference (unused-link-def)

   In both paths: read the lint config to detect config-drift — even markdownlint doesn't flag dead inline directives for globally-disabled rules. See frontmatter-convention.md rule for the required config template.

7. Output findings table sorted by type, then file.

Phase 3: Align

Resolve findings with user confirmation. Propose each fix and wait for approval.

| Violation | Fix | |-----------|-----| | broken-link | Update path. If target deleted, remove reference. | | duplicate | Keep in authority doc, replace in dependent doc with reference link. | | misplaced | Move content to authority doc, replace original with reference link. | | lint-compat | Remove HTML comments before frontmatter. | | config-drift | Delete the inline directive — the rule is already handled by .markdownlint.json. Do NOT collapse surrounding blank lines (they may be required spacing around headings/tables). | | unused-link-def | Add inline reference, or remove the definition if it serves no purpose. |

Rules

• Fix the authority doc first, then fix dependents
• Never duplicate — replace with a reference
• Confirm each fix before applying
• Keep edits minimal
• Read .markdownlint.json before adding any inline lint directives — if a rule is globally disabled, inline toggles are dead code that causes false positives when the enable half re-activates the rule
• When removing inline directives, delete only the directive line — do NOT collapse surrounding blank lines (use Edit tool, not greedy sed)
• Commit content changes before repo-wide lint cleanup — never mix content additions with formatting passes in the same uncommitted state

References

• rules/frontmatter-convention.md — required .markdownlint.json config template and anti-patterns for inline directives