git:20260609.53af070 to git:20260811.e3ac13c

22 added, 8 removed. Audit A to A.

---

name: markdown-compression

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

+ 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. This is not a general rewrite tool.

+ 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 workflow, agent, instruction, and wrapper Markdown under `.github/`, `.agents/`, `.claude/`, `.windsurf/`, `.opencode/`, `.codex/`

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

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

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

## Compression Rules

- Trim filler and redundant phrasing only.

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