dev-loops 0.1.0

package/skills/docs/copilot-ci-status-contract.md

@@ -0,0 +1,52 @@
+# Copilot PR CI/check normalization contract
+
+This document is the canonical bundled contract for deterministic interpretation of PR CI/check inputs used by Copilot PR follow-up flows.
+
+Installed skill/runtime consumers should read this bundled `skills/docs/` copy via [Copilot CI Status Contract](../docs/copilot-ci-status-contract.md) from the relevant skill directory. Repository-local docs may summarize or link this contract, but they should not redefine it.
+
+Implementation surface:
+- `@dev-loops/core/loop/copilot-ci-status`
+- source file: `packages/core/src/loop/copilot-ci-status.mjs`
+
+## Entry points
+
+- `normalizeStatusCheckRollupContract(statusCheckRollup)` — normalizes the PR `statusCheckRollup` snapshot from `gh pr view`
+- `normalizeHeadScopedCiContract({ checkRunsStatus, commitStatus })` — normalizes current-head refresh inputs after explicit `check-runs` / commit-status probes
+
+Both entry points return the same machine-readable contract shape.
+
+## Inputs
+
+### `normalizeStatusCheckRollupContract(statusCheckRollup)`
+
+- `statusCheckRollup` — the raw PR `statusCheckRollup` array from `gh pr view`; entries may be CheckRun-like (`status` + `conclusion`) or legacy StatusContext-like (`state`)
+
+### `normalizeHeadScopedCiContract({ checkRunsStatus, commitStatus })`
+
+- `checkRunsStatus` — normalized head-scoped check-runs status (`success` | `failure` | `pending` | `none`)
+- `commitStatus` — normalized head-scoped commit-status status (`success` | `failure` | `pending` | `none`)
+- optional `checkRunsUnsupportedCompleted` — `true` when the current-head check-runs probe observed an unsupported/non-success completed conclusion (for example `CANCELLED`) that must keep the merged result non-green even if commit status separately reports success
+
+## Output
+
+The returned object always includes:
+
+- `overallStatus` (`success` | `failure` | `pending` | `none`)
+- `rollup` (`success`/`failure`/`pending`/`none` booleans; exactly one true)
+- `semantics.wait` (`true` when `overallStatus` is `pending` or `none`)
+- `semantics.blocked` (`true` when `overallStatus` is `failure`)
+- `semantics.timeoutDisposition` (`remain_waiting` for `pending`/`none`; otherwise `not_applicable`)
+
+## Deterministic precedence
+
+The rollup precedence is fixed and policy-agnostic for ordinary normalized status values:
+1. `failure`
+2. `pending`
+3. `success`
+4. `none`
+
+Completed `SKIPPED` and `NEUTRAL` check-run conclusions count as non-blocking success-like signals. A completed `CANCELLED` check does not count as a successful readiness signal by itself; cancelled-only snapshots normalize to `none` so CI-dependent gates do not advance on cancelled work. Legacy successful `StatusContext` rollup entries also normalize to `success` instead of being mistaken for pending work.
+
+Merged current-head exception:
+- when `checkRunsUnsupportedCompleted=true`, a `checkRunsStatus: "none"` result caused by unsupported/non-success completed check-runs must remain non-green even if `commitStatus` is `success`
+- in that specific case, the merged `overallStatus` stays `none` rather than letting `success` mask the unsupported completed check-run signal

package/skills/docs/copilot-loop-operations.md

