From 5eab3618a729eb75f37342c8605859f663cf76e6 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 11 Jul 2026 04:10:13 -0400 Subject: [PATCH 1/3] chore: add markdown linting --- .github/pull_request_template.md | 1 + .github/workflows/ci.yml | 14 +++++++ .markdownlint-cli2.jsonc | 41 +++++++++++++++++++ CODE_OF_CONDUCT.md | 4 +- CONTRIBUTING.md | 2 + README.md | 4 ++ demos/README.md | 2 + package.json | 3 +- tests/fixtures/README.md | 1 - .../engine-regression/structured/README.md | 14 +++---- 10 files changed, 75 insertions(+), 11 deletions(-) create mode 100644 .markdownlint-cli2.jsonc diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5fb5fa0..dd0d8fd 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,5 +13,6 @@ ## Notes Validation details: + - `npm test`: - If not run, why: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b0b979d..bf9f897 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..fe59ac7 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,41 @@ +{ + "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" + } + ] +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index fc4efce..f78a827 100644 --- a/CODE_OF_CONDUCT.md +++ b/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]: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9cb8130..3bd207f 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index 8f53289..ba25718 100644 --- a/README.md +++ b/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` diff --git a/demos/README.md b/demos/README.md index 201272b..ba21f19 100644 --- a/demos/README.md +++ b/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) diff --git a/package.json b/package.json index 64bc622..a22ed3c 100644 --- a/package.json +++ b/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" }, "devDependencies": { "typescript": "^5.9.3", diff --git a/tests/fixtures/README.md b/tests/fixtures/README.md index 8ae6988..98f0fee 100644 --- a/tests/fixtures/README.md +++ b/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) - diff --git a/tests/fixtures/engine-regression/structured/README.md b/tests/fixtures/engine-regression/structured/README.md index 6d27fe8..8f8e7dc 100644 --- a/tests/fixtures/engine-regression/structured/README.md +++ b/tests/fixtures/engine-regression/structured/README.md @@ -41,19 +41,19 @@ A full checkpoint is stored and compared on every turn so regressions are visibl These fixtures validate **deterministic engine behavior only**: -- `engine.step(...)` outputs (`Decision.kind`, `prompt_to_user`) -- post-turn checkpoint (`authoritative_state` + `pending`) +* `engine.step(...)` outputs (`Decision.kind`, `prompt_to_user`) +* post-turn checkpoint (`authoritative_state` + `pending`) They do **not** cover: -- REPL / user-facing formatting -- LLM integration behavior -- acquisition-layer directive drafting +* REPL / user-facing formatting +* LLM integration behavior +* acquisition-layer directive drafting These surfaces are tested separately because: -- REPL output may intentionally differ from the underlying state representation -- acquisition-layer drafting is outside the engine contract +* REPL output may intentionally differ from the underlying state representation +* acquisition-layer drafting is outside the engine contract This fixture set is the **canonical engine-level conformance surface**, and may be reused by other implementations (e.g., TypeScript) to validate identical engine behavior. From 4a11dead0898fd0817592269540d130379864ec5 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 11 Jul 2026 04:21:56 -0400 Subject: [PATCH 2/3] chore: add markdown linting --- .markdownlint-cli2.jsonc | 9 +++++++++ package.json | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index fe59ac7..215f150 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -36,6 +36,15 @@ "MD032": false }, "combine": "merge" + }, + { + "filter": [ + "tests/fixtures/engine-regression/structured/README.md" + ], + "config": { + "MD004": false + }, + "combine": "merge" } ] } diff --git a/package.json b/package.json index a22ed3c..5c36271 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,7 @@ "prepack": "npm run build", "test": "vitest run", "test:watch": "vitest", - "lint:md": "npx --yes markdownlint-cli2" + "lint:md": "npx --yes markdownlint-cli2@0.23.0" }, "devDependencies": { "typescript": "^5.9.3", From 1dd80e8037649aa24cf20b5566bdc7f0a84a0a35 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 11 Jul 2026 04:25:47 -0400 Subject: [PATCH 3/3] chore: add markdown linting --- .../engine-regression/structured/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/fixtures/engine-regression/structured/README.md b/tests/fixtures/engine-regression/structured/README.md index 8f8e7dc..6d27fe8 100644 --- a/tests/fixtures/engine-regression/structured/README.md +++ b/tests/fixtures/engine-regression/structured/README.md @@ -41,19 +41,19 @@ A full checkpoint is stored and compared on every turn so regressions are visibl These fixtures validate **deterministic engine behavior only**: -* `engine.step(...)` outputs (`Decision.kind`, `prompt_to_user`) -* post-turn checkpoint (`authoritative_state` + `pending`) +- `engine.step(...)` outputs (`Decision.kind`, `prompt_to_user`) +- post-turn checkpoint (`authoritative_state` + `pending`) They do **not** cover: -* REPL / user-facing formatting -* LLM integration behavior -* acquisition-layer directive drafting +- REPL / user-facing formatting +- LLM integration behavior +- acquisition-layer directive drafting These surfaces are tested separately because: -* REPL output may intentionally differ from the underlying state representation -* acquisition-layer drafting is outside the engine contract +- REPL output may intentionally differ from the underlying state representation +- acquisition-layer drafting is outside the engine contract This fixture set is the **canonical engine-level conformance surface**, and may be reused by other implementations (e.g., TypeScript) to validate identical engine behavior.