dev-loops 0.1.0

package/skills/docs/stop-conditions.md

@@ -0,0 +1,29 @@
+# Stop conditions
+
+Canonical owner for agent stop / wait / block conditions across all workflow families.
+
+## Genuine stop conditions
+
+| Condition | Strategy | Behavior |
+|---|---|---|
+| `blocked` lifecycle state | all | Stop for human decision |
+| `done` lifecycle state | all | Terminal stop |
+| `approval_ready` without explicit merge auth | `final_approval` | Stop at approval gate |
+| `merge_ready` without explicit merge auth | all | Stop at `waiting_for_merge_authorization` |
+| Ambiguous / contradictory state | all | Fail closed to `needs_reconcile` |
+| Missing authoritative startup inputs | `dev-loop` | Fail closed |
+
+## Non-stop conditions
+
+| Condition | Strategy | Behavior |
+|---|---|---|
+| `waiting` lifecycle state | `wait_watch` | Healthy wait; re-dispatch from main session |
+| `waiting_for_initial_copilot_implementation` | `issue_intake` | Bootstrap wait with 1h watch budget |
+| `waiting_for_copilot_review` | `copilot_pr_followup` | Continuation boundary, not completion |
+| Quiet watcher observations | `wait_watch` | Observational only, do not surface |
+
+## Cross-references
+
+- [Confirmation rules](confirmation-rules.md)
+- [Merge preconditions](merge-preconditions.md)
+- [Public Dev Loop Contract](public-dev-loop-contract.md)

package/skills/docs/structural-quality.md

@@ -0,0 +1,42 @@
+# Structural quality
+
+Canonical owner for structural quality standards across all workflow families.
+
+## Core principles
+
+- **KISS**: Keep implementations simple; prefer thin glue over thick abstraction
+- **SRP**: Single Responsibility Principle — one reason to change per module
+- **YAGNI**: Don't add speculative features, compatibility shims, or unused abstractions
+- **Strict TypeScript**: No `any`, no implicit coercion, explicit return types
+
+## Deep review standards
+
+Apply these during implementation (not just review):
+
+1. **Cohesion**: Related functionality lives together; unrelated functionality is separated
+2. **Coupling**: Minimize dependencies between modules; prefer explicit injection over globals
+3. **Error handling**: All error paths are explicit and tested; no silent failures
+4. **Testability**: Every public function is independently testable; no hidden state
+5. **Naming**: Names describe what, not how; consistent vocabulary across codebase
+
+## Implementation self-check rules
+
+Apply these during implementation (not just at review time):
+
+- **Prefer deletion over addition**: Question every new file, export, layer, and moving part. If it does not earn its keep, remove it.
+- **File size ceiling**: Files over ~1k lines need extraction or an explicit justification kept in a code comment or doc reference.
+- **Logic placement**: Do not bolt conditionals onto unrelated paths; push logic into its own dedicated boundary.
+- **Avoid thin abstractions**: No thin wrappers, re-export-only files, or identity abstractions that add indirection without clarity.
+- **No leaky abstractions**: Do not leak feature-specific logic into shared or general-purpose modules.
+
+## Anti-patterns to avoid
+
+- Over-engineering: adding abstraction layers "just in case"
+- Copy-paste duplication: extracting shared logic too late
+- Magic values: undocumented constants or configuration
+- God modules: single file doing too many unrelated things
+
+## Cross-references
+
+- [Anti-patterns](anti-patterns.md)
+- [Validation policy](validation-policy.md)

package/skills/docs/tracker-first-loop-state.md

