feat(voyage)!: marketplace handoff — rename plugins/ultraplan-local to plugins/voyage [skip-docs]

Session 5 of voyage-rebrand (V6). Operator-authorized cross-plugin scope.

- git mv plugins/ultraplan-local plugins/voyage (rename detected, history preserved)
- .claude-plugin/marketplace.json: voyage entry replaces ultraplan-local
- CLAUDE.md: voyage row in plugin list, voyage in design-system consumer list
- README.md: bulk rename ultra*-local commands -> trek* commands; ultraplan-local refs -> voyage; type discriminators (type: trekbrief/trekreview); session-title pattern (voyage:<command>:<slug>); v4.0.0 release-note paragraph
- plugins/voyage/.claude-plugin/plugin.json: homepage/repository URLs point to monorepo voyage path
- plugins/voyage/verify.sh: drop URL whitelist exception (no longer needed)

Closes voyage-rebrand. bash plugins/voyage/verify.sh PASS 7/7. npm test 361/361.

plugins/voyage/lib/util/atomic-write.mjs

@@ -0,0 +1,14 @@
+// lib/util/atomic-write.mjs
+// Atomic JSON file write — writes to {path}.tmp then renames to {path}.
+// Crash-safe: a partial write leaves the original file untouched.
+//
+// Extracted from hooks/scripts/pre-compact-flush.mjs in v3.3.0 so that
+// session-state writers and progress.json writers share one implementation.
+
+import { writeFileSync, renameSync } from 'node:fs';
+
+export function atomicWriteJson(path, obj) {
+  const tmp = path + '.tmp';
+  writeFileSync(tmp, JSON.stringify(obj, null, 2));
+  renameSync(tmp, path);
+}

plugins/voyage/lib/util/autonomy-gate.mjs

@@ -0,0 +1,129 @@
+// lib/util/autonomy-gate.mjs
+// Autonomy-gate state machine for /trekexecute + /trekplan
+// (plan-v2 Step 4 — drives the --gates flag).
+//
+// States:
+//   idle             — not yet started
+//   gates_on         — gates enabled, between phases
+//   auto_running     — running phases continuously without pausing
+//   paused_for_gate  — stopped at a phase boundary; awaiting `resume`
+//   completed        — terminal
+//
+// Events:
+//   start            — begin a run (gates flag chooses route)
+//   phase_boundary   — a phase finished
+//   resume           — operator confirmed; leave the gate
+//   finish           — pipeline reached its end
+//
+// CLI shim:
+//   node lib/util/autonomy-gate.mjs --state X --event Y [--gates true|false]
+//   → JSON: { ok: true, next_state: "..." }   (success)
+//   → JSON: { ok: false, error: "..." }       (invalid transition; exit 1)
+//
+// Pure data; no I/O. Re-entry to `completed` is idempotent.
+
+export const STATES = Object.freeze({
+  IDLE: 'idle',
+  GATES_ON: 'gates_on',
+  AUTO_RUNNING: 'auto_running',
+  PAUSED_FOR_GATE: 'paused_for_gate',
+  COMPLETED: 'completed',
+});
+
+export const EVENTS = Object.freeze({
+  START: 'start',
+  PHASE_BOUNDARY: 'phase_boundary',
+  RESUME: 'resume',
+  FINISH: 'finish',
+});
+
+const STATE_SET = new Set(Object.values(STATES));
+const EVENT_SET = new Set(Object.values(EVENTS));
+
+/**
+ * Compute the next state given the current state, event, and (optional)
+ * gates-flag intent (only consulted on `start` from `idle`).
+ *
+ * @param {string} state
+ * @param {string} event
+ * @param {{ gates?: boolean }} [opts]
+ * @returns {{ ok: true, next_state: string } | { ok: false, error: string }}
+ */
+export function transition(state, event, opts = {}) {
+  if (!STATE_SET.has(state)) {
+    return { ok: false, error: `unknown state: ${state}` };
+  }
+  if (!EVENT_SET.has(event)) {
+    return { ok: false, error: `unknown event: ${event}` };
+  }
+
+  // completed is terminal & idempotent
+  if (state === STATES.COMPLETED) {
+    return { ok: true, next_state: STATES.COMPLETED };
+  }
+
+  if (state === STATES.IDLE) {
+    if (event === EVENTS.START) {
+      const gates = opts.gates === true;
+      return { ok: true, next_state: gates ? STATES.GATES_ON : STATES.AUTO_RUNNING };
+    }
+    return { ok: false, error: `invalid transition: idle + ${event} (only \`start\` allowed from idle)` };
+  }
+
+  if (state === STATES.GATES_ON) {
+    if (event === EVENTS.PHASE_BOUNDARY) return { ok: true, next_state: STATES.PAUSED_FOR_GATE };
+    if (event === EVENTS.FINISH) return { ok: true, next_state: STATES.COMPLETED };
+    return { ok: false, error: `invalid transition: gates_on + ${event}` };
+  }
+
+  if (state === STATES.AUTO_RUNNING) {
+    if (event === EVENTS.PHASE_BOUNDARY) return { ok: true, next_state: STATES.AUTO_RUNNING };
+    if (event === EVENTS.FINISH) return { ok: true, next_state: STATES.COMPLETED };
+    return { ok: false, error: `invalid transition: auto_running + ${event}` };
+  }
+
+  if (state === STATES.PAUSED_FOR_GATE) {
+    if (event === EVENTS.RESUME) return { ok: true, next_state: STATES.GATES_ON };
+    if (event === EVENTS.FINISH) return { ok: true, next_state: STATES.COMPLETED };
+    return { ok: false, error: `invalid transition: paused_for_gate + ${event}` };
+  }
+
+  return { ok: false, error: `unhandled state: ${state}` };
+}
+
+/**
+ * Convenience: is this state terminal?
+ */
+export function isTerminal(state) {
+  return state === STATES.COMPLETED;
+}
+
+// ---- CLI shim ----------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--state') out.state = argv[++i];
+    else if (a === '--event') out.event = argv[++i];
+    else if (a === '--gates') {
+      const v = argv[++i];
+      out.gates = v === 'true';
+    }
+  }
+  return out;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.state || !args.event) {
+    process.stdout.write(JSON.stringify({
+      ok: false,
+      error: 'usage: autonomy-gate.mjs --state <state> --event <event> [--gates true|false]',
+    }) + '\n');
+    process.exit(1);
+  }
+  const result = transition(args.state, args.event, { gates: args.gates });
+  process.stdout.write(JSON.stringify(result) + '\n');
+  process.exit(result.ok ? 0 : 1);
+}

