V48 (spec-impl): Codify 50/72 commit message law

Document subject soft ≤50, blank line, and body lines hard
≤72 in SPECIFYING §2.8, AGENTS, CONTRIBUTING,
FAMILIARIZATION, and the operator skill. Enforce via
scripts/check-bitcode-commit-msg.mjs (commit-msg hook).

Author: geraldarthurdavis

.docs/AGENTS.md

@@ -13,8 +13,12 @@
   - `(impl-only)` — Impl only (code, tests, tooling, scripts)
   - `(spec-impl)` — Spec + Impl in lockstep
   - **Never** write `(specification-only)`, `(implementation-only)`, or `(specification-implementation)` in a subject
-  Examples: `V48 Gate 3 (impl-only): Rename deposit input to Obfuscations` or `V48 Gate 3 (spec-only): Record SDIVF in V48 notes`. A change that touches both kinds is one `(spec-impl)` commit or a split into `(spec-only)` + `(impl-only)` — never an unlabeled mix. This keeps Complete Implementation Derivability (`.specifications/BITCODE_SPECIFYING.md` §2.8) auditable commit by commit.
-- **Commit subject length:** keep the first line under **72 characters** (git default soft limit). Prefer a short imperative subject; put proof commands, file lists, and rationale in the **commit body** when needed. Do not stuff the subject with long parentheticals or run-on clauses.
+  Examples: `V48 Gate 3 (impl-only): Rename Obfuscations` or `V48 Gate 3 (spec-only): Record SDIVF in notes`. A change that touches both kinds is one `(spec-impl)` commit or a split into `(spec-only)` + `(impl-only)` — never an unlabeled mix. This keeps Complete Implementation Derivability (`.specifications/BITCODE_SPECIFYING.md` §2.8) auditable commit by commit.
+- **Commit message shape (50/72 law)** — required for every commit and gate PR subject/body (see `.specifications/BITCODE_SPECIFYING.md` §2.8):
+  - **Subject (first line) ≤ 50 characters** (soft) — keep the summary readable in compact logs
+  - **Blank line** after the subject whenever a body follows
+  - **Body lines ≤ 72 characters** each (hard) — wrap proof commands, file lists, and rationale
+  Prefer a short imperative subject; do not stuff the subject with long parentheticals or run-on clauses.
 - Any inline code comment that cites an accepted QA finding shorthand must always carry the fully-qualified tag `[VERSION]-Gate[N]-F[ID]` (e.g. `V48-Gate3-F26-B`), never a bare `F26-B`-style tag. The same fully-qualified tag must always be discoverable in the specification/QA ledger file(s) (e.g. the finding's own `### V48-Gate3-F26` heading in `.qa/BITCODE_V48_QA.md`), so a reader can go from either direction — code comment to spec entry, or spec entry to every citing code comment — with a single grep. This keeps finding-to-fix traceability intact without requiring the surrounding file or commit to already establish which version/gate is active.
 - Once implementation starts on a gate branch, do not stop at partial progress unless blocked by missing external input or explicit user pause. A gate branch is ready to stop only when the gate's acceptance criteria are implemented, specified, tested, documented, committed, pushed, and pull-requested for closure into the version branch.
 - Treat gate and promotion workflow health as part of gate closure. Gate pull requests into version branches must be green through the maintained gate-quality checks, and repository-wide canon-quality checks must remain greenable during draft work. Version pull requests into `main` must pass the version promotion workflow, which performs promotion-grade validations and commits the standalone `BITCODE_SPEC.txt` pointer change only after those validations pass.

.docs/FAMILIARIZATION.md

@@ -90,7 +90,7 @@ from the active family alone — no silent inheritance from older specs or sourc
 
 ### 2.2 Commit law
 
-Every commit / gate PR **subject** (≤72 chars) declares exactly one of:
+Every commit / gate PR **subject** declares exactly one of:
 
 - `(spec-only)` — Spec only
 - `(impl-only)` — Impl only
@@ -99,9 +99,17 @@ Every commit / gate PR **subject** (≤72 chars) declares exactly one of:
 Use only these abbreviated parentheticals in commit/PR subjects — never
 `(specification-only)`, `(implementation-only)`, or `(specification-implementation)`.
 
-Example: `V48 (impl-only): Extract ReadsNeedReviewPanel`.
+**50/72 message shape** (SPECIFYING §2.8): subject ≤ **50** chars (soft); blank
+line before body; each body line ≤ **72** chars (hard).
 
-Put proof commands and longer rationale in the commit body.
+Example:
+
+```text
+V48 (impl-only): Extract NeedReviewPanel
+
+Move review chrome into ReadsNeedReviewPanel with
+co-located tests.
+```
 
 ### 2.3 Branches
 

.specifications/BITCODE_SPECIFYING.md

@@ -256,10 +256,21 @@ that parenthetical.
 | `(implementation-only)` | `(impl-only)` |
 | `(specification-implementation)` | `(spec-impl)` |
 
-Example: `V48 Gate 3 (impl-only): Rename deposit input to Obfuscations`.
+Example: `V48 Gate 3 (impl-only): Rename Obfuscations`.
 
-**Subject length:** keep the first line under **72 characters**. Put proof
-commands, file lists, and longer rationale in the commit body when needed.
+**Commit message shape (50/72 law)** — applies to every commit and gate PR
+subject/body:
+
+| Rule | Limit | Nature |
+| --- | --- | --- |
+| **Subject** (first line) | ≤ **50** characters | Soft limit — keep the summary readable in compact logs |
+| **Blank line** | Second line empty whenever a body follows | Required separator between title and body |
+| **Body lines** | ≤ **72** characters each | Hard limit for every subsequent line |
+
+Put proof commands, file lists, and longer rationale in the **body**, wrapped at
+72. Prefer a short imperative subject; do not stuff subjects with long
+parentheticals or run-on clauses. Category labels (`(spec-only)` / `(impl-only)` /
+`(spec-impl)`) still apply on the subject.
 
 A change that alters both kinds is committed as a single `(spec-impl)` commit,
 or split into a `(spec-only)` and an `(impl-only)` commit — never an unlabeled

CONTRIBUTING.md

@@ -88,31 +88,47 @@ main                    # protected; promoted canon only
 **Never** push product work straight to `main`. Expect PRs + verified signatures
 via the **Bitcode Core Contributions** ruleset.
 
-### 2.3 Commit and PR subjects
+### 2.3 Commit and PR messages (50/72 law)
 
-Every commit / gate PR **subject** (≤72 characters) declares exactly one of:
+Every commit / gate PR **subject** declares exactly one of:
 
 | Token | Meaning |
 | --- | --- |
 | `(spec-only)` | Spec family / notes / roadmap only |
 | `(impl-only)` | Code, tests, tooling, scripts only |
 | `(spec-impl)` | Spec + implementation in lockstep |
 
+**Message shape** (`.specifications/BITCODE_SPECIFYING.md` §2.8):
+
+| Part | Rule |
+| --- | --- |
+| **Subject** (line 1) | ≤ **50** characters (soft) — readable in compact logs |
+| **Blank line** | Required between subject and body when a body is present |
+| **Body lines** | ≤ **72** characters each (hard) |
+
 Examples:
 
 ```text
-V48 Gate 3 (impl-only): Wire deposit cancel into pipeline host
-V48 Gate 4 (spec-only): Record read settle acceptance rows
-V48 Gate 4 (spec-impl): Close read need panel parity
+V48 Gate 3 (impl-only): Wire deposit cancel
+
+Wire cancel into the pipeline host and add the
+focused host route test.
+```
+
+```text
+V48 Gate 4 (spec-only): Record read settle rows
+V48 Gate 4 (spec-impl): Close need panel parity
 ```
 
 **Never** use expanded forms like `(specification-only)` in subjects. Put proof
-commands and file lists in the **body**.
+commands and file lists in the **body** (wrapped at 72).
 
-Gate PR titles: `V48 Gate N (impl-only): Short topical title`  
+Gate PR titles follow the same subject shape:  
+`V48 Gate N (impl-only): Short topical title`  
 Version promotion PRs: uppercase version + “canonical promotion” wording.
 
-Full craft rules: [`.docs/AGENTS.md`](.docs/AGENTS.md).
+Full craft rules: [`.docs/AGENTS.md`](.docs/AGENTS.md).  
+Enforced by `.githooks/commit-msg` → `scripts/check-bitcode-commit-msg.mjs`.
 
 ### 2.4 QA finding tags
 

apps/claude/skills/bitcode-operator/SKILL.md

@@ -31,4 +31,4 @@ Never invent or dump protected raw source into user-facing artifacts. Packs carr
 ## When to escalate
 
 - Spec vs implementation drift → open `BITCODE_SPEC_V48_*` / active draft notes
-- Gate work → follow Agents.md gate branch + `(spec-impl)` / `(impl-only)` / `(spec-only)` commit labels (subject ≤72 chars)
+- Gate work → follow Agents.md gate branch + `(spec-impl)` / `(impl-only)` / `(spec-only)` commit labels; 50/72 commit message law (subject soft ≤50, blank line, body lines hard ≤72)

scripts/check-bitcode-commit-msg.mjs

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+/**
+ * commit-msg hook body — Spec/Impl labels + 50/72 commit message law
+ * (`.specifications/BITCODE_SPECIFYING.md` §2.8, `.docs/AGENTS.md`).
+ */
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
@@ -10,6 +14,11 @@ const __dirname = path.dirname(__filename);
 const defaultRepoRoot = path.resolve(__dirname, '..');
 const defaultQualityScript = path.join(defaultRepoRoot, 'scripts/run-bitcode-spec-quality.mjs');
 
+/** Soft subject limit — compact-log readability (50/72 law). */
+export const COMMIT_SUBJECT_SOFT_MAX = 50;
+/** Hard wrap for body lines (and absolute subject ceiling). */
+export const COMMIT_BODY_LINE_MAX = 72;
+
 /**
  * @param {string[]} argv
  * @returns {{ commitMessagePath: string | null, repoRoot: string, qualityScript: string }}
@@ -28,12 +37,38 @@ export function parseArgs(argv) {
   return { commitMessagePath, repoRoot, qualityScript };
 }
 
+/**
+ * Strip comment lines (`# …`) from a commit-msg file payload.
+ * @param {string} raw
+ * @returns {string}
+ */
+export function stripCommitMessageComments(raw) {
+  return raw
+    .split('\n')
+    .filter((line) => !line.startsWith('#'))
+    .join('\n')
+    .replace(/\s+$/u, '');
+}
+
 /**
  * @param {string} commitMessagePath
  * @returns {string}
  */
 export function readCommitTitle(commitMessagePath) {
-  return readFileSync(commitMessagePath, 'utf8').split('\n')[0].trim();
+  const text = stripCommitMessageComments(readFileSync(commitMessagePath, 'utf8'));
+  return text.split('\n')[0]?.trim() ?? '';
+}
+
+/**
+ * @param {string} commitMessagePath
+ * @returns {{ subject: string, bodyLines: string[] }}
+ */
+export function readCommitMessageParts(commitMessagePath) {
+  const text = stripCommitMessageComments(readFileSync(commitMessagePath, 'utf8'));
+  const lines = text.split('\n');
+  const subject = (lines[0] ?? '').trimEnd();
+  const bodyLines = lines.slice(1);
+  return { subject, bodyLines };
 }
 
 /** Expanded forms are illegal in subjects; only abbreviated Spec/Impl labels. */
@@ -78,6 +113,64 @@ export function assertAbbreviatedCommitCategoryLabel(commitTitle) {
   }
 }
 
