From 32a6ab85e7549bd912c51465bba32cf685ecc29b Mon Sep 17 00:00:00 2001 From: GUOGUO Date: Fri, 16 Oct 2026 17:41:18 +0800 Subject: [PATCH 1/4] docs(collaboration): document issue-led collaboration Define Implementer / Reviewer / Integrator boundaries and the three human/agent interaction patterns. Add the scoped-task issue template and the pull request template, and link the collaboration guide from AGENTS.md and docs/contributing.md. Refs #21 Signed-off-by: GUOGUO --- .github/ISSUE_TEMPLATE/scoped-task.md | 45 +++++++++ .github/PULL_REQUEST_TEMPLATE.md | 45 +++++++++ AGENTS.md | 1 + docs/agent-collaboration.md | 135 ++++++++++++++++++++++++++ docs/contributing.md | 3 + 5 files changed, 229 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/scoped-task.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 docs/agent-collaboration.md diff --git a/.github/ISSUE_TEMPLATE/scoped-task.md b/.github/ISSUE_TEMPLATE/scoped-task.md new file mode 100644 index 00000000..2cf8f580 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/scoped-task.md @@ -0,0 +1,45 @@ +--- +name: Scoped task +about: Propose a bounded issue for human or agent work; use Campaign acceptance for performance claims. +title: "task: " +--- + + + +## Goal and acceptance + + + +- **Problem / desired outcome:** +- **Completion criteria:** + +## Scope and constraints + +- **In scope / out of scope:** +- **Relevant dependencies, shared interfaces or limits (if any):** + +## Ownership and authorization + +- **Proposed by / actual requester:** +- **Status:** Proposed / Accepted / Deferred / Rejected +- **Accountable implementer (if assigned):** +- **Goal-acceptance owner:** +- **Accepted decision or scoped delegation:** Not yet granted / `` + +## Inputs and deliverables + +- **Relevant sources, revisions or linked issues:** +- **Expected artifacts:** + +## Completion and closure + + + +- **Who accepts completion and may close:** +- **Remaining uncertainty / next decision:** diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..f65236bc --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,45 @@ + + +## Governing Issue and delivery slice + +Refs #`` + +- **Accepted scope / delegation:** +- **What this PR delivers:** +- **What it does not deliver:** + +## Changed artifacts and evidence + + + +| Requirement | Actual change | Check / evidence and result | Remaining gap | +| --- | --- | --- | --- | +| `` | `` | `` | `` | + +## Checks and dependencies + +- **Checks actually run (result and tested scope):** +- **Failed, skipped, timed-out or not-run checks (if applicable):** +- **Dependencies / shared interfaces / integration assumptions (if applicable):** + + + +## Remaining work and Issue closure + +- **Remaining Issue requirements / follow-up:** +- **Goal-acceptance owner or accepted closure delegation:** +- **Goal ready for acceptance?** Not claimed / Proposed with evidence link + + + +## Handoff (only when an actual handoff or decision changed) + +- **Decision delta / acceptance link:** +- **Recipient; communicated vs applied/pending/unknown:** +- **Relevant workspace state and next action:** diff --git a/AGENTS.md b/AGENTS.md index fc491579..8f7a66a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ Coding agents (Cursor, Codex, Claude, etc.) should treat this file as the **entr | --- | --- | | [README.md](README.md) | Layout, dev smoke, copy checklist | | [docs/contributing.md](docs/contributing.md) | Development, acceptance, evidence and CI | +| [docs/agent-collaboration.md](docs/agent-collaboration.md) | Issue-led human–agent collaboration | | [docs/architecture.md](docs/architecture.md) | Module boundaries and extension contracts | ## Four-lane CI diff --git a/docs/agent-collaboration.md b/docs/agent-collaboration.md new file mode 100644 index 00000000..0d643d89 --- /dev/null +++ b/docs/agent-collaboration.md @@ -0,0 +1,135 @@ +# Agent collaboration (issue-led) + +Conventions for coordinating humans and agents through Issues and PRs, delivered +per the collaboration RFC +([#21](https://github.com/InferMatrixLab/OmniRSI/issues/21)). They are +documentation only: no new automation, permissions, merge gates or CI lanes. +Campaign acceptance, DCO, CI lanes and evidence rules stay in +[contributing](contributing.md); the agent entry contract stays in +[AGENTS](../AGENTS.md). + +## Identity and authority + +- Humans and agents may propose Issues. Proposal origin, assignment and labels do not grant authority. +- A GitHub account may represent a human and their authorized agent team. Assignment identifies accountability, not necessarily the executor. Record the acting person/agent and role when relevant; retain unknown identity rather than guessing. +- Work follows accepted scope and explicit or standing delegation. Record or link that authority. Material scope changes and exceptions return to the authorized owner. +- Routine PR review and integration may be delegated without fresh human approval per PR. Existing repository permissions and acceptance policies still apply. +- Completion is accepted by the named person or authorized agent. Acceptance/closure authority must be clear before those actions; it need not block already-authorized implementation. + +## Roles + +| Role | Responsibility | +| --- | --- | +| Implementer | Own a bounded slice; plan, research, coordinate, change, check and report actual results. | +| Reviewer | Independently inspect accepted requirements, actual diff, affected consumers and evidence; return revision-scoped findings and a recommendation. | +| Integrator | Verify authorization, current head/base, dependencies and applicable review/check results; integrate or report a blocker. | + +Roles are responsibilities, not three mandatory agents or services. Separate +agents may act under one account; an author's role switch is still self-review. +A substantive reviewer edit makes that reviewer a contributor requiring +appropriate independent review. Review recommendation is not merge permission. + +## Interaction patterns + +Illustrative responsibilities, not required services or new authority. + +### Human–Human: shared decisions only + +```mermaid +flowchart LR + A["Goal owner"] --> I["Issue: goal and constraints"] + B["Affected owner, if any"] --> I + I --> D["Record agreement or unresolved dependency"] + D -->|"When agreed by authorized owners"| S["Accepted scope and delegation"] +``` + +Shared-owner coordination is conditional; unresolved dependencies do not authorize blocked work. + +### Human–Agent: delegate work, accept the goal + +```mermaid +flowchart TB + H["Authorized owner"] -->|"Scope and delegation"| I["Issue"] + I --> A["Implementer"] + A --> R["Independent review"] + R -->|"Fixes needed"| A + R -->|"Recommendation"| G["Integrator checks existing authority and evidence"] + G -->|"Conditions satisfied"| P["Merged PR"] + P --> S["Goal evidence and remaining gaps"] + S --> O["Acceptance owner or authorized delegate"] + O -->|"Goal accepted; closure authorized"| C["Close Issue"] +``` + +No human-per-PR gate. Blocked integration or incomplete goals remain open; material scope exceptions return to the authorized owner. + +### Agent–Agent: isolated work and conditional handoff + +```mermaid +sequenceDiagram + participant A as Agent A + participant B as Agent B + participant E as Issue / PR / evidence + opt Authorized parallel work + A->>B: Coordinate slices and shared interfaces + Note over A,B: Separate worktrees/indexes and private scratch + end + A->>E: Artifacts and checked-content results + opt Actual handoff or accepted decision change + A->>B: Acceptance link, delta, artifacts, next action + A->>E: Recipient and communication status + B->>E: Applied with evidence, pending or unknown + end +``` + +## Working rules + +1. **Scope:** identify requirements, exclusions, owner and relevant dependencies. Keep each PR a coherent delivery slice; small follow-ups may reuse an Issue. +2. **Isolation:** concurrent writers use separate working directories/indexes and private scratch files. Branch names alone are insufficient. Inspect staged/committed content and coordinate shared IDs, schemas and interfaces. +3. **Evidence:** link checks to actual checked content and relevant environment/test definitions. Distinguish passed, failed, cancelled, skipped, timed-out and not-run. H/B/T—reviewed head, assessed base, tested content—may come from existing records, not mandatory worksheets. +4. **Refresh:** reassess affected evidence after relevant head/base/content/environment/check changes. Refresh checks or explain continued applicability. Neither blanket reuse nor full hardware reruns is the default; changed hashes alone prove neither content change nor equivalence. +5. **Handoff:** only for an actual transfer or accepted decision change, record the delta, recipient and next action. Keep acceptance status/link, communication status and application status separate. "Applied" needs artifact/evidence; otherwise retain pending or unknown. No full conversation traces or new ledger. +6. **Completion:** merged PR ≠ accepted goal ≠ campaign `PASS` ≠ release. Use non-closing `Refs #N` until closure is authorized. Subtasks cannot implicitly close a parent goal. Knowledge proposals to [#17](https://github.com/InferMatrixLab/OmniRSI/issues/17) are optional; no automatic promotion. + +## Records + +- **Issue:** goal/criteria; scope; accountable account and actor if known; acceptance/delegation link; completion/closure owner. Unknown fields may remain TBD while proposed. Ordinary work starts from the [scoped-task template](../.github/ISSUE_TEMPLATE/scoped-task.md); baseline-vs-candidate campaigns use the [campaign acceptance form](../.github/ISSUE_TEMPLATE/campaign-acceptance.yml). +- **PR:** governing Issue; delivered artifacts; checks/results/limitations; dependencies and gaps. Add requirement-to-artifact mapping only when useful, and handoff fields only when applicable. No author-prefilled independent approval. Start from the [PR template](../.github/PULL_REQUEST_TEMPLATE.md). +- **Commit:** short descriptive subject; why/what and Issue reference when useful. Preserve the required DCO sign-off (`git commit -s`); never invent a signing identity. + +Labels document coordination intent; they do not grant it. Reuse existing labels +where adequate: type (`bug`, `enhancement`, `documentation`, optionally `rfc`), +decision (`proposed`, `accepted`, `deferred`, at most one), coordination +(`blocked`, with a blocker link). Do not duplicate native open/closed or +review/check states with labels. Decision labels are synchronized with recorded +decisions by an authorized owner or delegate; setting labels up is a separate +decision, not part of these conventions. + +## Evidence refresh — hypothetical example + +**Hypothetical illustration only; it records no actual PR, run or result in this +repository.** + +Suppose a PR changing `src/omnirsi/harness/runner.py` was reviewed at head `H1` +against base `B1`, then is rebased onto `B2` (new head `H2`) because `B2` touched +the same file. Rule 4 asks what changed, not for a blanket rerun: + +- Compare the affected files between `H1` and `H2`. If the delta is empty and dependencies are unchanged, the earlier review and CI remain applicable; cite them with their original run and state that reasoning in the PR. +- If the delta is non-empty, refresh the affected checks on `H2` — for example `ruff check src tests` plus the relevant `pytest` selection — and report which content each result ran on. +- Either way, distinguish passed, skipped and not-run checks instead of implying a full rerun. A changed hash alone proves neither content change nor equivalence. + +## Historical evidence and limits + +These conventions are OmniRSI proposals informed by the reviewed C1–C7 case pack +from two pinned snapshots: the +[Magpie repository](https://github.com/yetone/magpie/tree/778000326adaa49cd790846acd2d535572ad5ceb) +and the separate +[release-workflow repository](https://github.com/yetone/magpie-releases/tree/fc85a074b1ba73417d2afda783e1c0a27ed79a1f). +The per-case summary and limits live in +[RFC #21](https://github.com/InferMatrixLab/OmniRSI/issues/21): C1–C3 inform +ownership and review; C4–C5, CI trade-offs; C6, completion states; C7, learning. + +They are proposals, not demonstrated Magpie enforcement or a causal speedup. +Described practice, inspected implementation, observed records and proposed +adaptations remain distinct evidence classes; see #21 for the per-case limits, +including the unresolved C1 root cause and the absence of a demonstrated +simultaneous deployment. diff --git a/docs/contributing.md b/docs/contributing.md index a91da667..33fe0f65 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -16,6 +16,9 @@ pytest git commit -s ``` +Issue-led ownership, review and completion conventions for humans and agents +are in [agent collaboration](agent-collaboration.md). + `image` is optional for the control CLI and required to run PNG quality tests. Synthetic benchmark scripts belong in `tests/fixtures/`; historical validator snapshots in `tests/fixtures/legacy/` remain byte-for-byte frozen. Current runnable From dfae2b37b0e0643cdbd64b6279c0364ed7d0193c Mon Sep 17 00:00:00 2001 From: GUOGUO Date: Fri, 16 Oct 2026 18:14:04 +0800 Subject: [PATCH 2/4] docs(collaboration): apply review findings and adopted refinements Address the PR #23 review: the hypothetical example now requires an explicit reason covering content, dependencies, environment and check definitions before reusing earlier evidence; the guide links #21's reviewed case pointers as the accessible C1-C7 extraction instead of calling snapshot roots a pack link; the PR-template handoff fields are split into decision, communication and application states. Align with the updated RFC #21: add the accountable parent role and Human-Agent diagram, an actionable AGENTS.md Issue-first rule, and the Agent-assisted-by commit convention. Refs #21 Agent-assisted-by: Claude Code (implementer) Signed-off-by: GUOGUO --- .github/ISSUE_TEMPLATE/scoped-task.md | 3 +- .github/PULL_REQUEST_TEMPLATE.md | 8 ++-- AGENTS.md | 1 + docs/agent-collaboration.md | 57 +++++++++++++++++---------- 4 files changed, 45 insertions(+), 24 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/scoped-task.md b/.github/ISSUE_TEMPLATE/scoped-task.md index 2cf8f580..4212446d 100644 --- a/.github/ISSUE_TEMPLATE/scoped-task.md +++ b/.github/ISSUE_TEMPLATE/scoped-task.md @@ -26,7 +26,8 @@ Conventions: docs/agent-collaboration.md --> - **Proposed by / actual requester:** - **Status:** Proposed / Accepted / Deferred / Rejected -- **Accountable implementer (if assigned):** +- **Accountable parent (Issue-level owner, if assigned):** +- **Slice implementer(s) / acting contributor (if assigned):** - **Goal-acceptance owner:** - **Accepted decision or scoped delegation:** Not yet granted / `` diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f65236bc..864c8101 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -36,10 +36,12 @@ explanation only when a material integration identity question remains. --> - **Goal ready for acceptance?** Not claimed / Proposed with evidence link +need not close its parent Issue. Commits must retain DCO sign-off; agent-assisted +commits add `Agent-assisted-by: ()` trailers. --> ## Handoff (only when an actual handoff or decision changed) -- **Decision delta / acceptance link:** -- **Recipient; communicated vs applied/pending/unknown:** +- **Accepted decision / status and link:** +- **Recipient and communication status:** +- **Application status and artifact/evidence:** applied / pending / unknown - **Relevant workspace state and next action:** diff --git a/AGENTS.md b/AGENTS.md index 8f7a66a4..870b6375 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -109,3 +109,4 @@ ruff check src tests 1. Read the contribution guide and validation levels before large code or CI changes. 2. Prefer minimal diffs; match existing layout and naming. 3. Do not reopen closed campaign work or add pins to shared automation without explicit human direction. +4. Work Issue-first: confirm the governing Issue's accepted scope before changing code, keep each change a bounded delegated slice with independent review, and report PR readiness and Issue completion separately — see [agent collaboration](docs/agent-collaboration.md). diff --git a/docs/agent-collaboration.md b/docs/agent-collaboration.md index 0d643d89..a714691d 100644 --- a/docs/agent-collaboration.md +++ b/docs/agent-collaboration.md @@ -20,11 +20,19 @@ Campaign acceptance, DCO, CI lanes and evidence rules stay in | Role | Responsibility | | --- | --- | +| Accountable agent (parent) | Own the Issue outcome, plan and remaining criteria; implement or delegate bounded slices and independent review; report completion for acceptance. | | Implementer | Own a bounded slice; plan, research, coordinate, change, check and report actual results. | | Reviewer | Independently inspect accepted requirements, actual diff, affected consumers and evidence; return revision-scoped findings and a recommendation. | | Integrator | Verify authorization, current head/base, dependencies and applicable review/check results; integrate or report a blocker. | -Roles are responsibilities, not three mandatory agents or services. Separate +Assign the accountable agent to the Issue, not only its first PR. One Issue may +have several delivery PRs; a delegated subagent stays within its slice and +reports to the parent. The parent sends review tasks with accepted criteria, +exact head/base revisions, diff and check evidence, without prescribing the +verdict. If independent review is unavailable, report that gap rather than +relabel self-review. + +Roles are responsibilities, not mandatory separate agents or services. Separate agents may act under one account; an author's role switch is still self-review. A substantive reviewer edit makes that reviewer a contributor requiring appropriate independent review. Review recommendation is not merge permission. @@ -49,18 +57,21 @@ Shared-owner coordination is conditional; unresolved dependencies do not authori ```mermaid flowchart TB - H["Authorized owner"] -->|"Scope and delegation"| I["Issue"] - I --> A["Implementer"] - A --> R["Independent review"] - R -->|"Fixes needed"| A - R -->|"Recommendation"| G["Integrator checks existing authority and evidence"] + H["Authorized owner"] -->|"Scope and delegation"| I["Issue: goal and criteria"] + I --> A["Accountable agent / parent"] + A -->|"Implement or delegate"| W["Bounded PR slice"] + A -->|"Delegate review with criteria and revisions"| R["Independent reviewer"] + W -->|"Diff and evidence"| R + R -->|"Findings and recommendation"| A + A -->|"Resolve findings; refresh affected evidence"| W + A --> G["Integrator checks authority and evidence"] G -->|"Conditions satisfied"| P["Merged PR"] - P --> S["Goal evidence and remaining gaps"] + P --> S["Parent assesses whole Issue and remaining gaps"] S --> O["Acceptance owner or authorized delegate"] O -->|"Goal accepted; closure authorized"| C["Close Issue"] ``` -No human-per-PR gate. Blocked integration or incomplete goals remain open; material scope exceptions return to the authorized owner. +Review reports remain attributable and available to the integrator; the parent cannot substitute its own approval for independent findings. No human-per-PR gate. Blocked integration or incomplete goals remain open; material scope exceptions return to the authorized owner. ### Agent–Agent: isolated work and conditional handoff @@ -83,7 +94,7 @@ sequenceDiagram ## Working rules -1. **Scope:** identify requirements, exclusions, owner and relevant dependencies. Keep each PR a coherent delivery slice; small follow-ups may reuse an Issue. +1. **Scope:** identify requirements, exclusions, owner and relevant dependencies. The accountable agent tracks Issue-level criteria and delegates bounded work; PR readiness and Issue completion are reported separately. Keep each PR a coherent delivery slice; small follow-ups may reuse an Issue. 2. **Isolation:** concurrent writers use separate working directories/indexes and private scratch files. Branch names alone are insufficient. Inspect staged/committed content and coordinate shared IDs, schemas and interfaces. 3. **Evidence:** link checks to actual checked content and relevant environment/test definitions. Distinguish passed, failed, cancelled, skipped, timed-out and not-run. H/B/T—reviewed head, assessed base, tested content—may come from existing records, not mandatory worksheets. 4. **Refresh:** reassess affected evidence after relevant head/base/content/environment/check changes. Refresh checks or explain continued applicability. Neither blanket reuse nor full hardware reruns is the default; changed hashes alone prove neither content change nor equivalence. @@ -92,9 +103,9 @@ sequenceDiagram ## Records -- **Issue:** goal/criteria; scope; accountable account and actor if known; acceptance/delegation link; completion/closure owner. Unknown fields may remain TBD while proposed. Ordinary work starts from the [scoped-task template](../.github/ISSUE_TEMPLATE/scoped-task.md); baseline-vs-candidate campaigns use the [campaign acceptance form](../.github/ISSUE_TEMPLATE/campaign-acceptance.yml). +- **Issue:** goal/criteria; scope; accountable account and parent agent if assigned; acting contributor if known; acceptance/delegation link; completion/closure owner. Unknown fields may remain TBD while proposed. Ordinary work starts from the [scoped-task template](../.github/ISSUE_TEMPLATE/scoped-task.md); baseline-vs-candidate campaigns use the [campaign acceptance form](../.github/ISSUE_TEMPLATE/campaign-acceptance.yml). - **PR:** governing Issue; delivered artifacts; checks/results/limitations; dependencies and gaps. Add requirement-to-artifact mapping only when useful, and handoff fields only when applicable. No author-prefilled independent approval. Start from the [PR template](../.github/PULL_REQUEST_TEMPLATE.md). -- **Commit:** short descriptive subject; why/what and Issue reference when useful. Preserve the required DCO sign-off (`git commit -s`); never invent a signing identity. +- **Commit:** short descriptive subject; why/what and Issue reference when useful. Preserve author identity and the required DCO sign-off (`git commit -s`); never invent a signing identity. Agent-assisted commits identify material agent contributors with `Agent-assisted-by: ()` trailers; repeat for multiple contributors and retain attribution when squashing. A known model/version is optional. The trailer is self-reported provenance, not cryptographic signing, independent review or approval; review attribution belongs on the revision-scoped review record. Labels document coordination intent; they do not grant it. Reuse existing labels where adequate: type (`bug`, `enhancement`, `documentation`, optionally `rfc`), @@ -111,22 +122,28 @@ repository.** Suppose a PR changing `src/omnirsi/harness/runner.py` was reviewed at head `H1` against base `B1`, then is rebased onto `B2` (new head `H2`) because `B2` touched -the same file. Rule 4 asks what changed, not for a blanket rerun: +the same file. Rule 4 asks what changed, not for a blanket rerun, and a +file-only comparison is insufficient on its own: -- Compare the affected files between `H1` and `H2`. If the delta is empty and dependencies are unchanged, the earlier review and CI remain applicable; cite them with their original run and state that reasoning in the PR. -- If the delta is non-empty, refresh the affected checks on `H2` — for example `ruff check src tests` plus the relevant `pytest` selection — and report which content each result ran on. +- Assess affected content, dependencies, environment and check definitions together: the `H1..H2` delta of the affected files, whether `B1..B2` changed anything the checks depend on (imports, fixtures, CI workflow steps, tool versions), and whether the earlier check definitions still test the same contract. +- If that assessment supports reuse, the earlier review and CI **may** remain applicable — say so with an explicit reason, and name in the PR exactly which earlier evidence is reused and why. +- If it does not, refresh the affected checks on `H2` — for example `ruff check src tests` plus the relevant `pytest` selection — and report which content each result ran on. - Either way, distinguish passed, skipped and not-run checks instead of implying a full rerun. A changed hash alone proves neither content change nor equivalence. ## Historical evidence and limits -These conventions are OmniRSI proposals informed by the reviewed C1–C7 case pack -from two pinned snapshots: the +These conventions are OmniRSI proposals informed by the reviewed C1–C7 case pack. +The two pinned snapshots — the [Magpie repository](https://github.com/yetone/magpie/tree/778000326adaa49cd790846acd2d535572ad5ceb) and the separate -[release-workflow repository](https://github.com/yetone/magpie-releases/tree/fc85a074b1ba73417d2afda783e1c0a27ed79a1f). -The per-case summary and limits live in -[RFC #21](https://github.com/InferMatrixLab/OmniRSI/issues/21): C1–C3 inform -ownership and review; C4–C5, CI trade-offs; C6, completion states; C7, learning. +[release-workflow repository](https://github.com/yetone/magpie-releases/tree/fc85a074b1ba73417d2afda783e1c0a27ed79a1f) +— identify lineage; they are not themselves a link to the case pack. The +accessible extraction with exact case readsets (original commit, PR and run +links, per-case limits) is the "Reviewed case pointers" section of +[RFC #21](https://github.com/InferMatrixLab/OmniRSI/issues/21); the full +reviewed pack with its detailed readset remains with its owner and is not +imported here. C1–C3 inform ownership and review; C4–C5, CI trade-offs; C6, +completion states; C7, learning. They are proposals, not demonstrated Magpie enforcement or a causal speedup. Described practice, inspected implementation, observed records and proposed From 5e9cdbbf009a21d0eb63d227be476c5710efb989 Mon Sep 17 00:00:00 2001 From: GUOGUO Date: Fri, 16 Oct 2026 18:31:11 +0800 Subject: [PATCH 3/4] docs(collaboration): keep issue references in PR bodies and require squash merge Governing Issue references now live in the PR body only, out of commit subjects, bodies, trailers and the final squash message. Document squash merge as the required integration method with a concise message that preserves DCO sign-off and material Agent-assisted-by attribution. Describe the C1-C7 material as an accessible case summary with concrete source pointers and stated limits, not exact case readsets. Agent-assisted-by: Claude Code (implementer) Signed-off-by: GUOGUO --- .github/PULL_REQUEST_TEMPLATE.md | 4 +++- docs/agent-collaboration.md | 15 ++++++++------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 864c8101..160e233d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -37,7 +37,9 @@ explanation only when a material integration identity question remains. --> +commits add `Agent-assisted-by: ()` trailers. Keep +governing Issue references in this PR body, out of commit subjects, bodies, +trailers and the final squash message; integration is a squash merge. --> ## Handoff (only when an actual handoff or decision changed) diff --git a/docs/agent-collaboration.md b/docs/agent-collaboration.md index a714691d..0cc9af7e 100644 --- a/docs/agent-collaboration.md +++ b/docs/agent-collaboration.md @@ -105,7 +105,8 @@ sequenceDiagram - **Issue:** goal/criteria; scope; accountable account and parent agent if assigned; acting contributor if known; acceptance/delegation link; completion/closure owner. Unknown fields may remain TBD while proposed. Ordinary work starts from the [scoped-task template](../.github/ISSUE_TEMPLATE/scoped-task.md); baseline-vs-candidate campaigns use the [campaign acceptance form](../.github/ISSUE_TEMPLATE/campaign-acceptance.yml). - **PR:** governing Issue; delivered artifacts; checks/results/limitations; dependencies and gaps. Add requirement-to-artifact mapping only when useful, and handoff fields only when applicable. No author-prefilled independent approval. Start from the [PR template](../.github/PULL_REQUEST_TEMPLATE.md). -- **Commit:** short descriptive subject; why/what and Issue reference when useful. Preserve author identity and the required DCO sign-off (`git commit -s`); never invent a signing identity. Agent-assisted commits identify material agent contributors with `Agent-assisted-by: ()` trailers; repeat for multiple contributors and retain attribution when squashing. A known model/version is optional. The trailer is self-reported provenance, not cryptographic signing, independent review or approval; review attribution belongs on the revision-scoped review record. +- **Commit:** short descriptive subject; why/what when useful. Keep governing Issue references out of commit subjects, bodies and trailers — the PR body carries them. Preserve author identity and the required DCO sign-off (`git commit -s`); never invent a signing identity. Agent-assisted commits identify material agent contributors with `Agent-assisted-by: ()` trailers; repeat for multiple contributors and retain attribution when squashing. A known model/version is optional. The trailer is self-reported provenance, not cryptographic signing, independent review or approval; review attribution belongs on the revision-scoped review record. +- **Squash merge:** the required integration method. Before an authorized merge, prepare a concise squash message: subject plus a short summary, no governing Issue references, no redundant intermediate-commit messages; preserve the required DCO sign-off and material `Agent-assisted-by` attribution. Never invent identities or sign-offs. Labels document coordination intent; they do not grant it. Reuse existing labels where adequate: type (`bug`, `enhancement`, `documentation`, optionally `rfc`), @@ -137,12 +138,12 @@ The two pinned snapshots — the [Magpie repository](https://github.com/yetone/magpie/tree/778000326adaa49cd790846acd2d535572ad5ceb) and the separate [release-workflow repository](https://github.com/yetone/magpie-releases/tree/fc85a074b1ba73417d2afda783e1c0a27ed79a1f) -— identify lineage; they are not themselves a link to the case pack. The -accessible extraction with exact case readsets (original commit, PR and run -links, per-case limits) is the "Reviewed case pointers" section of -[RFC #21](https://github.com/InferMatrixLab/OmniRSI/issues/21); the full -reviewed pack with its detailed readset remains with its owner and is not -imported here. C1–C3 inform ownership and review; C4–C5, CI trade-offs; C6, +— identify lineage; they are not themselves a link to the case pack. An +accessible case summary with concrete source pointers and stated limits — the +"Reviewed case pointers" section of +[RFC #21](https://github.com/InferMatrixLab/OmniRSI/issues/21) — covers C1–C7 +at the level this guide relies on; the full reviewed pack remains with its +owner and is not imported here. C1–C3 inform ownership and review; C4–C5, CI trade-offs; C6, completion states; C7, learning. They are proposals, not demonstrated Magpie enforcement or a causal speedup. From 6013965dae38f938d76af28cebffe986b7d40c49 Mon Sep 17 00:00:00 2001 From: GUOGUO Date: Fri, 16 Oct 2026 18:53:48 +0800 Subject: [PATCH 4/4] docs(collaboration): align stated Magpie limits with the RFC text The evidence-limits sentence cited "the absence of a demonstrated simultaneous deployment", which the RFC does not state. Replace it with a limit the RFC actually records: the unestablished final tested/merged equivalence. Agent-assisted-by: Claude Code (implementer) Signed-off-by: GUOGUO --- docs/agent-collaboration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/agent-collaboration.md b/docs/agent-collaboration.md index 0cc9af7e..9acfaafe 100644 --- a/docs/agent-collaboration.md +++ b/docs/agent-collaboration.md @@ -149,5 +149,5 @@ completion states; C7, learning. They are proposals, not demonstrated Magpie enforcement or a causal speedup. Described practice, inspected implementation, observed records and proposed adaptations remain distinct evidence classes; see #21 for the per-case limits, -including the unresolved C1 root cause and the absence of a demonstrated -simultaneous deployment. +including the unresolved C1 root cause and the unestablished final +tested/merged equivalence.