docs: make a clone of this repo self-contained - #32
Merged
Merged
Conversation
A fresh clone of this repo carried no coding contract at all. This one is written for publication: settled behaviour is stated as rules, and the reasoning behind it stays out of the repo. Claude-Session: https://claude.ai/code/session_01XAY7LzfeuEZBgSLuzpWUAH
The Scope section named only CLAUDE.md and two MCP paths, so the published contract disagreed with the published README about what the scanner walks by default. It now matches pkg/rules/fileclass.go: every harness instruction file and all four MCP config paths. Also fixes two stale fixture paths and states that an empty scan does not grade. Claude-Session: https://claude.ai/code/session_01XAY7LzfeuEZBgSLuzpWUAH
A fresh clone now states what the project is, how this repo is built, and how it relates to the hosted scanner and the Action. Design history and component state stay out of the repository. Claude-Session: https://claude.ai/code/session_01XAY7LzfeuEZBgSLuzpWUAH
The pipeline order, the dependency tree, the registry and permission descriptions, and the claim that the Action imports pkg/ were each wrong against the source. The docs map also asserted something about this repository's history that is not true. Claude-Session: https://claude.ai/code/session_01XAY7LzfeuEZBgSLuzpWUAH
This file is published. It carried two pointers to a decision record that does not exist in a clone, a fixture-subdir list that had gone stale, a package note contradicting `docs/architecture.md`, and a paragraph of internal measurement that told a reader nothing they could act on. - `pkg/triage` is now described the way `docs/architecture.md` describes it: a seam that is a no-op unless a Verifier is injected. - Fixture subdirs are no longer enumerated; `ls testdata/malicious/` is the live answer and cannot go stale. - Skill roots are described by what they are (a directory holding `SKILL.md` or `skill.yaml`) instead of by a pointer to an unpublished record. - The adversarial-fixtures rationale keeps its structural argument and loses the internal measurement; the table rows describe what each table asserts. - `make fmt` is documented as `gofmt -s -w .`, which is what the Makefile runs. Every command and `-run` pattern left in the file was executed against this tree: all pass, and `-run TestBench` was confirmed to select a test (a bogus pattern reports "no tests to run"). Claude-Session: https://claude.ai/code/session_01XAY7LzfeuEZBgSLuzpWUAH
- grade_reachability_test.go: the comments explained the grade-scale claim by citing documents instead of stating it, so a reader had to leave the file to learn what the test asserts. State the claim, its premise, and the reason each map exists inline. - development-guide.md: pkg/permission infers capabilities from findings and discovered file contents; it parses no manifest. pkg/scorer carries per-finding confidence, diagnosis and config overrides; there is no flat score in it. - README.md: --scan-all stops honoring .gitignore. The hardcoded skip-dirs survive it, and a SKILL.md inside one still creates no scope root. - architecture.md: Extract works from three inputs, not two — the third is a baseline filesystem permission added whenever any file was discovered. Claude-Session: https://claude.ai/code/session_01XAY7LzfeuEZBgSLuzpWUAH
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.
Development is moving to an external agent that receives one repository at a time as a fresh clone. Until now a clone of this repo carried
README.md,CONTRIBUTING.md,CHANGELOG.mdand code — no coding contract, no architecture, no statement of how this repo relates to the hosted scanner or the Action.This publishes a general-terms doc set and nothing more.
What a clone now carries
AGENTS.mdCLAUDE.mdis a symlink to it.docs/README.mddocs/architecture.mdRuleinterface, the path-gating contract, the skill-root predicate, axis aggregation, schema enforcement.docs/glossary.mddocs/product-context.mddocs/cross-repo.mddocs/development-guide.mdwas already published and is unchanged in purpose; it was corrected.What stays out
Design specs, implementation plans, decision records, verification logs and component state remain local-only, as before.
.gitignoremoves from a blanket exclusion to an explicit allow-list, so adding a document to the published set is now a deliberate act.AGENTS.mdgains a Settled behaviour section: a short list of things not to change on inference — the axis set, the exit-code contract, the JSON wire shape, the registry checksum's role, scope and path gates, demotion thresholds, and the empty-scan result shape. Each is settled for a reason that is not visible in this repository, so the rule is to ask first.Corrections found while writing it
Matching the documents against the code turned up statements that were wrong:
AGENTS.md,GEMINI.md,.cursorrules,.windsurfrules,.github/copilot-instructions.md,.cursor/rules/*.mdc,.cursor/mcp.jsonand.vscode/mcp.jsonpkg/scorerwas drawn as a dependency ofcmd/, which does not import itpkg/permissionwas described as parsing declared permissions; it infers them from findings and file contentREADME.mdsaid--scan-allwalks every scannable file; the hardcoded skip-dirs survive itgrade_reachability_test.gocited a document for a claim it no longer makes; they now state the claim inlinedocs/development-guide.mddescribedpkg/scoreras a legacy flat-score package andpkg/permissionas manifest extraction; neither was trueNo behaviour changes. The only non-documentation edits are comments.
Verification
go test ./...— 1085 tests, 12 packages, green.A gate in the workspace clones this repo and asserts that the published set is present, that the withheld set is absent, that no withheld pointer or internal term survives in any tracked file outside a written exemption list, and that every relative link resolves inside the clone. It was defeated three times during review and rebuilt each time — the checks that matter are the ones that have been shown to fail.
https://claude.ai/code/session_01XAY7LzfeuEZBgSLuzpWUAH