PureXML/docs/rules/git-discipline.md

GitHub and Git Discipline

Conventions for issues, labels, pull requests, branches, commits, and remotes in the PureXML repo. Commit-message format lives in docs/rules/commits.md; this file covers everything else.

The repo ships issue forms, a PR template, a label set, and git hooks that enforce most of these rules mechanically. The rules below are the durable conventions those mechanisms encode.

1. Issue tracker

Rule 1.1: Status block at the top, dated

Every issue body carries a ## Status (YYYY-MM-DD) heading as the first section. New-issue form templates make this required.

When state changes (work starts, acceptance bullets ship, scope narrows, deps close), edit the status block in place with a new date line. The rest of the body stays as the original framing.

Why: bodies without a dated status block age into fiction within a month. Issues with status blocks age well; the ones without age into wrong-default-value claims that shallow audits pass as "well-written, keep."

Rule 1.2: No line numbers in issue bodies

File references use symbol names, not Foo.swift:142. Lines drift on every PR; symbols do not.

When you need a line anchor, write Foo.swift (the searchSymbols function) so the symbol survives even if the line moves.

Why: line anchors like SearchIndex.swift:2409 go dead within one PR cycle the moment a file is split or reordered.

Rule 1.3: No phantom paths

Every backtick-quoted file path in an issue body must EXIST in the repo (or in a declared sibling repo) at write time.

A mechanical check on this is straightforward: extract backtick-quoted paths, check the filesystem, flag missing ones.

Why: a cited file that was never written is a fabrication that propagates. The work it implies may be real, but the path is a lie until the file exists. File it as an issue instead of citing a path that is not there.

Rule 1.4: Cross-reference hygiene

When citing #NNN in blocker phrasing ("blocked on", "pending in", "depends on", "after #N lands", "gated on", "awaits", "waiting on"), the referenced issue must be OPEN at write time.

When the referenced issue closes, edit the citing issue's body: either remove the cross-reference, or rewrite the surrounding sentence to say the dep shipped.

Why: "blocked on #X" where #X closed weeks earlier is a silent dependency lie. Wrong issue numbers are worse: they point a reader at unrelated work.

Rule 1.5: Schema and code claims are checkable

Do not cite <table>.<column> shapes, function signatures, or default values you have not verified against current source.

When the claim is structural (a schema column, a config default, a flag name), an audit script can mechanically verify it. Migrations move columns; flag defaults change; bodies do not auto-update.

Why: a body claiming a column lives in table A when a migration moved it to table B, or claiming a flag defaults to 0.5s when the real default is 0.05s (off by 10x), reads as authoritative and misleads. Verify before you write.

Rule 1.6: Issue templates use GitHub forms, not markdown

Use .yml form templates, not .github/ISSUE_TEMPLATE/feature.md style markdown. Forms enforce structure mechanically at filing time; markdown templates only suggest it.

Required fields: status date (input), priority (dropdown), complexity (dropdown). Required structured textareas per template kind (goal + acceptance for features; symptom + expected + reproduce + acceptance for bugs).

GitHub forms gotcha: dropdown selections produce TEXT in the issue body under ### <field label> headings; they DO NOT auto-apply as labels. To make dropdowns actually apply matching labels, add a labeler workflow that triggers on issues.opened, extracts the value under each heading, validates against the known label set, and applies the matching label.

Why: forms make filing discipline structural rather than suggestive. The labeler gotcha is easy to miss; the dropdowns look like they should label the issue, and they do not.

2. Labels

Rule 2.1: Brutal-minimum 5-label set

The canonical label set is 5 labels. Labels exist only to mechanically partition the issue space; everything else lives in the issue body or in native GitHub primitives (issue state, Milestones, Project boards).

