Skip to content

Contributing

Guide

Contributing

Human-facing conventions for KLMS. (AI-facing rules live in CLAUDE.md; this file is owned by the Rules & Governance unit.)

Local development

Prerequisites: Node.js 22 (LTS) and npm.

cd intranet && npm install   # install dependencies
npm run dev                  # local dev server (http://localhost:4321)
npm run build                # static build to intranet/dist
./scripts/archive-manifest.sh verify   # archive integrity check (read-only)

Git & PR workflow

  • Develop on claude/<topic> or <type>/<short-desc> branches; never commit straight to the default branch.
  • Clear, imperative commit subjects. Open PRs as draft first.
  • Push only at checkpoints (GR-7). Every push to a Vercel-connected branch (including main and open PRs) triggers a deploy and consumes a daily budget credit (ADR-0009). Batch work: commit freely locally, push once per session milestone or logical release boundary. Keep branches local or draft until the checkpoint is reached — do not push after every micro-task.
  • gh pr merge --auto queues the merge when all required checks pass. Use it when you want CI to gate the merge automatically. The PR stays open until checks complete; it merges silently.
  • After any document change, hand off to the Archivist (first immutable, refresh latest, run scripts/archive-manifest.sh update). Protect the archive record (GR-8): refresh the latest/ copy and MANIFEST hash in the same commit, never edit first/ rows (write-once), and treat scripts/archive-manifest.sh verify as authoritative — do not mass-rewrite hashes with update/refresh to silence it, and never bypass the CI archive check.

Code Review

This is a single-owner repo. Reviews are conducted by the Principal. The zero-approval merge policy is deliberate (see ADR-0012).

Author checklist before undrafting:

  • [ ] npm run build passes locally
  • [ ] Archive integrity: ./scripts/archive-manifest.sh verify
  • [ ] Update CHANGELOG.md — add entry to ## [Unreleased] describing what changed
  • [ ] Placeholders resolved (no {{...}} tokens in changed files)
  • [ ] Commit messages are imperative and descriptive

Reviewer guidance (when a second contributor exists):

  • State what you checked, not just “LGTM”
  • Blocking vs. non-blocking: prefix blocking comments with BLOCKING:
  • Approve only when all blocking comments are resolved

Issues vs. PRs

  • File an issue when tracking a bug, a feature request, or a work item that needs discussion before a PR exists.
  • Open a PR directly for straightforward changes where the intent is self-evident.
  • Link PRs to issues with Closes #N in the PR description.

Commit Message Format

Use the imperative mood in the subject line: “Add X”, “Fix Y”, “Remove Z” — not “Added” or “Fixes”.

For significant changes, use conventional commits:

  • feat: — new feature
  • fix: — bug fix
  • chore: — maintenance (deps, config, tooling)
  • docs: — documentation only
  • refactor: — code change with no behaviour change

Subject line max 72 characters. Body is optional but encouraged for non-obvious changes.

Documentation conventions

  • Layered (macro → job-aid). Every doc has a place in the hierarchy: Macro (vision/strategy/system map) → Foundational → Policy/Process → SOP/Runbook → Job aid. Index it in docs/canon.md.
  • Canon links, never restates. docs/canon.md indexes and links; it does not duplicate content that lives in the owning doc.
  • One home per decision. A durable rule lives in CLAUDE.md; a policy in hr/policies/; a one-off architectural decision in docs/adr/. Cross-link; never duplicate.

ID & cross-reference scheme

Stable IDs so links survive renames: GR-# (golden rules), ADR-####, SOP-###, JA-### (job aids), RISK-##, MS-## (milestones). Reference by ID, not filename.

Mermaid diagram standard

  • Documentation and SOPs include well-crafted Mermaid diagrams where they aid understanding (SOP process flowcharts, the system map, the Standard Flow).
  • Validate every diagram with the mermaid MCP before commit.
  • Accessibility: every diagram MUST carry a text fallback / alt description beneath it (see ORG.md and docs/methodology.md for the pattern).

Definition of Done

A change is done when it meets the DoD in docs/sop/change-management.md (archived, canon updated, diagrams validated + fallback, placeholders untouched, pushed, main synced).

Milestones

Milestones use the stable ID scheme MS-##. Each milestone also receives a git annotated tag with a freeform slug. The full list is in archive/SPECIFICATION.md section 4.

To tag a milestone:

git tag -a <slug> -m "Milestone: <description>"
git push origin <slug>

After tagging, add a Verification-log row to archive/MANIFEST.md.