Skip to content

Commit 22f32c9

Browse files
wesbillmanCarl
andauthored
docs(nest): make commit attribution policy-neutral (#6707)
## Summary - replace the generated Nest's unconditional human author/sign-off rules with portable guidance that separates authorship, material co-authorship, DCO certification, and cryptographic signing - defer attribution to repository-local policy, forbid inferred or guessed identities, and require inspection of every outgoing commit - bump the Nest template version so existing installations refresh, with regression coverage for fresh generation and upgrade preservation ### Related issue None found. Related runtime identity work exists in #6177, but this PR is intentionally limited to the generated Nest guidance and its refresh behavior. ### Testing - `bin/just desktop-tauri-clippy` - `bin/just desktop-tauri-test` - `bin/just file-size-check` - `git diff --check` - pre-push hooks: `push-head-scope`, `branch-skew`, `file-size-check`, and `desktop-tauri-checks` Signed-off-by: Wes <[email protected]> Co-authored-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz>
1 parent b58de7c commit 22f32c9

3 files changed

Lines changed: 54 additions & 8 deletions

File tree

‎desktop/src-tauri/src/managed_agents/nest.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ const BUZZ_CLI_SKILL_MD: &str = include_str!("nest_skill.md");
4848
/// Template content version for AGENTS.md static content (above managed markers).
4949
/// Bump this when changing `nest_agents.md` to trigger refresh on existing installs.
5050
/// Version 1 is implicitly "before this mechanism existed" (no version file).
51-
const NEST_AGENTS_VERSION: u32 = 4;
51+
const NEST_AGENTS_VERSION: u32 = 5;
5252

5353
/// Template content version for SKILL.md.
5454
/// Bump this when changing `nest_skill.md` to trigger refresh on existing installs.

‎desktop/src-tauri/src/managed_agents/nest/tests.rs‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,21 @@ fn nest_skill_contains_safe_mention_workflow() {
4141
assert!(BUZZ_CLI_SKILL_MD.contains("never changes membership automatically"));
4242
}
4343

44+
#[test]
45+
fn nest_agents_template_separates_commit_attribution_claims() {
46+
assert_eq!(AGENTS_MD.matches("## Git Commit Attribution").count(), 1);
47+
assert!(AGENTS_MD.contains(
48+
"Git authorship, co-authorship, DCO sign-off, and cryptographic signing are separate claims"
49+
));
50+
assert!(AGENTS_MD
51+
.contains("Request, approval, review, or accountability alone is not co-authorship"));
52+
assert!(AGENTS_MD.contains("A sign-off is not an approval marker"));
53+
assert!(AGENTS_MD.contains("Never use another person's signing key"));
54+
assert!(AGENTS_MD.contains("inspect every outgoing commit against the actual upstream or base"));
55+
assert!(AGENTS_MD.contains("An agent-owned repository may use the agent as author"));
56+
assert!(!AGENTS_MD.contains("every commit MUST include a `Signed-off-by`"));
57+
}
58+
4459
#[test]
4560
fn ensure_nest_creates_all_dirs_and_agents_md() {
4661
let tmp = tempfile::tempdir().unwrap();
@@ -431,6 +446,34 @@ fn refresh_agents_md_writes_version_file() {
431446
assert_eq!(version.trim(), NEST_AGENTS_VERSION.to_string());
432447
}
433448

449+
#[test]
450+
fn refresh_agents_md_upgrades_attribution_and_preserves_owned_content() {
451+
let tmp = tempfile::tempdir().unwrap();
452+
let root = tmp.path().join(".buzz");
453+
ensure_nest_at(&root).unwrap();
454+
455+
let agents_md = root.join("AGENTS.md");
456+
fs::write(
457+
&agents_md,
458+
"# Buzz Nest\n\n## Git Commit Identity\n\n\
459+
- **Human sign-off (required):** every commit MUST include a `Signed-off-by`.\n\n\
460+
<!-- BEGIN BUZZ MANAGED — regenerated automatically, do not edit below -->\n\
461+
## Active Agents\n\n| Name | Persona | How to address |\n\
462+
|------|---------|----------------|\n| Kit | Builder | @Kit |\n\
463+
<!-- END BUZZ MANAGED -->\n\n## Local Notes\n\nKeep me.\n",
464+
)
465+
.unwrap();
466+
fs::write(root.join(".nest-agents-version"), "4\n").unwrap();
467+
468+
ensure_nest_at(&root).unwrap();
469+
470+
let content = fs::read_to_string(&agents_md).unwrap();
471+
assert_eq!(content.matches("## Git Commit Attribution").count(), 1);
472+
assert!(!content.contains("**Human sign-off (required):**"));
473+
assert!(content.contains("| Kit | Builder | @Kit |"));
474+
assert!(content.contains("## Local Notes\n\nKeep me."));
475+
}
476+
434477
#[test]
435478
fn refresh_skill_md_writes_version_file() {
436479
let tmp = tempfile::tempdir().unwrap();

‎desktop/src-tauri/src/managed_agents/nest_agents.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,15 +44,18 @@ created: 2026-01-15
4444
- **`.scratch/` is disposable** — don't rely on it across sessions
4545
- **Stay on task** — only stage files relevant to your current work
4646

47-
## Git Commit Identity
47+
## Git Commit Attribution
4848

49-
The human operator signs off for accountability.
49+
Git authorship, co-authorship, DCO sign-off, and cryptographic signing are separate claims. Follow repository-local rules and the authorizing human's explicit directions; do not infer attribution from repository ownership or from who requested, approved, or reviewed the work.
5050

51-
- **Human sign-off (required):** every commit MUST include a `Signed-off-by` trailer for the human operator who is responsible for the agent's work. Add via `git commit --trailer "Signed-off-by: Human Name <human@email>"`. One blank line must separate trailers from the commit body.
52-
- **Human credit (`Co-authored-by`):** every commit MUST also include a `Co-authored-by` trailer for the same human operator, with identical name and email to the `Signed-off-by` line. GitHub parses `Co-authored-by` for contribution-graph credit; `Signed-off-by` alone does not grant it. Add via `git commit --trailer "Co-authored-by: Human Name <human@email>"`. Place `Co-authored-by` before `Signed-off-by` in the trailer block.
53-
- **Discovering the human's identity:** read `git config user.name` and `git config user.email` from the working repository. These reflect the human operator's configured identity for that repo (which may differ from their global config). Use these exact values for both trailers. Do NOT hardcode, guess, or prompt for the email — the repo config is the source of truth. If `git config user.email` returns empty, STOP and ask the human operator for their name and email before committing.
54-
- **Signing:** if the agent has a registered signing key, sign commits. If not, commits will land unverified — this is acceptable until agent SSH keys are provisioned. Do NOT use the human's signing key.
55-
- **Verify before pushing:** `git log -1` should show the human's `Signed-off-by` trailer.
51+
- **Author:** use the person or agent required by the applicable policy. If no policy specifies an author, use the identity that actually authored the change.
52+
- **Co-authors:** add `Co-authored-by` only for other people or agents who materially authored the change. Request, approval, review, or accountability alone is not co-authorship.
53+
- **DCO:** add `Signed-off-by` only when repository policy requires that identity's DCO certification. A sign-off is not an approval marker.
54+
- **Identity:** resolve required identities from trusted local configuration or explicit verified direction; never hard-code or guess them. A managed runtime may make effective `git config user.*` values identify the agent. Stop and ask if a required identity cannot be established.
55+
- **Signing:** use only the signing key configured for the committing identity. Never use another person's signing key.
56+
- **Verify before pushing:** inspect every outgoing commit against the actual upstream or base and confirm its attribution matches the applicable policy.
57+
58+
A repository may require an accountable human as author and the implementing agent as co-author. An agent-owned repository may use the agent as author and require no human trailer. In both cases, repository-local policy controls.
5659

5760
<!-- BEGIN BUZZ MANAGED — regenerated automatically, do not edit below -->
5861
## Active Agents

0 commit comments

Comments
 (0)