Label	Color	Use
bug	Red #FF3B30	Something ships incorrectly
enhancement	Blue #007AFF	New feature, refactor, or design proposal
epic	Purple #AF52DE	Aggregation parent of related issues; mechanically excluded from "missing kind" check
priority: high	Red #FF3B30	Critical / release-gating / actively-blocking. Absence means "do when you can."
good first issue	Green #34C759	Newcomer-friendly; GitHub renders specially in the contributor chooser

Kind is determined at filing time (feature template applies enhancement, bug template applies bug). Maintainers add epic, priority: high, good first issue post-filing where warranted.

What is not a label here:

• Complexity. Read the diff. If you need a label to tell readers the issue is hard, your prose is failing.
• Priority gradient. priority: medium and priority: low collapse to "absence of priority: high." If the gradient does not change behaviour, the gradient is decoration.
• Topical categorisation (search-quality, source-expansion, refactor, area: distribution, etc.). These are composition, not type. Encode in the body or in a milestone.
• Status / lifecycle (wishlist, transitional, blocker, big-win, fixed: awaiting release, released-in: v<X.Y.Z>). Status belongs to GitHub-native primitives (issue state, Milestones, Project boards), not to labels.

Why this size: each surviving label has at least one mechanical reason it cannot fold into the body. Form templates apply kind at filing time; a staleness script partitions on epic; priority: high is the only triage tier (absence is implicit "later"); good first issue is GitHub-native. Three lenses converge on this set:

• Cut mercilessly: cut even fine things that do not earn their place. A larger set still carries comfort-tags.
• Classify by type, not status: every classification must justify its existence; status / lifecycle / release-tracking are not types, route them to native primitives.
• Prose over labels: if you need a label to convey something, your prose is failing. Labels exist only for what mechanical tools must partition on.

Rule 2.2: 3-carrier threshold for adding a new label

If you feel the urge to add a sixth label, ask: does this label have at least 3 expected open carriers (today or within the next planning cycle)? AND does it survive each of the three lenses above?

• Would you ship this label, or delete it?
• Is this a type/axis, or is it status/lifecycle/composition pretending to be a type?
• Does this label mechanically partition the issue space in a way grep / filter / a CI script must use, or is it commentary that belongs in the body?

If any lens fails, fold the categorisation into the issue body. A one-line note in the body is as discoverable as a single-carrier label without the dropdown clutter.

Why: single-carrier labels are footnotes pretending to be axes. Sprawling label sets stop being navigable past about 10.

Rule 2.3: Apple system palette

The 5 canonical labels use 4 hues from Apple's published system colour palette:

Hex	Color	Use
#FF3B30	Red	Urgent / blocking: bug, priority: high
#007AFF	Blue	Active work: enhancement
#AF52DE	Purple	Aggregation / epic: epic
#34C759	Green	Newcomer-friendly / shipped: good first issue

If you add a sixth label under Rule 2.2, draw from Apple's other system colours by semantic grouping:

Hex	Color	Reserved for
#FF9500	Orange	Medium urgency
#FFCC00	Yellow	Awaiting / pending
#00C7BE	Mint	Low complexity (if you ever bring complexity back)
#30B0C7	Teal	Topical / categorical
#32ADE6	Cyan	Help / outreach
#5856D6	Indigo	High complexity / structural
#FF2D55	Pink	Celebration / high-impact
#A2845E	Brown	Maintainer / internal
#8E8E93	Gray	Speculative / wishlist

Why Apple's palette: 13 distinct hues with strong semantic associations. Picking from this set means labels render coherently in any view that supports colour (GitHub UI, project boards, third-party trackers reading from GitHub).

Rule 2.4: Label deletion is destructive on closed issues

gh label delete <name> removes the label from every issue that ever bore it, including closed issues. Use gh label edit --name <new> to rename when historical association matters.

Why: closed issues are the project's audit trail. A phase-1 label on closed refactor issues told a later reader "this was Phase 1 of that refactor"; deleting phase-1 removes that context. Renaming preserves it.