@@ -0,0 +1,281 @@
+# Tracker-First Story-to-PR Contract
+
+This document defines the adapter-agnostic MVP contract for the tracker-first
+story-to-PR workflow in `pi-dev-loops`.
+
+**MVP invariant: one tracker work item → one GitHub PR.**
+
+This document serves dual purpose:
+1. **Story-to-PR contract** — canonical for the PR-level tracker state machine
+2. **Loop state machine doc** — canonical for the tracker-first loop state machine (#449)
+
+Implementation for each:
+
+| Component | File |
+|---|---|
+| PR-level state machine (story-to-PR) | `packages/core/src/loop/tracker-pr-state.mjs` |
+| PR-level CLI detector | `scripts/loop/detect-tracker-pr-state.mjs` |
+| Loop state machine (tracker-first) | `packages/core/src/loop/tracker-first-loop-state.mjs` |
+| Loop state CLI detector | `scripts/loop/detect-tracker-first-loop-state.mjs` |
+| Loop state contract doc | this file |
+| Entrypoint briefing | `skills/docs/entrypoint-strategies.md#tracker-first` |
+
+## 1. Artifact Subset and MVP Invariant
+
+| Artifact | Role in this slice |
+|---|---|
+| One tracker work item (story, task, or bug) | Planning artifact; source of truth for work identity and planning state |
+| One GitHub PR | Execution artifact; source of truth for lifecycle, review, CI, and merge facts |
+| PR review / CI / merge facts | Observable from GitHub; feed reverse-sync decisions |
+| Epic / PRD reference | Optional linked metadata only; no roll-up or automation in this slice |
+| ADR / RFC reference | Optional linked metadata only; no decision-sync in this slice |
+
+**Invariant:** For any single tracker work item in scope, there is at most
+one active GitHub PR at a time. Multi-PR workflows and roll-up automation
+are out of scope for this slice.
+
+## 2. Source-of-Truth Ownership
+
+| Domain | Owner | Examples |
+|---|---|---|
+| Work-item identity and planning hierarchy | Tracker | Item ID, title, description, priority, assignee, epic link |
+| Tracker-native workflow state | Tracker | In-progress, blocked, done/completed, and any tracker-specific sub-states |
+| PR lifecycle facts | GitHub | Draft / ready-for-review, open / merged / closed, branch, head SHA |
+| PR review and CI facts | GitHub | Reviewer assignments, review states, check-run results, merge status |
+| Decision content | ADR / RFC artifacts (when linked) | Architecture decisions and RFCs referenced from PR body |
+| PR projection and reverse-sync logic | `pi-dev-loops` | Title/body/label generation rules, state mapping, sync triggers |
+
+`pi-dev-loops` **does not** become the canonical owner of any business fields.
+It provides projection and sync logic only.
+
+## 3. PR Projection Contract
+
+The following rules define how a tracker work item projects into GitHub PR
+metadata. All rules are deterministic and idempotent: applying them to the
+same inputs always produces the same output, and re-applying them to an
+already-correct PR leaves it unchanged.
+
+### 3.1 Required PR Metadata
+
+| Field | Rule |
+|---|---|
+| PR title | `[{TRACKER_ID}] {tracker item title}` — bracketed tracker identifier followed by the item title verbatim |
+| PR body — Tracker section | Required. Must include the tracker item ID and a direct link to the item. |
+| PR body — Summary section | Required. Brief description of the change implemented in this PR. |
+| PR body — Acceptance Criteria section | Required. Copied or linked from the tracker item's acceptance criteria. |
+| Labels | Required: `tracker:{TRACKER_ID}`. Optional reference labels: `epic:{EPIC_ID}`, `prd:{PRD_ID}` when references are present. |
+| Draft state | PR must start as a draft. It must not be marked ready-for-review until development work is complete. |
+
+### 3.2 Optional Reference Metadata
+
+Optional parent / decision references may appear in the PR body as links only.
+They are read-only metadata in this slice and do not trigger any automation:
+
+| Reference type | Placement | Effect |
+|---|---|---|
+| Epic | PR body — References section | Link only; no roll-up automation |
+| PRD | PR body — References section | Link only; no roll-up automation |
+| ADR | PR body — References section | Link only; no decision sync |
+| RFC | PR body — References section | Link only; no decision sync |
+
+### 3.3 Deterministic Update Rules
+
+1. **On PR create**: Generate title, body, and labels from tracker item fields.
+   Apply draft state.
+2. **On tracker item field change**: Re-apply projection rules to PR title,
+   body, and labels. Leave any sections not covered by projection rules
+   (e.g. reviewer-added review comments) intact.
+3. **Idempotent regeneration**: If the PR already has the correct title, body
+   sections, and labels, no mutation is performed. Projection is a no-op
+   when the current state already matches the target.
+
+### 3.4 PR Body Template
+
+```
+## Summary
+{brief description of the change}
+
+## Acceptance Criteria
+{copied or linked from tracker item}
+
+## Tracker
+- Item: [{TRACKER_ID}]({TRACKER_ITEM_URL})
+
+## References
+<!-- optional; add epic/PRD/ADR/RFC links here as plain links only -->
+```
+
+## 4. Reverse-Sync Contract
+
+The following table defines the canonical reverse-sync contract. Adapter
+implementations map canonical action names to tracker-native field updates.
+
+### 4.1 Canonical State Table
+
+| Lifecycle state | `reverseSyncAction` | Tracker effect |
+|---|---|---|
+| `ready_no_pr` — tracker item exists, no PR exists yet | `none` | No automatic mutation. Tracker-native readiness remains tracker-owned and is outside this snapshot-only helper. |
+| `draft_pr_open` — draft PR created or open | `set_in_progress` | Tracker moves to in-progress (or nearest equivalent) |
+| `pr_reviewable` — PR marked ready for review | `set_reviewable` | Tracker moves to reviewable / in-review (or nearest equivalent) |
+| `pr_merged` — PR merged | `set_done` | Tracker moves to done/completed terminal state |
+| `pr_closed_unmerged` — PR closed without merge | `none` | No automatic terminal transition; human decision required |
+| `no_tracker_item` | `none` | No tracker item to update |
+| `blocked_needs_user_decision` | `none` | Stop and report; no automatic tracker update |
+
+### 4.2 Event Triggers
+
+| PR lifecycle event | Maps to canonical state | Sync trigger |
+|---|---|---|
+| No PR created yet | `ready_no_pr` | No trigger |
+| Draft PR creation succeeds | `draft_pr_open` | Apply `set_in_progress` to tracker |
+| PR converted from draft to ready-for-review | `pr_reviewable` | Apply `set_reviewable` to tracker |
+| PR merged | `pr_merged` | Apply `set_done` to tracker |
+| PR closed without merge | `pr_closed_unmerged` | No automatic sync; report to user |
+
+### 4.3 Adapter Mapping Guidance
+
+Each tracker adapter maps the four canonical action names to its native API:
+
+| Canonical action | Adapter responsibility |
+|---|---|
+| `set_in_progress` | Move item to the adapter's in-progress equivalent (e.g. "In Progress" column, status field, or state transition) |
+| `set_reviewable` | Move item to the adapter's in-review / reviewable equivalent |
+| `set_done` | Move item to the adapter's done/completed terminal state |
+| `none` | No tracker mutation |
+
+## 5. State Machine
+
+The full lifecycle path for this MVP slice is:
+
+```text
+selected/ready (tracker-owned precondition; not encoded directly in this snapshot)
+  -> tracker item exists, no PR   [ready_no_pr]
+  -> draft PR created             [draft_pr_open]   -> tracker: set_in_progress
+  -> PR marked ready for review   [pr_reviewable]   -> tracker: set_reviewable
+  -> PR merged                    [pr_merged]       -> tracker: set_done
+```
+
+Alternate paths:
+
+```text
+PR closed without merge   [pr_closed_unmerged]          -> tracker: no automatic action
+No tracker item, no PR    [no_tracker_item]             -> blocked; report and stop
+Contradictory snapshot    [blocked_needs_user_decision] -> stop and report
+```
+
+### 5.1 State Definitions
+
+| State | Meaning |
+|---|---|
+| `no_tracker_item` | No tracker work item was found; lifecycle cannot proceed |
+| `ready_no_pr` | Tracker item exists and no PR has been created yet. This helper does not infer tracker-native readiness beyond that no-PR fact. |
+| `draft_pr_open` | Draft PR exists; tracker should reflect in-progress |
+| `pr_reviewable` | PR is open and not draft; tracker should reflect reviewable / in-review |
+| `pr_merged` | PR has been merged; tracker should be moved to done/completed |
+| `pr_closed_unmerged` | PR was closed without merge; no automatic tracker transition |
+| `blocked_needs_user_decision` | Unexpected or contradictory state; requires explicit user decision |
+
+### 5.2 Transition Graph
+
+```
+no_tracker_item
+  (no transitions — obtain a valid tracker item first)
+
+ready_no_pr
+  -> draft_pr_open         (create a draft PR with required tracker metadata)
+
+draft_pr_open
+  -> pr_reviewable         (mark the PR as ready for review)
+
+pr_reviewable
+  -> pr_merged             (PR is merged)
+  -> pr_closed_unmerged    (PR is closed without merge)
+  -> draft_pr_open         (convert back to draft if rework is needed)
+
+pr_merged
+  (no transitions — terminal success state)
+
+pr_closed_unmerged
+  -> ready_no_pr           (reopen work; create a new PR)
+  -> blocked_needs_user_decision  (escalate if context is unclear)
+
+blocked_needs_user_decision
+  (no transitions — stop and report; await explicit user authorization)
+```
+
+### 5.3 Snapshot Schema
+
+| Field | Type | Description |
+|---|---|---|
+| `trackerItemExists` | `boolean` | Whether a tracker work item was found |
+| `trackerItemId` | `string \| null` | Opaque tracker item identifier (e.g. `"PROJ-123"`) |
+| `prExists` | `boolean` | Whether a GitHub PR exists for this tracker item |
+| `prNumber` | `number \| null` | PR number if known. Canonical no-PR snapshots should set this to `null`; `prNumber` with `prExists=false` is treated as contradictory and blocked. |
+| `prDraft` | `boolean` | Whether the PR is in draft state |
+| `prMerged` | `boolean` | Whether the PR has been merged |
+| `prClosed` | `boolean` | Whether the PR is closed on GitHub. Merged PRs are also closed, so `pr_closed_unmerged` is derived from `prClosed && !prMerged`. |
+
+Unlike the Copilot/reviewer loop snapshots, this tracker contract uses `prClosed` for the raw GitHub closed state. Merged PRs therefore set both `prMerged=true` and `prClosed=true`, while `pr_closed_unmerged` remains the derived terminal state for `prClosed && !prMerged`.
+
+This snapshot intentionally omits tracker-native workflow fields such as selected/ready, blocked, or done. Higher-level callers must combine tracker-owned readiness/state separately when deciding whether opening a PR is appropriate.
+
+## 6. Scope Boundaries
+
+This contract is intentionally narrower than the parent epics:
+
+| Boundary | In scope (this slice) | Out of scope (deferred) |
+|---|---|---|
+| Tracker adapters | Adapter-agnostic contract only | Jira adapter, Shortcut adapter, any specific adapter |
+| Artifact model | One tracker item + one PR | Multi-PR, roll-up, cross-artifact sync |
+| Epic / PRD | Metadata reference links only | Automated roll-up or field sync |
+| ADR / RFC | Metadata reference links only | Decision synchronization |
+| Reverse sync | Four canonical states above | Tracker comment mirroring, full bidirectional field sync |
+| Parent epics | Consistent with #17 and #19 | Does not re-own the umbrella artifact model |
+
+## 7. Related
+
+- Parent workflow-family epic: [mfittko/pi-dev-loops#17](https://github.com/mfittko/pi-dev-loops/issues/17)
+- Umbrella artifact model epic: [mfittko/pi-dev-loops#19](https://github.com/mfittko/pi-dev-loops/issues/19)
+- This contract (first implementable slice): [mfittko/pi-dev-loops#21](https://github.com/mfittko/pi-dev-loops/issues/21)
+- Copilot loop state graph: [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md)
+- Reviewer loop state graph: [Reviewer Loop State Graph](../../docs/reviewer-loop-state-graph.md)
+
+---
+
+## State machine integration
+
+This document is also the canonical state-graph doc for the tracker-first loop state machine.
+
+### Loop state machine (distinct from PR-level machine above)
+
+Implementation:
+- `packages/core/src/loop/tracker-first-loop-state.mjs` — pure logic layer (`interpretTrackerLoopState`)
+- `scripts/loop/detect-tracker-first-loop-state.mjs` — CLI wrapper (same interface as `detect-copilot-loop-state.mjs`)
+
+**Loop state vocabulary:** `drafting`, `needs_triage`, `in_progress`, `in_review`, `merge_ready`, `blocked`, `completed`, `unknown`
+
+**Loop interface contract:** `{ ok, state, snapshot, allowedTransitions, nextAction }`
+
+**Loop snapshot fields:**
+| Field | Type | Description |
+|---|---|---|
+| `trackerState` | `string` | Canonical loop state |
+| `rawTrackerState` | `string` | Raw input state string |
+| `prLinked` | `boolean` | Whether a linked PR was found |
+| `prContext` | `object \| null` | Linked PR context (number, state, headRefName) |
+
+**Loop nextAction mapping:**
+| State | nextAction |
+|---|---|
+| `drafting` | `triage_or_block` |
+| `needs_triage` | `start_work` |
+| `in_progress` | `review` |
+| `in_review` | `merge_or_fix` |
+| `merge_ready` | `merge` |
+| `blocked` | `resolve_blocker` |
+| `completed` | `done` |
+| `unknown` | `reconcile` |
+
+**Fail-closed contract:** Unrecognized/empty/garbage tracker state → `needs_triage`. Only explicit `"unknown"` → canonical `unknown` state.
+
+**PR-level state machine** (sections 1-5 above) uses a separate vocabulary (`ready_no_pr`, `draft_pr_open`, `pr_reviewable`, `pr_merged`, `pr_closed_unmerged`, `no_tracker_item`, `blocked_needs_user_decision`) with its own snapshot schema and reverse-sync actions.

package/skills/docs/validation-policy.md

@@ -0,0 +1,27 @@
+# Validation policy
+
+Canonical owner for validation requirements across all workflow families.
+
+## Default validation
+
+- `npm run verify` is the default repo-level local validation path
+- Must pass before: PR creation, gate entry, merge
+- At minimum: `npm test && npm run test:dev-loop`
+
+## Gate-specific requirements
+
+| Gate | Validation required |
+|---|---|
+| `draft_gate` | CI green on current head (or `--local-validation-head-sha` if CI absent) |
+| `pre_approval_gate` | CI green on current head + resolved review threads + clean re-review |
+
+## Coverage requirements
+
+- ≥90% coverage for lines, statements, functions, and branches on changed files
+- Test-first for all non-trivial logic
+
+## Cross-references
+
+- [Merge preconditions](merge-preconditions.md)
+- [Stop conditions](stop-conditions.md)
+- [Public Dev Loop Contract](public-dev-loop-contract.md)

package/skills/docs/workflow-handoff-contract.md

@@ -0,0 +1,135 @@
+# Workflow Handoff — Derivation Contract
+
+> **Status:** This document defines the **contract** for the
+> `buildDevLoopHandoffEnvelope()` function in `@dev-loops/core`.
+> Agents should read the envelope as their first artifact and then load
+> only the listed `requiredReads` before executing `nextAction`.
+
+## Authoritative sources
+
+Every field in the handoff envelope is derived from authoritative sources as shown below. No field uses a hard-coded magic string or prose
+template.
+
+| Source | Fields derived |
+|---|---|
+| Resolver output (`resolve-dev-loop-startup.mjs` bundle) | `target`, `nextAction`, `requiredReads`, `executionMode` |
+| Caller options (`repoRoot`, `worktreeCwd`) | `cwd` |
+| Gate state (detectors) + strategy defaults | `currentGate`, `worktreeRequired` |
+| Settings (`.devloops` at repo root + `defaults.yaml`) | `gateConfig`, `stopRules`, `asyncStartMode`, `requireDraftFirst`, `maxCopilotRounds` |
+| Gate state (detectors) | `currentHeadSha`, `ciStatus`, `unresolvedThreadCount`, `copilotRoundCount` |
+
+## Acceptance templates
+
+`acceptance.criteria`, `acceptance.evidence`, `acceptance.maxFinalizationTurns`,
+and `control.*` are derived from a static strategy+gate mapping table:
+
+| Strategy | Gate | criteria | evidence | maxFinalizationTurns | needsAttentionAfterMs |
+|---|---|---|---|---|---|
+| `copilot_pr_followup` | `draft` | AC check, scope, coverage, DoD alignment | commands-run, validation-output, review-findings | 4 | 300000 |
+| `copilot_pr_followup` | `watch` | Copilot activity detection, no stuck watch | commands-run | 2 | 1800000 |
+| `copilot_pr_followup` | `pre-approval` | Full pre-approval gate chain, clean verdict, unresolved threads, CI green | commands-run, validation-output, review-findings, residual-risks | 6 | 300000 |
+| `final_approval` | `default` | Gate evidence, human confirmation, CI green | validation-output, manual-notes | 2 | 300000 |
+| `local_implementation` | `default` | Phase-acceptance criteria, verify green | commands-run, validation-output, changed-files | 6 | 300000 |
+| `issue_intake` | `default` | Contract compliance | commands-run, validation-output | 4 | 300000 |
+| `external_pr_followup` | `default` | Contract compliance | commands-run, validation-output | 4 | 300000 |
+| `reviewer_fixer` | `default` | Contract compliance | commands-run, validation-output | 4 | 300000 |
+| `wait_watch` | `default` | Contract compliance | commands-run, validation-output | 4 | 1800000 |
+
+Unknown strategy+gate combinations throw an explicit error listing known combos.
+
+## Stop rules
+
+Stop rules are derived from `settings.autonomy.stopAt` when present.
+When absent, strategy defaults apply:
+
+| Strategy | Default stop rules |
+|---|---|
+| `copilot_pr_followup` | `["draft-pr", "merge"]` |
+| `issue_intake` | `["merge"]` |
+| `external_pr_followup` | `["merge"]` |
+| `reviewer_fixer` | `["merge"]` |
+| `wait_watch` | `["merge"]` |
+| `final_approval` | `["merge"]` |
+| `local_implementation` | `[]` (auto-continue) |
+
+## Envelope schema
+
+```typescript
+interface HandoffEnvelope {
+  handoffVersion: 1;
+  derivedAt: string; // ISO timestamp
+
+  target: {
+    kind: "issue" | "pr" | "local_branch" | "local_phase";
+    repo: string;
+    issue?: number;
+    pr?: number;
+    linkedPr?: number;
+    branch?: string;
+    phase?: string;
+  };
+
+  currentGate: string;
+  currentHeadSha: string | null;
+  ciStatus: string | null;
+  unresolvedThreadCount: number;
+  copilotRoundCount: number;
+  maxCopilotRounds: number;
+  executionMode: "bounded_handoff" | "durable_auto";
+
+  nextAction: string;
+  requiredReads: string[];
+
+  gateConfig?: {
+    angles: string[];
+    excludeAngles?: string[];
+    blockCleanOnFindingSeverities: string[];
+    requireCi: boolean;
+  };
+
+  stopRules: string[];
+  asyncStartMode: "required" | "allowed";
+  requireDraftFirst: boolean;
+
+  cwd: string | null;
+  worktreeRequired: boolean;
+
+  acceptance: {
+    criteria: Array<{ id: string; must: string; severity: "required" | "recommended" }>;
+    evidence: string[];
+    maxFinalizationTurns: number;
+  };
+
+  control: {
+    needsAttentionAfterMs: number;
+    activeNoticeAfterMs: number;
+  };
+
+  overrides?: {
+    mergeAuthorized?: boolean;
+    preferLocal?: boolean;
+    scopeConstraint?: string;
+    customStopAt?: string;
+  };
+}
+```
+
+## Agent consumption pattern
+
+1. Read the handoff envelope as the first artifact.
+2. Read every path listed in `requiredReads` (in order).
+3. Execute `nextAction`.
+4. Respect `stopRules` — do not proceed past a gated stop point without authorization.
+5. Use `acceptance` to self-validate before declaring completion.
+
+## Backward compatibility
+
+The `acceptance` block maps 1:1 into the existing `subagent()` acceptance
+contract shape. When the envelope is present, no separate prose task
+parameter is required.
+
+## Non-goals
+
+- This contract does not define dispatch mechanics.
+- This contract does not define UI/UX for envelope display.
+- This contract does not modify the `subagent()` API itself.

package/skills/final-approval/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: final-approval
+description: >-
+  Internal routed strategy behind `dev-loop` for the final human approval and
+  merge gate. The canonical procedure now lives in copilot-pr-followup.
+compatibility: Pi skill for git+GitHub repositories. Requires gh auth.
+allowed-tools: read bash edit write subagent review_loop
+user-invocable: false
+---
+
+# Final Approval (redirect)
+
+This route now uses [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md) as the canonical procedure owner.
+
+When the public router selects `final_approval`, load [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md)
+and follow its **Human approval checkpoint** section inside Step 7.
+
+Use this redirect only as a narrowed read-set pointer for the routed `final_approval` strategy.
+Do not restate merge-ready preconditions, gate evidence rules, or merge authorization policy here.