docs(rules): run communication, PR, and review as rules

[zolotokrylin]

Migrates the remaining CONTRIBUTING sections into the rules system and thins CONTRIBUTING to a link-only index. Consolidates the former #125 (Review) into this PR so there is a single PR to review instead of a stack.

New rules:

Communication (DEV-2xx)

• DEV-210 route discussion to the right channel
• DEV-220 reference issues and PRs as list items

PR requirements (DEV-3xx)

• DEV-310 sign every commit
• DEV-320 scope a PR to a few hours
• DEV-330 keep docs in sync and each fact in one place
• DEV-340 name a PR for what users gain
• DEV-350 mark a design PR docs(ui) with a Design section
• DEV-360 follow the PR lifecycle
• DEV-370 report time across all stages
• DEV-380 enforce markdown lint on push with a pinned rumdl hook

Review (DEV-4xx)

• DEV-410 reject with Request Changes for objective problems
• DEV-420 scout open PRs when idle
• DEV-430 deliver bug-free work; review is a safety check

DEV-330 also covers external and volatile facts: link a system's canonical docs instead of restating details that drift (DEV-140 links the Wizard command docs rather than hardcoding a command string).

Also wires up the lint enforcement so developers complies with DEV-380, mirroring partners/partnerships: a pinned rumdl devDependency, a postinstall that sets core.hooksPath to .githooks, and a .githooks/pre-push that runs the npm-pinned rumdl on changed markdown. node_modules is gitignored. Verified end-to-end: the hook ran on this branch's push.

CONTRIBUTING is now the thin narrative index over the rules, each section linking to its rules.

Summary by CodeRabbit

• Documentation
  • Added a central docs/ index organized by audience and content type.
  • Rewrote “For Developers” and updated contributor/setup guidance (Local/Stage/Preview/Production).
  • Shortened contributor docs to a rules-system pointer and added/expanded developer rules for naming, PR scope, docs consistency, canonical facts, indexing, and review/process expectations.
  • Clarified how specs graduate into shipped documentation.
• Developer Experience
  • Added an automatic pre-push Markdown/lint enforcement flow that auto-formats, then blocks pushes if issues are introduced.
  • Added a CLI that validates developer rules and documentation indexing/reachability.

[holdex]

Time Submission Status

Member	#	Time	Running Total	Status	Last Update
zolotokrylin	1	2h 24min	2h 24min		Jul 15, 2026, 4:34 AM
zolotokrylin	2	+1h 6min	3h 30min		Jul 15, 2026, 6:25 AM
zolotokrylin	3	+11min	3h 41min		Jul 15, 2026, 6:30 AM
zolotokrylin			3h 41min	✅ Submitted
@tiffmyaaw			-	⏳ Pending	-

---

Submit or update total time with:

@holdex pr submit-time 2h

Add time on top of previous submission with:

@holdex pr add-time 1h30m

See available commands to help comply with our Guidelines.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 96d5fb30-169a-40d7-a2c5-6ec92e109f60

📥 Commits

Reviewing files that changed from the base of the PR and between 5b11323 and 9f225e1.

📒 Files selected for processing (17)

• .githooks/pre-push
• README.md
• docs/CONTRIBUTING.md
• docs/rules/DEV-125.md
• docs/rules/DEV-335.md
• docs/rules/DEV-337.md
• docs/rules/DEV-338.md
• docs/rules/DEV-350.md
• docs/rules/DEV-360.md
• docs/rules/DEV-365.md
• docs/rules/DEV-370.md
• docs/rules/DEV-380.md
• docs/rules/DEV-390.md
• docs/rules/DEV-410.md
• docs/rules/DEV-415.md
• docs/rules/README.md
• scripts/check-rules.mjs

🚧 Files skipped from review as they are similar to previous changes (9)

• docs/rules/DEV-337.md
• docs/rules/DEV-410.md
• docs/rules/DEV-390.md
• docs/rules/DEV-380.md
• docs/rules/DEV-335.md
• docs/rules/DEV-370.md
• docs/rules/DEV-350.md
• README.md
• docs/rules/README.md

---

Walkthrough

This PR establishes indexed, rules-based contributor documentation, adds developer rules and validation tooling, and configures a pinned rumdl pre-push hook with repository-wide documentation checks.

Changes

Documentation foundation

Layer / File(s)	Summary
Documentation foundation and contribution workflow README.md, docs/README.md, docs/CONTRIBUTING.md, docs/rules/DEV-050.md, docs/rules/DEV-180.md	Contributor guidance now points to indexed rules, separates docs/specs/ from docs/product/, and standardizes rule heading structure.

Developer rule catalog

Layer / File(s)	Summary
Developer rule catalog and index docs/rules/DEV-125.md, docs/rules/DEV-210.md, docs/rules/DEV-220.md, docs/rules/DEV-310.md ... docs/rules/DEV-430.md, docs/rules/README.md	New rules define contribution, communication, documentation, PR, design, lifecycle, and review requirements, with categorized links in the rules index.

Rule audit tooling

Layer / File(s)	Summary
Rule audit CLI and npm wiring package.json, scripts/check-rules.mjs	The repository gains npm setup scripts and a CLI that validates rule metadata, headings, dependencies, cycles, links, documentation reachability, and README structure.

Push-time enforcement

Layer / File(s)	Summary
Pre-push Markdown and rules validation .githooks/pre-push, docs/rules/DEV-380.md	The hook runs the pinned local rumdl on changed Markdown, blocks formatter changes, and invokes the rules audit for documentation changes.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant GitHook as pre-push hook
  participant Rumdl as local rumdl
  participant RuleAudit as check-rules.mjs
  Developer->>GitHook: push commits
  GitHook->>Rumdl: lint changed Markdown
  Rumdl-->>GitHook: report or apply fixes
  GitHook->>RuleAudit: validate changed documentation
  RuleAudit-->>GitHook: report audit result
  GitHook-->>Developer: allow or block push

Loading

Possibly related PRs

• holdex/developers#123: Overlaps on DEV-180 and the rules-system documentation.
• holdex/developers#122: Relates to the rules catalog audited by the new CLI.
• holdex/developers#102: Relates to documentation indexing and canonical documentation rules.

Suggested reviewers: markholdex, angelicawill

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: converting communication, PR, and review guidance into rules.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/rules-pr-requirements

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[zolotokrylin]

@holdex pr add-time 2.4h

[zolotokrylin]

@holdex pr add-time 1.1h

[zolotokrylin]

@holdex pr add-time 11m