When in doubt: prefer rename over delete for labels with closed carriers. Brutal trims that delete closed-carrier labels should be a deliberate, documented choice (acceptable when the information still lives in Release notes, the CHANGELOG, and merge commits).

3. Pull requests

Rule 3.1: One focused change per PR

A PR ships one cohesive change. If the diff spans two unrelated concerns, split.

Critic-fix iterations on the same change belong in the same PR (separate commits, same branch). Different concerns belong in different PRs even if they touch the same files.

Rule 3.2: CHANGELOG required for non-trivial changes

Projects that maintain a CHANGELOG require an entry per non-trivial PR. "Non-trivial" means: production source touched. Trivial means: docs / tests / scripts / configuration only.

A mechanical pre-commit + CI check enforces this. Opt-out via a [no-changelog] token in the commit message body when the change genuinely does not warrant an entry.

Why: PR descriptions live in the merge graph; CHANGELOG lives in the release. Without enforcement, source ships ahead of its description. A mechanical gate prevents the batch of PRs that merge without entries.

Rule 3.3: Critic-fix loop on every non-trivial PR

After opening a PR, do a self-critic pass: read your own diff as a reviewer would, find issues, fix them in additional commits on the same branch. Iterate until critique surfaces nothing new.

Commit naming: critic-fix(<scope>): <what was wrong>. The git history shows the iteration as separate commits; the PR diff shows the converged result.

Why: mechanical edits without re-reading the surrounding paragraph create new bugs. A sed that injects a reference inside a sentence saying "this is independent" creates a contradiction. Critic-fix loops catch the self-introduced bugs that the original change did not have.

Rule 3.4: PR head is never the canonical branch for release merges

When merging a release branch into main (or develop into main, etc.), the PR head is a dedicated release/v<X.Y.Z> branch, not the canonical working branch. Auto-delete-on-merge would kill the canonical branch otherwise.

Why: the GitHub auto-delete-branch-on-merge feature is useful for short-lived feature branches and destructive for long-lived development branches. Always interpose a release branch as the head.

4. Branches

Rule 4.1: Branch naming

• fix/<issue>-<topic>; bug fixes (e.g. fix/284-error-page-filter)
• feat/<topic>; features
• chore/<topic>; tooling, infrastructure, non-functional cleanup
• docs/<topic>; documentation-only changes
• refactor/<topic>; structural code reorganisation
• release/v<X.Y.Z>; release-prep branches (PR head for canonical-branch merges per Rule 3.4)

Issue-anchored prefixes (fix/<NNN>-...) when an issue exists; otherwise topic-anchored.

Rule 4.2: Branch from canonical base

Branch from the current tip of the canonical base branch (the one the PR will target). For Swift projects this is usually main or develop depending on the project's branching model.

git fetch origin <base> && git checkout -b <new-branch> origin/<base> is the safe form. Branching from a stale local copy of the base creates merge conflicts later.

Rule 4.3: Issue-first workflow

For every bug fix: file the GitHub issue first, then branch. The branch name carries the issue number; the PR auto-links via Closes #N in the description.

For features: an issue is optional but recommended when scope is non-trivial or when the change crosses two or more bug-list cycles.

Why: the issue is the audit trail. A branch + PR without an issue has no place for the symptom / repro / acceptance discussion. The PR body can hold that data but does not survive squash-merge as well as an issue does.

5. Commits

See docs/rules/commits.md for commit message format. The following are additional GitHub-related conventions.

Rule 5.1: No AI attribution

Generated content carries no AI attribution in any committed text. Specifically forbidden:

• Any AI co-author line in commit messages
• Tool-attribution lines in PR descriptions, code comments, or documentation
• The names of AI tools or vendors, or the words "AI", "LLM", "agent", "assistant", "automated", "machine-generated", or any synonym, in commits / PRs / branch names / file names that could end up in front of a colleague
• AI-tell stylistic patterns: emoji signatures, "Here's a quick summary:" preludes, gratuitous emoji-prefixed bullets, "I'll now..." / "Let me..." preambles in committed text
• Watermarks: zero-width characters, hidden HTML comments naming a tool, branch suffixes like -ai / -bot

