diff --git a/.planning/phases/15-ci-skip-api-harness-jobs-for-doc-only-prs/15-01-SUMMARY.md b/.planning/phases/15-ci-skip-api-harness-jobs-for-doc-only-prs/15-01-SUMMARY.md new file mode 100644 index 0000000..c7a5973 --- /dev/null +++ b/.planning/phases/15-ci-skip-api-harness-jobs-for-doc-only-prs/15-01-SUMMARY.md @@ -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