chore: enforce agent doc gates (checklist + CI + PR template)

[phuongnse]

Summary

Refactors CLAUDE.md for readability and enforcement alignment (PR #48).

CLAUDE.md (~580 → ~220 lines)

• Table of contents + clear split: context / rules / workflow / index
• Agents directed to agent-checklist.md for daily work; CLAUDE = architecture + P0 only
• Removed duplicate Gate 1 table, Steps 1–8 (already in checklist), long wireframe generator section, repeated DoD/pre-mark-done blocks
• Implementation detail → links to patterns.md, frontend.md, process.md, testing.md
• Fixed tenant schema: tenant_{organizationId:N} (was org_slug)

agent-checklist.md

• Full Gate 2 row list for PR paste
• Gate 3 questions inline

Unchanged

• P0 hard stops, module boundaries, layer order, Definition of done callout format
• ./scripts/check-doc-drift.sh + CI job

Gate 2

• Changed architecture/process → CLAUDE.md + agent-checklist.md updated

Gate 3

All No.

  

Summary by CodeRabbit

• Chores
  • Introduced standardized pull request submission template with required verification checklists.
  • Added automated documentation consistency checks to the CI pipeline.
  • Updated project architecture and workflow documentation with refined guidelines and module boundary rules.
  • Created new workflow checklist documentation to improve process clarity.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 208ecdc9-1422-4bb4-9179-8f633a3391c1

📥 Commits

Reviewing files that changed from the base of the PR and between d3e9fe1 and b88e82c.

📒 Files selected for processing (7)

• .github/PULL_REQUEST_TEMPLATE.md
• .github/workflows/build-and-test.yml
• CLAUDE.md
• docs/README.md
• docs/playbooks/agent-checklist.md
• docs/playbooks/process.md
• scripts/check-doc-drift.sh

---

📝 Walkthrough

Walkthrough

This PR establishes a comprehensive documentation workflow and CI compliance system for the Axis project. It includes governance rule restructuring (CLAUDE.md), a standardized PR template with gate checklists, a new CI job that validates documentation drift, an agent checklist playbook, a Bash validation script, and updates to documentation navigation.

Changes

Documentation Workflow & Compliance System

Layer / File(s)	Summary
Architecture & Workflow Governance CLAUDE.md	Restructures governance documentation with new table of contents, converts tech stack to table format, tightens module boundary P0 constraints with explicit "Never" rules, reorganizes Machine Rules into P0/P1/P2 structure, rewrites Workflow section with Gate 1/2/3 descriptions tied to doc-drift checks, condenses Development rules with .NET/frontend style guidance, and refreshes Definition of Done.
PR Template & CI Job Setup .github/PULL_REQUEST_TEMPLATE.md, .github/workflows/build-and-test.yml	Adds GitHub PR template with AC map, Gate 2 (Docs) checklist, Gate 3 (Retrospective) checklist, and Verification task list. Introduces doc-drift CI job that checks out repo with full history and executes documentation drift validation.
Agent Workflow Checklist docs/playbooks/agent-checklist.md	Creates one-page agent checklist with Before-Coding template (AC/Docs-touched table), Gate 1/2/3 specifications including CI commands and doc-drift checks, Layer status rules, P0 non-negotiables, Epic map linking code areas to doc folders, and Playbooks reference table.
Documentation Drift Validation Script scripts/check-doc-drift.sh	Implements Bash script that computes diff range, maps code changes to required Epic documentation, verifies handler files have matching tests under tests/Modules/*, validates Epic README files for unresolved placeholders (`
Documentation Navigation Updates docs/README.md, docs/playbooks/process.md	Updates Playbooks section in docs/README.md to add agent-checklist entry. Updates process.md header with links to agent-checklist.md and check-doc-drift.sh; removes duplicated Step 6 doc-drift instructions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• phuong-labs/axis#18: Both PRs modify CLAUDE.md, specifically updating workflow and testing process rules.
• phuong-labs/axis#30: The documentation governance overhaul (CLAUDE.md rewrite plus playbook restructuring) aligns directly with previous restructuring of governance and modular playbooks.
• phuong-labs/axis#33: Introduces doc-drift validation of Epic documentation completeness; the retrieved PR updates docs/epics/* with wireframe references and assets affected by this validation.

Poem

🐇 A script to keep docs in line,
Gates and checklists, so divine,
Governance rules now crystal clear,
Playbooks guide the code frontier,
Drift be gone—compliance won!

✨ 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 cursor/enforce-agent-docs-a1e8

---

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