The work must read as entirely human-authored. The standard is "would a colleague reading this guess a tool wrote it?" If yes, remove it.

For mechanical enforcement at the commit boundary, install the commit-message style hook described in Section 7. Rule 5.1 plus Rule 5.2 plus the hook together close the loop: the rule states intent, the hook refuses violations at commit time, so no commit reaches git push carrying either failure.

Rule 5.2: No em dashes in committed text

The em dash (the U+2014 character) is a recognisable writing tell. Replace with commas, periods, colons, semicolons, or restructure the sentence. Apply to commit messages, PR descriptions, code comments, issue bodies, documentation, README content; everything that lands in the repo or in front of a colleague.

This is a stylistic rule, not a syntactic one. En dashes (U+2013) and hyphens (U+002D) are fine. Only the em dash is forbidden.

Enforced mechanically by the commit-message style hook in Section 7 for commit messages. For file content, run the same byte check in a pre-commit hook over staged diffs.

Rule 5.3: Verify after git commit --amend --no-edit

--no-edit keeps the previous commit's message verbatim. After any amend with --no-edit, run git log -1 to confirm the message still describes the new tree accurately. If the staged change made the previous message wrong, drop --no-edit and rewrite.

Why: silent message staleness is the second-easiest commit-history bug to introduce (after force-pushing the wrong branch). The previous message gets anchored by --no-edit and lies about content that has since changed.

6. Remotes

Rule 6.1: Push conventions

Pushes follow the usual conventions: short-lived feature branches push freely; canonical branches (main / develop) only land via merge of an approved PR.

7. Mechanical enforcement

A repo that adopts these rules should ship a mechanical backstop:

• Body-drift scan: a scheduled script that greps open issue bodies for renamed paths, phantom paths, stale cross-refs, stale schema claims, and label drift. Output goes into a single tracking issue that gets updated on each run.
• CHANGELOG gate: a pre-commit hook + CI gate that refuses commits / PRs touching production source without a CHANGELOG entry.
• Issue forms with labeler: GitHub form templates for new issues + a workflow on issues.opened that translates form dropdown values into matching labels.
• Style-tell commit-msg hook: a commit-msg hook that refuses messages containing em dashes (U+2014), the forbidden AI-attribution phrases from Rule 5.1, or AI-signature emojis. Keep it portable (BSD-grep compatible, no PCRE dependency). Install per repo by symlink or copy into .git/hooks/commit-msg. Strip comment lines and the diff scissors block before checking so notes in # ... lines are not penalised.

Why mechanical enforcement matters. A disciplined author following Rule 5.2 can still push a commit whose message contains an em dash, because nothing at the commit boundary stops it. A 3-line commit-msg hook prevents this entire failure class at write time, after which git push cannot carry a violation regardless of who or what wrote the message. Discipline scales with attention; hooks do not.

8. CI workflows and truthful badges

Rule 8.1: One workflow file per concern, one badge per workflow

Each CI concern (style/gates, and each build-or-test platform) is its own workflow file with a unique name:. A README badge points at that one workflow's status endpoint, so the badge tracks exactly one job and is truthful.

Do NOT use a single multi-job workflow (ci.yml) with several shields.io ?label=... badges that all point at the same workflow. The actions/workflow/status endpoint reports the whole-workflow status; the label= is cosmetic, so every such badge renders the same result. A failure in any one job turns all of them red, and none of them tracks its named platform. That is a lying badge.

Canonical layout (one file each, names are the badge labels):

.github/workflows/style.yml          # name: Style and namespacing
.github/workflows/swift-macos.yml    # name: Swift (macOS)
.github/workflows/swift-linux.yml    # name: Swift (Linux)
.github/workflows/swift-windows.yml  # name: Swift (Windows)
.github/workflows/swift-wasm.yml     # name: Swift (WASM)

