Skip to content

docs(rules): one copy of the org rules for every session and run - #74

Merged
realRaghavGupta merged 1 commit into
mainfrom
lead/one-org-rules-2
Nov 9, 2026
Merged

realRaghavGupta merged 1 commit into
mainfrom
lead/one-org-rules-2

Conversation

@realRaghavGupta

Copy link
Copy Markdown
Contributor

Refs setkernel/hq#1521 (F7). Reopens #73, which GitHub closed when its base branch (#72's) was deleted on merge. Rebased onto main after #72; same change, approved on #73 by lyra and orion.

Why

Raghav decided on 2026-11-09 that this file is the one source of the org rules. hq's copy, agents/rules/org-rules.md, is the one every headless run (the Lead on raghav-dev, seat assign.yml runs) gets today. The managed settings don't reach those runs: vega-dev's remote-settings.json is empty. A setkernel/hq PR makes both runners fetch this file and deletes hq's copy.

What

This adds the rules only hq's copy had, so nothing is lost when it goes:

  • Changes: request changes only for merge blockers; at most 5 approval nits; a changes round fixes only those blockers.
  • Who did it:
    • the 5 Claude seats, with no other seat, bot or shared account;
    • 2–3 sessions per person;
    • only the Lead does Lead work (the raghav-dev timer, or a session Raghav starts as Lead), and it keeps no scratch scripts or pollers.
  • When a service is down: stop, commit locally, retry, post to Buzz or the issue; never work around it; break-glass is Raghav's.

Where the copies differed, this file's wording and branch prefixes stay (the Mac Lead session is lead/ / — Claude Lead).

Budget: the file is 74 lines, so the limit in tests/run.sh, README and AGENTS.md goes from 64 to 80. That's the size hq's copy (80 lines) already had in every run.

Checks

  • bin/generate --check: current.
  • bash tests/run.sh on macOS: 776/786. The 10 failures are the request-review cases that fail on main on this machine too.

Policy, so it's Raghav's merge.

— Claude Lead

🤖 Generated with Claude Code

@lyra-setkernel lyra-setkernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed head b0d9871.

No merge blockers. Approving.

What I checked and how

  • Checks: the head has one check run, check, and it completed with success. I also ran CI's steps on this head locally: bash tests/run.sh gave 789/789 passed (that includes the org rules stay within 80 lines), and bin/generate --check printed generated files are current.
  • Acceptance criteria: the PR closes no issue. It says Refs setkernel/hq#1521, and closing_issues is empty. I can't reach GitHub in this run, so I didn't check hq#1521's criteria. Instead I checked the PR's own claims:
    • rules/org-rules.md has 74 lines (wc -l).
    • The three added blocks are in the file: request changes only for merge blockers (lines 40–43), seats, sessions and Lead work (lines 48–51), and "When a service is down" (lines 58–61).
    • managed/settings.json changes only in claudeMd, which bin/generate --check shows matches the rules file. The permissions deny list and every other key are unchanged.
    • Nothing still says 64 lines: grep -rn "64 lines\|40–64\|-le 64" finds nothing.
  • Correctness: the new text doesn't conflict with the existing Changes and Merging rules. The seat count holds: Raghav's seat plus vega-, rigel-, lyra- and orion-setkernel makes 5.
  • Scope: I didn't check scope against ## Files likely touched, because no issue is linked. The 5 files touched (the rules file, its generated copy, README, AGENTS.md and the limit in tests/run.sh) are all ones this change needs.
  • Org rules and security: the diff has no secrets. The deny list is untouched. What goes live on merge is the new claudeMd text for every seat, which is the stated intent. The PR is policy, so it also needs Raghav's review under the gate rule, and he is the author.
  • Test edit: tests/run.sh raises the line limit from 64 to 80. This repo's CI (.github/workflows/check.yml) has no test-diff guard, and no guard check ran on this head. I couldn't check whether hq's gate treats this as a guarded test edit. If it does, an allow-test-changes: line would need to go on an issue, and this PR only Refs one.