@@ -0,0 +1,233 @@
+# Copilot loop operations
+
+This document is the canonical operational reference for the deterministic Copilot PR follow-up state machine used by the routed `copilot_pr_followup`, `wait_watch`, `reviewer_fixer`, and `final_approval` paths behind `dev-loop`.
+
+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
+
+## Deterministic orchestration authority
+
+When operating in PR follow-up or async watch mode, use the deterministic state machines
+as the authoritative source for:
+
+- Copilot follow-up loop: `detect-copilot-loop-state.mjs` from the resolved skill scripts directory
+- reviewer-side PR review loop: `detect-reviewer-loop-state.mjs` from the resolved skill scripts directory
+
+Resolve those helper paths from the skill asset layout described by the main skill. In the `dev-loops`
+source repository the skill scripts directory is `../../scripts/` relative to `skills/copilot-pr-followup/SKILL.md`; in normalized
+installed copies it may instead be `scripts/` inside the installed skill directory when that layout bundles the helper scripts.
+
+Use the machines to answer:
+- what state the PR/loop is in right now
+- what transitions are currently allowed
+- what the next required action is
+- when to stop instead of guessing
+
+Each machine captures an observable snapshot from GitHub facts (plus explicit bounded local loop
+metadata when required) and interprets it into exactly one current state plus allowed next
+transitions. In the `dev-loops` source repository, the supporting source-authority references are [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md) and [Reviewer Loop State Graph](../../docs/reviewer-loop-state-graph.md) under `../../docs/` relative to `skills/copilot-pr-followup/SKILL.md`. Treat those links as source-repo references, not bundled installed-skill docs.
+
+For tracker-first MVP `story -> PR -> tracker sync` work, the source-repo reference is [Tracker-First Story-to-PR Contract](../../docs/tracker-story-pr-contract.md). That source doc inherits source-of-truth ownership, the required work item <-> PR link, and reverse-sync semantics from `#21`; it only adds the mutually exclusive workflow-family states and post-merge sync-verification states for this narrower MVP slice.
+
+## Key guarantees from the state machine
+
+- `unresolvedThreadCount > 0` always routes to fix/reply-resolve — never to a wait/watch state
+- `snapshot.copilotReviewRequestStatus === "unavailable"` or `snapshot.copilotReviewRequestStatus === "failed"` routes to a terminal stop state — never to sleep or watch
+- `agentFixStatus === "applied"` with unresolved threads routes to `already_fixed_needs_reply_resolve` — reply/resolve on GitHub is required before re-requesting review
+- Copilot being in `requested_reviewers` (`"requested"` or `"already-requested"`) routes to `waiting_for_copilot_review`
+
+## How to use the state machine in practice
+
+1. Run `node <resolved-skill-scripts>/loop/detect-copilot-loop-state.mjs --repo <owner/name> --pr <number>`
+   to get the current Copilot-loop state, decisive snapshot fields, and recommended next action.
+
+2. If you already ran `<resolved-skill-scripts>/github/request-copilot-review.mjs` and got a known status,
+   inject it without re-probing: add `--review-request-status <status>`.
+
+3. When the agent has applied a fix and wants to signal reply/resolve is next, build a snapshot
+   with `agentFixStatus: "applied"` and use `--input <snapshot.json>` for interpretation.
+
+4. Branch on the detector output instead of inventing a polling loop:
+   - `state=waiting_for_copilot_review` with `snapshot.copilotReviewOnCurrentHead=false`: do **not** poll manually; either run `node <resolved-skill-scripts>/loop/run-watch-cycle.mjs --repo <owner/name> --pr <number>` for persistent async waiting or report the wait state and resume later after the single detector call
+   - `state=waiting_for_ci` with `snapshot.ciStatus` in `{ "pending", "none" }`: do **not** poll manually by default; use `gh run watch <run-id> --repo <owner/name>` when the current-head run id is already known, otherwise report pending CI and resume later after the single detector refresh. Bounded exception: if GitHub created zero current-head check suites/statuses, the previous head rollup was green, and local `npm run verify` already passed for the same current head, rerun `detect-copilot-loop-state.mjs` with `--local-validation-head-sha <current-head-sha>` so the detector can promote that exact zero-suite case to `snapshot.ciStatus="crediblyGreen"` instead of waiting forever on raw `none`.
+   - `snapshot.ciStatus="failure"` remains a stop/fix state, never a wait loop
+
+5. For reviewer-side draft-review work, run `node <resolved-skill-scripts>/loop/detect-reviewer-loop-state.mjs --repo <owner/name> --pr <number> [--reviewer-login <login>] [--local-state <path>]`.
+   If the state reaches `draft_review_ready`, stage the pending review with
+   `node <resolved-skill-scripts>/github/stage-reviewer-draft.mjs --repo <owner/name> --pr <number> --review-file <merged-review.json> --local-state-output <state.json>`,
+   then re-run the detector with `--local-state <state.json>`.
+
+6. Follow the `nextAction` from the machine output. For stop states (`review_request_unavailable`,
+   `blocked_needs_user_decision`), report to the user and do not proceed.
+
+## Judgment calls that remain in the agent layer
+
+- Whether a comment should be accepted, deferred, or disagreed with
+- Whether the code change is already sufficient (→ sets `agentFixStatus: "applied"`)
+- What the narrowest valid fix is
+- Whether another Copilot pass is desired (→ triggers re-request or selects `done`)
+
+## Workflow overview
+
+```text
+ready issue -> confirm scope -> Copilot branch/PR -> async review/watch -> Pi follow-up fixes -> validation -> confirm verdict/action -> merge when authorized
+```
+
+Use the resolved `detect-copilot-loop-state.mjs` helper from the skill scripts directory at each
+decision point in this flow to determine the current state and route to the correct next step
+deterministically.
+
+## Pre-follow-up working rules
+
+> **Phase boundary:** Steps 1-4 apply when no PR exists yet (issue intake).
+> If a PR already exists, skip to [Deterministic orchestration authority](#deterministic-orchestration-authority) —
+> the state machine owns all post-PR routing.
+
+### Step 1: Choose the work item
+
+Prefer a GitHub issue over an ad hoc local TODO.
+
+When selecting the next item:
+- prefer `type:task` issues under the relevant epic
+- prefer `status:ready`
+- inspect milestone, labels, and acceptance criteria
+- confirm whether a PR already exists for the issue before proposing new execution
+
+Useful checks:
+- `gh issue list --state open`
+- `gh issue view <number>`
+- `gh pr list --state open`
+
+If the user asks for status/progress/readiness/merge-state/next-step (including “what is next”):
+- resolve authoritative active artifact identity first (issue/PR, plus branch/head SHA when useful)
+- for issue targets, do not assert "no open PR" until authoritative issue↔PR linkage is resolved via the startup resolver (`dev-loops loop startup --issue <number>`, run inside the `dev-loop` async subagent) — do not run `detect-linked-issue-pr.mjs` manually
+- resolve artifact state (`open`/`closed`/`merged`/`not_applicable`)
+- resolve current loop state and next action from deterministic helper/state output
+- include explicit resolved artifact identity in the answer
+- if identity/state cannot be resolved confidently, stop with reconcile/unknown instead of guessing from chat context
+
+### Step 2: Confirm issue scope before execution
+
+Before handing work to Copilot or doing follow-up fixes, summarize:
+- issue number and title
+- parent epic if present
+- milestone
+- labels
+- exact acceptance criteria
+- intended narrow scope
+- non-goals inferred from the issue and plan
+
+If the work item is phase-like, ambiguous, or likely to shape more than one downstream step, default to a short fan-out / fan-in refinement pass before implementation:
+- generate 2-3 plan variants in parallel when practical
+- compare the variants explicitly
+- merge them into one bounded execution plan
+- only then proceed with GitHub execution
+
+If the issue text is too vague, stop and ask a short clarification question rather than guessing.
+
+### Step 3: Decide whether Copilot or Pi should act next
+
+Use this heuristic:
+
+#### Prefer Copilot when
+- there is a ready implementation issue with clear acceptance criteria
+- no PR exists yet for that issue
+- the user wants the repository's normal GitHub/Copilot path
+- the next step is “start work” rather than “finish this already-open PR right now”
+
+#### Prefer Pi follow-up when
+- a PR already exists
+- Copilot has already pushed work and now needs review/fix follow-up
+- there are unresolved comments or failing checks
+- the user wants async in-session watching and response
+
+#### Prefer plain analysis only when
+- the user is asking what should happen next
+- authorization for GitHub state changes has not been given yet
+- the issue/PR state is unclear and needs inspection first
+
+### Step 4: Copilot handoff rules
+
+When preparing work for Copilot:
+- use the GitHub issue as the source of truth
+- preserve the issue's acceptance criteria
+- keep the requested scope narrow
+- do not broaden into adjacent backlog items
+- prefer one issue per PR unless the user explicitly wants bundling
+
+Before any GitHub mutation such as assigning the issue, posting instructions, or changing labels, confirm first unless explicitly authorized.
+
+When you do hand work to Copilot:
+- assign `copilot-swe-agent`
+- reference the issue number and acceptance criteria clearly
+- keep instructions implementation-focused and test-aware
+
+## PR description contract
+
+Follow the PR description contract (see [Agent Instructions](../../AGENTS.md) if present; otherwise use the structure below): detailed structured descriptions, not thin placeholders. At minimum include change summary, scope/context, explicit acceptance criteria, explicit definition of done, and explicit non-goals, and `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge.
+
+Checkbox rule: acceptance criteria, definition-of-done items, and any task list must be rendered as real GitHub markdown checkboxes inside list items (`- [ ]` / `- [x]`, also `* [ ]` / `* [x]`). Do not wrap checkbox markers (e.g. `[x]`) in backticks. Do not place checkbox markers inside table cells — task lists are not interactive there even with a leading `- `.
+
+New PRs in this workflow must be opened as **draft** PRs first when the repository enables `.devloops` at repo root `workflow.requireDraftFirst`. The built-in shipped default remains permissive; this repo opts in. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope. The draft gate inspection is a real workflow boundary, so a new PR must exist in draft before `gh pr ready` is even eligible.
+
+Only use `node <resolved-skill-scripts>/github/create-draft-pr.mjs` when authoritative issue↔PR resolution says there is no already-open linked PR. If a PR already exists, reuse/update that canonical PR instead of opening another one. This wrapper preserves the underlying `gh pr create` output contract while enforcing draft-first mechanically.
+
+MUST use `node <resolved-skill-scripts>/github/create-draft-pr.mjs --repo <owner/name> --assignee @me --base <base> --head <head> --title "..." --body-file <body-file>`.
+
+## Timeout and watch policy
+
+This workflow is intentionally long-lived, but one Copilot review watch boundary must still be capped.
+
+Preferred defaults for this repo:
+- poll interval for review/activity watchers: **1 minute** (derived from `packages/core/src/loop/policy-constants.mjs` DEFAULT_POLL_INTERVAL_MS)
+- max watch timeout per Copilot review boundary: **30 minutes** (derived from `packages/core/src/loop/policy-constants.mjs` COPILOT_REVIEW_WAIT_TIMEOUT_MS)
+- if that 30-minute watch budget expires, refresh authoritative state once; if the refreshed state still resolves `waiting_for_copilot_review`, stop with `watch timeout — PR #<number> needs manual attention`
+- do not silently extend that 30-minute cap unless the user or conductor explicitly authorizes a longer watch budget for the active PR
+- parent/subagent no-activity threshold for watcher-style runs: at least **15 minutes**
+- active-long-running notice threshold for watcher-style runs: about **30 minutes**
+
+These are the defaults built into `probe-copilot-review.mjs`, `run-watch-cycle.mjs`, and the `watchArgs` emitted by `copilot-pr-handoff.mjs`. Do not pass removed CLI policy flags (`--poll-interval-ms`, `--timeout-ms`, `--probe-only`) — helpers hard-error when they are provided. Timeouts and intervals are derived from `packages/core/src/loop/policy-constants.mjs`.
+
+### Outer-loop checkpoint: canonical re-attachment artifact
+
+The outer-loop checkpoint (`tmp/copilot-loop/<owner>/<repo>/pr-<n>/outer-loop-state.json`)
+is the canonical re-attachment artifact for async subagent runs. It is written by
+`outer-loop.mjs` at every conductor cycle and records:
+
+| Field | Meaning |
+|---|---|
+| `pr` | PR number |
+| `repo` | Repository slug (`owner/name`; lowercased by `outer-loop.mjs`) |
+| `outerAction` | Next action: `continue_wait`, `reenter_copilot_loop`, `reenter_reviewer_loop`, `stop`, `done` |
+| `copilotState` | Current copilot inner-loop state |
+| `reviewerState` | Current reviewer inner-loop state |
+| `reviewerScope` | Reviewer scope mode (always present; e.g. `all_reviewers` or `single_reviewer`) |
+| `reviewerLogin` | Reviewer GitHub login (always present; `null` unless single-reviewer scope) |
+| `reason` | Stop reason (`null` when `outerAction` is not `stop`) |
+| `timestamp` | ISO 8601 timestamp of checkpoint write |
+| `waitCycles` | Number of wait cycles accumulated |
+| `headSha` | PR head SHA at checkpoint time (`null` when unavailable) |
+
+### Re-attachment contract
+
+When a fresh `dev-loop` async subagent starts on a PR that already has an outer-loop
+checkpoint, it must read the checkpoint before entering any intake or follow-up procedure:
+
+1. If `outerAction` is `continue_wait` or `reenter_copilot_loop`: auto-resume the loop
+   rather than treating the start as fresh intake.
+2. If `outerAction` is `reenter_reviewer_loop`: enter the reviewer-loop path.
+3. If `outerAction` is `stop`: the loop is blocked or needs a human decision; report the `reason` and ask for direction.
+4. If no checkpoint or `outerAction` is `done`: `done` means the PR is merged/closed; normal fresh startup.
+
+The checkpoint is the only source of truth for re-attachment. Do not rely on chat context
+or local notes to determine "where we left off."
+
+## Hard rule: no agent-authored shell polling
+
+Helper-owned sleep inside `run-watch-cycle.mjs`, `probe-copilot-review.mjs`, or `watch-initial-copilot-pr.mjs` is allowed. Agent-authored shell polling (`sleep`, `for`, `while`, `timeout` wrappers around tool invocations) is a contract breach. This rule applies to ALL repos using the dev-loop workflow, not just the source repo.
+
+A watcher sleeping between polls is expected behavior, not a blocker.
+
+If the polling interval is 1 minute, do not treat silence shorter than one full poll interval as suspicious, and do not configure needs-attention thresholds close to a few seconds for this loop.

package/skills/docs/debt-remediation-contract.md

@@ -0,0 +1,107 @@
+# Debt remediation contract
+
+Canonical authority for the debt remediation pipeline and its integration with the `dev-loop` execution path.
+
+## Pipeline
+
+```
+debt_signals → cluster → score → shape → remediation_item → GitHub issue → dev-loop
+```
+
+Core pipeline stages under `packages/core/src/debt/`:
+
+| Module | Role | Side effects |
+|---|---|---|
+| `debt-signal.mjs` | Signal schema and validation | None |
+| `cluster.mjs` | Group signals into findings by file, module, theme | None |
+| `score.mjs` | 0-100 score from frequency, severity, impact | None |
+| `shape.mjs` | Classify findings: remediation_item, debt_epic, defer, watch, dismiss | None |
+| `remediation-to-issue.mjs` | Convert remediation_item to GitHub issue payload; create via `gh issue create` | `gh issue create` call |
+
+The cluster, score, and shape stages are deterministic pure functions.
+`remediation-to-issue.mjs` performs a side effect (`gh issue create`) and requires GitHub auth.
+
+## CLI entrypoint
+
+`scripts/loop/debt-remediate.mjs` is the single CLI entrypoint routed under `dev-loops loop debt-remediate`.
+
+```
+dev-loops loop debt-remediate --input <signals.json> [--repo <owner/name>] [--dry-run]
+```
+
+### Contract
+
+- **Input**: JSON array of `debt_signal` objects (validated against `DebtSignalSchema`)
+- **Pipeline**: cluster → score → shape → issue creation
+- **Issue creation**: calls `gh issue create --assignee @me` for each `remediation_item`
+- **Output**: JSON report with counts, issue URLs, and summary
+- **Exit codes**: 0 (success — all remediation issue creations succeeded), 1 (argument error, input validation failure, or any issue creation failure)
+- **Dry run**: `--dry-run` runs the full pipeline and validates but skips issue creation
+
+### Output shape
+
+```json
+{
+  "ok": true,
+  "dryRun": false,
+  "repo": "owner/name",
+  "signals": 5,
+  "findings": 2,
+  "remediationItems": 1,
+  "debtEpics": 0,
+  "deferred": 1,
+  "watching": 0,
+  "dismissed": 0,
+  "issues": [
+    {
+      "findingId": "uuid",
+      "title": "...",
+      "created": true,
+      "issueNumber": 123,
+      "issueUrl": "https://github.com/owner/name/issues/123",
+      "error": null
+    }
+  ],
+  "summary": "5 signals → 2 findings; 1 remediation items (1 issues created, 0 failed); ..."
+}
+```
+
+## Integration with dev-loop
+
+Once a remediation issue is created, it is a standard GitHub issue that feeds into the existing `dev-loop` execution path:
+
+1. `dev-loops loop startup --issue <n>` resolves the issue
+2. Standard `copilot-pr-followup` or `issue_intake` strategy takes over
+3. PR → review → merge as normal
+
+This closes the remediation execution loop: `remediation_item → issue → dev-loop → PR → merge`.
+
+## Shape thresholds
+
+Thresholds are hardcoded constants in `shape.mjs`. The outcome for a finding is determined by the combined thresholds:
+
+| Threshold | Value | Outcome |
+|---|---|---|
+| `EPIC_SIGNAL_COUNT_THRESHOLD` | 3 | When `signalCount > 3` and score ≥ `ITEM_THRESHOLD`, the finding becomes a `debt_epic` instead of `remediation_item` |
+| `ITEM_THRESHOLD` | 65 | `remediation_item` (unless signal count pushes to `debt_epic`) |
+| `DEFER_THRESHOLD` | 50 | `defer` |
+| `WATCH_THRESHOLD` | 30 | `watch` |
+| (below) | <30 | `dismiss` |
+
+The `EPIC_SIGNAL_COUNT_THRESHOLD` takes precedence: a finding with score ≥ `ITEM_THRESHOLD` and `signalCount > 3` becomes a `debt_epic`, not a `remediation_item`.
+
+## Scoring model
+
+Three dimensions, weighted:
+
+| Dimension | Weight | Description |
+|---|---|---|
+| Frequency | 0.35 | Signal count, logarithmic cap |
+| Severity | 0.40 | Average severity hint (info=1..critical=5) |
+| Impact | 0.25 | File presence, confidence, category diversity |
+
+Clamped to 0-100.
+
+## Labels
+
+Created issues receive the `workflow` label by default. This keeps them discoverable in the standard dev-loop issue tracking surface.

package/skills/docs/entrypoint-strategies.md

@@ -0,0 +1,115 @@
+# Entrypoint strategies
+
+This document replaces the seven individual `entrypoint-briefing-*.md` files with a single per-strategy-section reference. Each section preserves the state vocabulary and key operational content for that strategy.
+
+## Copilot PR follow-up
+
+State vocabulary: `waiting_for_initial_copilot_implementation`, `waiting_for_copilot_review`, `review_feedback_received`, `linked_pr_ready_for_followup`, `blocked_needs_user_decision`
+
+Next-action sentence: "Load PR state from `detect-copilot-loop-state.mjs`, resolve gate coordination, then execute the appropriate follow-up action (fix, review, wait, or escalate)."
+
+Helpers to run first:
+1. `dev-loops loop loop-state --repo <owner/name> --pr <N>` — resolve loop state
+2. `dev-loops loop gate-coordination --repo <owner/name> --pr <N>` — resolve gate state
+3. `dev-loops gate upsert-verdict` — post/update gate comments
+
+Required reading:
+- [Public Dev Loop Contract](public-dev-loop-contract.md)
+- [Copilot Loop Operations](copilot-loop-operations.md)
+- [Confirmation rules](confirmation-rules.md)
+- [Stop conditions](stop-conditions.md)
+- [Validation policy](validation-policy.md)
+
+## External PR follow-up
+
+State vocabulary: Same as Copilot PR follow-up but with external-human ownership.
+
+Next-action sentence: "Load PR state, check for external review cycles, then route to reviewer/fixer or maintenance workflow."
+
+Helpers to run first: Same as [Copilot PR follow-up](#copilot-pr-follow-up).
+
+Required reading: Same as [Copilot PR follow-up](#copilot-pr-follow-up).
+
+## Final approval
+
+State vocabulary: `approval_ready`, `merge_ready`, `waiting_for_merge_authorization`
+
+Next-action sentence: "Verify pre_approval_gate evidence, confirm CI green + resolved threads, then request explicit merge authorization."
+
+Helpers to run first:
+1. `dev-loops gate detect-evidence --repo <owner/name> --pr <N>` — verify gate evidence
+2. `dev-loops gate upsert-verdict` — post pre_approval_gate
+
+Required reading:
+- [Public Dev Loop Contract](public-dev-loop-contract.md)
+- [Final Approval SKILL](../final-approval/SKILL.md)
+- [Merge preconditions](merge-preconditions.md)
+- [Confirmation rules](confirmation-rules.md)
+
+## Issue intake
+
+State vocabulary: `waiting_for_initial_copilot_implementation`, `needs_refinement`, `ready_needs_assignment_confirmation`, `ready_assign_now`, `assigned_to_copilot`
+
+Next-action sentence: "Resolve issue readiness, handle assignment seam, then bootstrap PR creation or wait for Copilot implementation."
+
+Helpers to run first:
+1. `dev-loops loop linked-issue-pr --repo <owner/name> --issue <N>` — resolve issue↔PR linkage
+2. `dev-loops loop startup` — resolve routing
+
+Required reading:
+- [Public Dev Loop Contract](public-dev-loop-contract.md)
+- [Issue Intake Procedure](issue-intake-procedure.md)
+- [Confirmation rules](confirmation-rules.md)
+- [Stop conditions](stop-conditions.md)
+
+## Local implementation
+
+State vocabulary: `local_branch`, `local_phase`, `in_progress`, `review`, `merge_ready`
+
+Next-action sentence: "Fan-out refinement (unless light-mode), implement phase, validate, then create PR or continue to next phase."
+
+Helpers to run first:
+1. `dev-loops loop startup` — resolve routing
+2. `node scripts/loop/pre-commit-branch-guard.mjs --expected-branch <name> [--require-worktree] [--block-main-checkout]` — verify isolation (no CLI route; use script path)
+
+Required reading:
+- [Public Dev Loop Contract](public-dev-loop-contract.md)
+- [Local Implementation SKILL](../local-implementation/SKILL.md)
+- [Anti-patterns](anti-patterns.md)
+- [Structural quality](structural-quality.md)
+- [Validation policy](validation-policy.md)
+
+## Tracker-first
+
+**Strategy:** `tracker_first` (reserved for future `dev-loop` routing when tracker context detected)
+
+**Purpose:** Tracker-first workflow for story/epic tracker items that follow a PR-based GitHub execution path.
+
+**Routing status:** Routing integration in `resolve-dev-loop-startup.mjs` is deferred (no `tracker_first` route exists yet). This briefing documents the intended contract surface; the state machine and detector are implemented and tested.
+
+**Key artifacts:**
+- Tracker issue (canonical spec)
+- [Tracker-First Loop State](tracker-first-loop-state.md) — state machine doc
+- `detect-tracker-first-loop-state.mjs` — loop state detector
+- `detect-tracker-pr-state.mjs` — PR-level state detector
+
+**Routing:** `dev-loop` will resolve to tracker-first when a tracker context is detected (issue has tracker labels, is a tracker-backed issue). Fail-closed: unknown tracker state → `needs_triage`.
+
+**State vocabulary:** `drafting`, `needs_triage`, `in_progress`, `in_review`, `merge_ready`, `blocked`, `completed`, `unknown`
+
+**Interface contract:** Same as Copilot loop: `{ ok, state, snapshot, allowedTransitions, nextAction }`
+
+## Wait / watch
+
+State vocabulary: `waiting`, `waiting_for_initial_copilot_implementation`, `waiting_for_copilot_review`
+
+Next-action sentence: "Enter healthy-watch mode with configured timeout; escalate only on genuine blocked/authorization/reconcile states."
+
+Helpers to run first:
+1. `dev-loops loop watch-initial --repo <owner/name> --issue <N>` — bootstrap watcher
+2. `dev-loops loop watch-cycle --repo <owner/name> --pr <N>` — cycle watcher
+
+Required reading:
+- [Public Dev Loop Contract](public-dev-loop-contract.md)
+- [Copilot Loop Operations](copilot-loop-operations.md)
+- [Stop conditions](stop-conditions.md)