Rule 8.2: Native per-workflow badge markdown, plus a license badge

Use GitHub's native per-workflow badge (it reflects the real status of that one workflow), not a shields.io workflow-status badge with a cosmetic label:

[![Style and namespacing](https://github.com/<owner>/<repo>/actions/workflows/style.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/style.yml)
[![Swift macOS](https://github.com/<owner>/<repo>/actions/workflows/swift-macos.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/swift-macos.yml)
[![Swift Linux](https://github.com/<owner>/<repo>/actions/workflows/swift-linux.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/swift-linux.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

The license badge is static and links to the repo's LICENSE; match the label to the actual license (MIT, AGPL--3.0, etc.).

Rule 8.3: Add a platform job and badge ONLY when that platform is genuinely possible

A badge is a claim. Only claim a platform the repo can actually build or test on. Never ship a workflow or badge for a platform the package does not support; an absent badge is honest, a red-or-fictional badge is not.

Decide possibility from the repo's topology (see cross-platform.md):

• Apple platforms (iOS, visionOS, tvOS, watchOS) and any UI build or test run on macOS runners only. There is no "iOS CI on Linux" and no Windows/Linux UI. An iOS/visionOS app or a SwiftUI/UIKit/AppKit target is exercised by a macOS-hosted job (simulator or xcodebuild -destination), reported under the macOS badge or a dedicated swift-ios.yml that still runs-on: macos. Do not add a Linux or Windows badge for UI code.
• Linux badge only when the product builds on a Linux toolchain (libraries, servers, CLIs). A pure Apple-UI repo has no Linux badge.
• Windows badge only when the targets compile on Windows. If the test tooling is POSIX-only, Windows is a build-only gate: build the portable library targets (debug and release), skip the suite, and say so in a header comment. The badge then truthfully means "compiles on Windows."
• WASM/WASI badge only when the package builds for wasm32-unknown-wasip1. Code that needs Foundation networking, threads, or other WASI-absent surface does not get a WASM badge. WASM is typically a build gate; running wasm tests needs a separate runtime and is usually out of scope.

When a platform can build but not run the full suite, the workflow is a build gate, not a test gate. The header comment states the scope so the green badge is not read as "tests pass" when it means "compiles."

Rule 8.4: Triggers and permissions are uniform across the split

Every workflow uses the same trigger surface so the badges refresh together: on: push: branches: [main] plus pull_request: plus workflow_dispatch:. Keep permissions: least-privilege (contents: read, plus issues: read only where a gate reads issues, e.g. a roadmap check). The commit-message attribution gate (Rule 5.1) lives in the style workflow and needs fetch-depth: 0 on checkout plus BASE_SHA / HEAD_SHA from the PR event to scan the commit range.

Triggers (when to load this rule)

Load this rule when:

• Filing a new GitHub issue (Rule 1.1, Rule 1.2, Rule 1.3, Rule 1.6)
• Editing an open issue body (Rule 1.1, Rule 1.4, Rule 1.5)
• Adding or deleting a GitHub label (Rule 2.1, Rule 2.2, Rule 2.3, Rule 2.4)
• Opening a PR (Rule 3.1, Rule 3.2, Rule 3.3, Rule 3.4)
• Creating a branch (Rule 4.1, Rule 4.2, Rule 4.3)
• Writing a commit message that will be pushed (Rule 5.1, Rule 5.2)
• Running git commit --amend (Rule 5.3)
• Running git push (Rule 6.1, Rule 6.2)
• Designing a tracker-discipline mechanism for a new repo (Rule 7)
• Setting up CI workflows or README status badges (Rule 8.1, Rule 8.2, Rule 8.3, Rule 8.4)

Load on demand per the trigger; do not auto-load.