Nits (non-blocking)

  1. The signing list and the new Lead line disagree. rules/org-rules.md:50 says the Lead is "the timer on raghav-dev". But line 55 maps hostname raghav-dev to raghav-dev/<topic> / — raghav-dev, and line 56 gives lead/ / — Claude Lead only to "Raghav's Mac lead session". Once hq's copy is deleted, the timer Lead would sign as raghav-dev. hq's copy says "On raghav-dev: the Lead lead/<topic>, — Claude Lead". The PR body says this file's prefixes were kept on purpose. Even so, a line such as "the Lead, wherever it runs: lead/<topic>, — Claude Lead" would remove the ambiguity.
  2. Two lines this PR doesn't change are now out of step with the Merging rule. rules/org-rules.md:20 says "merging (Claude Lead: see Merging)", but Merging says only the gate Worker merges. Line 57 still mentions /approve <sha>, which the gate rule no longer uses. These could go in a follow-up.
  3. The new tests/run.sh:88 comment is a long single line. It could wrap like the comments around it.

@orion-setkernel orion-setkernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed head b0d9871.

No merge blockers found.

What I checked and how

  • Checks: the head has one check run, check, and it completed with success. I also ran CI's two main steps locally on head b0d9871:

    • bin/generate --check printed generated files are current and exited 0.
    • bash tests/run.sh printed 789/789 passed and exited 0 on Ubuntu.
  • Acceptance criteria: the PR closes no issue and only says Refs setkernel/hq#1521. This run can't reach setkernel/hq, so I had no - [ ] list to check. I did not check the criteria against hq#1521. Instead I checked the PR's own claims:

    • rules/org-rules.md has 74 lines (wc -l), which is under the new limit of 80.
    • The three sections the PR names are in rules/org-rules.md. The merge-blocker and nit rule is at lines 40-43, the seats, sessions and Lead lines at 48-51, and "When a service is down" at 58-61.
    • managed/settings.json changes only its claudeMd string, and bin/generate --check confirms that string matches the rules file. The permissions.deny list and every other key are unchanged.
  • Scope: five files change, and each one belongs to this change:

    • the rules file;
    • its generated copy, managed/settings.json;
    • the 64 to 80 line limit in tests/run.sh, README.md and AGENTS.md.

    There is no ## Files likely touched list to compare against, because hq#1521 was not readable here.

  • Org rules: the diff contains no secrets. tests/run.sh raises the line limit from 64 to 80 and changes nothing else. This repo's CI has no test-diff guard (.github/workflows/check.yml has only check). I could not see whether the gate Worker's guard flags this edit, or whether hq#1521 has an allow-test-changes: line. Not checked.

  • Security and what goes live on merge: this is a policy change, so treat it as R3. When it merges, the new claudeMd reaches every seat. The diff adds only rule text: no permissions, hooks or deny-list entries change. Raghav opened the PR, so the owner-path rule's "unless he opened it" exception applies, and the PR body already says it's Raghav's merge.

  • The PR text and code contain no instructions aimed at reviewers or agents.

Nits (non-blocking)

  1. The Lead has no row for its branch prefix and signature. Lines 50-51 now say the Lead is "the timer on raghav-dev, or a session Raghav starts as Lead". But the signing list binds lead/ and — Claude Lead only to "Raghav's Mac lead session" (line 56). A Lead run on raghav-dev therefore matches only the raghav-dev/ and — raghav-dev row (line 55). hq's copy gave the Lead on raghav-dev lead/ and — Claude Lead. So once hq's copy is deleted, the Lead's commits will be signed — raghav-dev. The PR body says this file's prefixes stay on purpose. If the Lead should still be told apart from Raghav's other raghav-dev sessions, one row would fix it, for example: "Claude Lead (the raghav-dev timer or a Mac lead session): lead/<topic>, — Claude Lead".
  2. The rules this run received differ from this repo's rules. The managed-settings rules in this review run's own context are not rules/org-rules.md on main. They mention "R0–R3", "sk-agent" and "the merge App", where main says "normal/owner" and "the gate Worker". So the managed settings being served are out of sync with this repo, and this PR doesn't change that. It's a separate issue, but worth confirming before relying on "one copy". I couldn't check where that text is served from.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants