Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,10 @@ Parse:
- **"let's go with m/acc"** = formal adoption of the name
- **"(shadow*) Aaron: 'We do m/acc work' yes i like this"** = per
the shadow-star shorthand
(`memory/feedback_aaron_shadow_star_shorthand_means_autocomplete_generated_not_aaron_authored_grey_text_completed_2026_05_15.md`),
(`memory/feedback_aaron_shadow_star_shorthand_means_autocomplete_generated_not_aaron_authored_grey_text_completed_2026_05_15.md`
— user-scope only at `~/.claude/projects/.../memory/`; cold-boot
agents on fresh checkouts read [`shadow-star-shorthand-autocomplete-marker.md`](shadow-star-shorthand-autocomplete-marker.md)
for the in-repo rule that names the shorthand definitively),
the "We do m/acc work" phrase was Otto's autocomplete that Aaron
is confirming; he likes the operational-not-identity-investment
framing
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ Per `.claude/rules/backlog-item-start-gate.md`:
3. **Per-repo three-axis classification** owed for existing
and proposed repos
4. **Ruleset audit** — survey existing rulesets; document
divergences as candidate-split signals
divergences as candidate-split signals (Done via B-0476)
5. **Soraya consultation** for formal-verification sub-axis
(per-property-class evaluation)

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: B-0476
priority: P1
status: open
status: closed
title: "GitHub ruleset divergence audit — survey rulesets across repos; identify smell signals"
type: research
origin: B-0427 decomposition (Otto, 2026-05-14)
Expand Down Expand Up @@ -36,9 +36,9 @@ candidate-split signals.

Per `.claude/rules/backlog-item-start-gate.md`:

- [ ] B-0475 output doc reviewed (prior-art audit complete; no blocking conflicts)
- [ ] Walk `depends_on:` chain — B-0475 closed with output doc committed
- [ ] Prior-art search: any existing ruleset documentation in substrate?
- [x] B-0475 output doc reviewed (prior-art audit complete; no blocking conflicts)
- [x] Walk `depends_on:` chain — B-0475 closed with output doc committed
- [x] Prior-art search: any existing ruleset documentation in substrate?

## What to survey

Expand Down Expand Up @@ -111,12 +111,12 @@ gh api repos/Lucent-Financial-Group/civsim/rulesets --jq '.[] | {id,name,target,

## Definition of done

- [ ] All existing repos surveyed (LFG/Zeta, AceHack/Zeta, LFG/civsim)
- [ ] Proposed repo expected rulesets documented
- [ ] Divergence matrix complete
- [ ] Candidate-split signals identified and documented
- [ ] Output doc committed and referenced from B-0427
- [ ] B-0476 closed with PR link
- [x] All existing repos surveyed (LFG/Zeta, AceHack/Zeta, LFG/civsim)
- [x] Proposed repo expected rulesets documented
- [x] Divergence matrix complete
- [x] Candidate-split signals identified and documented
- [x] Output doc committed and referenced from B-0427
- [x] B-0476 closed with PR link
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add the PR URL before checking closure criteria

This checklist item is marked complete, but the row does not include any PR link, so the Definition of done currently asserts traceability that isn't present. Because B-0427 and future audits depend on these backlog rows as the durable closure record, marking this as done without the URL can mislead downstream reviewers and automation about whether the closure evidence exists.

Useful? React with 👍 / 👎.


## Why P1

Expand Down
67 changes: 67 additions & 0 deletions docs/research/2026-05-14-github-ruleset-divergence-audit-b0476.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# GitHub ruleset divergence audit — survey rulesets across repos; identify smell signals

**Date:** 2026-05-14
**Author:** Otto
**Related row:** B-0476

## Purpose
Apply Aaron's smell test: *"If two substrate clusters need DIFFERENT GitHub rulesets to govern them, that divergence IS the signal they should live in DIFFERENT repos."*

## Per-repo Ruleset Enumeration