+/**
+ * Enforce 50/72 commit message law (SPECIFYING §2.8).
+ * - Subject ≤ 50 soft (warn); > 72 hard fail
+ * - Blank line after subject when body content follows
+ * - Each body line ≤ 72 hard fail
+ *
+ * @param {{ subject: string, bodyLines: string[] }} parts
+ * @param {{ warn?: (message: string) => void }} [options]
+ */
+export function assertCommitMessageFiftySeventyTwo(parts, options = {}) {
+  const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+  const subject = parts.subject ?? '';
+  const subjectLen = subject.length;
+
+  if (!subject.trim()) {
+    throw new Error('Commit subject (first line) must not be empty.');
+  }
+
+  if (subjectLen > COMMIT_BODY_LINE_MAX) {
+    throw new Error(
+      `Commit subject is ${subjectLen} characters (hard max ${COMMIT_BODY_LINE_MAX}). ` +
+        `Keep the first line ≤ ${COMMIT_SUBJECT_SOFT_MAX} (soft 50/72 law) and put detail in the body.`,
+    );
+  }
+
+  if (subjectLen > COMMIT_SUBJECT_SOFT_MAX) {
+    warn(
+      `Bitcode 50/72: subject is ${subjectLen} characters (soft max ${COMMIT_SUBJECT_SOFT_MAX}). ` +
+        `Prefer a shorter first line; put detail in the body (≤ ${COMMIT_BODY_LINE_MAX} per line).`,
+    );
+  }
+
+  const bodyLines = parts.bodyLines ?? [];
+  // Trailing empty lines after a body are fine; detect non-empty body content.
+  const firstNonEmptyBodyIndex = bodyLines.findIndex((line) => line.trim().length > 0);
+  if (firstNonEmptyBodyIndex === -1) {
+    return;
+  }
+
+  // When a body follows, line immediately after the subject must be blank.
+  if (bodyLines.length === 0 || bodyLines[0].trim().length > 0) {
+    throw new Error(
+      'Commit message 50/72 law: leave the second line completely empty to separate ' +
+        'the subject from the body.',
+    );
+  }
+
+  for (let index = 0; index < bodyLines.length; index += 1) {
+    const line = bodyLines[index];
+    if (line.length > COMMIT_BODY_LINE_MAX) {
+      throw new Error(
+        `Commit body line ${index + 2} is ${line.length} characters ` +
+          `(hard max ${COMMIT_BODY_LINE_MAX} under 50/72 law). Wrap the body.`,
+      );
+    }
+  }
+}
+
 /**
  * @param {{ commitMessagePath: string | null, repoRoot: string, qualityScript: string }} options
  */
@@ -86,8 +179,10 @@ export function runCommitMessageCheck({ commitMessagePath, repoRoot, qualityScri
     throw new Error('A commit message file path is required.');
   }
 
-  const commitTitle = readCommitTitle(commitMessagePath);
+  const parts = readCommitMessageParts(commitMessagePath);
+  const commitTitle = parts.subject.trim();
   assertAbbreviatedCommitCategoryLabel(commitTitle);
+  assertCommitMessageFiftySeventyTwo(parts);
   execFileSync(
     process.execPath,
     [