docs(claude+skills): CLAUDE.md restructure + path-guard + new skills#1301
Merged
John-David Dalton (jdalton) merged 2 commits intomainfrom May 5, 2026
Merged
docs(claude+skills): CLAUDE.md restructure + path-guard + new skills#1301John-David Dalton (jdalton) merged 2 commits intomainfrom
John-David Dalton (jdalton) merged 2 commits intomainfrom
Conversation
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue.
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 101f571. Configure here.
Synced from socket-repo-template canonical. The fleet CLAUDE.md
moved to a fleet-canonical / project-specific layout — public-surface
hygiene rules, parallel-session safeguards, code style, and tooling
go in CLAUDE.md; project-specific extensions (build commands, test
targets, repo-particular conventions) go below.
Skills added:
- path-guard — audit and fix path duplication ("1 path, 1 reference")
- programmatic-claude-lockdown — reference for locking down headless
Claude invocations (claude CLI in workflows, agent-sdk query() in
code) per the four-flag lockdown pattern
- promise-race-pitfall — reference for the Promise.race
cross-iteration handler-leak bug
Skills updated:
- security-scan — wires AgentShield + zizmor + Socket CLI dependency
scanning, A-F graded report
Path-guard infra:
- scripts/check-paths.mts — repo-level path-duplication scanner
- .github/paths-allowlist.yml — known-acceptable duplicates
- .claude/skills/path-guard/reference/* — templates for new repos
Doctrine references:
- docs/references/inclusive-language.md — substitution table
- docs/references/sorting.md — alphanumeric sort rules
Repo-template integration:
- .socket-repo-template.json — repo-particular kind config
- scripts/socket-repo-template-{schema,emit-schema}.mts — schema tooling
- socket-repo-template-schema.json — emitted JSON schema
Splits content out of #1286. Companion split PR #1300 covers hooks +
harness config; deps_misc bucket folds into #1285 SHA cascade per
project direction.
John-David Dalton (jdalton)
force-pushed
the
chore/split-skills-claudemd
branch
from
101f571 to
9944e14
Compare
Cursor Bugbot caught: `checkRuleF` grouped Rule-A findings purely by string-literal shape and promoted to Rule F whenever count >= 2, without checking distinct files. Two hand-builds of the same path shape in the SAME file would be incorrectly flagged as 'cross-file repetition' — but Rule F's whole point is cross-file duplication. Fix: build a Set of distinct file paths and gate the promotion on size >= 2. Also include the file count in the message (`in N files (M places)`) so the reviewer knows both numbers. Synced to socket-repo-template canonical.
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
hygiene, parallel-session safeguards, code style, tooling rules)
with project-specific extensions below.
path-guard,programmatic-claude-lockdown,promise-race-pitfall.security-scan(AgentShield + zizmor + SocketCLI dependency scanning, A–F graded report).
scripts/check-paths.mts,.github/paths-allowlist.yml, skill reference templates.docs/references/inclusive-language.md,docs/references/sorting.md..socket-repo-template.json+schema tooling.
Scope
This is the skills + CLAUDE.md slice split out of #1286. Companion
splits:
After all three splits are reviewed, #1286 closes.
Test plan
pnpm exec tsgo --noEmit scripts/check-paths.mtspasses/path-guard check)matches the corresponding file on
chore/hooks-mts-path-tokenNote
Medium Risk
Medium risk because it introduces a new repo-wide
check-pathsgate script and associated allowlist/templates that could later be wired into CI/pnpm checkand start blocking merges if detection heuristics are too strict or noisy.Overview
Adds path hygiene enforcement infrastructure: a new
scripts/check-paths.mtsgate (with allowlisting via.github/paths-allowlist.yml) plus the/path-guardskill and shared rule text, to enforce the “1 path, 1 reference” policy across TS, workflows, and build scripts.Restructures
CLAUDE.mdinto a fleet-canonical section and adds new guidance references/skills (programmatic Claude invocation lockdown,Promise.racepitfall) and minor security-scan/security-reviewer documentation tweaks (e.g., zizmor markers, soak-window checklist wording).Introduces socket-repo-template integration artifacts (
.socket-repo-template.jsonplus schema source/emit script and generatedsocket-repo-template-schema.json) and adds doctrine reference docs for inclusive language and sorting.Reviewed by Cursor Bugbot for commit 101f571. Configure here.