### 1. `LFG/Zeta` (main)
Uses **GitHub Rulesets**:
- **Branch Safety** (16189060): Requires linear history, blocks non-fast-forward, blocks deletion.
- **CI Gate** (16134995): Requires 7 strict status checks (`build-and-test` on macos/ubuntu/ubuntu-arm, `actionlint`, `markdownlint`, `semgrep`, `shellcheck`).
- **Review Policy** (16168181): Requires `copilot_code_review`, requires PR thread resolution. Squash-merge only.

Legacy protection: Requires conversation resolution. `allow_squash_merge: true`, `allow_auto_merge: true`.

### 2. `AceHack/Zeta` (mirror)
Uses **GitHub Rulesets**:
- **Default** (15524390): Requires linear history, blocks deletion/non-fast-forward, requires `copilot_code_review`, requires `code_quality` (all severity). Squash-merge only. Includes bypass permissions for the `AceHack` user.
`allow_squash_merge: true`, `allow_auto_merge: true`.

### 3. `LFG/civsim` (new product repo)
Uses **Legacy Branch Protection** on `main`:
- Requires 1 approving review.
- Strict status checks enabled (but empty context list).
- Requires signed commits.
- Requires linear history, blocks force pushes.
- Requires conversation resolution.
`allow_squash_merge: true`, `allow_auto_merge: true`.

## Divergence Comparison Matrix

| Dimension | `LFG/Zeta` | `AceHack/Zeta` | `LFG/civsim` | Proposed Forge | Proposed Owner-only |
|-----------|-----------|---------------|--------------|----------------|---------------------|
| **Branch Prot.** | PR + Copilot + Strict CI | PR + Copilot + CodeQL | PR (1 review) + Empty CI | Strict Factory CI | Loose (self-review) |
| **Force-push** | Blocked | Blocked (User Bypass) | Blocked | Blocked | Unrestricted |
| **Signed Commits**| Optional | Optional | Required | Required | Optional |
| **Merge Strategy**| Squash | Squash | Squash | Squash | Any |
| **Auto-merge** | Enabled | Enabled | Enabled | Enabled | Disabled |

## Candidate-Split Signals (Smell Test Applications)

1. **Zeta (DB) vs Forge (Factory)**
- **Divergence:** `LFG/Zeta` enforces `build-and-test` for F#/C# on macos/ubuntu. `Forge` requires TypeScript build/test and hygiene script validations.
- **Smell Test:** Fires. The required CI status checks are divergent. They must live in different repos to avoid triggering DB tests on factory changes (and vice versa).

2. **Zeta vs civsim (Product)**
- **Divergence:** `LFG/Zeta` uses modern rulesets with Copilot Code Review. `civsim` uses legacy branch protection requiring signed commits and 1 human approving review.
- **Smell Test:** Fires. Divergent review and signature requirements justify the repo split.

3. **Code vs English (Axis-3)**
- **Divergence:** Code requires compilation, test execution, and static analysis (e.g. `semgrep`, CodeQL). English docs (research, memories) only require `markdownlint` and prose review.
- **Smell Test:** Fires. If English stays with Code, either the CI paths become incredibly complex (path-filtering), or Code CI runs redundantly on English changes. Splitting English into its own repo allows an English-specific ruleset (just `markdownlint` and fast auto-merge).

4. **Formal Verification Sub-axis**
- **Divergence:** TLA+ model checking or Z3/Lean proofs can take hours to run, far exceeding the timeout limits of standard CI workflows for F# unit tests.
- **Smell Test:** Fires. The CI execution cadence and timeout rulesets required for Formal Verification are violently divergent from standard Code. FV is a strong candidate for its own repo.

## Recommended Axis-3 Implications

The ruleset divergence smell test **strongly validates** Axis-3.
- **Code vs English Split:** Mechanically justified by the need for divergent required status checks (compilation/tests vs linting).
- **Formal Verification Split:** Mechanically justified by divergent CI execution limits and specific proof-validation gates.
- **Engineering-Docs Exception:** Docs like `README` and `ADRs` must stay with Code because their *versioning* is strictly tied to the code they describe. While they don't need compilation, they must be gated by the same PR review process as the code they touch.
Loading