markdown-compression

name	markdown-compression
description	Safely compresses narrative Markdown using deterministic compaction plus validator checks. Only for allowlisted non-parser-sensitive artifacts.

Markdown Compression

Use this only for safe narrative Markdown. This is not a general rewrite tool.

Safe Targets

• README.md
• docs/**/*.md
• specs/<feature>/research.md
• specs/<feature>/analysis-report.md
• specs/<feature>/manual-test.md

Blocked Targets

• project-instructions.md, AGENTS.md, CLAUDE.md
• all workflow, agent, instruction, and wrapper Markdown under .github/, .agents/, .claude/, .windsurf/, .opencode/, .codex/
• specs/prd.md, specs/sad.md, specs/dod.md, specs/project-plan.md, specs/adrs/*.md, specs/plan/*.md
• feature-workspace parser-sensitive artifacts: spec.md, plan.md, tasks.md, qc-report.md, checklists/*.md, autopilot-log.md

Process

1. Run node scripts/compress-markdown.mjs --check <path> to confirm the path is allowlisted and validator-safe.
2. For preview only, run node scripts/compress-markdown.mjs --stdout <path>.
3. To write the compressed file, run node scripts/compress-markdown.mjs <path>.
4. The script creates <name>.original.md once, then preserves it on later runs.
5. If validation fails, stop. Do not write partial output.

Validation Guarantees

The validator preserves these elements exactly:

• headings
• fenced code blocks
• inline code
• bare URLs and Markdown links
• requirement and task identifiers
• table rows
• checkbox lines

Compression Rules

• Trim filler and redundant phrasing only.
• Keep commands, paths, and structural lines exact.
• Prefer concise normal prose, not stylized shorthand, for persisted files.

Fallback

• If Node is unavailable, do not auto-compress.
• If the target is blocked, leave it unchanged and tighten the source workflow instructions instead.