dev-loops 0.7.2 → 0.8.0

package/scripts/loop/run-watch-cycle.mjs

@@ -10,6 +10,9 @@ import { runHandoff } from "./copilot-pr-handoff.mjs";
 import { STATE } from "@dev-loops/core/loop/copilot-loop-state";
 import { DEFAULT_POLL_INTERVAL_MS } from "@dev-loops/core/loop/policy-constants";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
+import { ensureAsyncRunnerOwnership } from "./_pr-runner-coordination.mjs";
+import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
+import { resolveStaleRunnerMaxAgeMs } from "./_stale-runner-detection.mjs";
 import { parseArgs } from "node:util";
 import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
@@ -205,6 +208,33 @@ function buildWatchCycleContractTrace({
     },
   };
 }
+// A blocking watch can run for the full external-healthy-wait timeout (30 min for
+// Copilot/CI), which equals the runner-coordination stale window. Without a
+// heartbeat the claim ages to stale across a single watch and the next step is
+// refused. Refresh the lease on entry, on a periodic interval below
+// the stale window, and once more on return so the resuming runner has a fresh claim.
+async function runWatchHoldingLease(watchFactory, { repo, pr, env, cwd, ensureOwnershipImpl }) {
+  const heartbeat = async () => {
+    try {
+      // claimIfMissing:true self-heals a missing record but never stomps a live
+      // competitor (assertRunnerOwnership refuses to write on OWNERSHIP_LOST), so
+      // fail-closed competitor semantics are preserved.
+      await ensureOwnershipImpl({ repo, pr, env, cwd, claimIfMissing: true, requireExisting: false });
+    } catch {
+      // best-effort: a heartbeat failure must never affect the watch
+    }
+  };
+  const intervalMs = Math.max(1, Math.floor(resolveStaleRunnerMaxAgeMs({}, env) / 2));
+  await heartbeat();
+  const timer = setInterval(() => { void heartbeat(); }, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+  try {
+    return await watchFactory();
+  } finally {
+    clearInterval(timer);
+    await heartbeat();
+  }
+}
 export function parseWatchCycleCliArgs(argv) {
   const options = {
     help: false,
@@ -278,9 +308,11 @@ export async function runWatchCycle(
     detectCopilotSessionActivityImpl = detectCopilotSessionActivity,
     fetchPrHeadBranchImpl = fetchPrHeadBranch,
     watchWorkflowRunImpl = watchWorkflowRun,
+    ensureOwnershipImpl = ensureAsyncRunnerOwnership,
     detectSessionActivity = false,
   } = {},
 ) {
+  const leaseCwd = resolveRepoRoot(process.cwd());
   const handoff = await runHandoffImpl(options, { env, ghCommand });
   const result = {
     ok: true,
@@ -370,13 +402,16 @@ export async function runWatchCycle(
       session.activity === "active"
       && Number.isInteger(session.runId)
     ) {
-      const workflowWatchResult = await watchWorkflowRunImpl(
-        {
-          repo: options.repo,
-          runId: session.runId,
-          timeoutMs: persistentWatchTimeoutMs,
-        },
-        { env, ghCommand },
+      const workflowWatchResult = await runWatchHoldingLease(
+        () => watchWorkflowRunImpl(
+          {
+            repo: options.repo,
+            runId: session.runId,
+            timeoutMs: persistentWatchTimeoutMs,
+          },
+          { env, ghCommand },
+        ),
+        { repo: options.repo, pr: options.pr, env, cwd: leaseCwd, ensureOwnershipImpl },
       );
       workflowRunWatch = {
         attempted: true,

package/scripts/loop/sanctioned-commands.mjs

@@ -37,6 +37,7 @@ export const SANCTIONED_COMMANDS = Object.freeze({
   // Metadata edits.
   edits: Object.freeze({
     "pr-body-title-assignee-milestone": "scripts/github/edit-pr.mjs",
+    "issue-body-title-assignee-milestone": "scripts/github/edit-issue.mjs",
     "issue-comment": "scripts/github/comment-issue.mjs",
   }),
 

package/scripts/pages/build-state-atlas.mjs

@@ -13,6 +13,7 @@
 // (NAV_CSS references --heading/--kicker/--accent-soft, all declared here).
 import { STATE, TRANSITIONS } from '../../packages/core/src/loop/copilot-loop-state.mjs';
 import { REVIEWER_STATE, REVIEWER_TRANSITIONS } from '../../packages/core/src/loop/reviewer-loop-state.mjs';
+import { GRILL_STATE, GRILL_TRANSITIONS } from '../../packages/core/src/loop/refinement-grill-state.mjs';
 import { OUTER_STATE, OUTER_TRANSITIONS } from '../../packages/core/src/loop/conductor-routing.mjs';
 import { PUBLIC_DEV_LOOP_GATE_CONTRACT } from '../../packages/core/src/loop/public-dev-loop-routing-contract.mjs';
 import { PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS } from '../../packages/core/src/loop/pr-lifecycle.mjs';
@@ -100,6 +101,10 @@ const reviewerDiagram = renderStateDiagram(
   edgesFromTransitions(Object.values(REVIEWER_STATE), REVIEWER_TRANSITIONS),
   Object.values(REVIEWER_STATE),
 );
+const refinementGrillDiagram = renderStateDiagram(
+  edgesFromTransitions(Object.values(GRILL_STATE), GRILL_TRANSITIONS),
+  Object.values(GRILL_STATE),
+);
 const outerDiagram = renderStateDiagram(
   edgesFromTransitions(Object.values(OUTER_STATE), OUTER_TRANSITIONS),
   Object.values(OUTER_STATE),
@@ -214,6 +219,16 @@ const SECTIONS = [
     ],
     diagram: reviewerDiagram,
   },
+  {
+    id: 'refinement-grill',
+    title: 'Refinement / grill sub-loop',
+    source: 'packages/core/src/loop/refinement-grill-state.mjs — GRILL_STATE + GRILL_TRANSITIONS',
+    prose: [
+      'Before a slice enters the loop, the refinement grill runs as a closed, deterministic sub-loop over the issue, PR body, or plan file. It loads the target, detects spec gaps, and iterates detect-gaps to answer to synthesize to re-grill until it reaches a fixed point. The iteration lives entirely in the transition graph; the LLM answer and synthesis enter only as a bounded input consumed at the await_answers state, never as hidden orchestration in a coordinator script.',
+      'Write-back synthesizes only sharpened Acceptance criteria, Definition of done, and Non-goals into the body — the raw Q&A transcript never lands in the artifact. An uncitable gap stops honestly at needs_human_handoff naming the question rather than fabricating an answer to force convergence, and any load or parse failure fails closed to blocked_needs_user_decision.',
+    ],
+    diagram: refinementGrillDiagram,
+  },
   {
     id: 'release-pipeline',
     title: 'Release pipeline',

package/scripts/projects/add-queue-item.mjs

@@ -4,7 +4,8 @@ import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { resolveProjectSelector, findProject, applyDevloopsBoard } from "./_resolve-project.mjs";
 import { parseArgs } from "node:util";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
-import { loadStateColumnMap, LOGICAL_COLUMN } from "@dev-loops/core/loop/queue-board-sync";
+import { loadStateColumnMap, LOGICAL_COLUMN, nonSuccessBoardColumn } from "@dev-loops/core/loop/queue-board-sync";
+import { decideEnqueueRefinementGate, detectIssueRefinementArtifact } from "@dev-loops/core/loop/issue-refinement-artifact";
 
 const USAGE = `Usage: dev-loops queue add --repo <owner/name> [--project <number|id>] --item <number>
        dev-loops project add … (back-compat alias for "queue add")
@@ -24,10 +25,20 @@ Options:
                               default, honors queue.statusColumns.next_up). Sugar
                               for --column <that column>; cannot be combined with
                               a conflicting --column/--status.
+  --auto                      Headless mode. When an issue targets the pickup
+                              (next_up) column without a refinement artifact
+                              (Acceptance criteria/DoD/linked doc), divert it
+                              to the non-pickup park column instead of failing.
+                              Without --auto, the same case throws
+                              MISSING_REFINEMENT_ARTIFACT.
   --help, -h                  Show this help.
 
 Output (stdout):
-  JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, alreadyPresent } }
+  JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, alreadyPresent },
+          refinement? }
+  refinement (present only when the pickup-column gate ran): either
+    { refined: true } or, on a headless --auto divert,
+    { refined: false, diverted: true, requestedColumn, parkedColumn, reason, missing }.
 
 ${JQ_OUTPUT_USAGE}
 
@@ -36,6 +47,8 @@ Exit codes:
   1 — usage or argument error
   2 — GitHub API error / invalid --jq filter
   3 — project, field, column, or issue/PR not found
+  4 — issue targets the pickup column without a refinement artifact
+      (MISSING_REFINEMENT_ARTIFACT; interactive only, --auto diverts instead)
 `.trim();
 
 function parseCliArgs(argv) {
@@ -58,6 +71,7 @@ function parseCliArgs(argv) {
       column: { type: "string" },
       status: { type: "string" },
       "next-up": { type: "boolean" },
+      auto: { type: "boolean" },
       help: { type: "boolean", short: "h" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
@@ -113,6 +127,12 @@ function parseCliArgs(argv) {
         }
         args.nextUp = true;
         break;
+      case "auto":
+        if (token.value !== undefined) {
+          throw Object.assign(new Error(`Unknown flag: ${token.rawName}=${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
+        }
+        args.auto = true;
+        break;
       default: {
         if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
         throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
@@ -367,6 +387,7 @@ function classifyExitCode(err) {
       err.code === "INVALID_STATUS" || err.code === "INVALID_ARGS") return 1;
   if (err.code === "PROJECT_NOT_FOUND" || err.code === "FIELD_NOT_FOUND" || err.code === "COLUMN_NOT_FOUND" ||
       err.code === "ITEM_NOT_FOUND" || err.code === "CONTENT_NOT_FOUND") return 3;
+  if (err.code === "MISSING_REFINEMENT_ARTIFACT") return 4;
   return 2;
 }
 
@@ -502,6 +523,67 @@ async function main(args, { env = process.env, runChild, cwd = process.cwd() } =
   let issueNumber = fullResult.__typename === "Issue" ? itemNumber : null;
   let prNumber = fullResult.__typename === "PullRequest" ? itemNumber : null;
 
+  // 5b. Refinement-artifact gate: shift the draft-gate check
+  // LEFT to enqueue time so an un-refined issue never lands in the Next Up
+  // pickup column. Scoped to issues (not PRs) targeting the pickup column —
+  // create-pr.mjs auto-enqueues PRs into In Progress, which never trips this.
+  let refinement;
+  let effectiveTargetOption = targetOption;
+  let effectiveTargetStatus = targetStatus;
+  if (issueNumber !== null && targetStatus === nextUpColumn) {
+    const bodyResult = await child(
+      "gh",
+      ["issue", "view", String(issueNumber), "--repo", repo, "--json", "body"],
+      env,
+    );
+    if (bodyResult.code !== 0) {
+      const detail = bodyResult.stderr.trim() || `exit code ${bodyResult.code}`;
+      throw Object.assign(new Error(`gh issue view failed: ${detail}`), { code: "GH_API_ERROR" });
+    }
+    const bodyPayload = parseJsonText(bodyResult.stdout, { label: "gh issue view" });
+    const body = typeof bodyPayload?.body === "string" ? bodyPayload.body : "";
+    const artifact = detectIssueRefinementArtifact({ body, issueNumber });
+    const decision = decideEnqueueRefinementGate({ artifact, targetIsPickup: true, auto: !!args.auto });
+    if (decision.action === "block") {
+      throw Object.assign(new Error(decision.reason), {
+        code: "MISSING_REFINEMENT_ARTIFACT",
+        missing: decision.missing,
+      });
+    }
+    if (decision.action === "divert") {
+      const parkedColumn = nonSuccessBoardColumn(cwd);
+      if (parkedColumn === nextUpColumn) {
+        // A non-success park column equal to the pickup column would divert the
+        // un-refined item straight back into Next Up, defeating the gate. Fail
+        // closed on that misconfiguration rather than parking into pickup.
+        throw Object.assign(
+          new Error(`Park column "${parkedColumn}" (queue.nonSuccessStatus) is the pickup column; cannot divert an un-refined item into Next Up.`),
+          { code: "INVALID_STATUS" },
+        );
+      }
+      const parkedOption = statusField.options.find((o) => o.name === parkedColumn);
+      if (!parkedOption) {
+        const available = statusField.options.map((o) => o.name).join(", ");
+        throw Object.assign(
+          new Error(`Park column "${parkedColumn}" (queue.nonSuccessStatus) not found in Status field. Available: ${available}`),
+          { code: "COLUMN_NOT_FOUND" },
+        );
+      }
+      effectiveTargetOption = parkedOption;
+      effectiveTargetStatus = parkedColumn;
+      refinement = {
+        refined: false,
+        diverted: true,
+        requestedColumn: nextUpColumn,
+        parkedColumn,
+        reason: decision.reason,
+        missing: decision.missing,
+      };
+    } else {
+      refinement = { refined: true };
+    }
+  }
+
   // 6. Add item to project
   const addPayload = await ghGraphql(ADD_PROJECT_ITEM, {
     projectId: project.id,
@@ -518,7 +600,7 @@ async function main(args, { env = process.env, runChild, cwd = process.cwd() } =
     projectId: project.id,
     itemId: newItem.id,
     fieldId: statusField.id,
-    optionId: targetOption.id,
+    optionId: effectiveTargetOption.id,
   }, env, child);
 
   const updated = updatePayload?.data?.updateProjectV2ItemFieldValue?.projectV2Item;
@@ -532,9 +614,10 @@ async function main(args, { env = process.env, runChild, cwd = process.cwd() } =
       itemId: newItem.id,
       issueNumber,
       prNumber,
-      status: targetStatus,
+      status: effectiveTargetStatus,
       alreadyPresent: false,
     },
+    ...(refinement ? { refinement } : {}),
   };
 }
 

package/skills/copilot-pr-followup/SKILL.md

@@ -13,7 +13,7 @@ user-invocable: false
 
 # Copilot PR Follow-up
 
-This skill is the canonical internal `copilot_pr_followup` route behind the public `dev-loop` façade.
+Canonical owner for the internal `copilot_pr_followup` route behind the public `dev-loop` façade.
 
 It is also the canonical internal owner of the shared post-PR mechanics used by this repo:
 PR discovery and interpretation, async watch behavior, fix / reply-resolve / re-request flow,
@@ -238,12 +238,12 @@ When unresolved feedback exists, use a narrow follow-up loop:
    - when the intent is GitHub linkability, keep commit SHAs and issue/PR refs as plain text (for example 3ee82fc and owner/repo#70) and do not wrap them in backticks
    - keep backticks for actual code/path/CLI literals only
    - if either helper was newly added or recently changed, smoke-check it against one real thread before assuming the rest of the loop can rely on it
-9. before resolving an addressed review thread, run a post-fix verification checkpoint
+9. <!-- rule: COPILOT-FOLLOWUP-VERIFY-BEFORE-RESOLVE --> `COPILOT-FOLLOWUP-VERIFY-BEFORE-RESOLVE`: before resolving an addressed review thread, run a post-fix verification checkpoint
    - confirm the GitHub reply actually exists on the intended thread/comment, not only in local notes or helper stdout
    - confirm the pushed current-head diff genuinely addresses the reviewer concern on the flagged lines or pattern; if the concern is only partially addressed, leave the thread open and explain what remains
    - refresh the API-backed thread snapshot via `dev-loops gate capture-threads` and use that refreshed data — including the unresolved thread count — for follow-up decisions rather than prose assumptions
    - if any verification check fails, do **not** resolve the thread; leave it open, add a short explanation when needed, and re-enter the fix/reply loop
-10. resolve the addressed review thread only after the reply is attached successfully, the verification checkpoint passes, and the concern is genuinely addressed
+10. <!-- rule: COPILOT-FOLLOWUP-RESOLVE-AFTER-REPLY --> `COPILOT-FOLLOWUP-RESOLVE-AFTER-REPLY`: resolve the addressed review thread only after the reply is attached successfully, the verification checkpoint passes, and the concern is genuinely addressed
     - do not stop at a local fix if GitHub-side reply/resolve is authorized
 11. after completing reply/resolve for a pass, verify zero unresolved threads remain via `dev-loops gate capture-threads` before proceeding
     - if the refreshed snapshot reports unresolved threads, re-enter the reply/resolve loop for the missed threads
@@ -252,14 +252,14 @@ When unresolved feedback exists, use a narrow follow-up loop:
     - for a light-dispatched PR, pass `--lightweight` on every round-cap-consuming helper invocation — `detect-copilot-loop-state.mjs`, `copilot-pr-handoff.mjs`, `detect-pr-gate-coordination-state.mjs`, `request-copilot-review.mjs`, and `upsert-checkpoint-verdict.mjs` — otherwise those tools resolve the full-PR cap and the composed lightweight cap is never enforced
     - **Opt out entirely:** `maxCopilotRounds: 0` disables the external Copilot review gate for the repo — the loop runs `draft_gate → pre_approval_gate` with the local harness only, never requesting or waiting on Copilot. Use this when the repo has no Copilot reviewer configured or prefers local-harness-only review.
     - use the completed Copilot review-round count from `detect-copilot-loop-state.mjs` / `copilot-pr-handoff.mjs` as the current PR's review-round count
-    - if completed review rounds have reached the maximum (default: 5), do **not** re-request Copilot review within that concluded cycle
+    - if completed review rounds have reached the resolved round cap above, do **not** re-request Copilot review within that concluded cycle
     - if the loop already converged and then significant post-convergence changes land on a newer head (new/changed product or test logic, not doc/message/comment-only edits), treat that as a NEW cycle and re-request Copilot review when regular rounds are already > 0 (the prior cycle's cap does not suppress this new-cycle request)
     - when the round limit is reached **and** the refreshed thread snapshot proves zero unresolved threads **and** current-head CI is green or credibly green, treat that clean state as eligible for `pre_approval_gate` fallback instead of deadlocking on another Copilot rerequest
     - when using that fallback, add a short round-exhaustion note to the visible `pre_approval_gate` gate evidence so the PR records why no further Copilot rerequest occurred
     - if the round cap is reached before the PR is thread-clean or before CI is green/credibly green, reply-resolve any remaining intentionally deferred threads with a short `deferred to follow-up` note, then stop and report that the Copilot round limit was reached
     - **Signal-gated re-request suppression:** the `detect-copilot-loop-state.mjs` state machine classifies review-thread comments by signal level (High/Mid/Low). High-signal (bugs, security, contract violations) always re-requests; Low-signal (cosmetic nits) never re-requests. When low-signal detection is enabled and thresholds are met, the machine returns a low-signal-converged terminal state routing to `pre_approval_gate` without further re-requests. See [Copilot Loop Operations](../docs/copilot-loop-operations.md) for full signal-level semantics.
     - if that local validation is still known red, continue remediation instead of re-requesting Copilot
-    - after a fix push advances the PR head SHA, re-run `detect-copilot-loop-state.mjs` for the new head and apply the [Copilot CI Status Contract](../docs/copilot-ci-status-contract.md). Previous-head CI is stale; only current-head results unblock CI-dependent steps. if GitHub CI/checks for the updated head are known red for a fixable issue, continue remediation instead of re-requesting Copilot. only once the updated head is green or credibly green, explicitly re-request Copilot review for the new head. Always use `request-copilot-review.mjs` — never `gh api POST repos/.../requested_reviewers` directly.
+    - after a fix push advances the PR head SHA, re-run `detect-copilot-loop-state.mjs` for the new head and apply the [Copilot CI Status Contract](../docs/copilot-ci-status-contract.md). Previous-head CI is stale; only current-head results unblock CI-dependent steps. if GitHub CI/checks for the updated head are known red for a fixable issue, continue remediation instead of re-requesting Copilot. <!-- rule: COPILOT-FOLLOWUP-REREQUEST-GREEN-GATE --> `COPILOT-FOLLOWUP-REREQUEST-GREEN-GATE`: only once the updated head is green or credibly green, explicitly re-request Copilot review for the new head. Always use `request-copilot-review.mjs` — never `gh api POST repos/.../requested_reviewers` directly.
     - only enter a wait/watch loop if the request result is confirmed as `requested` or `already-requested`
     - for `requested` / `already-requested`, immediately re-baseline with `detect-copilot-loop-state.mjs`; if the returned state is `waiting_for_copilot_review`, use `dev-loops loop watch-cycle` or stop/resume later, and if the returned state is `waiting_for_ci`, use `dev-loops loop watch-ci` (provider-agnostic CI wait; `gh run watch` is an Actions-only fallback) or stop/resume later after that single detector refresh
     - if the request result is `unavailable`, report that limitation and stop unless the user explicitly wants passive waiting anyway

package/skills/dev-loop/SKILL.md

@@ -151,9 +151,9 @@ When you need a fact from a dev-loops JSON-emitting script, climb this ladder an
 
 **Inline-first rule:** Prefer inline commands over nested async delegation when managing a single PR. Use nested delegation only for parallel fan-out or when the parent needs to continue other work.
 
-**Bounded async task contract:** Break work into discrete tasks with clear inputs, explicit outputs, bounded scope. No shell polling — use `run-watch-cycle.mjs` or `gh run watch`. For fan-out reviewer waits (gate sub-loops or any Agent-tool fan-out), await completion via the harness completion notification or the reviewer's findings artifact at its deterministic path, then join via `consolidateFanin` — never tail/parse a subagent transcript, never `node -e`/`python3`-parse tool JSON, never `sleep`-poll (see the [fan-in wait anti-pattern](../docs/anti-patterns.md) and [Checkpoint Review Chain Contract](../../docs/gate-review-sub-loop-contract.md) Phase 2).
+**Bounded async task contract:** Break work into discrete tasks with clear inputs, explicit outputs, bounded scope. No shell polling — use `run-watch-cycle.mjs` or `gh run watch`. Fan-out reviewer waits (gate sub-loops or any Agent-tool fan-out) follow `ANTIPATTERN-FANIN-WAIT` in [Anti-patterns](../docs/anti-patterns.md): await completion via the harness notification or the reviewer's findings artifact at its deterministic path and join via `consolidateFanin` — never transcript-tail, `node -e`/`python3`-parse tool JSON, or `sleep`-poll.
 
-**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the maximum (default: 5). Stop re-requesting Copilot review when the limit is reached **within that review cycle**. Exception: if the loop already converged and then significant post-convergence changes land on a newer head (new/changed product or test logic, not doc/message/comment-only edits), open a new Copilot review cycle and re-request review when regular rounds are already > 0, even if the previous cycle hit the cap. Read these gate-cadence facts via the token-economical convention above (`run-watch-cycle.mjs --concise`, or `--jq`/`--silent` for a single field/predicate) — never `| python3` or `node -e`.
+**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the resolved round cap (`refinement.maxCopilotRounds`, default 5; light-dispatched PRs resolve the lower `resolveEffectiveCopilotRoundCap`, default 1 — owned by `COPILOT-FOLLOWUP-ROUND-CAP`). Stop re-requesting Copilot review when the limit is reached **within that review cycle**. Exception: the post-convergence new-cycle re-request carve-out (a converged loop that later takes significant post-convergence changes on a newer head opens a new cycle even if the previous one hit the cap) is owned by `COPILOT-FOLLOWUP-ROUND-CAP`. Read these gate-cadence facts via the token-economical convention above (`run-watch-cycle.mjs --concise`, or `--jq`/`--silent` for a single field/predicate) — never `| python3` or `node -e`.
 
 ## Shorthand issue-based auto trigger contract
 

package/skills/docs/acceptance-criteria-verification.md

@@ -5,9 +5,17 @@ Canonical owner for the acceptance-criteria verification procedure run during th
 ## Procedure
 
 <!-- rule: ACCEPT-CRITERIA-VERIFY-AND-REFLECT -->
-`ACCEPT-CRITERIA-VERIFY-AND-REFLECT`: Before posting the `pre_approval_gate` comment, the agent MUST verify every acceptance criteria checklist item in the issue linked to this PR, and MUST reflect the verified items back into both the linked issue body and the PR body (exception: under the lightweight path — `specSource: pr_body` — the step 5 issue-body mirroring is skipped, since the PR body, not the issue body, is the canonical spec surface; see the lightweight fork below):
-
-> **Lightweight (PR-body-as-spec) fork:** when the session is lightweight — the resolver output / handoff envelope carries `specSource: pr_body` (`canonicalSpecSource: pr_body`) — a linked issue still exists (`--lightweight` runs on the `--issue` path, so keep the `Closes #N` linkage and all issue-level tracking), but the **PR body**, not the issue body, is the canonical spec-of-record read for AC/DoD. In that case, still resolve the linked issue for tracking, but read the AC/DoD/invariants from the PR body rather than the issue body (skip step 2's issue-body read for spec purposes). Run `node scripts/loop/validate-pr-body-spec.mjs --repo <owner/name> --pr <pr-number> --expected-issue <issue-number>` (reuses `@dev-loops/core/loop/issue-refinement-artifact`) to confirm the body carries the required invariants — it fails closed with a per-section `missing_*` reason if any is absent, in which case post the gate comment with verdict `blocked`. The PR body MUST carry the `Closes #N` linkage (or GitHub's other closing-keyword forms): `validate-pr-body-spec` fails closed with `missing_closing_issue_reference` without it, and with `closes_wrong_issue` when `--expected-issue` doesn't match. Then continue at step 3, extracting the **Acceptance criteria** checklist items from the PR body itself; step 5's issue-body AC-tick update is unnecessary for lightweight since the issue body is not the spec surface (the PR body is ticked in step 6 as usual). The default issue-backed procedure below is unchanged.
+`ACCEPT-CRITERIA-VERIFY-AND-REFLECT`: Before posting the `pre_approval_gate` comment, the agent MUST verify every acceptance criteria checklist item in the issue linked to this PR, and MUST reflect the verified items back into both the linked issue body and the PR body (exception: when the linked issue body is not the spec-of-record — under a lightweight session (tracker-backed or issue-less; the PR body is the spec) or a plan-file promotion session (the committed plan doc the PR body points to is the spec) — the step 5 issue-body mirroring is skipped; see the fork below):
+
+> **Non-tracker spec-source fork:** when the linked issue body is not the spec-of-record, the fork covers three arms — lightweight (the PR body itself is the spec; splits on whether a backing issue exists) and plan-file promotion (a distinct local-planning origin whose committed plan doc, pointed to from the PR body, is the spec). Handle each arm as below.
+>
+> **Tracker-backed lightweight** (`--issue --lightweight`): a linked issue exists, so keep the `Closes #N` linkage and all issue-level tracking, but the **PR body**, not the issue body, is the canonical spec-of-record read for AC/DoD. Still resolve the linked issue for tracking, but read the AC/DoD/invariants from the PR body rather than the issue body (skip step 2's issue-body read for spec purposes). Run `node scripts/loop/validate-pr-body-spec.mjs --repo <owner/name> --pr <pr-number> --expected-issue <issue-number>` (reuses `@dev-loops/core/loop/issue-refinement-artifact`) to confirm the body carries the required invariants — it fails closed with a per-section `missing_*` reason if any is absent, in which case post the gate comment with verdict `blocked`. The PR body MUST carry the `Closes #N` linkage (or GitHub's other closing-keyword forms): `validate-pr-body-spec` fails closed with `missing_closing_issue_reference` without it, and with `closes_wrong_issue` when `--expected-issue` doesn't match. Then continue at step 3, extracting the **Acceptance criteria** checklist items from the PR body itself; step 5's issue-body AC-tick update is unnecessary since the issue body is not the spec surface (the PR body is ticked in step 6 as usual).
+>
+> **Issue-less lightweight** (`--lightweight` alone): no linked issue exists — by design, not a gap. There is nothing to resolve at step 1 and nothing to read or mirror at steps 2 and 5; skip all three. Read AC/DoD/invariants directly from the PR body and run `node scripts/loop/validate-pr-body-spec.mjs --repo <owner/name> --pr <pr-number> --no-issue`, which fails closed with a per-section `missing_*` reason for any absent invariant and with `unexpected_closing_issue_reference` if the body carries a closing reference to an issue that doesn't back it (a closing reference MUST NOT be present). On any validation failure, post the gate comment with verdict `blocked`. Step 1's "zero candidates → blocked" rule is scoped to tracker-backed sessions; for a deliberately issue-less session, zero closing references is the expected state, not a blocked condition. Continue at step 3 against the PR body, then step 4 and 6 as usual.
+>
+> **Plan-file promotion (P4) — a distinct local-planning origin, not a lightweight sub-arm:** no linked issue exists — similar to the issue-less lightweight arm, there is nothing to resolve at step 1 and nothing to read or mirror at steps 2 and 5; skip all three. AC/DoD live in the PR body, copied from the committed plan doc that is the spec-of-record; read them from the PR body as usual.
+>
+> The default issue-backed procedure below is unchanged.
 
 1. **Resolve the linked issue number deterministically:** use `gh pr view <pr-number> --repo <owner/name> --json closingIssuesReferences,body` and apply this decision tree: if there is exactly one closing issue reference, use it; else if there is exactly one PR-body `Closes #N` / `Fixes #N` pattern, use it; otherwise (zero or multiple candidates), post the gate comment with verdict `blocked` (gate cannot complete deterministically) rather than guessing.
 
@@ -17,7 +25,7 @@ Canonical owner for the acceptance-criteria verification procedure run during th
 
 4. **Verify each AC item** against the proposed changes on the current PR head.
 
-5. **Update the issue body once:** compute the fully-updated issue body by replacing each verified item's `- [ ]` with `- [x]`, write it to a temporary file, and perform a single `gh issue edit <issue-number> --body-file <tmp-file> --repo <owner/name>`. Do not issue one edit per item; prefer `--body-file` over inline `--body` to avoid shell quoting/escaping hazards.
+5. **Update the issue body once:** compute the fully-updated issue body by replacing each verified item's `- [ ]` with `- [x]`, write it to a temporary file, and perform a single `node scripts/github/edit-issue.mjs --repo <owner/name> --issue <issue-number> --body-file <tmp-file>`. Do not issue one edit per item; prefer `--body-file` over inline `--body` to avoid shell quoting/escaping hazards.
 
 6. **Tick the PR body once:** after the verification is clean, flip each verified item's `- [ ]` to `- [x]` in the PR body via a single `gh pr edit --body-file` update, so the merged PR shows checked AC/DoD. Run `node scripts/github/tick-verified-checkboxes.mjs --repo <owner/name> --pr <pr-number> --verified <exact label>...` (one edit; exact-label match; only items actually verified are ticked; unverified or deferred items stay `- [ ]`; fail closed). This runs automatically as part of the `pre_approval_gate`, not by memory.
 

package/skills/docs/anti-patterns.md

@@ -6,18 +6,18 @@ Canonical owner for anti-pattern guidance across all workflow families.
 
 1. **Skipping fan-out/fan-in for non-trivial changes**: Do not implement directly without refinement when scope exceeds light-mode thresholds.
 2. **Routing review-only work through local_implementation**: Review-only comparison, synthesis, or consolidation must use `refiner` agent, not `dev-loop` + `local_implementation`.
-3. **Thin placeholder PR descriptions**: Always include change summary, scope/context, acceptance criteria, definition of done, non-goals, and `Closes #N`.
+3. **Thin placeholder PR descriptions**: Always include change summary, scope/context, acceptance criteria, definition of done, non-goals, and `Closes #N` (tracker-backed; issue-less lightweight and plan-file promotion PRs instead follow [merge precondition 7](merge-preconditions.md#required-before-merge)).
 4. **Merging directly to main without PR**: Use PR-based remote loop when practical.
 5. **Duplicate worktree paths**: See `WORKTREE-DEDUPE` in [Worktree usage guidance](../../docs/worktree-guidance.md#coordination-and-collision-checks).
 6. **Main-checkout mutation**: See `WORKTREE-DEFAULT-USE` in [Worktree usage guidance](../../docs/worktree-guidance.md#default-rule-use-a-worktree-for-mutating-local-work).
 7. **Spelunking tooling internals instead of using the public surface**: Do not read installed package internals, scan tooling source, or run ad-hoc scripts to understand a tool's behavior. Use the CLI, its `--help` subcommands, and `skills/docs/`. Read tool source only when the task is to inspect or change that tool, or when a concrete failure path is inside it and no public CLI/docs path exists. Once a failure is concrete, search changed files for the exact pattern — don't run duplicate broad searches.
 8. **Hand-editing the queue file when a board is configured**: When a GitHub Projects board is configured (`queue.projectNumber`/`queue.boardTitle` in `.devloops`), the board is the authoritative queue MEMBERSHIP and ordering source — not just status. Add work via the board (`dev-loops queue add ... --next-up` to land directly in the normative `Next Up` pickup queue; default lands in Backlog, which is unprioritized intake and never auto-picked), not by hand-editing `.pi/dev-loop-queue.json`; the queue runner reconciles board `Next Up` items into queue entries before each run. See the operator guides under `docs/` (queue board usage/setup) for the workflow.
-9. **Hand-rolling a fan-in wait by polling a subagent transcript or parsing tool JSON with `node -e`/`python3`**: When awaiting fan-out reviewers (gate `draft_gate`/`pre_approval_gate` sub-loops, or any Agent-tool fan-out), NEVER tail/parse another agent's JSONL transcript, NEVER use `node -e`/`python3` to parse tool/subagent JSON, and NEVER `sleep`-poll in a shell loop for completion. These improvisations breach the [internal-tooling-only rule (issue #982)](retrospective-checkpoint-contract.md#internal-tooling-only-rule-issue-982--now-advisory) (no `node -e`/`python3` parsing of tool JSON) and the no-shell-polling rule, and a single improvised wait adds a non-empty entry to the advisory `retrospectiveFindings.rawCallViolations` array (issue #1077: reported to the conductor, **never blocking**). **Sanctioned wait:** rely on the harness completion notification, or read each reviewer's findings artifact at its deterministic output path (see [Checkpoint Review Chain Contract](../../docs/gate-review-sub-loop-contract.md) Phase 2), then join via `consolidateFanin` from `@dev-loops/core/loop/gate-fanin` (Phase 3). See also the dev-loop SKILL "Bounded async task contract".
+9. <!-- rule: ANTIPATTERN-FANIN-WAIT --> `ANTIPATTERN-FANIN-WAIT` — **Hand-rolling a fan-in wait by polling a subagent transcript or parsing tool JSON with `node -e`/`python3`**: When awaiting fan-out reviewers (gate `draft_gate`/`pre_approval_gate` sub-loops, or any Agent-tool fan-out), NEVER tail/parse another agent's JSONL transcript, NEVER use `node -e`/`python3` to parse tool/subagent JSON, and NEVER `sleep`-poll in a shell loop for completion. These improvisations breach the [internal-tooling-only rule (issue #982)](retrospective-checkpoint-contract.md#internal-tooling-only-rule-issue-982--now-advisory) (no `node -e`/`python3` parsing of tool JSON) and the no-shell-polling rule, and a single improvised wait adds a non-empty entry to the advisory `retrospectiveFindings.rawCallViolations` array (issue #1077: reported to the conductor, **never blocking**). **Sanctioned wait:** rely on the harness completion notification, or read each reviewer's findings artifact at its deterministic output path (see [Checkpoint Review Chain Contract](../../docs/gate-review-sub-loop-contract.md) Phase 2), then join via `consolidateFanin` from `@dev-loops/core/loop/gate-fanin` (Phase 3). See also the dev-loop SKILL "Bounded async task contract".
 10. **Ad hoc `gh api graphql` review-thread queries or `gh pr checks`/shell-pipe CI polling**: Do not hand-write a GraphQL query to enumerate review threads, and do not wrap `gh pr checks` in an `awk`/`grep`/`until`-based shell loop to wait for CI. Enumerate threads (with the ids `reply-resolve-review-thread.mjs` needs) via `scripts/github/list-review-threads.mjs`; block on current-head CI settling via `scripts/github/wait-pr-checks.mjs` (or `dev-loops loop watch-ci` for the JSON-status variant); read the aggregate loop/CI/thread state via `detect-copilot-loop-state.mjs` instead of re-deriving it from raw `gh` output.
 
 ## Light mode exception
 
-Small scoped changes (≤3 files, ≤200 lines) may skip fan-out/fan-in but must still run validation and a single review pass. See [Local Implementation](../local-implementation/SKILL.md) for details.
+Small scoped changes under the configured `localImplementation.lightMode` thresholds (owned by `LOCAL-LIGHT-MODE-CONFIG-SURFACE` in [Local Implementation](../local-implementation/SKILL.md)) may skip fan-out/fan-in but must still run validation and a single review pass.
 
 ## Cross-references
 

package/skills/docs/artifact-authority-contract.md

@@ -1,17 +1,19 @@
 # Artifact authority contract
 
-This document is the canonical authority for the artifact-selection model: whether a work item originates from a GitHub issue (tracker-first) or from a persisted markdown plan file (local-planning).
+Canonical owner for the artifact-selection model: whether a work item originates from a GitHub issue (tracker-first), a persisted markdown plan file (local-planning), or the sanctioned lightweight PR-body-as-spec path.
 
 This canonical owner lives in the shipped `skills/docs/` surface because installed skill/runtime consumers reliably own the skills subtree. In installed layouts, read the same contract via [Artifact Authority Contract](../docs/artifact-authority-contract.md) from the installed skill directory.
 
 Other repo docs may summarize or link this contract, but they should not redefine it.
 
-## Two-tier model
+## Three-origin model
 
 <!-- rule: ARTIFACT-TWO-TIER-EXCLUSIVE -->
-dev-loops supports two mutually exclusive artifact authority modes. Every work item MUST originate from exactly one authoritative artifact: a GitHub issue or a persisted markdown plan file. Work MUST NOT originate from a PR or a direct local change unless explicitly requested.
+<!-- The rule ID predates the three-origin wording below (it was written when the
+     model was two-tier); retained as-is for ID stability, not renamed. -->
+dev-loops supports three mutually exclusive artifact authority origins. Every work item MUST originate from exactly one authoritative artifact: a GitHub issue, a persisted markdown plan file, or — on the sanctioned lightweight path — the PR description itself as the spec-of-record (no committed plan artifact). Work MUST NOT originate from a PR (other than the sanctioned lightweight PR-body-as-spec path) or a direct local change unless explicitly requested.
 
-The shipped extension default selects local-planning; see [Shipped default posture](#shipped-default-posture) below. The mode names that follow describe the two tiers; "default" in their headings refers to the local-first code-level default in `BUILT_IN_DEFAULTS`.
+The shipped extension default selects local-planning; see [Shipped default posture](#shipped-default-posture) below. The mode names that follow describe the origins; "default" in their headings refers to the local-first code-level default in `BUILT_IN_DEFAULTS`.
 
 ### Tracker-first
 

package/skills/docs/confirmation-rules.md

@@ -5,7 +5,7 @@ Canonical owner for agent confirmation / authorization rules across all workflow
 ## Core rule
 
 <!-- rule: CONFIRM-CORE-EXPLICIT -->
-Before any state-changing action, get explicit confirmation unless the latest user message already clearly authorizes that exact action.
+`CONFIRM-CORE-EXPLICIT`: Before any state-changing action, the agent MUST obtain explicit confirmation unless the latest user message already clearly authorizes that exact action.
 
 ## What counts as confirmation
 

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

@@ -1,6 +1,6 @@
 # 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`.
+Canonical owner for operating the deterministic Copilot PR follow-up state machine — the operational reference for the routed `copilot_pr_followup`, `wait_watch`, `reviewer_fixer`, and `final_approval` paths behind `dev-loop`. The machine's states and transitions are defined by [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md).
 
 Use it together with:
 - [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md)
@@ -162,12 +162,14 @@ When you do hand work to Copilot:
 
 ## PR description contract
 
+This section governs tracker-backed (Copilot-handoff) PRs; issue-less/plan-file-backed PRs are governed by merge precondition 7 in merge-preconditions.md instead.
+
 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 `- `.
 
 <!-- rule: OPS-DRAFT-FIRST-PR -->
-`OPS-DRAFT-FIRST-PR`: 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) — mechanically enforced by the `create-pr.mjs` wrapper below. Agents MUST 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.
+`OPS-DRAFT-FIRST-PR`: New PRs in this workflow MUST always be opened as **draft** PRs — mechanically enforced by the `create-pr.mjs` wrapper below, which is unconditionally draft-only and rejects `--ready`. Agents MUST NOT create a fresh PR directly in ready-for-review state; `gh pr ready` (via the `ready-for-review.mjs` wrapper) is the only path out of draft, gated on clean draft-gate evidence. This rule owns the draft-first mechanism itself; [TRACKER-PROJECTION-REQUIRED-METADATA](./tracker-first-loop-state.md#31-required-pr-metadata) owns the tracker-facing "PR MUST start as a draft" metadata expectation. 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-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 and self-assigning the PR by default (`--assignee @me`).
 

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

@@ -26,6 +26,15 @@ For **all new ideas** that are not already anchored to an existing issue (includ
 - 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
 
+**Quick-capture exemption:** board quick-capture enqueue (the `/loop-enqueue` freeform
+path — freeform text turned directly into a minimal issue, gated on explicit human
+approval, then grilled inline and added to the board) MAY defer the up-front proposal
+artifact, the async classification pass, the async fan-out/fan-in proposal generation, and
+the second async mutation pass; its inline confirm→create→grill steps stand in for them,
+with grilling supplying classification/refinement after creation. The human-gated-mutation
+and create-new-only safeties still apply — it always creates a new issue and never
+repurposes/overwrites an existing one.
+
 Deterministic intake + mutation-gate state machine:
 
 ```text
@@ -127,15 +136,15 @@ Preflight verdicts:
   - `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
+  - <!-- rule: INTAKE-TIMEOUT-ROUTE-ON-SEAM-EXIT --> `INTAKE-TIMEOUT-ROUTE-ON-SEAM-EXIT`: 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 per [FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION](public-dev-loop-contract.md): 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
+  - <!-- rule: INTAKE-TIMEOUT-SURFACE-BUDGET-EXHAUSTED --> `INTAKE-TIMEOUT-SURFACE-BUDGET-EXHAUSTED`: 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
+- <!-- rule: INTAKE-REPO-SLUG-RESOLVE-FIRST --> `INTAKE-REPO-SLUG-RESOLVE-FIRST`: 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:

package/skills/docs/merge-preconditions.md

@@ -39,13 +39,15 @@ doing manually; it is not a general conflict-resolution engine.
 ## Required before merge
 
 <!-- rule: MERGE-PRECOND-REQUIRED -->
+Before merge, ALL of the following MUST hold:
+
 1. ✅ Conflict-free with base (`mergeable: MERGEABLE`; not `CONFLICTING`/`DIRTY`/`BEHIND`/`UNKNOWN`)
 2. ✅ CI green on current head (or crediblyGreen via `--local-validation-head-sha`)
 3. ✅ Draft gate satisfied — clean `draft_gate` verdict per `GATE-COMMENT-VERDICT-VALUES` ([Checkpoint Verdict Comment Contract](../../docs/gate-review-comment-contract.md))
 4. ✅ Pre-approval gate satisfied — clean `pre_approval_gate` verdict on the current head, same rule
 5. ✅ All review threads resolved
 6. ✅ Explicit merge authorization from operator
-7. ✅ Issue-backed work: PR body contains `Closes #N` or `Fixes #N`; for an issue-less lightweight PR the closing reference is instead absent by design (owned by `ARTIFACT-LIGHTWEIGHT-BODY-INVARIANTS` in [Artifact Authority Contract](artifact-authority-contract.md))
+7. ✅ Closing-reference state matches artifact backing, each arm owned by a different contract: tracker-backed work — PR body contains `Closes #N` or `Fixes #N` (owned by the PR description contract in [copilot-loop-operations.md](copilot-loop-operations.md)); issue-less lightweight (PR-body-as-spec, no backing issue) — the closing reference is absent by design and `node scripts/loop/validate-pr-body-spec.mjs --repo <owner/name> --pr <number> --no-issue` passes clean (owned by `ARTIFACT-LIGHTWEIGHT-BODY-INVARIANTS` in [Artifact Authority Contract](artifact-authority-contract.md)); plan-file promotion (P4) — the PR body carries the committed plan-doc path as the spec-of-record and, being issue-less by design (`buildPromotionPrBody` neutralizes closing keywords), the closing reference MUST NOT be present
 8. ✅ PR **title** free of merge-blocking markers — `WIP`, `[WIP]`, `DRAFT`, `DO NOT MERGE`, `🚧` (case-insensitive)
 
 > Runner-coordination lock: the pre-merge evidence check fails closed on a stale/foreign runner claim for the PR. A completing run releases its claim best-effort at every terminal stop (including the human approval checkpoint), so a merge re-dispatch normally proceeds. If a lock held by a completed/dead run still blocks the merge, take it over explicitly with `node <resolved-skill-scripts>/loop/pr-runner-coordination.mjs takeover --repo <owner/name> --pr <number>`. Never take over a genuinely active (non-stale) run — that fail-closed block is intentional.
@@ -80,9 +82,9 @@ A marker is allowed only while the PR is still in draft; it must be removed befo
 
 ## Merge authorization
 
-- Must be explicit for the active issue/PR scope
+- 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
+- Implied approval from prior turns MUST NOT be treated as sufficient
 
 ### `autonomy.humanMergeOnly` — fixed human-only merge (non-overridable)
 

package/skills/docs/pr-lifecycle-contract.md

@@ -80,7 +80,7 @@ This gate uses review angles resolved from config (`resolveGateAngles(config, "p
 Boundary note:
 - `pre_approval_gate` governs only final approval readiness for the reviewed head
 - a clean verdict requires no findings at any severity in the gate's `blockCleanOnFindingSeverities` (resolved from config via `resolveGateConfig(config, "preApproval").blockCleanOnFindingSeverities`)
-- non-draft PRs do not need visible `draft_gate` evidence to enter the post-draft review / `pre_approval_gate` lifecycle; only the draft -> ready transition depends on `draft_gate`
+- non-draft PRs do not need *per-head* `draft_gate` evidence to enter the post-draft review / `pre_approval_gate` lifecycle — the one-time draft -> ready transition record still applies; a non-draft PR with no clean `draft_gate` evidence at all fails closed and must reconcile that missing evidence first (see the current-head `draft_gate` evidence bullet under [Fail-closed rules](#fail-closed-rules))
 
 ## Lifecycle states
 

package/skills/docs/public-dev-loop-contract.md

@@ -72,7 +72,8 @@ Use this taxonomy consistently across docs, discovery surfaces, and tests:
 | Internal routed strategy modules | `issue-intake`, `copilot-pr-followup`, `local-implementation`, `final-approval` | keep internal-only behind `dev-loop`; do not expose as executable peer workflow entrypoints |
 | Reusable role agents | `developer`, `docs`, `review`, `fixer`, `quality`, `refiner` | keep framed as reusable building blocks, not peer public workflow entrypoints |
 
-Any remaining specialized Copilot behavior stays internal-only behind `dev-loop`.
+<!-- rule: FACADE-COPILOT-INTERNAL-ONLY -->
+`FACADE-COPILOT-INTERNAL-ONLY`: Any remaining specialized Copilot behavior stays internal-only behind `dev-loop`.
 
 <!-- rule: FACADE-TAXONOMY-DRIFT-TEST -->
 `FACADE-TAXONOMY-DRIFT-TEST`: Regression tests MUST fail if this taxonomy drifts in wording or surfaced entrypoint assets.