familysync/.planning/phases/15-ci-skip-api-harness-jobs-for-doc-only-prs/15-01-SUMMARY.md

phase, plan, subsystem, tags, dependency_graph, tech_stack, key_files, decisions, metrics

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics
15-ci-skip-api-harness-jobs-for-doc-only-prs	01	ci	markdownlint ci docs fast-checks	requires provides affects markdownlint-cli2 root devDependency (0.22.1) md:lint root package.json script .markdownlint-cli2.jsonc config (Prettier-compatible preset + content rules) Markdown lint step in fast-checks CI job .gitea/workflows/ci.yml (fast-checks job — new Markdown lint step) package.json (new script + devDependency) 7 doc files (13 baseline violations fixed)	added patterns markdownlint-cli2@0.22.1 (root devDependency) Config-file-driven markdownlint (globs/ignores in .markdownlint-cli2.jsonc, not CLI args) markdownlint/style/prettier preset to avoid Prettier/markdownlint rule conflicts	created modified .markdownlint-cli2.jsonc package.json pnpm-lock.yaml .gitea/workflows/ci.yml README.md apps/api/README.md apps/pwa/README.md apps/pwa/e2e/README.md docs/API.md docs/ARCHITECTURE.md docs/DEVELOPMENT.md docs/GETTING-STARTED.md	md:lint script uses no glob args — globs and ignores live in .markdownlint-cli2.jsonc so pnpm md:lint and npx markdownlint-cli2 behave identically (RESEARCH Open Question 3) MD031 re-enabled despite prettier preset disabling it — GETTING-STARTED.md has a genuine structural fix (fence inside list item with no blank lines); verified MD031 fix does not conflict with Prettier (format:check still 0 after fix) MD040 bare fences tagged as 'text' for plain-output blocks (SSE event format, directory trees); 'bash' for shell commands Prettier reformatted .markdownlint-cli2.jsonc (added trailing commas per JSONC trailingComma:all rule) — committed in Task 2	duration_minutes completed_date tasks_completed files_changed 4 2026-06-12 2 12

Phase 15 Plan 01: Markdown Lint Gate Summary

One-liner: markdownlint-cli2@0.22.1 with Prettier-compatible config wired into fast-checks CI; 13 baseline violations fixed across 7 doc files, gate starts green.

Tasks Completed

Task	Name	Commit	Files
1	Install markdownlint-cli2, add md:lint script, create .markdownlint-cli2.jsonc	adb7641	.markdownlint-cli2.jsonc, package.json, pnpm-lock.yaml
2	Fix 13 baseline violations; green md:lint + format:check; wire fast-checks step	46bea03	.gitea/workflows/ci.yml, .markdownlint-cli2.jsonc (Prettier reformat), README.md, apps/api/README.md, apps/pwa/README.md, apps/pwa/e2e/README.md, docs/API.md, docs/ARCHITECTURE.md, docs/DEVELOPMENT.md, docs/GETTING-STARTED.md

What Was Built

Task 1: markdownlint-cli2 install + config

• Installed markdownlint-cli2@0.22.1 as a root workspace devDependency via pnpm add -D markdownlint-cli2@0.22.1 --workspace-root
• Added "md:lint": "markdownlint-cli2" script to root package.json after format:check
• Created .markdownlint-cli2.jsonc at repo root with:
  • extends: "markdownlint/style/prettier" — disables the 23 rules Prettier owns (including MD013 line-length, which would produce 700+ false positives against printWidth 100)
  • Content rules ENABLED: MD001, MD024, MD040, MD031, MD051, MD052
  • Rules DISABLED: MD041 (CLAUDE.md starts with ## Project), MD034 (pkg@version syntax in version tables), MD036 (docs/API.md uses **Response 200** as semantic labels)
  • globs: ["docs/**/*.md", "*.md", "apps/**/*.md"]
  • ignores: [".planning/**", "node_modules/**", "**/node_modules/**", ".pnpm-store/**"]

Task 2: Baseline fixes + CI wiring

Fixed all 13 violations:

• MD040 (11 bare fences): Added language tags across 7 files:
  • apps/api/README.md:19 — directory tree → text
  • apps/pwa/e2e/README.md:76 — pseudo-code block → text
  • apps/pwa/README.md:45 — directory tree → text
  • docs/API.md:517 — SSE event format → text
  • docs/API.md:544 — SSE event format example → text
  • docs/ARCHITECTURE.md:64 — directory tree → text
  • docs/ARCHITECTURE.md:171 — backend module flow → text
  • docs/DEVELOPMENT.md:9 — directory tree → text
  • docs/DEVELOPMENT.md:22 — directory tree → text
  • README.md:78 — monorepo structure → text
  • README.md:119 — CalDAV principal URL → text
• MD031 (2 violations): docs/GETTING-STARTED.md:52-54 — added blank lines before ```bash and after closing ``` surrounding the node -e command inside a list item

Wired CI step in .gitea/workflows/ci.yml:

      - name: Markdown lint
        run: pnpm md:lint

Inserted after Format check, before Typecheck in the fast-checks job.

Verification performed:

• pnpm md:lint exits 0 (Summary: 0 error(s), 12 files scanned)
• pnpm format:check exits 0 (no Prettier conflict from MD031 blank-line additions)
• Gate-can-fail test: appended a bare fence to README.md, confirmed pnpm md:lint exits non-zero (1 error), then reverted via git checkout -- README.md (NOTE: this reverted the Task 2 README.md fixes; they were re-applied before the Task 2 commit)

Deviations from Plan

Auto-fixed Issues

1. [Rule 1 - Bug] Prettier reformatted .markdownlint-cli2.jsonc

• Found during: Task 2 format:check run
• Issue: .markdownlint-cli2.jsonc created in Task 1 had no trailing commas; Prettier's trailingComma: "all" added trailing commas to the JSONC properties and arrays
• Fix: Ran pnpm format -- .markdownlint-cli2.jsonc to apply Prettier's preferred style; verified pnpm md:lint still passes after the reformat
• Files modified: .markdownlint-cli2.jsonc
• Commit: 46bea03 (included in Task 2 commit with the doc fixes)

2. [Rule 1 - Bug] gate-can-fail test reverted README.md MD040 fixes

• Found during: Task 2 gate verification test
• Issue: Using git checkout -- README.md to revert the test bare fence also reverted the two MD040 fixes previously applied in Task 2 (README.md:78 and :119). The gate-can-fail test used git checkout -- README.md for cleanup which is a blanket revert.
• Fix: Re-read README.md, re-applied both MD040 fixes (text language tags at lines 78 and 119), confirmed pnpm md:lint exits 0 before committing
• Files modified: README.md
• Commit: 46bea03

Known Stubs

None — plan goal (markdownlint gate) is fully wired and green.

Threat Surface Scan

No new network endpoints, auth paths, file access patterns, or schema changes introduced. The only surface is the markdownlint-cli2 devDependency (supply chain) — addressed in the plan's threat model (T-15-01: pinned to exact 0.22.1, package legitimacy audit OK in RESEARCH.md).

Self-Check: PASSED

• .markdownlint-cli2.jsonc exists at repo root: FOUND
• package.json contains md:lint script and markdownlint-cli2 devDep: FOUND
• .gitea/workflows/ci.yml contains pnpm md:lint step: FOUND
• Commit adb7641 exists: FOUND
• Commit 46bea03 exists: FOUND
• pnpm md:lint exits 0: VERIFIED
• pnpm format:check exits 0: VERIFIED