chore(claude): refresh the contributor, CI and Claude Code setup - #12
Merged
Conversation
An outside pull request failed the commit check because nothing a contributor reads said what the standard is. The rules now live in CONTRIBUTING.md and the pull request template, in plain words. - CONTRIBUTING.md covers setup with uv, the test command, the two-engine rule, /v1 compatibility, every commit rule CI enforces, and CHANGELOG scope - The pull request template carries the same checklist - The README links both, and its "From source" steps use uv and Python 3.14 instead of pip and 3.9 - The README's em dashes are gone, so it passes the rule it points to - Adds a short code of conduct
Nothing ran the test suite on a pull request, and nothing proved the commit hooks still reject what they claim to. Both now run in CI, and a person can be credited as a co-author. - A Tests workflow runs the browser-free suite on pull requests and pushes to main, on Python 3.14 through uv - .githooks/tests/run.sh asserts a failing and a passing case for every hook rule, and the Standards job runs it before trusting the hooks - commit-msg rejects only AI co-author trailers, so a human one passes - pre-commit also lints CONTRIBUTING.md and CLAUDE.md, both of which the naming rule already covers - Every action is pinned to a commit, and Renovate keeps the pins current - .gitattributes stores and checks out text as LF, since the hooks break under bash with CRLF; .editorconfig matches it
Claude could merge a pull request and read secret files through the shell, and the review agents still described a web app. The guard now covers both, and the agents review the code this repository actually has. - The command guard blocks gh pr merge and API merges, since a person merges every PR, and blocks shell reads of .env, keys, secrets/ and the local deny list, which the Read deny rule never covered - A safe /dev/null redirect no longer trips the raw-device check, and no longer hides a dangerous redirect later in the same command - A bare git push is judged by the session's own branch, so a push from a loop worktree is not read against the main tree - Eight new hook cases cover each change, all seen failing first - Settings narrow gh pr to reads plus draft PRs, deny history-destroying git commands, ask before force-with-lease pushes, history rewrites, public comments, release writes and write-method API calls, allow read-only git in PowerShell, and wire notifications to notify.sh, which reaches Windows - The four review agents are rewritten for Solverr's stack, rules and untrusted-input boundaries - Removes two hooks that were never wired and gave advice for another stack, and an example file of template text
Several rules contradicted the engine-layer law or each other, and a handful of docs still described the code as it was before 1.6.0. The owner ruled on each conflict; the rules now say one thing. - An engine pair is never split: "fix some, name the rest" stays for ordinary sibling sites only, and a parity gap on a surface being touched is levelled up in that change - Tests may loop with subTest over a fixed tuple of engines, the shape the conformance suite already uses, and every new test is seen failing - A knob or dependency that only one clearing core uses falls under the clearing-core decline, and one boolean from each adapter is allowed until a second divergent bit appears on the same surface - A WHAT comment is allowed when the what is not visible in the code - Merging is by a person with a merge commit; a human co-author trailer is credit; reports cap at 700 words with graded detail - The architecture notes move to a rule scoped to src/, and CLAUDE.md gains the hooks, agents, test commands and working rules it lacked - The ledger, the architecture record and loops.md drop stale versions, "(unreleased)" markers, a shipped gap, the dropped SessionRef, the old test count, and the idea that the loop worker never touches engines - CONTRIBUTING.md describes the naming check without using a word the check rejects
The loop skills and their contract were an experiment that never ran, so they are gone, along with the permissions that existed only for them. The remaining skills predated the engine-layer program and now follow it. - Removes /port-scan, /audit-scan, /loop-work and docs/dev/loops.md, and every reference to them - Opening a PR or filing an issue now asks first, and loop branches lose their push allowance, since nothing does either unattended - upstream-audit compares each clearing core file against file, walks taken-over surfaces as behaviour, checks transitive dependency pins, and may now be invoked by the model - release and session-handoff run the whole browser-free suite, scout knows the spine, pr-review uses the Agent tool, and a new code-research skill covers broad questions
The file guard only matched forward-slash paths, and on Windows the tools send backslash paths, so edits to hook scripts, secrets/, .git/ and settings.json went through without being refused or asked about. - protect-files.sh turns backslashes into slashes before matching, the same fix the gold-standard repo took - Three fixtures pin it, and fail with the line removed - Two fixtures cover the gc and type aliases the command guard already treats as secret readers - CI runs the Claude Code hook fixtures alongside the git hook self-test
Adds the gold-standard repo's range audit, rewritten for Solverr, so a branch can be checked end to end before it becomes a pull request. It reports; the owner decides what gets fixed. - A Workflow maps the range into code, tests, docs and tooling slices, write/read pairs, fix commits and taken-over surfaces, then stops for approval before anything expensive runs - Fourteen lenses, including engine parity against the write-once rule, a tooling lens for hooks, settings and CI, packaging and config wiring, and two-ends tracing across one value's writer and reader - Every finding faces skeptics that default to refuting it, a critic names uncovered ground once, and up to five new tests are mutation checked by default, since the suite runs in seconds here - Refuted findings go in a ledger so the next run does not raise them
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
1 participant
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
Brings the repository's contributor standards, CI and Claude Code configuration up to the owner's gold-standard setup, and fixes the gap #11 exposed: nothing a contributor reads said what the commit standard is. No code under
src/changes and nothing reaches a deployer, so there is no CHANGELOG entry.What changes
CONTRIBUTING.mdstates every commit rule CI enforces, plus setup with uv, the test command, the two-engine rule and CHANGELOG scope. There is a pull request template and a code of conduct, and the README's "From source" steps use uv and Python 3.14.gh pr mergeand shell reads of secret files, and two/dev/redirect checks that were wrong are fixed. The file guard now matches Windows backslash paths, which it never did. Permissions are tightened, and notifications reach Windows.src/, and the stale lines inCLAUDE.md, the sync ledger and the architecture record are fixed./code-researchand/deep-auditskills are added.How it was tested
bash .githooks/tests/run.sh: 25 passed. The two rules that changed were seen failing first.bash .claude/hooks/tests/run-all.sh: 59 passed. The new guard and path cases were seen failing before the fix..githooks/commit-msg, and.githooks/pre-commit main..HEADpasses./deep-auditworkflow script was exercised in both modes against stub agents; it has not yet run against real agents.Checklist
/v1request and response shape is unchanged