plugins/voyage/lib/util/cleanup.mjs

@@ -0,0 +1,94 @@
+// lib/util/cleanup.mjs
+// Bug 4 — operator-invoked cleanup of completed-project state files.
+//
+// The trekplan pipeline does NOT auto-cleanup state on session-end:
+// stale .session-state.local.json + NEXT-SESSION-PROMPT.local.md across many
+// projects accumulate over time. This util removes them safely once the
+// project is fully done (status === 'completed' as seen by validateSessionState).
+//
+// Invariants:
+// - Strict equality on parsed.status === 'completed' (no soft-match).
+// - Idempotent: re-running on a partially-cleaned dir succeeds with deleted: [].
+// - Refuses dryRun: false without an explicit confirm: true (prevents accidents).
+// - ENOENT counts as "already absent" — never an error.
+// - Cleanup is operator-invoked from /trekcontinue --cleanup; no Bash binding here.
+
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { issue, fail, ok } from './result.mjs';
+import { validateSessionState } from '../validators/session-state-validator.mjs';
+
+const CANDIDATE_FILES = Object.freeze([
+  '.session-state.local.json',
+  'NEXT-SESSION-PROMPT.local.md',
+]);
+
+/**
+ * Clean up state files for a completed trekplan project.
+ *
+ * @param {string} projectDir - absolute or cwd-relative path to the project directory
+ * @param {{dryRun?: boolean, confirm?: boolean}} [opts]
+ * @returns {{valid: boolean, errors: object[], warnings: object[], parsed?: {wouldDelete?: string[], deleted?: string[]}}}
+ */
+export function cleanupProject(projectDir, opts = {}) {
+  const dryRun = opts.dryRun !== false; // default true
+  const confirm = opts.confirm === true;
+
+  if (!dryRun && !confirm) {
+    return fail(issue(
+      'CLEANUP_REQUIRES_CONFIRM',
+      'Refused: dryRun=false requires confirm=true (explicit operator confirmation)',
+      'Re-run with {dryRun: false, confirm: true} to actually delete files.',
+    ));
+  }
+
+  if (typeof projectDir !== 'string' || projectDir.length === 0) {
+    return fail(issue('CLEANUP_INVALID_PROJECT_DIR', 'projectDir must be a non-empty string'));
+  }
+
+  const stateFile = join(projectDir, '.session-state.local.json');
+
+  if (!existsSync(stateFile)) {
+    return fail(issue(
+      'CLEANUP_NO_STATE_FILE',
+      `No state file at ${stateFile}; nothing to clean up`,
+      'cleanup is only valid for projects that have a .session-state.local.json with status: completed',
+    ));
+  }
+
+  const validation = validateSessionState(stateFile);
+  if (!validation.valid) {
+    return fail(issue(
+      'CLEANUP_INVALID_STATE_FILE',
+      `State file at ${stateFile} is invalid: ${validation.errors.map(e => e.code).join(', ')}`,
+    ));
+  }
+
+  if (validation.parsed.status !== 'completed') {
+    return fail(issue(
+      'CLEANUP_NOT_COMPLETED',
+      `Refused: status is "${validation.parsed.status}", not "completed"`,
+      'cleanup is reserved for fully-finished projects. Resume via /trekcontinue or wait until the run completes.',
+    ));
+  }
+
+  const candidates = CANDIDATE_FILES.map(f => join(projectDir, f));
+
+  if (dryRun) {
+    const wouldDelete = candidates.filter(p => existsSync(p));
+    return { valid: true, errors: [], warnings: [], parsed: { wouldDelete, deleted: [] } };
+  }
+
+  const deleted = [];
+  for (const p of candidates) {
+    try {
+      unlinkSync(p);
+      deleted.push(p);
+    } catch (e) {
+      if (e && e.code === 'ENOENT') continue; // idempotent: already absent
+      return fail(issue('CLEANUP_UNLINK_FAILED', `Failed to delete ${p}: ${e.message}`));
+    }
+  }
+
+  return ok({ wouldDelete: [], deleted });
+}

