harness v2: spec-compliant parser, suites + CommonMark conformance gate in CI

.github/workflows/lint.yml

@@ -20,6 +20,19 @@ jobs:
           node-version: 22
       - run: npx --yes markdownlint-cli2@0.23.3 "**/*.md" "#node_modules"
 
+  code:
+    name: shellcheck + pyflakes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # shellcheck is preinstalled on ubuntu-latest runners; .shellcheckrc holds the two reviewed exclusions
+      - run: shellcheck --version | head -2 && shellcheck -s bash harness/tests/*.sh
+      # pyflakes rules only (unused names, undefined names, bad imports); flake8 honors the `noqa` markers
+      - run: pip install flake8==7.3.0 && python3 -m flake8 --select=F harness
+
   knowledge:
     name: check-knowledge.py
     runs-on: ubuntu-latest
@@ -28,4 +41,35 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+      - run: pip install -r harness/requirements.txt
       - run: python3 harness/check-knowledge.py
+
+  suites:
+    name: negative-test suites
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -r harness/requirements.txt
+      - run: bash harness/tests/run.sh
+
+  conformance:
+    name: CommonMark conformance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: pip install -r harness/requirements.txt html5lib==1.1
+      # The HTML tokenizer the checker uses to find never-displayed markup, against html5lib (WHATWG).
+      - run: python3 harness/conformance/html_oracle.py
+      # The reference implementation and the official spec examples, pinned to CommonMark 0.31.2.
+      - run: npm install --no-save --no-audit --no-fund --prefix "$RUNNER_TEMP/ref" commonmark@0.31.2 commonmark-spec@0.31.2
+      - run: node harness/conformance/reference.cjs "$RUNNER_TEMP/ref/node_modules" > "$RUNNER_TEMP/ref.json"
+      - run: python3 harness/conformance/check.py "$RUNNER_TEMP/ref.json"

.shellcheckrc

@@ -0,0 +1,5 @@
+# shellcheck settings for harness/tests/*.sh (CI runs shellcheck at its default severity).
+# SC2016: the suites pass Python and Markdown in single quotes on purpose; nothing there may expand.
+disable=SC2016
+# SC2001: `sed 's/^/    /'` indents every line of multi-line output; parameter expansion cannot anchor per line.
+disable=SC2001

CONTRIBUTING.md

@@ -27,12 +27,19 @@ verified fact sheets and fix things. These rules keep them from colliding.
 - Hand or session changes go on `claude/<topic>` and land through a pull
   request. Connector commits are the one exception.
 - The PR body says what changed, pastes the `check-knowledge.py` result, and
-  names the risk.
+  names the risk. A change under `harness/` also pastes `bash harness/tests/run.sh`;
+  a change to `harness/knowledge_md.py` or the markdown-it-py pin must keep the
+  conformance gate green (see the `conformance` job in `.github/workflows/lint.yml`).
+- Found a Markdown shape the checker gets wrong? Render it with the reference
+  implementation (commonmark.js 0.31.2) first, then add it to
+  `harness/conformance/cases.json` and a failing case to `harness/tests/` before fixing.
 - Merge only on green CI.
 
 ## Ledger
 
 Every hand or session change adds one row to `LEDGER.md` (newest first).
+A row written inside its own pull request says `open`; the next ledger change
+flips it to `merged` or `closed` with the merge commit.
 Connector runs are not logged there; their trail is the git history of
 `knowledge.md`.
 

LEDGER.md

@@ -9,7 +9,8 @@ Columns: **Date** is UTC. **Session** is the claude.ai/code link or `hand`.
 
 | Date | Session | Branch | PR | Outcome | Evidence |
 | --- | --- | --- | --- | --- | --- |
-| 2026-09-27 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `claude/face-lift-v1` | #1 | open | correction: `verified/2026-09-26_claude-surfaces_v2.md` (session ran in the chat/Cowork tab, not the Code tab — T's correction 2026-09-27); v1 banner-marked superseded |
-| 2026-09-27 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `claude/face-lift-v1` | #1 | open | README restructure, CONTRIBUTING, ledger, `harness/check-knowledge.py` (RESULT: PASS — 12 pass, 0 warn, 0 fail after review fixes), lint CI, description + topics set via `gh` on the linked PC; follow-up pushes fix 3 Sourcery + 129 Codex findings, 1 pushed back with evidence (27 rounds; rounds 22-25 also rewrote 14 earlier suite cases whose vehicle or CommonMark reading no longer held, each checked against commonmark.js 0.31.2 or by mutation) |
+| 2026-09-27 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `claude/harness-v2` | #2 | open | harness v2: `check-knowledge.py` rebuilt on markdown-it-py (1,345 → 695 lines + 199-line `knowledge_md.py`), 201 negative-test cases moved into `harness/tests/` and CI, CommonMark conformance gate (652/652 spec examples, 71 edge cases vs commonmark.js 0.31.2), 4 old test assertions corrected with reference evidence, `verified/…_v3.md` for the launch-pad rename, lesson feed documented as paused, PR #1 rows flipped to merged (merge `7946224`); 2nd push fixes 5 Codex findings on `78d12a9` (offsets after `<pre>`, invisible-only fields, comments in labels, `--json` without deps, code splitting the confidence word) with round-28 suite (17 cases) and a shellcheck + pyflakes CI job; 3rd push fixes 5 more (whitespace-keeping raw HTML, empty source-link text, mutations that fail silently, `<?>` closing, v3 sheet wording) plus invisible-markup ends matched to Chromium, with round-29 suite (20 cases); 4th push answers 3 more (hidden raw-HTML subtrees, comments around the title, comment-like text in attributes / raw text) by replacing the regex with a browser-faithful HTML tokenizer checked against html5lib (100,000 seeded fuzz fragments in CI) and a rule that raw HTML never counts as a field value, round-30 suite (17 cases); 6th push answers 11 more across three reviews (quoted `</script>` closure via the tokenizer, link-glued confidence, stray end tags, hidden titles, whitespace across inline boundaries, empty later blocks, svg nesting, scoped whitespace preservation, neg11 routed through `mutate()`; the DOCTYPE claim disproved with html5lib + Chromium), round-31 suite (21 cases); 7th push: the review loop on raw-HTML semantics ended by T's decision to ban raw HTML other than comments from lessons (14 positive cases, 4 of them from PR #1, now expect the ban), plus the inline-code-title regression and `</svg/>` fixed, round-32 suite (18 cases); 8th push: Source links must be inline `[title](https://…)` again (a reference-style link was accepted), round-32 suite 21 cases, 297 total; 22 of 22 mutants caught on 37a18eb; 9th push fixes 4 more (inline code at the link boundary, hidden verified H1s, a comment block before the title, allowlisted conformance outputs pinned) and brings raw inline tags in line with the spec on NBSP, round-33 suite (7 cases); 10th push answers Codex + Kilo on 4187200 (newlines inside `<pre>` kept in the conformance canonicalizer; raw-HTML-only H1 text stays a FAIL by the same rule as lessons; Kilo's index and crash reports disproved by T2/T3), round-34 suite (5 cases, 309 total); the HTML-tag whitespace patches now take ASCII whitespace (form feed / vertical tab were wrongly rejected since 78d12a9; 5 new conformance cases); 11th push: fence closure read from the parse (an over-indented would-be closer no longer counts), `<pre>` protected in any case, round-35 suite (3 cases); 12th push: comment blocks before a field label skipped, raw HTML inside image descriptions caught by the ban, round-36 suite (4 cases, 316 total) |
+| 2026-09-27 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `claude/face-lift-v1` | #1 | merged | correction: `verified/2026-09-26_claude-surfaces_v2.md` (session ran in the chat/Cowork tab, not the Code tab — T's correction 2026-09-27); v1 banner-marked superseded |
+| 2026-09-27 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `claude/face-lift-v1` | #1 | merged | README restructure, CONTRIBUTING, ledger, `harness/check-knowledge.py` (RESULT: PASS — 12 pass, 0 warn, 0 fail after review fixes), lint CI, description + topics set via `gh` on the linked PC; follow-up pushes fix 3 Sourcery + 129 Codex findings, 1 pushed back with evidence (27 rounds; rounds 22-25 also rewrote 14 earlier suite cases whose vehicle or CommonMark reading no longer held, each checked against commonmark.js 0.31.2 or by mutation) |
 | 2026-09-26 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `main` | — | direct | commit `ef0c3ac`: `verified/2026-09-26_claude-surfaces_v1.md` |
 | 2026-08-24 | Cowork session | `main` | — | direct | commits `27aa529`…`0763bf4`: repo bootstrap, first 5 lessons (`cfd032a`), README |

README.md

@@ -15,6 +15,13 @@ Written mostly by a machine. The daily.dev MCP connector (Cloudflare Worker
 add verified fact sheets; humans fix typos. Run state (seen-post watermark,
 counters) lives in Cloudflare KV, not here.
 
+> **Status (2026-09-27): the lesson feed is paused.** The scheduled run
+> ("daily-dev-agentic · daily learn") never had the daily.dev connector
+> attached, so from 2026-08-24 it exited early every day while reporting
+> success; T retired it on 2026-09-27. The last lessons are from 2026-08-24.
+> To restart: add the connector in claude.ai (Settings → Connectors → custom
+> connector), enable it on that scheduled task, and switch the task back on.
+
 ## Layout
 
 | Path | What it holds | Written by |
@@ -23,6 +30,9 @@ counters) lives in Cloudflare KV, not here.
 | `lessons/YYYY-MM-DD.md` | The same lessons, one file per day | Connector |
 | `verified/YYYY-MM-DD_topic_vN.md` | Fact sheets verified live in a Claude session, not daily.dev lessons. Revisions bump `vN` | Claude sessions, hand-maintained |
 | `harness/check-knowledge.py` | PASS/FAIL check that the files above still have the shape readers rely on | Run by CI and by sessions |
+| `harness/knowledge_md.py` | The one Markdown parser the checks use: markdown-it-py (CommonMark 0.31.2) plus the patches that align it with the reference | Sessions |
+| `harness/tests/` | 316 negative-test cases: each copies the repo, breaks one thing, and asserts the checker's verdict | Sessions |
+| `harness/conformance/` | Differential gates: the parser must render all 652 CommonMark spec examples and 71 edge cases like the reference implementation, and the HTML tokenizer must split HTML like html5lib | Sessions |
 | `LEDGER.md` | One row per hand-made or session-made change (connector runs are not logged here) | Sessions and hand edits |
 
 ## How a lesson is shaped
@@ -51,12 +61,24 @@ Zero lessons on a quiet day is a valid result; the loop is told never to pad.
 ## Checking it
 
 ```bash
+pip install -r harness/requirements.txt     # markdown-it-py, pinned
 python3 harness/check-knowledge.py          # PASS/FAIL lines
 python3 harness/check-knowledge.py --json   # same, as one JSON object
+bash harness/tests/run.sh                   # the 316 negative-test cases
 ```
 
-CI runs this plus markdownlint on every pull request and on every push to
-`main` (`.github/workflows/lint.yml`). Run it locally before pushing a branch.
+The checker reads Markdown the way CommonMark 0.31.2 does, using a real parser
+rather than pattern matching. Two copies of a lesson count as the same when they
+render to the same visible HTML. Lessons are plain Markdown: raw HTML can
+hide, restyle or swallow what a reader sees, so a lesson holding any raw HTML
+other than a `<!-- comment -->` fails the check. CI runs the checker, the test suites,
+markdownlint, shellcheck, pyflakes and two conformance gates (the Markdown
+parser against the reference implementation, the HTML tokenizer against
+html5lib) on every pull request and every push to `main`
+(`.github/workflows/lint.yml`).
+GitHub itself renders with an older spec (cmark-gfm, 0.29): in rare edge cases,
+such as a lowercase `<!foo>` line, GitHub shows text where 0.31.2 hides a
+declaration.
 
 ## Hand edits