heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/promote-diagnose.mjs

@@ -26,6 +26,10 @@
 import { readSourceFrontmatter, resolveBreakdownSource } from './breakdown-source.mjs';
 import { applyLadder, causeIsKnown, scanExistingCoverage } from './breakdown-ladder.mjs';
 import { executeBreakdownWrites } from './breakdown-writer.mjs';
+import { resolveWriteModeFromDeps, cloudModeUnsupportedWrite } from './promotion-helpers.mjs';
+import { collectOccupiedKeysEitherKindViaTier } from './occupied-keys.mjs';
+import { resolveReadTier } from './read-path.mjs';
+import { effectiveConsoleUrl } from './mcp-config.mjs';
 
 /** Rungs that produce no work at all — the stage reports and writes nothing. */
 const NO_SPAWN_RUNGS = new Set(['no_breakdown', 'no_fixes_listed']);
@@ -65,10 +69,74 @@ export function recommendPlacement(coverage) {
   };
 }
 
+/**
+ * Resolve the file-key occupancy `executeBreakdownWrites` mints against
+ * ([[HS-FJWL]]). The writer is synchronous and no longer scans the vault
+ * itself, so the async, tier-aware resolution happens here.
+ *
+ * In practice the cloud branch is unreachable today — the `writeMode ===
+ * 'cloud'` refusal above returns before any write stage — so this resolves the
+ * disk scan and costs exactly what it did before, zero console calls. It is
+ * wired anyway so the writer is already correct the day that refusal is lifted
+ * (HS-BYU4 §Scope names this path as the follow-on), rather than quietly
+ * minting duplicates the moment it is.
+ *
+ * Returns `{ occupiedKeys }` or `{ error, message }` — never a silent fallback
+ * to the local scan, because that is the blind read this fix removes.
+ */
+async function resolveBreakdownOccupancy(vaultRoot, deps) {
+  try {
+    return {
+      occupiedKeys: await collectOccupiedKeysEitherKindViaTier(vaultRoot, {
+        tier: deps?.tier ?? (await resolveReadTier()),
+        consoleUrl: deps?.consoleUrl ?? effectiveConsoleUrl(),
+        ...(deps?.consoleFetch ? { consoleFetch: deps.consoleFetch } : {}),
+      }),
+    };
+  } catch (err) {
+    return {
+      error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+      message:
+        `Refusing to mint file keys for the breakdown: ${String(err?.message ?? err)}. ` +
+        `In cloud reliance the occupied-key set lives in the console's vault, not on this ` +
+        `machine — minting from the local clone would hand out ids other specs may already hold.`,
+    };
+  }
+}
+
 /**
  * @param {{ vaultRoot: string, args?: Record<string, unknown>, deps?: Record<string, unknown> }} ctx
  */
 export async function executePromoteDiagnose({ vaultRoot, args = {}, deps = {} }) {
+  // Vault WRITE mode ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]),
+  // resolved ONCE here and defaulting to `local` so every pre-existing caller
+  // is byte-identical.
+  //
+  // EXPLICIT DEGRADE (cloud): this module is deliberately thin — it owns the
+  // grounding + sizing decision and delegates EVERY write to
+  // `executeBreakdownWrites` (breakdown-writer.mjs), which mints its own file
+  // keys off a `collectOccupiedKeysEitherKind` vault scan and commits through
+  // the disk-only `commitWrites`. Routing those writes through the console is
+  // a change to THAT module, not this one (HS-BYU4 §Scope explicitly lists the
+  // diagnose breakdown path as "same shape, follow after"). Rather than let a
+  // cloud-reliant session write a milestone/epic/task set onto a machine whose
+  // vault the console has never heard of, the stage refuses BEFORE the writer
+  // is reached — the review/no-breakdown phases below are read-only and are
+  // deliberately left reachable.
+  const writeMode = resolveWriteModeFromDeps(deps);
+  const wantsWrites = args.accepted === true;
+  if (writeMode === 'cloud' && wantsWrites) {
+    return cloudModeUnsupportedWrite(
+      'vendor/heyspex-mcp/breakdown-writer.mjs (executeBreakdownWrites)',
+      'the diagnose breakdown writer mints file keys from a local vault scan and commits through the disk-only commitWrites — it has no console (POST/PUT /api/specs) path yet, so a cloud-mode breakdown would write specs the console\'s index never sees',
+      {
+        stage: 'promote_diagnose',
+        follow_up:
+          'Run the breakdown in local (disk) write mode, or convert executeBreakdownWrites to the cloud write path (HS-BYU4 §Scope lists promote-diagnose as the follow-on).',
+      },
+    );
+  }
+
   const ref = args.diagnose_id ?? args.source_id ?? args.spec_id;
   const resolved = resolveBreakdownSource(vaultRoot, ref, { kinds: ['diagnose'] });
   if (resolved.error) {
@@ -131,12 +199,15 @@ export async function executePromoteDiagnose({ vaultRoot, args = {}, deps = {} }
         message: ladder.reason,
       };
     }
+    const measureOccupancy = await resolveBreakdownOccupancy(vaultRoot, deps);
+    if (measureOccupancy.error) return { ...base, placement: measurePlacement, ...measureOccupancy };
     const measured = executeBreakdownWrites({
       vaultRoot,
       source,
       sourceFrontmatter: frontmatter,
       ladder,
       placement: measurePlacement,
+      occupiedKeys: measureOccupancy.occupiedKeys,
       args,
       deps,
     });
@@ -165,12 +236,15 @@ export async function executePromoteDiagnose({ vaultRoot, args = {}, deps = {} }
     };
   }
 
+  const occupancy = await resolveBreakdownOccupancy(vaultRoot, deps);
+  if (occupancy.error) return { ...base, placement, ...occupancy };
   const written = executeBreakdownWrites({
     vaultRoot,
     source,
     sourceFrontmatter: frontmatter,
     ladder,
     placement,
+    occupiedKeys: occupancy.occupiedKeys,
     args,
     deps,
   });

package/vendor/heyspex-mcp/promote-research-to-diagnose.mjs

@@ -34,7 +34,7 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
-import { familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { collectOccupiedKeysEitherKind, familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
 import { buildDiagnoseSkeletonSections } from './diagnose-skeleton.mjs';
 import {
@@ -278,7 +278,14 @@ export async function executePromoteResearchToDiagnose(vaultRoot, args = {}, dep
     mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit });
   // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
   // and (V3) the anchor for `id:` itself.
-  const fileKey = mintFileKey(vaultRoot, { randomUnit: deps?.randomUnit });
+  // Disk occupancy ([[HS-FJWL]]). NOT tier-aware, and knowingly so: this
+  // module has no cloud write path at all — it commits through the disk-only
+  // `commitWrites` into `specs/diagnoses/`, so a cloud-reliant session is
+  // already broken here in a larger way than the id mint (same shape as the
+  // refusal promote-diagnose.mjs raises for breakdown-writer). Wire the
+  // occupancy through `collectOccupiedKeysEitherKindViaTier` when the writer
+  // itself learns the console path.
+  const fileKey = mintFileKey(collectOccupiedKeysEitherKind(vaultRoot), { randomUnit: deps?.randomUnit });
   const diagnoseId = `HS-${fileKey}`;
   const diagnoseBasename = `${diagnoseId}-${familyKey}-DIAG-${slug}`;
   const diagnoseRelPath = `specs/diagnoses/${diagnoseBasename}.md`;