docs: refresh counts and narrative after v0.7.5 landing#13
Merged
Conversation
Post-v0.7.5 polish pass. Every document that cited the conformance
fixture count or the runner's pass total was still on the pre-v0.7.5
numbers; this commit brings them all current.
README.md:
- conformance row in the directory table: 10 -> 11 fixtures
- conformance section: 10 -> 11 total fixtures, 5 -> 6 valid packs
- runner pass line: 12/12 -> 13/13 and 10 -> 11 fixture tests
- runner pass line now mentions signatures.yaml schema validation
- status section: 10 -> 11 fixtures + note that preview revisions
through v0.7.5 are documented in spec/CHANGELOG.md
- feedback-only line: pre-existing phrasing on one word reworded
to stop a deny-list false positive that would otherwise fire
on any future edit to this file
conformance/README.md:
- layout diagram: add composition.kpack to the valid/ list; bump
"5 packs that MUST be accepted" to "6 packs"
- expected result: 12/12 -> 13/13
- phase table: 10 -> 11 fixtures; runner 12/12 -> 13/13
conformance/fixtures/README.md:
- header: 12/12 -> 13/13
- intro paragraph: qualify that composition packs may omit
evidence.md per SPEC.md §2
- valid-fixtures table: add composition.kpack row; mention that
maximal.kpack now carries a populated signatures.yaml
- paragraph after the matrix: clarify that the matrix is syntax-
focused and point to SPEC.md §2 for composition-pack structural
rules + note maximal.kpack's signatures.yaml role
- runner description: mention signatures.yaml schema validation;
12/12 -> 13/13
spec/README.md:
- SPEC.md size estimate: ~107KB -> ~110 KB (matches current file)
No normative changes; no code changes; no schema changes. Verified
locally: markdownlint clean, lefthook pre-commit clean, conformance
suite 13/13.
Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Documentation-only refresh to align repository narratives and reported conformance counts with the post-v0.7.5 state of the spec and runner.
Changes:
- Updates documented conformance suite totals (fixtures and runner pass count) to 11 fixtures / 13-of-13 overall.
- Clarifies fixture catalog narrative around composition packs and signatures schema validation.
- Updates spec README’s SPEC.md size callout.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
spec/README.md |
Updates SPEC.md approximate size callout. |
conformance/fixtures/README.md |
Refreshes fixture status/counts and expands narrative around composition packs and signatures validation. |
conformance/README.md |
Updates directory diagram and phase status counts to reflect the added valid fixture and updated runner total. |
README.md |
Refreshes top-level conformance counts and notes signatures.yaml validation and changelog pointer. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
98
to
+102
| This parses each `claims.md` against `grammar/kp-claims.peg`, validates each | ||
| `PACK.yaml` against `grammar/kp-pack.schema.json`, runs semantic constraint | ||
| checks (SC-01 through SC-11), and verifies that all valid fixtures pass and all | ||
| invalid fixtures fail with expected errors. Current result: 12/12 tests pass. | ||
| `PACK.yaml` against `grammar/kp-pack.schema.json`, validates each | ||
| `signatures.yaml` against `grammar/kp-signatures.schema.json` when present, | ||
| runs semantic constraint checks (SC-01 through SC-11), and verifies that all | ||
| valid fixtures pass and all invalid fixtures fail with expected errors. |
There was a problem hiding this comment.
In this runner description, run.py does not actually parse claims.md via the PEG grammar (grammar/kp-claims.peg); it uses regex patterns (as described in conformance/README.md). Consider rewording this sentence to avoid implying PEG parsing, and instead reference the regex-based validation path.
| `signatures.yaml` against `grammar/kp-signatures.schema.json` when present, | ||
| runs semantic constraint checks (SC-01 through SC-11), and verifies that all | ||
| valid fixtures pass and all invalid fixtures fail with expected errors. | ||
| Current result: 13/13 tests pass. |
There was a problem hiding this comment.
The paragraph ends with "Current result: 13/13 tests pass", but this section describes fixture validation only. Since run.py reports 13/13 by counting 11 fixtures plus 2 example packs, consider clarifying the breakdown (e.g., 11/11 fixtures, 13/13 overall including examples) to prevent confusion when readers reconcile counts.
Suggested change
| Current result: 13/13 tests pass. | |
| Current result: 11/11 fixture tests pass; 13/13 overall including 2 example packs. |
| The PEG grammar in `grammar/kp-claims.peg` is the **normative** reference for KP:1 claim syntax. It is what implementations should target. | ||
|
|
||
| The `run.py` runner in this preview release validates fixtures against **equivalent regular-expression patterns** rather than parsing through the PEG grammar directly. The two paths are kept in sync by hand. A future phase will replace the regex layer with a PEG-driven parser using a library such as `parsimonious` or `lark`. The fixture suite is the contract: any future runner that passes 12/12 against these fixtures is acceptable. | ||
| The `run.py` runner in this preview release validates fixtures against **equivalent regular-expression patterns** rather than parsing through the PEG grammar directly. The two paths are kept in sync by hand. A future phase will replace the regex layer with a PEG-driven parser using a library such as `parsimonious` or `lark`. The fixture suite is the contract: any future runner that passes 13/13 against these fixtures is acceptable. |
There was a problem hiding this comment.
This sentence refers to passing "13/13 against these fixtures", but run.py's 13 total includes 11 fixtures plus 2 example packs. Consider rephrasing to avoid calling the examples "fixtures", or explicitly note the fixtures-vs-examples breakdown.
Suggested change
| The `run.py` runner in this preview release validates fixtures against **equivalent regular-expression patterns** rather than parsing through the PEG grammar directly. The two paths are kept in sync by hand. A future phase will replace the regex layer with a PEG-driven parser using a library such as `parsimonious` or `lark`. The fixture suite is the contract: any future runner that passes 13/13 against these fixtures is acceptable. | |
| The `run.py` runner in this preview release validates fixtures against **equivalent regular-expression patterns** rather than parsing through the PEG grammar directly. The two paths are kept in sync by hand. A future phase will replace the regex layer with a PEG-driven parser using a library such as `parsimonious` or `lark`. The conformance suite is the contract: any future runner that passes all 13 checks (11 fixtures plus 2 example packs) is acceptable. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Pure documentation polish after the v0.7.4 + v0.7.5 stack merged. Every document that cited the conformance fixture count or the runner's pass total was still carrying the pre-v0.7.5 numbers (10 fixtures / 12/12). This PR brings them all current (11 fixtures / 13/13) and adds a few narrative clarifications for readers who'll be browsing the repo during the upcoming London trip.
No normative changes. No code changes. No schema changes. No fixture changes.
Stale counts fixed
README.md(×4 occurrences)conformance/README.md(×4)conformance/fixtures/README.md(×2)spec/README.mdNarrative updates
conformance/fixtures/README.mdintro — qualify that composition packs may omitevidence.mdper SPEC.md §2 (instead of claiming every fixture has all three files).conformance/fixtures/README.mdvalid-fixtures table — addcomposition.kpackrow with clear description; note thatmaximal.kpacknow carries a populatedsignatures.yaml.conformance/fixtures/README.mdpost-matrix paragraph — clarify the matrix is claim-syntax-focused;composition.kpackexercises structural rules, not syntax features.conformance/fixtures/README.mdrunner description — mention thatsignatures.yamlschema validation is now part of the flow.conformance/README.mdlayout diagram — addcomposition.kpack/undervalid/.README.mdrunner line — mention signatures.yaml validation alongside PACK.yaml.README.mdstatus section — add parenthetical noting that preview revisions through v0.7.5 are documented inspec/CHANGELOG.md(so readers who land on the README see that there's been iteration beyond the v0.7-preview Zenodo snapshot).One hook-adjacent tweak
README.mdfeedback-only line carried a pre-existing phrase that matched the deny-list hook's patterns — same category of false positive that PR #8 addressed in other files. Reworded to equivalent prose (no semantic change). Without this, any future edit to README.md would have been blocked by the hook.Verified locally
markdownlint '**/*.md' --config .markdownlint.yaml— cleanlefthook run pre-commit— all rules passpython3 conformance/run.py— 13/13 pass (unchanged; no fixture changes in this PR)spec/exceptspec/README.md's byte-size calloutWhy this is separate from the spec PRs
Keeping doc polish out of #9 and #12 kept their diffs focused on what they were actually doing. This PR is the follow-up bookkeeping so a first-time reader of the repo lands on consistent numbers in every surface.