Add Markdown linting

.github/pull_request_template.md

@@ -13,5 +13,6 @@
 ## Notes
 
 Validation details:
+
 - `npm test`: <!-- passed / not run -->
 - If not run, why: <!-- short reason -->

.github/workflows/ci.yml

@@ -9,6 +9,20 @@ on:
       - main
 
 jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run Markdown lint
+        run: npm run lint:md
+
   build-and-test:
     runs-on: ubuntu-latest
     timeout-minutes: 15

.markdownlint-cli2.jsonc

@@ -0,0 +1,50 @@
+{
+  "globs": [
+    "**/*.md",
+    "!**/node_modules/**",
+    "!**/.venv/**",
+    "!**/.next/**",
+    "!**/.pytest_cache/**"
+  ],
+  "config": {
+    "default": true,
+    "MD013": false,
+    "MD024": {
+      "siblings_only": true
+    },
+    "MD033": false,
+    "MD046": {
+      "style": "fenced"
+    }
+  },
+  "overrides": [
+    {
+      "filter": [
+        ".github/ISSUE_TEMPLATE/*.md",
+        ".github/pull_request_template.md"
+      ],
+      "config": {
+        "MD041": false
+      },
+      "combine": "merge"
+    },
+    {
+      "filter": [
+        "AGENTS.md"
+      ],
+      "config": {
+        "MD032": false
+      },
+      "combine": "merge"
+    },
+    {
+      "filter": [
+        "tests/fixtures/engine-regression/structured/README.md"
+      ],
+      "config": {
+        "MD004": false
+      },
+      "combine": "merge"
+    }
+  ]
+}

CODE_OF_CONDUCT.md

@@ -66,6 +66,6 @@ violation of this Code of Conduct.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.1, available at
-https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
 
-[homepage]: https://www.contributor-covenant.org
+[homepage]: <https://www.contributor-covenant.org>

CONTRIBUTING.md

@@ -19,6 +19,7 @@ The fixture corpus and directive grammar specification are authoritative.
 For README, demo, integration, and package-listing docs, explain user-visible behavior before architecture.
 
 Prefer plain, concrete wording when accurate. Examples:
+
 - "rules and corrections that stick"
 - "saved compiler state"
 - "stored premise and policy rules"
@@ -28,6 +29,7 @@ Prefer plain, concrete wording when accurate. Examples:
 Avoid describing features only in architectural terms when a behavior-first explanation is possible.
 
 Specification and contract documents are different:
+
 - Preserve precise terminology
 - Preserve unambiguous behavioral guarantees
 - Do not weaken formal semantics for readability

README.md

@@ -25,6 +25,7 @@ are accepted.
 Saved state can drive prompt rendering, schema selection, routing, tool
 availability, or other host behavior, but your app still needs rules for when
 that state is allowed to change:
+
 - when a replacement is valid
 - when a conflicting update should stop and ask for confirmation
 - when a change should be rejected instead of silently overwriting state
@@ -33,17 +34,20 @@ that state is allowed to change:
 ## How it solves it
 
 Context Compiler lets a host application:
+
 - prevent silent overwrites when a new update conflicts with what is already saved
 - require clarification before conflicting or confirmation-only changes are accepted
 - let the host preview a change before applying it and keep live state unchanged until it is accepted
 - restore both saved state and an in-progress clarification flow safely between requests
 
 Each user input produces a decision for the host:
+
 - `update` -> stored premise/policy rules changed
 - `passthrough` -> input does not affect saved state
 - `clarify` -> do not mutate state; ask the user to confirm or clarify
 
 Directive examples:
+
 - `set premise current project uses uv`
 - `use sqlite`
 - `prohibit docker`

demos/README.md

@@ -3,6 +3,7 @@
 These scripts show side-by-side LLM outcomes with and without stored compiler rules, aligned with the [Python reference demos](https://github.com/rlippmann/context-compiler/blob/main/demos/README.md).
 
 Scored demos compare three host-side flows:
+
 - baseline
 - compiler path (full transcript + injected stored rules and state)
 - compiler+compact (compacted transcript + injected stored rules and state)
@@ -32,6 +33,7 @@ LLM demo outcomes can vary across environments. PASS/FAIL patterns may differ ba
 ## Requirements
 
 Environment variables:
+
 - `OPENAI_API_KEY` (required)
 - `MODEL` (required)
 - `OPENAI_BASE_URL` (optional; set for OpenAI-compatible local/hosted endpoints)

package.json

@@ -48,7 +48,8 @@
     "fixtures:check:all": "npm run fixtures:check && npm run fixtures:structured:check",
     "prepack": "npm run build",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "lint:md": "npx --yes markdownlint-cli2@0.23.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

tests/fixtures/README.md

@@ -106,4 +106,3 @@ See the TypeScript fixture runners in this repository for execution details:
 * [`checkpoint-fixtures.test.ts`](../checkpoint-fixtures.test.ts)
 * [`controller-fixtures.test.ts`](../controller-fixtures.test.ts)
 * [`structured-regression-fixtures.test.ts`](../structured-regression-fixtures.test.ts)
-