dev-loops 0.1.0

package/skills/docs/epic-tree-refinement-procedure.md

@@ -0,0 +1,234 @@
+# Epic tree refinement procedure
+
+This document is the canonical procedure for depth-first, top-down-then-bottom-up refinement of
+an existing GitHub sub-issue tree (parent → children → grandchildren).
+
+Use it together with:
+- [Issue Intake Procedure](./issue-intake-procedure.md) — Phase 3b calls this procedure for epic decomposition
+- [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md) — authoritative sub-issue tooling (source-repo reference)
+
+When you have a tree of GitHub issues that already exists and you need to align AC, DoD, scope
+boundaries, and delegation contracts across all levels, follow this procedure. It is deterministic
+enough that a fresh agent can run it without prior context about the tree.
+
+---
+
+## Definitions
+
+| Term | Meaning |
+|---|---|
+| **Root** | The umbrella/epic issue at the top of the tree |
+| **Parent** | Any issue that has at least one sub-issue child |
+| **Child** | A direct sub-issue of a parent |
+| **Leaf** | An issue with no sub-issue children |
+| **Phase table** | A section of the root/parent body that names each child and what it owns vs excludes |
+| **Scope boundary** | Explicit text in an issue body: `"This issue owns X. It does NOT own Y (#NNN)."` |
+| **AC/DoD matrix** | A two-column table mapping each acceptance criterion to its corresponding DoD checklist item(s) |
+
+---
+
+## Prerequisites
+
+Before starting, verify:
+
+1. The root issue and all intended children/grandchildren exist as GitHub issues in the repo.
+2. The sub-issue tree is attached (run `node <resolved-skill-scripts>/github/manage-sub-issues.mjs list --repo <repo> --issue <root>` to inspect it).
+3. You have the resolved repo slug (`owner/name`).
+
+Optional but recommended before and after edits:
+
+```sh
+dev-loops refine verify --issue <root> --repo <repo>
+```
+
+This verification command checks linkage policy, sibling scope boundaries, refinement completeness,
+and tree integrity in one deterministic pass.
+
+If the sub-issue tree does not yet exist, use [Issue Intake Procedure](./issue-intake-procedure.md) Phase 3b to decompose and attach it first.
+
+---
+
+## Phases
+
+### Phase A — Root refinement (serial)
+
+Refine the root issue **first** before touching any child.
+
+For the root issue:
+1. Read the current body: `gh issue view <root> --repo <repo> --json number,title,body`
+2. Confirm the problem statement is clear and scoped
+3. Confirm a **phase scope table** exists — one row per immediate child naming what each child
+   owns and what it excludes; add or update this table if missing
+4. Confirm **AC checklist** covers the end-to-end goal (not the implementation details owned by children)
+5. Confirm **DoD checklist** — merge-ready condition for the root issue as a whole
+6. Confirm **AC/DoD matrix** — each AC maps to at least one DoD item
+7. Confirm **non-goals** section — prevents scope creep into adjacent areas
+8. Write the updated body to a tmp file: `tmp/issues/<root>/refinement/root-body.md`
+9. Show the diff and obtain confirmation before mutating GitHub
+10. Apply: `gh issue edit <root> --repo <repo> --body-file tmp/issues/<root>/refinement/root-body.md`
+
+**Gate:** Phase B must not start until Phase A is complete and the root body is updated on GitHub.
+
+---
+
+### Phase B — Descend: refine children against parent (parallel fan-out per level)
+
+For **each level** of the tree (breadth-first traversal of levels, depth-first traversal within
+a single branch), refine all siblings in parallel — siblings are independent and only need the
+parent's updated body, not each other's output.
+
+**For each issue at this level:**
+
+1. Read the parent's updated body: `gh issue view <parent> --repo <repo> --json number,title,body`
+2. Read the current child body: `gh issue view <child> --repo <repo> --json number,title,body`
+3. Verify the child's scope matches what the parent's phase table delegates to it
+4. Identify any overlap with sibling issues (read sibling titles/bodies if needed)
+5. Refine the child body with:
+   - **Scope boundary** (explicit): `"This issue owns X. It does NOT own Y (#NNN) or Z (#MMM)."`
+   - **AC checklist** specific to this child's bounded scope
+   - **DoD checklist** — when is this child independently closable?
+   - **AC/DoD matrix**
+   - **Non-goals** — what this child intentionally excludes
+6. Write refined body to `tmp/issues/<child>/refinement/child-body.md`
+7. Show the diff and obtain confirmation before mutating (unless running unattended with explicit authorization)
+8. Apply: `gh issue edit <child> --repo <repo> --body-file tmp/issues/<child>/refinement/child-body.md`
+
+**Parallelism rule:** All siblings at the same level can be refined concurrently. No child needs
+another child's output; each child only reads the parent's contract and its own current body.
+
+**Serial gate between levels:** All children at level N must complete before descending to level N+1.
+
+Repeat Phase B until all leaves are refined.
+
+---
+
+### Phase C — Ascend: reconcile parents with children (parallel fan-out per level)
+
+After all children under a given parent are refined, reconcile that parent. Work bottom-up.
+
+All parents at the same depth can be reconciled in parallel (they only need their own children's
+updated bodies, not sibling parents).
+
+**For each parent (bottom-up):**
+
+1. Re-read the parent body: `gh issue view <parent> --repo <repo> --json number,title,body`
+2. Re-read all direct children bodies
+3. Verify:
+   - The parent's phase scope table still matches what the children now claim to own
+   - No orphaned responsibilities (parent promised something no child owns)
+   - No duplicate ownership (two children claiming the same thing)
+4. Update the parent's phase scope table and AC/DoD as needed to reflect what children now explicitly own
+5. Write refined body to `tmp/issues/<parent>/refinement/parent-reconciled-body.md`
+6. Show the diff and obtain confirmation before mutating
+7. Apply: `gh issue edit <parent> --repo <repo> --body-file tmp/issues/<parent>/refinement/parent-reconciled-body.md`
+
+**Serial gate between levels:** All parents at depth N must complete reconciliation before ascending to depth N-1.
+
+---
+
+### Phase D — Root final reconcile (serial)
+
+After all immediate children of the root have been reconciled:
+
+1. Re-read the root body: `gh issue view <root> --repo <repo> --json number,title,body`
+2. Re-read all immediate children bodies
+3. Verify:
+   - Phase scope table matches actual child scope
+   - Dependency chain is correct (does execution order in the sub-issue tree match dependencies?)
+   - No orphaned responsibilities; no duplicate ownership
+4. Update the root body with the final reconciled phase scope table and AC/DoD
+5. Write to `tmp/issues/<root>/refinement/root-final-body.md`
+6. Show the diff and obtain confirmation before mutating
+7. Apply: `gh issue edit <root> --repo <repo> --body-file tmp/issues/<root>/refinement/root-final-body.md`
+8. Verify the sub-issue tree still reflects the correct execution order:
+   ```sh
+   node <resolved-skill-scripts>/github/manage-sub-issues.mjs verify \
+     --repo <repo> --issue <root> --expected <n1,n2,...> --ordered
+   ```
+
+**Gate:** Root final reconcile completes the procedure. All issues in the tree must now have:
+- AC checklist, DoD checklist, AC/DoD matrix, non-goals, explicit scope boundary
+
+---
+
+## Rules
+
+- **No implementation, no PRs, no Copilot assignment** — this procedure is refinement-only
+- **Use `gh issue edit`** to apply changes directly — do not create new issues or PRs
+- **No prose parent/child links in bodies** — GitHub sub-issues API handles hierarchy
+- **Each issue must have:** AC checklist, DoD checklist, non-goals, AC/DoD matrix, scope boundary
+- **Scope boundary format:** `"This issue owns X. It does NOT own Y (#NNN) or Z (#MMM)."`
+- **Show the diff** and get confirmation before each `gh issue edit` mutation (unless unattended with explicit authorization)
+- **Write tmp artifacts** under `tmp/issues/<number>/refinement/` before applying
+- **Do not duplicate** the child list in parent bodies — the sub-issue tree API owns hierarchy
+
+---
+
+## Parallelism model
+
+Sibling refinements are independent: siblings only need the parent's contract, not each other's
+output. The wall-clock complexity is O(depth), not O(nodes).
+
+```text
+Phase A:  [root]                            serial (1 step)
+Phase B:  [child1 || child2 || child3]      parallel per level (1 step per level)
+          [gc1a || gc1b || gc2a || gc3a]    parallel per level (1 step per level)
+Phase C:  [child1 || child2 || child3]      parallel per level (1 step per level)
+Phase D:  [root]                            serial (1 step)
+```
+
+Total serial steps for a tree with depth D: `1 + (D-1) + (D-1) + 1 = 2D`
+
+**Fan-out rule:** At any level, when a parent is refined, ALL its children can be refined in parallel.
+
+**Serial gates:**
+- Root refinement must complete before any child starts
+- A parent's reconciliation must wait for ALL its children to finish
+- Root reconciliation must wait for all immediate children to reconcile
+
+---
+
+## Completion criteria
+
+The procedure is complete when all issues in the tree satisfy:
+
+| Check | How to verify |
+|---|---|
+| AC checklist present | Issue body contains `## Acceptance Criteria` with at least one `- [ ]` item |
+| DoD checklist present | Issue body contains `## Definition of Done` with at least one `- [ ]` item |
+| AC/DoD matrix present | Issue body contains a two-column table mapping AC items to DoD items |
+| Non-goals present | Issue body contains `## Non-goals` section |
+| Scope boundary present | Issue body contains explicit `"This issue owns ... It does NOT own ..."` text |
+| No orphaned responsibilities | Each thing the parent delegates maps to exactly one child |
+| No duplicate ownership | No two siblings claim the same responsibility |
+| Sub-issue tree order valid | `manage-sub-issues.mjs verify --ordered` exits 0 |
+
+---
+
+## Example traversal for a 3-level tree
+
+For root #715 with children #716, #717, #718 and grandchildren #720–#729:
+
+```
+Phase A: #715 refine
+Phase B level 2 (parallel): #716 refine  ‖  #717 refine  ‖  #718 refine
+Phase B level 3 (parallel): #720 ‖ #721 ‖ #722  (under #716)
+                             #723 ‖ #724         (under #717)
+                             #726 ‖ #729 ‖ #727 ‖ #728  (under #718)
+Phase C level 2 (parallel): #716 reconcile  ‖  #717 reconcile  ‖  #718 reconcile
+Phase D: #715 root reconcile
+```
+
+Wall-clock serial steps: 5 (not 17).
+
+---
+
+## Relationship to other procedures
+
+| Procedure | When to use it |
+|---|---|
+| [Issue Intake Procedure](./issue-intake-procedure.md) Phase 3b | *Creating* a new sub-issue tree from an umbrella issue |
+| **This procedure** | *Refining* an existing sub-issue tree to align scope, AC, DoD, and delegation contracts |
+| [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md) | Tooling for listing, attaching, ordering, and verifying sub-issue trees |
+
+These are complementary. Phase 3b creates the structure; this procedure aligns the contracts.

