2026-06-12 11:08:54 -04:00
1 changed files with 137 additions and 0 deletions
@@ -0,0 +1,137 @@
+---
+phase: 15-ci-skip-api-harness-jobs-for-doc-only-prs
+plan: "01"
+subsystem: ci
+tags: [markdownlint, ci, docs, fast-checks]
+dependency_graph:
+  requires: []
+  provides:
+    - 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
+  affects:
+    - .gitea/workflows/ci.yml (fast-checks job — new Markdown lint step)
+    - package.json (new script + devDependency)
+    - 7 doc files (13 baseline violations fixed)
+tech_stack:
+  added:
+    - markdownlint-cli2@0.22.1 (root devDependency)
+  patterns:
+    - Config-file-driven markdownlint (globs/ignores in .markdownlint-cli2.jsonc, not CLI args)
+    - markdownlint/style/prettier preset to avoid Prettier/markdownlint rule conflicts
+key_files:
+  created:
+    - .markdownlint-cli2.jsonc
+  modified:
+    - 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
+decisions:
+  - "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"
+metrics:
+  duration_minutes: 4
+  completed_date: "2026-06-12"
+  tasks_completed: 2
+  files_changed: 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`:
+```yaml
+      - 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