git:20260811.e3ac13c to git:20260813.ba935f1

4 added, 1 removed. Audit A to A.

---

name: markdown-compression

description: "Safely compresses narrative Markdown using deterministic compaction plus validator checks. Only for allowlisted and gated artifacts."

---

# Markdown Compression

Use this only for safe narrative Markdown or explicitly gated governance prose. 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`

## Gated Targets

- `.github/skills/implement-tasks/SKILL.md` - exact manifest entry; compresses only prose inside `<rules>` and `<workflow>` blocks

- all other governance files require a separate manifest entry and dry-run review before compression

## Blocked Targets

- `project-instructions.md`, `AGENTS.md`, `CLAUDE.md`

- all unlisted 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 or explicitly gated and validator-safe.

2. For preview only, run `node scripts/compress-markdown.mjs --stdout <path>`; gated targets automatically use narrative-only mode.

3. Review the proposed diff. For a manual narrative-only preview, add `--narrative-only`.

4. To write the compressed file, run `node scripts/compress-markdown.mjs <path>`.

5. Run `node scripts/compress-markdown.mjs --idempotent <path>` after writing and in CI.

6. The script creates `<name>.original.md` once, then preserves it on later runs.

7. If validation fails, stop. Do not write partial output.

+ 8. Symbolic-link paths are blocked; authorization uses the canonical target path.

## Validation Guarantees

The validator preserves these elements exactly:

- frontmatter

- headings

- fenced code blocks

- inline code

- bare URLs and Markdown links

- requirement and task identifiers

- table rows

- checkbox lines

- Markdown list prefixes and indented lines

- HTML comment blocks

- `<rules>` and `<workflow>` tag lines

- every line outside gated narrative blocks

+ - HTML blocks, tables, nested blockquotes, and ordered-parenthesis lists

+ - original line endings

## Compression Rules

- - Trim filler and redundant phrasing only.

+ - Normalize redundant whitespace and punctuation spacing only; do not substitute words or phrases.

- Keep commands, paths, and structural lines exact.

- Compress governance prose only inside the explicitly supported narrative blocks.

- 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.