Document Lab branch identity contract#6
Conversation
|
Reviewed docs-only branch identity contract. No blockers from my pass: the policy cleanly distinguishes canonical Work Item identity from branch naming hygiene, preserves the contamination guard via scope cleanliness / |
There was a problem hiding this comment.
Pull request overview
Adds a control-plane documentation contract clarifying that Lab Work Item identity is canonical and Git branch names are execution artifacts, with guidance on when branch-name mismatches are acceptable and when rebranching is justified.
Changes:
- Introduces a “Lab Branch Identity Contract” doc defining canonical identity vs. execution branch naming.
- Documents branch policy, rebranching criteria (contamination/unsafe base), and PR conventions for noncanonical branches.
- Clarifies interpretation of the dispatch packet
branchfield and Work ItemBranchproperty (though this section currently diverges from observed implementation behavior).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| If the Work Item `Branch` property is empty, execution agents may default to `main` for read-only/audit work or create a preferred branch for new code work. | ||
|
|
There was a problem hiding this comment.
Addressed in f322995 by clarifying the branch-name casing rule, using the canonical Kill/Stop Condition property name, and aligning empty Branch behavior with dispatch branch=main for non-sandbox items.
| 2. The branch is pushed or otherwise inspectable. | ||
| 3. The Work Item records the actual branch name in `Branch`. | ||
| 4. The issue or PR title/body references the Work Item handle. | ||
| 5. The branch passes the Work Item objective, stop condition, metrics, and acceptance checks. |
There was a problem hiding this comment.
Addressed in f322995 by clarifying the branch-name casing rule, using the canonical Kill/Stop Condition property name, and aligning empty Branch behavior with dispatch branch=main for non-sandbox items.
| Preferred branch names should include the Work Item handle: | ||
|
|
||
| ```text | ||
| work/sra-imp-1 | ||
| ``` | ||
|
|
||
| or: | ||
|
|
||
| ```text | ||
| sra-imp-1 | ||
| ``` |
There was a problem hiding this comment.
Addressed in f322995 by clarifying the branch-name casing rule, using the canonical Kill/Stop Condition property name, and aligning empty Branch behavior with dispatch branch=main for non-sandbox items.
|
Addressed Copilot review comments in f322995: empty |
Summary
Adds a Lab branch identity contract documenting that Work Item identity is canonical and branch names are execution artifacts.
Policy
Why
This prevents agents from rebranching useful work solely for naming hygiene, while preserving the existing contamination guard based on
git log main..HEAD --oneline.Repos in scope
This PR covers the control-plane contract in
notion-forge. A companionagent-envPR adds the agent-facing reference.