@dev-loops/core 0.1.0

package/src/loop/issue-refinement-artifact.mjs

@@ -0,0 +1,268 @@
+/**
+ * Deterministic issue refinement-artifact detection.
+ *
+ * Implements the bounded refinement check required by the draft gate per
+ * issue #532: a draft PR cannot leave draft unless the linked issue has an
+ * explicit refinement artifact (Acceptance criteria section, DoD section,
+ * or a linked refinement doc) that the pre-approval gate can verify
+ * against. Prose-only issues (Problem / Root Cause / Fix) without an
+ * `Acceptance criteria` or `DoD` section cause the draft gate to post
+ * `verdict=blocked` with the `missing_refinement_artifact` finding.
+ *
+ * This module owns:
+ * - canonical section-name matching for AC / DoD blocks
+ * - bullet-item extraction (both `- [ ]` and `- [x]`)
+ * - linked-refinement-doc detection from issue body
+ *
+ * It deliberately does NOT:
+ * - auto-generate ACs from prose
+ * - mutate GitHub state
+ * - re-implement the issue<->PR linkage detection (callers own that)
+ */
+
+export const REFINEMENT_SOURCE = Object.freeze({
+  ISSUE_BODY_AC: "issue-body-ac",
+  ISSUE_BODY_DOD: "issue-body-dod",
+  LINKED_DOC: "linked-doc",
+  MISSING: "missing",
+});
+
+const REFINEMENT_ARTIFACT_FINDING = "missing_refinement_artifact";
+
+/**
+ * Canonical list of section headings that satisfy the refinement check.
+ * Matching is case-insensitive and tolerates trailing/leading whitespace.
+ * The two-element minimum keeps the contract explicit:
+ *   - one AC section (Acceptance criteria)
+ *   - one DoD-style section (DoD or Definition of Done)
+ */
+const ACCEPTANCE_SECTION_PATTERNS = Object.freeze([
+  /^acceptance criteria\s*$/i,
+  /^ac\b.*$/i,
+]);
+
+const DOD_SECTION_PATTERNS = Object.freeze([
+  /^definition of done\s*$/i,
+  /^done\s*$/i,
+  /^dod\s*$/i,
+]);
+
+/**
+ * Extract `## ...` heading boundaries from a Markdown body.
+ * Returns a sorted array of { level, name, bodyLines } records.
+ */
+export function parseMarkdownSections(body) {
+  if (typeof body !== "string" || body.length === 0) {
+    return [];
+  }
+
+  const lines = body.split(/\r?\n/u);
+  const sections = [];
+  let current = null;
+
+  for (const line of lines) {
+    const match = /^(#{1,6})\s+(.+?)\s*$/u.exec(line);
+    if (match) {
+      if (current) {
+        sections.push(current);
+      }
+      current = {
+        level: match[1].length,
+        name: match[2],
+        bodyLines: [],
+      };
+      continue;
+    }
+    if (current) {
+      current.bodyLines.push(line);
+    }
+  }
+
+  if (current) {
+    sections.push(current);
+  }
+
+  return sections;
+}
+
+function findSectionByPatterns(sections, patterns) {
+  for (const section of sections) {
+    for (const pattern of patterns) {
+      if (pattern.test(section.name)) {
+        return section;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract checklist bullet items (`- [ ]` and `- [x]`) from a section body.
+ * Returns the trimmed item text for each matching line. The checkbox state
+ * (checked vs unchecked) is intentionally not preserved: callers only need
+ * the item text to satisfy the refinement-artifact contract.
+ */
+export function extractChecklistItems(sectionBody) {
+  if (typeof sectionBody !== "string" || sectionBody.length === 0) {
+    return [];
+  }
+
+  const items = [];
+  const lines = sectionBody.split(/\r?\n/u);
+
+  for (const line of lines) {
+    const match = /^\s*-\s+\[(?:[ xX])\]\s+(.+?)\s*$/u.exec(line);
+    if (match) {
+      const text = match[1].trim();
+      if (text.length > 0) {
+        items.push(text);
+      }
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Detect a linked refinement doc path from the issue body.
+ * Looks for explicit `tmp/refinement/<n>-plan.md` style paths and the
+ * `## Refinement` / `## Plan` / `## Refinement doc` sections.
+ */
+export function detectLinkedRefinementDoc(body) {
+  if (typeof body !== "string" || body.length === 0) {
+    return { found: false, path: null, reason: "empty-body" };
+  }
+
+  const pathMatch = /(?:^|\s|[`(\[<])(tmp\/refinement\/[A-Za-z0-9._/\-]+\.md)\b/u.exec(body);
+  if (pathMatch) {
+    return { found: true, path: pathMatch[1], reason: "explicit-path" };
+  }
+
+  const sections = parseMarkdownSections(body);
+  const refinementSection = findSectionByPatterns(sections, [
+    /^refinement doc\s*$/i,
+    /^refinement\s*$/i,
+    /^plan doc\s*$/i,
+    /^plan\s*$/i,
+  ]);
+  if (refinementSection) {
+    const inlinePath = /(?:^|\s)(tmp\/refinement\/[^\s)`'"]+\.md)\b/u.exec(refinementSection.bodyLines.join("\n"));
+    if (inlinePath) {
+      return { found: true, path: inlinePath[1], reason: "refinement-section-path" };
+    }
+  }
+
+  return { found: false, path: null, reason: "no-linked-doc" };
+}
+
+/**
+ * Detect the refinement artifact on a parsed issue body.
+ *
+ * @param {object} input
+ * @param {string} [input.body]  Raw issue body Markdown.
+ * @param {number} [input.issueNumber]  Issue number, used for linked-doc convention.
+ * @returns {{
+ *   hasACs: boolean,
+ *   source: string,
+ *   acItems: string[],
+ *   dodItems: string[],
+ *   sections: string[],
+ *   linkedDoc: { found: boolean, path: string|null, reason: string },
+ *   reason: string,
+ *   finding: string|null,
+ * }}
+ */
+export function detectIssueRefinementArtifact({ body = "", issueNumber = null } = {}) {
+  if (typeof body !== "string" || body.length === 0) {
+    return {
+      hasACs: false,
+      source: REFINEMENT_SOURCE.MISSING,
+      acItems: [],
+      dodItems: [],
+      sections: [],
+      linkedDoc: { found: false, path: null, reason: "empty-body" },
+      reason: "Issue body is empty; no ACs/DoD/linked-doc can be detected.",
+      finding: REFINEMENT_ARTIFACT_FINDING,
+    };
+  }
+
+  const sections = parseMarkdownSections(body);
+  const sectionNames = sections.map((s) => s.name);
+
+  const acceptanceSection = findSectionByPatterns(sections, ACCEPTANCE_SECTION_PATTERNS);
+  const dodSection = findSectionByPatterns(sections, DOD_SECTION_PATTERNS);
+
+  const acItems = acceptanceSection ? extractChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
+  const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
+
+  const linkedDoc = detectLinkedRefinementDoc(body);
+
+  if (acItems.length > 0) {
+    return {
+      hasACs: true,
+      source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
+      acItems,
+      dodItems,
+      sections: sectionNames,
+      linkedDoc,
+      reason: `Found ${acItems.length} Acceptance criteria checklist item(s) in the issue body.`,
+      finding: null,
+    };
+  }
+
+  if (dodItems.length > 0) {
+    return {
+      hasACs: true,
+      source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
+      acItems,
+      dodItems,
+      sections: sectionNames,
+      linkedDoc,
+      reason: `Found ${dodItems.length} DoD checklist item(s) in the issue body.`,
+      finding: null,
+    };
+  }
+
+  if (linkedDoc.found) {
+    return {
+      hasACs: true,
+      source: REFINEMENT_SOURCE.LINKED_DOC,
+      acItems: [],
+      dodItems: [],
+      sections: sectionNames,
+      linkedDoc,
+      reason: `Issue body links a refinement doc at ${linkedDoc.path}; treating that as the refinement artifact source.`,
+      finding: null,
+    };
+  }
+
+  return {
+    hasACs: false,
+    source: REFINEMENT_SOURCE.MISSING,
+    acItems: [],
+    dodItems: [],
+    sections: sectionNames,
+    linkedDoc,
+    reason: "Issue body has no Acceptance criteria section, no DoD section, and no linked refinement doc.",
+    finding: REFINEMENT_ARTIFACT_FINDING,
+  };
+}
+
+/**
+ * Map a draft-gate refinement check to the result surface consumed by
+ * `evaluatePrGateCoordination`. The mapping keeps the contract
+ * deterministic: the draft gate must not produce a `clean` verdict
+ * for the current head when the refinement check is `missing`.
+ */
+export function summarizeRefinementGateCheck({ body = "", issueNumber = null } = {}) {
+  const artifact = detectIssueRefinementArtifact({ body, issueNumber });
+  const verdict = artifact.hasACs ? "clean" : "blocked";
+  const finding = artifact.finding;
+  return {
+    artifact,
+    verdict,
+    finding,
+    blocking: !artifact.hasACs,
+    reason: artifact.reason,
+  };
+}

package/src/loop/lifecycle-state.mjs

@@ -0,0 +1,342 @@
+/**
+ * Deterministic outer dev-loop lifecycle state model.
+ *
+ * This module defines the sequential lifecycle phases — issue_intake →
+ * refinement → implementation → draft_gate → feedback_resolution →
+ * pre_approval_gate → merge — as a consultable graph so skills use
+ * machine-resolved state instead of restating the flow in prose.
+ *
+ * This module provides:
+ * - LIFECYCLE_STATE: stable phase name constants
+ * - LIFECYCLE_TRANSITIONS: legal transition graph between phases
+ * - LIFECYCLE_GRAPH: metadata (start, end, entry, terminal, nonterminal)
+ * - LIFECYCLE_NEXT_ACTIONS: recommended next action for each phase
+ * - resolveLifecycleState: resolver that maps inputs to one lifecycle phase
+ * - getAllowedTransitions: helper to list allowed next phases
+ * - COPILOT_INNER_STATE_MAP: maps lifecycle phases to copilot-loop-state.mjs inner states
+ *
+ * Contract guarantees:
+ * - One deterministic lifecycle phase per normalized input set
+ * - Ambiguous or incomplete inputs fall back to issue_intake
+ * - Transition graph enforces legal phase progression
+ * - Purely functional; no I/O or side effects
+ *
+ * Integration boundary:
+ * - Skills call resolveLifecycleState to determine current phase
+ * - Copilot-loop-state.mjs remains the inner machine for the Copilot review portion
+ * - Lifecycle phases are the outer sequence; inner states are sub-phase detail
+ */
+
+// ---------------------------------------------------------------------------
+// Exported constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Stable lifecycle phase name constants.
+ *
+ * These are the sequential outer dev-loop phases from issue intake to merge.
+ */
+export const LIFECYCLE_STATE = Object.freeze({
+  /** Issue normalization, scope confirmation, PR linkage detection. */
+  ISSUE_INTAKE: "issue_intake",
+  /** Issue refinement: spec elaboration, audit, acceptance criteria hardening. */
+  REFINEMENT: "refinement",
+  /** Active code implementation (local or Copilot-assisted). */
+  IMPLEMENTATION: "implementation",
+  /** Draft gate review before marking PR ready for review. */
+  DRAFT_GATE: "draft_gate",
+  /** Review feedback fix/reply/resolve loop. */
+  FEEDBACK_RESOLUTION: "feedback_resolution",
+  /** Pre-approval gate before merge. */
+  PRE_APPROVAL_GATE: "pre_approval_gate",
+  /** Final merge step. */
+  MERGE: "merge",
+});
+
+const LIFECYCLE_STATE_VALUES = Object.freeze(Object.values(LIFECYCLE_STATE));
+const LIFECYCLE_STATE_SET = new Set(LIFECYCLE_STATE_VALUES);
+
+/**
+ * Legal transitions between lifecycle phases.
+ *
+ * Each entry lists the phases reachable from the given phase.
+ * Terminal states (merge) have no outgoing transitions.
+ */
+export const LIFECYCLE_TRANSITIONS = Object.freeze({
+  [LIFECYCLE_STATE.ISSUE_INTAKE]: Object.freeze([
+    LIFECYCLE_STATE.REFINEMENT,
+    LIFECYCLE_STATE.IMPLEMENTATION,
+  ]),
+  [LIFECYCLE_STATE.REFINEMENT]: Object.freeze([
+    LIFECYCLE_STATE.ISSUE_INTAKE,
+    LIFECYCLE_STATE.IMPLEMENTATION,
+  ]),
+  [LIFECYCLE_STATE.IMPLEMENTATION]: Object.freeze([
+    LIFECYCLE_STATE.DRAFT_GATE,
+    LIFECYCLE_STATE.FEEDBACK_RESOLUTION,
+  ]),
+  [LIFECYCLE_STATE.DRAFT_GATE]: Object.freeze([
+    LIFECYCLE_STATE.IMPLEMENTATION,
+    LIFECYCLE_STATE.FEEDBACK_RESOLUTION,
+  ]),
+  [LIFECYCLE_STATE.FEEDBACK_RESOLUTION]: Object.freeze([
+    LIFECYCLE_STATE.IMPLEMENTATION,
+    LIFECYCLE_STATE.PRE_APPROVAL_GATE,
+  ]),
+  [LIFECYCLE_STATE.PRE_APPROVAL_GATE]: Object.freeze([
+    LIFECYCLE_STATE.IMPLEMENTATION,
+    LIFECYCLE_STATE.FEEDBACK_RESOLUTION,
+    LIFECYCLE_STATE.MERGE,
+  ]),
+  [LIFECYCLE_STATE.MERGE]: Object.freeze([]),
+});
+
+/** Terminal lifecycle phases — no further progression. */
+export const LIFECYCLE_TERMINAL_STATES = Object.freeze([
+  LIFECYCLE_STATE.MERGE,
+]);
+
+/** Nonterminal lifecycle phases — progression still possible. */
+export const LIFECYCLE_NONTERMINAL_STATES = Object.freeze([
+  LIFECYCLE_STATE.ISSUE_INTAKE,
+  LIFECYCLE_STATE.REFINEMENT,
+  LIFECYCLE_STATE.IMPLEMENTATION,
+  LIFECYCLE_STATE.DRAFT_GATE,
+  LIFECYCLE_STATE.FEEDBACK_RESOLUTION,
+  LIFECYCLE_STATE.PRE_APPROVAL_GATE,
+]);
+
+const LIFECYCLE_TERMINAL_SET = new Set(LIFECYCLE_TERMINAL_STATES);
+
+/** High-level graph metadata for visualization and inspection. */
+export const LIFECYCLE_GRAPH = Object.freeze({
+  start: Object.freeze({ id: "lifecycle_start", label: "Start", semantic: true }),
+  end: Object.freeze({ id: "lifecycle_end", label: "End", semantic: true }),
+  entryState: LIFECYCLE_STATE.ISSUE_INTAKE,
+  entryStates: Object.freeze([...LIFECYCLE_STATE_VALUES]),
+  terminalStates: LIFECYCLE_TERMINAL_STATES,
+  nonterminalStates: LIFECYCLE_NONTERMINAL_STATES,
+});
+
+/** Recommended next action for each lifecycle phase. */
+export const LIFECYCLE_NEXT_ACTIONS = Object.freeze({
+  [LIFECYCLE_STATE.ISSUE_INTAKE]:
+    "Normalize the issue: confirm scope, detect linked PR, and determine readiness.",
+  [LIFECYCLE_STATE.REFINEMENT]:
+    "Refine the issue: elaborate spec, run bounded audit if needed, harden acceptance criteria.",
+  [LIFECYCLE_STATE.IMPLEMENTATION]:
+    "Implement the accepted scope on a feature branch or via Copilot handoff.",
+  [LIFECYCLE_STATE.DRAFT_GATE]:
+    "Run draft gate review before marking the PR ready for review.",
+  [LIFECYCLE_STATE.FEEDBACK_RESOLUTION]:
+    "Address review feedback: fix, reply to, and resolve threads on GitHub.",
+  [LIFECYCLE_STATE.PRE_APPROVAL_GATE]:
+    "Run pre-approval gate review; verify gate evidence, CI, and unresolved threads.",
+  [LIFECYCLE_STATE.MERGE]:
+    "Merge is authorized; run the final merge step and write the retrospective checkpoint.",
+});
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Map an explicit lifecycle phase string to its canonical state value.
+ * Returns the canonical state if recognized, otherwise null.
+ */
+function normalizeLifecycleState(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim().toLowerCase();
+  return LIFECYCLE_STATE_SET.has(trimmed) ? trimmed : null;
+}
+
+/**
+ * Resolve the current lifecycle phase from authoritative inputs.
+ *
+ * Input shape:
+ * ```js
+ * {
+ *   phase,              // explicit phase string (overrides infer)
+ *   hasLinkedPr,        // boolean: open linked PR exists
+ *   prIsDraft,          // boolean: PR is in draft state
+ *   hasUnresolvedThreads, // boolean: unresolved review threads exist
+ *   preApprovalGatePassed, // boolean: current-head pre_approval_gate clean
+ *   mergeAuthorized,    // boolean: explicit merge authorization granted
+ *   isMerged,           // boolean: PR has been merged
+ * }
+ * ```
+ *
+ * Returns:
+ * ```js
+ * {
+ *   state: string,              // canonical lifecycle phase
+ *   allowedTransitions: string[], // legal next phases
+ *   nextAction: string,         // recommended next action
+ *   isTerminal: boolean,        // true if merge (no further progression)
+ * }
+ * ```
+ *
+ * Resolution order (first-match):
+ * 1. Explicit phase → return canonical if recognized, fall through if not
+ * 2. Merged → merge (terminal)
+ * 3. Merge authorized + pre-approval passed + linked PR → merge
+ * 4. Pre-approval passed + PR exists → pre_approval_gate
+ * 5. Unresolved threads + PR exists → feedback_resolution
+ * 6. Draft PR → implementation
+ * 7. Ready PR (not draft) → implementation
+ * 8. No linked PR → issue_intake
+ */
+export function resolveLifecycleState(input = {}) {
+  const {
+    phase = null,
+    hasLinkedPr = false,
+    prIsDraft = false,
+    hasUnresolvedThreads = false,
+    preApprovalGatePassed = false,
+    mergeAuthorized = false,
+    isMerged = false,
+  } = input;
+
+  // 1. Explicit phase override — canonical or fail closed
+  if (phase !== null && phase !== undefined) {
+    const normalized = normalizeLifecycleState(phase);
+    if (normalized) {
+      return buildResult(normalized);
+    }
+    // unrecognized phase: fall through to inference
+  }
+
+  // 2. Merged → terminal
+  if (isMerged) {
+    return buildResult(LIFECYCLE_STATE.MERGE);
+  }
+
+  // 3. Merge authorized with pre-approval + linked PR → merge
+  if (mergeAuthorized && preApprovalGatePassed && hasLinkedPr) {
+    return buildResult(LIFECYCLE_STATE.MERGE);
+  }
+
+  // 4. Pre-approval gate passed (but merge not yet authorized)
+  if (preApprovalGatePassed && hasLinkedPr) {
+    return buildResult(LIFECYCLE_STATE.PRE_APPROVAL_GATE);
+  }
+
+  // 5. Unresolved threads exist → feedback resolution
+  if (hasUnresolvedThreads && hasLinkedPr) {
+    return buildResult(LIFECYCLE_STATE.FEEDBACK_RESOLUTION);
+  }
+
+  // 6. Draft PR → implementation
+  if (prIsDraft && hasLinkedPr) {
+    return buildResult(LIFECYCLE_STATE.IMPLEMENTATION);
+  }
+
+  // 7. PR exists (not draft) → implementation
+  if (hasLinkedPr && !prIsDraft) {
+    return buildResult(LIFECYCLE_STATE.IMPLEMENTATION);
+  }
+
+  // 8. No linked PR → issue intake
+  return buildResult(LIFECYCLE_STATE.ISSUE_INTAKE);
+}
+
+function buildResult(state) {
+  const transitions = LIFECYCLE_TRANSITIONS[state] ?? [];
+  return {
+    state,
+    allowedTransitions: [...transitions],
+    nextAction: LIFECYCLE_NEXT_ACTIONS[state] ?? "",
+    isTerminal: LIFECYCLE_TERMINAL_SET.has(state),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the allowed next phases for a given lifecycle state.
+ * Unknown states return an empty array.
+ */
+export function getAllowedTransitions(state) {
+  if (!LIFECYCLE_STATE_SET.has(state)) return [];
+  return [...(LIFECYCLE_TRANSITIONS[state] ?? [])];
+}
+
+/**
+ * Check whether a transition from one phase to another is legal.
+ */
+export function isTransitionAllowed(fromState, toState) {
+  if (!LIFECYCLE_STATE_SET.has(fromState) || !LIFECYCLE_STATE_SET.has(toState)) {
+    return false;
+  }
+  return LIFECYCLE_TRANSITIONS[fromState].includes(toState);
+}
+
+/**
+ * Check whether a value is a recognized lifecycle state.
+ */
+export function isKnownLifecycleState(value) {
+  return LIFECYCLE_STATE_SET.has(value);
+}
+
+// ---------------------------------------------------------------------------
+// Connection to copilot-loop-state.mjs inner machine
+// ---------------------------------------------------------------------------
+
+/**
+ * Map from outer lifecycle phases to copilot-loop-state.mjs inner machine states.
+ *
+ * Skills use this mapping to determine which inner-machine states are active
+ * during a given lifecycle phase. Not all lifecycle phases have a corresponding
+ * inner-machine state (issue_intake and refinement are outer-only).
+ *
+ * The inner machine is the authority for Copilot review/fix loop states;
+ * this mapping is advisory for routing and status reporting.
+ */
+export const COPILOT_INNER_STATE_MAP = Object.freeze({
+  [LIFECYCLE_STATE.ISSUE_INTAKE]: Object.freeze([]),
+  [LIFECYCLE_STATE.REFINEMENT]: Object.freeze([]),
+  [LIFECYCLE_STATE.IMPLEMENTATION]: Object.freeze([
+    "no_pr",
+    "pr_draft",
+  ]),
+  [LIFECYCLE_STATE.DRAFT_GATE]: Object.freeze([
+    "pr_ready_no_feedback",
+  ]),
+  [LIFECYCLE_STATE.FEEDBACK_RESOLUTION]: Object.freeze([
+    "waiting_for_copilot_review",
+    "unresolved_feedback_present",
+    "already_fixed_needs_reply_resolve",
+    "ready_to_rerequest_review",
+    "waiting_for_ci",
+    "review_request_unavailable",
+    "blocked_needs_user_decision",
+    "round_cap_reached",
+  ]),
+  [LIFECYCLE_STATE.PRE_APPROVAL_GATE]: Object.freeze([
+    "low_signal_converged",
+    "round_cap_clean_fallback",
+    "internal_tooling_direct_gate",
+  ]),
+  [LIFECYCLE_STATE.MERGE]: Object.freeze([
+    "done",
+  ]),
+});
+
+/**
+ * Resolve the lifecycle phase implied by a given copilot-loop-state.mjs inner state.
+ *
+ * Returns the lifecycle phase that typically contains the given inner state,
+ * or null if the inner state maps to no lifecycle phase.
+ */
+export function lifecyclePhaseForCopilotState(copilotState) {
+  if (typeof copilotState !== "string") return null;
+
+  for (const [phase, innerStates] of Object.entries(COPILOT_INNER_STATE_MAP)) {
+    if (innerStates.includes(copilotState)) {
+      return phase;
+    }
+  }
+  return null;
+}