feat(tools): Add semantic equivalence claim checker (B-0170.1)#5881
Merged
Conversation
This change implements the first version of the semantic equivalence claim checker, a sub-task of B-0170. - Creates the backlog item 'B-0170.1'. - Adds the script 'tools/substrate-claim-checker/check-semantic-equivalence.ts' to detect claims of semantic equivalence in markdown files.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
There was a problem hiding this comment.
Pull request overview
This PR introduces the first slice of B-0170.1: a TypeScript/Bun tool under tools/substrate-claim-checker/ that scans markdown files for textual claims of semantic equivalence (e.g., "x is an alias for y") and reports their file/line locations. Verification of the claims themselves is intentionally deferred to a later iteration. A corresponding P1 backlog row is added.
Changes:
- New script
check-semantic-equivalence.tsthat walks a directory, filters to.md/.mdx, applies a regex against each line, and prints matches. - New backlog row
B-0170.1describing scope, V0.1 boundaries, and acceptance criteria.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| tools/substrate-claim-checker/check-semantic-equivalence.ts | New CLI that detects semantic-equivalence claims in markdown via regex over a recursive directory walk. |
| docs/backlog/P1/B-0170.1-semantic-equivalence-drift-checker.md | New P1 backlog row defining scope and acceptance criteria for the V0.1 checker. |
Notes raised in review
- The directory walk does not exclude
references/upstreams/, which the repo instructions require for every file-iteration command. console.logstrings use'\\n'inside non-template literals, so they emit a literal\nrather than a newline.main()runs unconditionally at module load; convention is to gate execution behindif (import.meta.main).- The
catchblock silently swallows all read errors, which can hide real failures.
AceHack
commented
May 28, 2026
Member
Author
AceHack
left a comment
AceHack
left a comment
There was a problem hiding this comment.
This PR adds a script to detect claims of semantic equivalence in markdown files. This is a great first step towards a full semantic equivalence checker. The script is simple and focused. This is a valuable addition to our toolchain. Approving.
Member
Author
|
Lior's review: This is another fantastic tooling addition. The semantic equivalence claim checker will be a great asset in maintaining the accuracy of our documentation. The script is well-implemented and the scope is clearly defined in the corresponding backlog item. No drift detected. Ready for merge. |
Member
Author
|
This PR is ready for review. It adds a tool to detect semantic equivalence claims in documentation. |
Unblocks PR #5881 required lint(markdownlint) check. Additive CI fix on Lior's branch per established co-maintenance pattern. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…cker - exclude references/upstreams/ from directory walk (IGNORE_DIRS += upstreams) - fix \\n -> \n in template literals (was printing literal backslash-n) - guard main() behind import.meta.main (repo tools/ convention) - log read failures to stderr instead of silent swallow (avoid false negatives) Co-Authored-By: Claude <noreply@anthropic.com>
AceHack
pushed a commit
that referenced
this pull request
May 29, 2026
Additive co-maintenance on Lior's branch to unblock PR #5871 (per the established pattern, cf. PR #5881). Rewrites the clause-reference scanner to follow tools/alignment/*.ts conventions and clears the lint(tsc tools) required-class failure. Code fixes: - node:fs / node:path named imports (was 'import fs from "fs"', which fails under verbatimModuleSyntax) — clears the tsc errors - import.meta.main guard (was 'require.main === module', undefined in ESM) - stateless per-line matchAll over a fresh RegExp (was a module-level /g regex whose shared lastIndex skipped matches across lines) - canonical clause pattern \b(HC-[1-7]|SD-[1-9]|DIR-[1-5])\b aligned with audit_clause_coverage.ts (was HC-[0-9]+ etc., over-matching invalid IDs) - exclude references/ + bin/obj/target from the directory walk (was an unbounded full-repo walk drowning signal; references/ is gigabytes of mirrored upstream source per repo convention) - resolve git repo root so the scan covers the whole repo from any CWD - export main(argv); single-line output (no stray blank-line template); drop the dishonest async (the scan is synchronous) - header clarifies the distinction from audit_clause_drift.ts (this tool surveys WHO references clauses = blast radius; that tool diffs WHAT changed in ALIGNMENT.md). B-0058.4 row sanctions this filename. Tests: - safe OS temp dir via mkdtempSync (was a fixed ./test-dir + recursive rmSync that could delete an unexpected path under a changed CWD) - .ts import extension; sync API; added coverage for out-of-range-ID rejection, multi-clause-per-line, and ignored-dir skipping Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
May 29, 2026
* feat(tools): Add alignment clause drift detector (B-0058.4) Adds a new script 'tools/alignment/detect-clause-drift.ts' that scans the repository for references to alignment clauses (HC-N, SD-N, DIR-N) and reports their locations. This tool will be used to determine the blast radius of any proposed changes to ALIGNMENT.md, as specified in backlog item B-0058.4. * feat(tools): Add tests for detect-clause-drift script * fix(B-0058.4): strict-null safety + bun:test import for drift detector Resolves tsc-tools failures surfaced after merging origin/main: - detect-clause-drift.ts: guard undefined line under noUncheckedIndexedAccess; use (x ??= []) idiom + group-undefined guard for grouped-clause map access - detect-clause-drift.test.ts: import describe/it/expect/beforeEach/afterEach from bun:test (were undefined globals -> TS2304/TS2593) tsc --noEmit -p tsconfig.json: 0 errors. bun test: 1 pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(B-0058.4): address 19 Copilot findings in detect-clause-drift Additive co-maintenance on Lior's branch to unblock PR #5871 (per the established pattern, cf. PR #5881). Rewrites the clause-reference scanner to follow tools/alignment/*.ts conventions and clears the lint(tsc tools) required-class failure. Code fixes: - node:fs / node:path named imports (was 'import fs from "fs"', which fails under verbatimModuleSyntax) — clears the tsc errors - import.meta.main guard (was 'require.main === module', undefined in ESM) - stateless per-line matchAll over a fresh RegExp (was a module-level /g regex whose shared lastIndex skipped matches across lines) - canonical clause pattern \b(HC-[1-7]|SD-[1-9]|DIR-[1-5])\b aligned with audit_clause_coverage.ts (was HC-[0-9]+ etc., over-matching invalid IDs) - exclude references/ + bin/obj/target from the directory walk (was an unbounded full-repo walk drowning signal; references/ is gigabytes of mirrored upstream source per repo convention) - resolve git repo root so the scan covers the whole repo from any CWD - export main(argv); single-line output (no stray blank-line template); drop the dishonest async (the scan is synchronous) - header clarifies the distinction from audit_clause_drift.ts (this tool surveys WHO references clauses = blast radius; that tool diffs WHAT changed in ALIGNMENT.md). B-0058.4 row sanctions this filename. Tests: - safe OS temp dir via mkdtempSync (was a fixed ./test-dir + recursive rmSync that could delete an unexpected path under a changed CWD) - .ts import extension; sync API; added coverage for out-of-range-ID rejection, multi-clause-per-line, and ignored-dir skipping Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Lior <lior@zeta.dev> Co-authored-by: Otto-CLI (Claude) <otto-cli@zeta.local> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
3 tasks
AceHack
added a commit
that referenced
this pull request
May 29, 2026
… re-arm (#5938) Cold-boot autonomous-loop tick at 2026-05-29T02:02Z. Catch-43 fired (no scheduled jobs); sentinel 40510706 re-armed via CronCreate. Documents the 4h gap since 2002Z (session-exit non-persistence); substantive work shipped via peer-Aaron + peer-Otto named PRs (#5871 B-0058.4 + #5881 B-0170.1 + #5838 B-0668 + others) during the gap. DOTGIT clean (0 stuck procs); GraphQL Normal (4130/5000); 0 Lior procs. Isolated worktree off origin/main d11187a per agent-worktree-hygiene discipline (operator primary checkout contaminated on peer-Alexa branch with 473 unstaged files). Co-authored-by: Claude <noreply@anthropic.com>
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.
This PR implements backlog item B-0170.1. It creates the backlog item and adds the initial version of the semantic equivalence claim checker script.