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..215f150 --- /dev/null +++ b/.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" + } + ] +} 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..5c36271 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@0.23.0" }, "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) -