package/skills/docs/issue-intake-procedure.md

@@ -0,0 +1,235 @@
+# Issue intake procedure
+
+This document is the canonical owner of the routed `issue_intake` procedure behind the public `dev-loop` façade.
+
+Use it together with:
+- [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md)
+- [Public Dev Loop Contract](./public-dev-loop-contract.md)
+- [Retrospective Checkpoint Contract](./retrospective-checkpoint-contract.md) when the current step depends on async start/resume/status or retrospective enforcement
+
+When routed work is issue-first rather than already in active PR follow-up, use the procedure below before entering the shared post-PR loop. Treat this document as the issue-refinement specialist procedure for the routed `issue_intake` seam.
+
+## New-idea safety layer (default contract in this repo)
+
+For **all new ideas** that are not already anchored to an existing issue (including abstract ideas such as plain-language requests without an issue number or plan-doc path), apply this procedure-owned intake contract before any GitHub mutation:
+
+- procedure owns classification; human operator gates all mutations
+- run classification in fresh context by default
+- run classification asynchronously when practical
+- run async fan-out / fan-in proposal generation by default when practical
+- emit a proposal artifact before any GitHub state-changing mutation, including create/edit/retitle/collapse/link operations
+- default to create-new over overwrite/update when a new tracked artifact is justified
+- do not repurpose/retitle/collapse/overwrite an existing issue unless that exact mutation is explicitly proposed and explicitly approved
+- after approval, run a second async mutation pass (dispatched via the procedure) instead of mutating directly from inherited context
+- verify post-mutation artifact state and record what actually changed
+
+Deterministic intake + mutation-gate state machine:
+
+```text
+idea_received
+  -> fresh_context_started
+  -> fanout_started
+  -> fanin_complete
+  -> artifact_scan_complete
+  -> classified
+  -> proposal_emitted
+  -> awaiting_user_approval
+  -> ready_for_mutation
+  -> mutation_executed
+  -> mutation_verified
+  -> done
+
+stop states:
+- stopped_overlap_needs_decision
+- stopped_low_confidence
+- stopped_explicit_reject
+```
+
+Proposal artifact contract:
+- human-readable Markdown proposal
+- machine-readable JSON snapshot
+- write temporary artifacts under `Proposal` (`tmp/new-idea-intake/<run-id>/proposal.md`) and `tmp/new-idea-intake/<run-id>/proposal.json`
+
+If the Phase 1 preflight verdict is `pause_for_clarification`, stop and ask.
+If the intake state machine stops at `stopped_overlap_needs_decision` or `stopped_low_confidence`, stop and ask.
+If the intake state machine stops at `stopped_explicit_reject`, stop and record that the proposal was rejected; do not mutate GitHub.
+After approval, start a separate async mutation pass (dispatched via the procedure) that consumes the approved proposal and emits a post-mutation verification artifact. Emit a concise post-mutation verification artifact and record what the mutation pass actually changed and verify the resulting issue/artifact state.
+
+## Unattended issue-first execution and automatic re-entry
+
+When the user explicitly authorizes unattended execution for a specific issue/PR scope, continue through the normal loop mutations for that scope without stopping at every intermediate phase boundary.
+
+Under that unattended execution contract:
+- automatically detect the current lifecycle entrypoint from existing GitHub state
+- use the deterministic helper/state-machine surface as the authority for current-state routing and next-step selection
+- if local facts, GitHub facts, and helper/state-machine output do not agree, or the state is materially unclear, contradictory, off-trail, or not cleanly covered, stop and ask for human direction rather than guessing
+- a pre-existing PR is not a stop-by-default condition
+- If a PR already exists, classify the post-assignment seam before follow-up
+- `waiting_for_initial_copilot_implementation`: keep waiting
+- `linked_pr_ready_for_followup`: route to the existing PR follow-up path immediately; resume from that PR
+- when routing leaves bootstrap wait for `linked_pr_ready_for_followup`, do not stop only because local isolation is required; re-enter the same PR follow-up from a safe isolated checkout/worktree
+- When the draft PR appears, classify whether it is still the bootstrap-only Copilot draft before entering normal follow-up
+- if a child async run exits while the deterministic state is still non-terminal (for example `waiting_for_copilot_review`), automatically resume/restart follow-up when continuation is feasible instead of requiring manual operator restart
+- continue unattended until the human approval checkpoint unless a genuine stop condition is reached
+- stop for a human approval decision by default
+- after approval, report `waiting_for_merge_authorization` and stop again unless merge has been explicitly authorized
+- this does **not** imply unattended merge by default
+
+Issue-first shorthand such as `auto dev loop on issue <n>` should preserve this same stop boundary and human approval checkpoint default.
+
+## Phase 1 — Preflight intake
+
+Before any automation, answer these questions:
+1. smallest executable work item
+2. existing issue check
+3. scope clarity
+4. acceptance criteria
+5. verification path
+6. active PR check
+
+Accepted input types:
+- GitHub issue number or URL
+- plan-doc path
+- abstract roadmap idea
+
+Preflight verdicts:
+- `proceed`
+- `proceed_with_assumptions`
+- `pause_for_clarification`
+
+## Phase 2 — Input normalization
+
+### From a GitHub issue number or URL
+
+- if the input is a full GitHub issue URL, parse `<owner/name>` and `<number>`
+- fetch with `gh issue view <number> --repo <owner/name> --json number,title,body,state,labels,assignees,milestone`
+- If the issue is closed, stop for a user decision before proceeding
+- detect an existing linked PR with the deterministic linked-PR helper:
+  `node <resolved-skill-scripts>/github/detect-linked-issue-pr.mjs --repo <resolved-repo> --issue <number>`
+- treat the helper output as authoritative for linked-PR detection/selection
+- do not re-implement linked-event query behavior, pagination, repo filtering, or tie-break logic
+- do not rely only on PR title/body containing a literal issue number
+- treat an open linked PR as the active implementation for this issue
+- once an open linked PR exists, that PR is the only canonical follow-up artifact for the issue; attach follow-up work to it and do not open another PR unless the prior PR was explicitly superseded and reconciled first
+- if a PR already exists, classify bootstrap-wait versus follow-up:
+  `node <resolved-skill-scripts>/loop/detect-initial-copilot-pr-state.mjs --repo <resolved-repo> --issue <number>`
+- `waiting_for_initial_copilot_implementation`: keep waiting; in durable-auto mode use:
+  ```sh
+  node <resolved-skill-scripts>/loop/watch-initial-copilot-pr.mjs --repo <resolved-repo> --issue <number>
+  ```
+  - must use the dedicated `watch-initial-copilot-pr.mjs` watcher and its default 1-hour watch budget
+  - quiet/no-activity watch observations alone are non-terminal
+  - `ready_for_followup`: linked PR has become substantive; resume from that PR
+  - `timed_out`: observational first; refresh authoritative state
+  - if refreshed state is still `waiting_for_initial_copilot_implementation`, remain attached to the same durable wait seam and continue waiting
+  - if the refreshed state exits this seam, route based on that refreshed state instead of surfacing timeout attention
+  - when the refreshed state is `linked_pr_ready_for_followup`, re-enter normal PR follow-up; if the follow-up handoff carries `conductorRouting.handoffEnvelope.requiresLocalIsolation=true`, perform the expected isolated-checkout/worktree handoff and continue
+  - only surface timeout attention when the seam's durable watch budget is actually exhausted
+  - for explicit inspect/status requests, report the still-waiting state and exit normally
+- carry that resolved repo slug through every later GitHub issue/PR command
+
+### From a plan-doc path
+
+- Resolve the target repository slug for this work item before any GitHub search or mutation
+- default to the current repository slug
+- if the plan-doc reference explicitly points at another GitHub repository, resolve `<resolved-repo>` first
+- search existing issues with:
+  ```sh
+  gh issue list --repo <resolved-repo> --state all --search "<title keywords>"
+  ```
+- If a matching issue exists:
+  - if the matching issue is closed, stop for a user decision before proceeding
+  - if that matching issue turns out to be closed, stop for a user decision
+  - if a PR already exists, classify bootstrap-wait versus follow-up
+- if a governing plan doc or roadmap section actually applies, follow the plan-doc normalization path above
+
+### From an abstract idea
+
+- otherwise search existing issues directly
+- if a matching issue exists, follow the issue-number/URL normalization path
+- resolve `<resolved-repo>` for this work item using the same rule as the plan-doc path
+
+## Phase 3 — Async issue refinement
+
+Before updating or assigning the issue, refine it asynchronously when practical. Keep issue refinement separate from the phase-scoped refiner used by the local implementation workflow. Use the `refiner` agent for this review-only issue-refinement chain, including the consolidation/fan-in step; do not route those comparison/synthesis steps through `dev-loop` + `local_implementation` (the strategy loaded by `skills/local-implementation`).
+
+When issue refinement would benefit from structural/slop discovery and the likely code/doc surface is knowable, run the bounded audit first.
+- write the issue-refinement audit artifact to `tmp/issues/issue-<number>/audit/refinement-audit-summary.json`
+- use the same audit artifact shape as local phase refinement
+- keep the audit bounded to the named files/areas for this issue; do not widen into a full-repo scan
+- pass a concise audit summary into refiner fan-out and fan-in
+- require the issue-refinement write-up to translate audit findings into scope, AC/DoD, risks, and explicit non-goals without silently broadening the issue
+
+## Phase 3b — Epic decomposition with GitHub sub-issue trees
+
+When the work item is an umbrella/epic issue that must be decomposed into bounded child slices,
+use **real GitHub sub-issue trees** as the default durable output — not body checklists, not
+a manual follow-up linking step.
+
+Prefer real sub-issue linkage over parent-body checklists when a work tree is intended.
+A parent issue body should stay lean once the tree exists: keep scope, acceptance criteria, and
+non-goals there, but do **not** duplicate the ordered child list in the body.
+
+Full decomposition flow:
+
+1. refine umbrella issue framing (scope, acceptance criteria, non-goals)
+2. define bounded child slices — each slice must be independently closable
+3. create child issues with `gh issue create --repo <resolved-repo> --assignee @me`
+4. attach each child as a real sub-issue:
+   ```sh
+   node <resolved-skill-scripts>/github/manage-sub-issues.mjs add \
+     --repo <resolved-repo> --issue <parent-number> --child <child-number>
+   ```
+5. set execution order (highest priority first):
+   ```sh
+   node <resolved-skill-scripts>/github/manage-sub-issues.mjs reorder \
+     --repo <resolved-repo> --issue <parent-number> --order <n1,n2,...>
+   ```
+6. verify the resulting tree:
+   ```sh
+   node <resolved-skill-scripts>/github/manage-sub-issues.mjs verify \
+     --repo <resolved-repo> --issue <parent-number> --expected <n1,n2,...> [--ordered]
+   ```
+7. keep the parent issue body lean — sequencing and progress now live in the sub-issue tree
+
+To inspect the current tree at any time:
+```sh
+node <resolved-skill-scripts>/github/manage-sub-issues.mjs list \
+  --repo <resolved-repo> --issue <parent-number>
+```
+
+Do **not** re-implement sub-issue management ad hoc or bypass `manage-sub-issues.mjs`.
+Do **not** maintain a body checklist that duplicates the sub-issue tree.
+
+For the full `manage-sub-issues.mjs` contract, use [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md) when working in the `dev-loops` source repository. That contract is a source-repo reference, not part of the bundled installed skill-doc surface. For installed or normalized skill copies, inspect the target repository docs/source directly instead of assuming a bundled shared-doc copy exists.
+
+When an existing sub-issue tree needs **scope alignment, AC/DoD contracts, and delegation boundary refinement** across all levels (parent → children → grandchildren), use the [Epic Tree Refinement Procedure](./epic-tree-refinement-procedure.md) — it owns the deterministic depth-first, top-down-then-bottom-up refinement protocol.
+
+## Phase 4 — Copilot handoff and bootstrap wait
+
+Before updating the GitHub issue body, show the diff and get explicit confirmation. Then use:
+```sh
+gh issue edit <number> --repo <resolved-repo> --body-file <updated-body-file>
+gh issue edit <number> --repo <resolved-repo> --add-assignee copilot-swe-agent
+```
+Verify assignment with:
+```sh
+gh issue view <number> --repo <resolved-repo> --json assignees
+```
+
+When the linked PR becomes substantive, keep the shared loop scoped to the resolved repo, for example:
+```sh
+node <resolved-skill-scripts>/loop/copilot-pr-handoff.mjs --repo <resolved-repo> --pr <number>
+gh pr edit <pr-number> --repo <resolved-repo> --title "..." --body-file <body-file>
+gh pr ready <pr-number> --repo <resolved-repo>
+gh pr review <pr-number> --repo <resolved-repo> --approve --body "..."
+node <resolved-skill-scripts>/github/detect-checkpoint-evidence.mjs --repo <resolved-repo> --pr <pr-number>
+gh pr merge <pr-number> --repo <resolved-repo> --squash --delete-branch
+```
+
+Bootstrap-wait interpretation remains fail-closed and observational-first:
+- `ready_for_followup`: linked PR has become substantive; resume from that PR
+- `timed_out`: observational first; refresh authoritative state
+- if refreshed state is still `waiting_for_initial_copilot_implementation`, remain attached to the same durable wait seam and continue waiting
+- if refreshed state exits that seam, route based on refreshed state instead of surfacing timeout attention
+

