heyspex 0.1.0

package/vendor/heyspex-mcp/plan-ground-conflicts.mjs

@@ -0,0 +1,321 @@
+/**
+ * Conflict / drift analysis for hs-ground — same engine as console On Deck
+ * ([[HS-EPIC-6RKN-spec-conflict-detection-pre-flight-check]], GET /api/specs/:id/conflicts).
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, basename as pathBasename } from 'node:path';
+import {
+  detectSpecConflicts,
+  extractBehavioralClaims,
+  findConflicts,
+  resolveWikilink,
+  extractWikilinks,
+} from './plan-push.mjs';
+
+const SOURCE_OF_TRUTH_RULES = [
+  {
+    layer: 'L1',
+    spec: 'heyspex-north-star',
+    rule: 'North-star wins on vision and product intent conflicts.',
+  },
+  {
+    layer: 'L2',
+    spec: 'architecture-pillars',
+    rule: 'Pillars win on milestone scope and system-shape conflicts.',
+  },
+  {
+    layer: 'memory-decision',
+    rule: 'Memory decisions/lessons are authoritative for documented implementation choices.',
+  },
+  {
+    layer: 'protocol',
+    rule: 'Default: **protocol specs** are source of truth for stable product behavior.',
+  },
+  {
+    layer: 'epic',
+    rule: 'Epics may supersede protocols only with explicit override ([[hs-resolve]] Option A/C).',
+  },
+  {
+    layer: 'console',
+    rule: 'Focused epic conflicts use the same detector as Console **On Deck** and **Specs** (`/api/specs/:id/conflicts`).',
+  },
+];
+
+function readSpecContent(vaultRoot, specBasename) {
+  const path = resolveWikilink(vaultRoot, specBasename);
+  if (!path) return null;
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { frontmatter: {}, body: content };
+  const body = content.slice(match[0].length).trim();
+  const frontmatter = {};
+  const lines = match[1].split(/\r?\n/);
+  let currentArray = null;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const arrayItem = line.match(/^\s+-\s*(.*)$/);
+    if (arrayItem && currentArray) {
+      currentArray.push(arrayItem[1].trim().replace(/^["']|["']$/g, ''));
+      continue;
+    }
+    const keyMatch = line.match(/^(\w[\w_-]*):\s*(.*)$/);
+    if (keyMatch) {
+      const key = keyMatch[1];
+      const value = keyMatch[2].trim();
+      currentArray = null;
+      if (value === '') {
+        frontmatter[key] = [];
+        currentArray = frontmatter[key];
+      } else {
+        frontmatter[key] = value.replace(/^["']|["']$/g, '');
+      }
+    }
+  }
+  return { frontmatter, body };
+}
+
+function normalizeConflict(raw, meta) {
+  return {
+    ...raw,
+    source: meta.source,
+    severity: meta.severity || 'blocker',
+    spec_a: meta.spec_a || raw.epic_source || null,
+    spec_b: meta.spec_b || raw.spec,
+    recommended_source_of_truth: meta.recommended_source_of_truth || 'protocol',
+    rationale: meta.rationale || SOURCE_OF_TRUTH_RULES[3].rule,
+    resolve_before_context: meta.resolve_before_context !== false,
+    console_ui_note:
+      meta.source === 'focused_epic'
+        ? 'Also visible in Console On Deck / Specs editor for the focused epic.'
+        : null,
+  };
+}
+
+function detectPairwiseDrift(vaultRoot, basenameA, basenameB) {
+  const contentA = readSpecContent(vaultRoot, basenameA);
+  const contentB = readSpecContent(vaultRoot, basenameB);
+  if (!contentA || !contentB) return [];
+
+  const claimsA = extractBehavioralClaims(contentA, basenameA);
+  const claimsB = extractBehavioralClaims(contentB, basenameB);
+  if (claimsA.length === 0 || claimsB.length === 0) return [];
+
+  const aVsB = findConflicts(claimsA, claimsB);
+  const bVsA = findConflicts(claimsB, claimsA);
+
+  const merged = [];
+  const seen = new Set();
+
+  for (const c of [...aVsB, ...bVsA]) {
+    const key = [basenameA, basenameB, c.action, c.spec_claim].sort().join('|');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(
+      normalizeConflict(c, {
+        source: 'cross_spec_drift',
+        spec_a: basenameA,
+        spec_b: basenameB,
+        epic_source: basenameA,
+        recommended_source_of_truth: 'resolve_interactively',
+        rationale: `Drift between [[${basenameA}]] and [[${basenameB}]] — pick one authority (usually protocol for behavior, epic only if superseding).`,
+        resolve_before_context: true,
+      }),
+    );
+  }
+  return merged;
+}
+
+/**
+ * @param {string} vaultRoot
+ * @param {object} options
+ * @param {string} [options.topic]
+ * @param {string} [options.summary] - draft plan / chat description
+ * @param {string[]} [options.protocolBasenames]
+ * @param {Array<{basename: string, relevance: number, type?: string}>} [options.topSpecs]
+ * @param {boolean} [options.check_focus_epic]
+ * @param {string} [options.focusSpecPath] - Neon layer-2 focus selection spec_path,
+ *   injected at the async handler boundary ([[HS-TASK-FSEL]]); takes precedence
+ *   over the dormant `.heyspex/focus.yaml` on a Neon-up machine.
+ */
+export function analyzeGroundingConflicts(vaultRoot, options = {}) {
+  const {
+    topic = '',
+    summary = '',
+    protocolBasenames = [],
+    topSpecs = [],
+    check_focus_epic = true,
+    focusSpecPath = null,
+  } = options;
+
+  const allConflicts = [];
+  const linkedSpecsChecked = new Set();
+  let focusedEpicId = null;
+  let focusedEpicPath = null;
+
+  // 1) Focused epic (same as hs-resolve / console On Deck). The Neon layer-2
+  // selection is injected as `focusSpecPath` at the async handler boundary
+  // ([[HS-TASK-FSEL]]). There is no `.heyspex/focus.yaml` fallback
+  // ([[no-fallbacks-by-default]]) — when the console is unreachable / no focus
+  // is set, the focused-epic conflict check is simply skipped.
+  if (check_focus_epic) {
+    const focusPath = focusSpecPath;
+    if (focusPath && existsSync(join(vaultRoot, focusPath))) {
+      try {
+        const epicContent = readFileSync(join(vaultRoot, focusPath), 'utf8');
+        const { frontmatter } = parseFrontmatter(epicContent);
+        if (frontmatter.type === 'epic') {
+          focusedEpicId = frontmatter.id || pathBasename(focusPath, '.md');
+          focusedEpicPath = focusPath;
+          const related = extractWikilinks(frontmatter.related || []);
+          const { conflicts, linked_specs_checked } = detectSpecConflicts(
+            vaultRoot,
+            epicContent,
+            related,
+          );
+          linked_specs_checked.forEach((s) => linkedSpecsChecked.add(s));
+          for (const c of conflicts) {
+            allConflicts.push(
+              normalizeConflict(c, {
+                source: 'focused_epic',
+                spec_a: focusedEpicId,
+                spec_b: c.spec,
+                recommended_source_of_truth: 'protocol',
+                rationale:
+                  'On-deck epic vs linked protocol — resolve via /hs-resolve before grounding a new plan on stale claims.',
+                resolve_before_context: true,
+              }),
+            );
+          }
+        }
+      } catch {
+        /* skip */
+      }
+    }
+  }
+
+  // 2) Draft plan (topic + summary) vs governing protocols
+  const draftBody = [
+    `# Draft plan: ${topic}`,
+    '',
+    summary || topic,
+    '',
+    '## Proposed behavior',
+    '',
+    summary,
+  ].join('\n');
+
+  const protocolSet = [
+    ...new Set([
+      ...protocolBasenames,
+      ...topSpecs.filter((s) => s.type === 'protocol' || String(s.basename).includes('protocol')).map((s) => s.basename),
+    ]),
+  ].slice(0, 12);
+
+  if (draftBody.trim().length > 20 && protocolSet.length > 0) {
+    const { conflicts, linked_specs_checked } = detectSpecConflicts(
+      vaultRoot,
+      draftBody,
+      protocolSet,
+    );
+    linked_specs_checked.forEach((s) => linkedSpecsChecked.add(s));
+    for (const c of conflicts) {
+      allConflicts.push(
+        normalizeConflict(c, {
+          source: 'draft_plan',
+          spec_a: '(draft plan from hs-ground)',
+          spec_b: c.spec,
+          recommended_source_of_truth: 'protocol',
+          rationale:
+            'Draft plan contradicts a governing protocol — align draft or update protocol before using as plan context.',
+          resolve_before_context: true,
+        }),
+      );
+    }
+  }
+
+  // 3) Cross-spec drift among high-relevance discoveries (pairwise)
+  const driftCandidates = topSpecs
+    .filter((s) => s.relevance >= 3)
+    .slice(0, 6)
+    .map((s) => s.basename);
+
+  for (let i = 0; i < driftCandidates.length; i++) {
+    for (let j = i + 1; j < driftCandidates.length; j++) {
+      const pairDrift = detectPairwiseDrift(vaultRoot, driftCandidates[i], driftCandidates[j]);
+      allConflicts.push(...pairDrift);
+    }
+  }
+
+  const conflictedBasenames = new Set();
+  for (const c of allConflicts) {
+    if (c.spec_b) conflictedBasenames.add(c.spec_b);
+    if (c.spec_a && !String(c.spec_a).includes('draft')) conflictedBasenames.add(c.spec_a);
+    if (c.spec_a && c.spec_b) {
+      conflictedBasenames.add(c.spec_a);
+      conflictedBasenames.add(c.spec_b);
+    }
+  }
+
+  const hasBlocking = allConflicts.some((c) => c.resolve_before_context);
+
+  const recommendations = [];
+  if (allConflicts.length > 0) {
+    recommendations.push({
+      priority: 'blocker',
+      action: 'Resolve conflicts before using conflicting specs as authoritative plan context.',
+      steps: [
+        focusedEpicId
+          ? `Run \`/hs-resolve ${focusedEpicId}\` or open Console **On Deck** for the focused epic.`
+          : 'Run `/hs-resolve` when an epic is on deck, or fix draft/protocol alignment in chat.',
+        'Pick source of truth per row in `conflicts` (default: protocol for behavior; north-star for vision).',
+        'Re-run `/hs-ground` after resolution so `safe_context_specs` is current.',
+      ],
+    });
+  }
+
+  if (focusedEpicId && allConflicts.some((c) => c.source === 'focused_epic')) {
+    recommendations.push({
+      priority: 'info',
+      action: 'Console parity',
+      steps: [
+        `Epic ${focusedEpicId} conflicts match GET /api/specs/${focusedEpicId}/conflicts — same as On Deck UI.`,
+      ],
+    });
+  }
+
+  return {
+    has_blocking_conflicts: hasBlocking,
+    conflict_count: allConflicts.length,
+    conflicts: allConflicts,
+    linked_specs_checked: [...linkedSpecsChecked],
+    focused_epic: focusedEpicId
+      ? { id: focusedEpicId, path: focusedEpicPath, conflicts_in_ui: true }
+      : null,
+    source_of_truth_rules: SOURCE_OF_TRUTH_RULES,
+    conflicted_spec_basenames: [...conflictedBasenames],
+    recommendations,
+    resolve_commands: [
+      focusedEpicId ? `/hs-resolve ${focusedEpicId}` : '/hs-resolve',
+      'Console: On Deck surface → Spec Conflicts section',
+    ],
+  };
+}
+
+/**
+ * @param {string[]} suggestedRelated
+ * @param {Set<string>|string[]} conflictedBasenames
+ */
+export function computeSafeContextSpecs(suggestedRelated, conflictedBasenames) {
+  const blocked = conflictedBasenames instanceof Set
+    ? conflictedBasenames
+    : new Set(conflictedBasenames);
+  return suggestedRelated.filter((b) => !blocked.has(b));
+}