plugins/voyage/lib/util/frontmatter.mjs

@@ -0,0 +1,158 @@
+// lib/util/frontmatter.mjs
+// Hand-rolled YAML-frontmatter parser.
+//
+// Supported subset:
+//   - String scalars (quoted or unquoted)
+//   - Numbers (integer + float)
+//   - Booleans (true / false)
+//   - null
+//   - Single-level dicts
+//   - Lists of scalars (- value)
+//
+// Deliberately rejects: nested dicts in lists, multi-line strings,
+// anchors/aliases, tags, flow style ({...} / [...]).
+//
+// Why no js-yaml: zero-deps invariant. Templates emit only this subset.
+
+import { issue, ok, fail } from './result.mjs';
+
+const FRONTMATTER_RE = /^?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?$/;
+
+/**
+ * Split raw markdown into { frontmatter, body }.
+ * Returns { hasFrontmatter: false } when no leading --- block exists.
+ */
+export function splitFrontmatter(text) {
+  if (typeof text !== 'string') return { hasFrontmatter: false, body: '' };
+  const stripped = text.replace(/^/, '');
+  const m = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?$/);
+  if (!m) return { hasFrontmatter: false, body: stripped };
+  return {
+    hasFrontmatter: true,
+    frontmatter: m[1],
+    body: m[2] || '',
+  };
+}
+
+/**
+ * Parse a YAML-frontmatter string into a JS object.
+ * @returns {import('./result.mjs').Result}
+ */
+export function parseFrontmatter(yamlText) {
+  if (typeof yamlText !== 'string') {
+    return fail(issue('FM_INPUT', 'Frontmatter input is not a string'));
+  }
+  const lines = yamlText.split(/\r?\n/);
+  const out = {};
+  const errors = [];
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (line.trim() === '' || line.trimStart().startsWith('#')) {
+      i++;
+      continue;
+    }
+
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[0].length : 0;
+    if (indent > 0) {
+      errors.push(issue('FM_INDENT', `Unexpected indentation at line ${i + 1}`, 'Top-level keys only; nested dicts unsupported.'));
+      i++;
+      continue;
+    }
+
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!kv) {
+      errors.push(issue('FM_SYNTAX', `Cannot parse line ${i + 1}: ${line}`));
+      i++;
+      continue;
+    }
+
+    const key = kv[1];
+    const rest = kv[2];
+
+    if (rest === '' || rest === undefined) {
+      const list = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const next = lines[j];
+        if (next.trim() === '') { j++; continue; }
+        const itemMatch = next.match(/^(\s+)-\s+(.*)$/);
+        if (!itemMatch) break;
+        const itemIndent = itemMatch[1].length;
+        const firstContent = itemMatch[2];
+        const dictKeyMatch = firstContent.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+        if (dictKeyMatch) {
+          const item = {};
+          item[dictKeyMatch[1]] = parseScalar(dictKeyMatch[2]);
+          let k = j + 1;
+          while (k < lines.length) {
+            const cont = lines[k];
+            if (cont.trim() === '') { k++; continue; }
+            const contMatch = cont.match(/^(\s+)([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+            if (!contMatch) break;
+            if (contMatch[1].length <= itemIndent + 1) break;
+            item[contMatch[2]] = parseScalar(contMatch[3]);
+            k++;
+          }
+          list.push(item);
+          j = k;
+        } else {
+          list.push(parseScalar(firstContent));
+          j++;
+        }
+      }
+      if (list.length > 0) {
+        out[key] = list;
+        i = j;
+      } else {
+        out[key] = null;
+        i++;
+      }
+      continue;
+    }
+
+    out[key] = parseScalar(rest);
+    i++;
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings: [], parsed: out };
+  return ok(out);
+}
+
+function parseScalar(raw) {
+  const s = raw.trim();
+  if (s === '') return '';
+  if (s === 'null' || s === '~') return null;
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s === '[]') return [];
+  if (s === '{}') return {};
+  if (/^-?\d+$/.test(s)) return Number.parseInt(s, 10);
+  if (/^-?\d+\.\d+$/.test(s)) return Number.parseFloat(s);
+  if (s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1).replace(/\\(.)/g, (_, ch) => {
+      if (ch === 'n') return '\n';
+      if (ch === 't') return '\t';
+      if (ch === 'r') return '\r';
+      return ch;
+    });
+  }
+  if (s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1);
+  return s;
+}
+
+/**
+ * Parse a markdown file's frontmatter directly from its full text.
+ * @returns {import('./result.mjs').Result}
+ */
+export function parseDocument(text) {
+  const split = splitFrontmatter(text);
+  if (!split.hasFrontmatter) {
+    return fail(issue('FM_MISSING', 'No frontmatter block found'));
+  }
+  const result = parseFrontmatter(split.frontmatter);
+  return { ...result, parsed: { frontmatter: result.parsed, body: split.body } };
+}

plugins/voyage/lib/util/result.mjs

@@ -0,0 +1,35 @@
+// lib/util/result.mjs
+// Validation result shape used by every validator and parser.
+
+/**
+ * @typedef {{ code: string, message: string, hint?: string, location?: string }} Issue
+ * @typedef {{ valid: boolean, errors: Issue[], warnings: Issue[], parsed?: any }} Result
+ */
+
+/** @returns {Result} */
+export function ok(parsed) {
+  return { valid: true, errors: [], warnings: [], parsed };
+}
+
+/** @returns {Result} */
+export function fail(errors, parsed) {
+  return { valid: false, errors: Array.isArray(errors) ? errors : [errors], warnings: [], parsed };
+}
+
+/** @returns {Result} */
+export function combine(results) {
+  const errors = [];
+  const warnings = [];
+  let parsed;
+  for (const r of results) {
+    if (r.errors) errors.push(...r.errors);
+    if (r.warnings) warnings.push(...r.warnings);
+    if (r.parsed !== undefined && parsed === undefined) parsed = r.parsed;
+  }
+  return { valid: errors.length === 0, errors, warnings, parsed };
+}
+
+/** @returns {Issue} */
+export function issue(code, message, hint, location) {
+  return { code, message, hint, location };
+}