package/skills/docs/main-agent-contract.md

@@ -0,0 +1,72 @@
+# Main-agent delegation contract
+
+> **Absolute read-only boundary.** The main agent must never mutate files tracked by the repository.
+> All mutations flow through the `dev-loop` async subagent.
+
+## Contract
+
+The main agent is **read-only** for every file tracked by the repository. Every
+write, edit, delete, commit, branch, push, and PR lifecycle operation must flow
+through the `dev-loop` async subagent.
+
+This contract is a hard rule, not a default or guideline. The main agent must
+never rationalize a direct mutation — not because the work is small, not
+because "the user said yes," not because it is running from a worktree.
+
+## Main agent owns (allowed)
+
+- Read, inspect, search any repo file
+- `git worktree list`, `git status`, `git log` (read-only git). `git fetch` is also allowed (updates local refs but does not touch tracked working-tree files).
+- `gh issue view / create / edit / comment / close` (GitHub API, not file mutations)
+- `gh pr view / list` (read-only GitHub API)
+- Write to `/tmp` or other non-repo paths (e.g., issue body drafts)
+- Delegate to the `dev-loop` agent (async, with worktree cwd)
+- Report findings, ask questions, get confirmation
+- `npm test`, `npm run verify` (read-only validation)
+
+## Main agent must NEVER
+
+- `write`, `edit`, or delete any file tracked by the repo
+- `git commit`, `git push`, create branches, create worktrees
+- Run state-changing dev-loops CLI subcommands (`gate`, any state-changing `loop` subcommand, `pr` commands — those belong inside `dev-loop`).
+- Delegate implementation to any agent other than `dev-loop`
+
+## Dev-loop agent (async) owns
+
+- ALL file mutations in the repo (write, edit, delete)
+- ALL git operations (branch, commit, push)
+- ALL PR lifecycle (create, draft, review, merge)
+- Sub-delegation to developer, fixer, review, quality agents
+
+## Boundary examples
+
+| Operation | Verdict |
+|---|---|
+| `gh issue create --title "..." --body "..."` | Allowed — mutates GitHub, not files tracked by the repository |
+| Write to `/tmp/issue-body.md` | Allowed — outside the repo |
+| Write to `packages/core/src/foo.mjs` | **BREACH** — must delegate to `dev-loop` |
+| `git status` | Allowed — read-only |
+| `git commit -m "..."` | **BREACH** — must delegate to `dev-loop` |
+| `subagent dev-loop` | Allowed — correct delegation |
+| `subagent fixer` | Allowed only when called from within `dev-loop`; describe the task as part of the message |
+
+## Dev-loop startup
+
+When a user triggers the dev loop, the main agent must immediately dispatch the
+`dev-loop` async subagent. The subagent owns the startup resolver, route selection,
+and all subsequent implementation steps. The main agent never runs `dev-loops loop startup`
+directly.
+
+## Enforcement posture
+
+- This contract is enforced by convention and review, not by tool-level guards.
+- Mechanical enforcement (pre-commit hooks, tool-level write guards) is a
+  non-goal for this document and may be addressed in follow-up work.
+- A `dev-loop` async subagent should reject delegation attempts that bypass
+  the contract (e.g., direct mutation requests from the main agent).
+
+## Non-goals
+
+- Tool-level enforcement (file-write guards, pre-commit hooks)
+- Changing dev-loop resolver behavior
+- Modifying the subagent API itself

package/skills/docs/merge-preconditions.md

@@ -0,0 +1,29 @@
+# Merge preconditions
+
+Canonical owner for merge preconditions across all workflow families.
+
+## Required before merge
+
+1. ✅ CI green on current head (or crediblyGreen via `--local-validation-head-sha`)
+2. ✅ Draft gate satisfied (clean verdict)
+3. ✅ Pre-approval gate satisfied (clean verdict, current head)
+4. ✅ All review threads resolved
+5. ✅ Explicit merge authorization from operator
+6. ✅ PR body contains `Closes #N` or `Fixes #N`
+
+## Merge authorization
+
+- Must be explicit for the active issue/PR scope
+- `"Merge authorized if gates green"` is valid explicit authorization
+- Implied approval from prior turns is not sufficient
+
+## Post-merge
+
+- Remove merged worktree: `git worktree remove --force <path> && git worktree prune`
+- Clean up stale branches
+
+## Cross-references
+
+- [Confirmation rules](confirmation-rules.md)
+- [Validation policy](validation-policy.md)
+- [Stop conditions](stop-conditions.md)