docs: dev-docs/ engineering knowledge base, slimmer CLAUDE.md, enforced Sui-pin consistency

[omersadika]

Summary

Reorganizes engineering documentation around how AI coding agents (and humans) actually consume it, applies current agentic-coding best practice to CLAUDE.md — converting advisory rules into deterministic enforcement wherever possible — and ships the on-demand tooling (skills, a reviewer subagent, a git-guard hook) that the always-loaded file should not carry.

The design, and the research behind it

• CLAUDE.md carries only always-applicable rules. Anthropic's Claude Code best practices are explicit: CLAUDE.md is loaded into every session ("For each line, ask: would removing this cause Claude to make mistakes?" — "Bloated CLAUDE.md files cause Claude to ignore your actual instructions"). Deep-dive material moved out behind plain-path pointers (deliberately not @imports, which inline into every session).
• dev-docs/ is the on-demand knowledge base (docs/ remains the public website), structured per Karpathy's context-engineering framing (definition; agent-legible docs critique: "What is the thing I should copy-paste to my agent?") — playbooks lead with copy-pasteable commands; learnings are compiled into a persistent markdown base.
• Enforce, don't document: rules a machine can check were moved into machines — clippy.toml already covered six of CLAUDE.md's style rules (now deleted behind one meta-rule), unsafe_code = "deny" makes "NEVER use unsafe" a compile error, the Sui-pin rule gets a CI script, and the git rules get a PreToolUse hook.
• AGENTS.md → CLAUDE.md symlink per the agents.md cross-tool standard.

dev-docs/ contents

dev-docs/
├── README.md                     index + the CLAUDE.md-vs-dev-docs contract
├── specs/                        relocated unchanged (git mv; same maintenance rule)
├── playbooks/
│   ├── ci-suites.md              dispatchable suite workflows, runner facts, artifact recovery
│   ├── mpc-stall-postmortem.md   the check-ordered diagnosis from the wedge investigations
│   └── localnet.md               local Sui+ika localnet: version traps, readiness, fresh-ids trap
├── conventions/
│   ├── sui-version-bump.md       every pin location + the bump procedure
│   └── simtest.md                moved from CLAUDE.md + run commands
├── learnings/
│   └── pitfalls.md               failure CLASSES with the general rule each taught
├── plans/                        multi-PR implementation plans, explicit status lifecycle
│                                 (active → landed/superseded/abandoned); behavior moves to
│                                 specs/ on landing; code comments never reference plan phases
└── reviews/                      long-form PR/design/audit reviews — point-in-time records
                                  with per-finding RESOLUTION tracking, not maintained truth

CLAUDE.md changes

• Karpathy's four working principles added (think before coding / simplicity first / surgical changes / goal-driven execution) — the compact form of the viral four rules.
• Six clippy-enforced style rules deleted behind one meta-rule: mechanically-enforceable rules go in clippy.toml/lints, not here. Near-duplicate lines merged.
• New: minimal-verification-by-change-type map; compaction-preservation instruction for long sessions; the multi-location Sui-pin gotcha (mainnet-v* or testnet-v* — bump everywhere in one PR).
• Net: 297 → ~250 lines with strictly more load-bearing content.

Enforcement

• scripts/check-sui-version-consistency.sh (wired into the CI Format job): the single root-Cargo.toml Sui tag is the source of truth; the TS workflows' binary-download URLs, CLAUDE.md, and any wasm-workspace pins must match exactly, flavor included.
• Cargo.toml: unsafe_code = "deny" workspace lint (workspace verified zero-unsafe; full CI build green).
• .claude/hooks/git-guard.sh (PreToolUse[Bash], wired in the checked-in settings.json): blocks-and-explains --no-verify, pushes targeting dev/main/master, commits made while ON a protected branch, and commits of .rs files with a dirty rustfmt check. Flags are scanned on a heredoc-cut, quote-stripped view of the command so commit messages mentioning them can't false-positive — a class found when the hook blocked its own introduction commit, which also verified its liveness end-to-end. Validated against 9 scenarios.

Team-shared .claude/

.gitignore now ships agents/, hooks/, skills/, and settings.json (personal settings.local.json/worktrees stay ignored; personal skills belong in ~/.claude/skills/):

• Skills: /dispatch-suites (fire the three heavy suites, triage by failure shape), /stall-postmortem (the ordered MPC-stall diagnosis as a command), /bump-sui (the full bump checklist, manual-invoke only).
• Subagent: consensus-reviewer — six review lenses encoding the invariants real wedges taught: consensus determinism, epoch-close lock gating, batch-loop continues, no silent skips, parameter-set agreement, liveness symmetry.

Notes for reviewers

• dev-docs/specs/ content is byte-identical to the old specs/ (pure git mv).
• The playbooks/learnings distill the epoch-close-wedge and CI-slowness investigations (PRs Off-chain validator metadata + EndOfPublishV2 #1721/fix(dwallet-mpc): network-key adoption gates — no committee-unapproved parameter set may go live #1735, issue Epoch-entry stale-mpc_data race: per-epoch silent dead-presign validator; two laggards wedge the epoch #1736) — everything in them is already public in those threads.
• The hook is conservative by design: block-and-explain only, never auto-modifies; scoped strictly to git commands.

🤖 Generated with Claude Code

[omersadika]

Second commit (d8f039e5b3) extends the same best-practice pass from advisory to enforced:

• Karpathy's four working principles added to CLAUDE.md (think before coding / simplicity first / surgical changes / goal-driven execution) — the compact form of the viral four rules.
• Enforce, don't document: the six style rules clippy.toml already catches are deleted behind one meta-rule ("mechanically-enforceable rules go in clippy.toml/lints, not here"), and unsafe_code = "deny" lands as a workspace lint — "NEVER use unsafe" is now a compile error.
• On-demand pieces instead of per-session prose: three repo skills (/dispatch-suites, /stall-postmortem, /bump-sui) and a consensus-reviewer subagent encoding the six invariant lenses the wedge investigations taught. .claude/ is now selectively checked in (project settings, agents, skills; personal files stay ignored).
• Plus: minimal-verification-by-change-type map and a compaction-preservation instruction for long sessions.