godpowers 2.3.1 → 2.4.1

package/lib/command-families.js

@@ -0,0 +1,375 @@
+/**
+ * Command family metadata.
+ *
+ * Keeps the user-facing command catalog small without removing leaf commands.
+ * These groupings are used by help, routing, docs, and UX audits.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const COMMAND_FAMILIES = [
+  {
+    id: 'start',
+    label: 'Start',
+    purpose: 'Start or import a project.',
+    commands: [
+      '/god',
+      '/god-init',
+      '/god-mode',
+      '/god-explore',
+      '/god-discuss',
+      '/god-list-assumptions',
+      '/god-prd',
+      '/god-design',
+      '/god-design-impact',
+      '/god-arch',
+      '/god-roadmap',
+      '/god-stack',
+      '/god-repo',
+      '/god-preflight',
+      '/god-map-codebase',
+      '/god-archaeology',
+      '/god-org-context',
+      '/god-migrate'
+    ]
+  },
+  {
+    id: 'continue',
+    label: 'Continue',
+    purpose: 'Understand state and choose the next move.',
+    commands: [
+      '/god-status',
+      '/god-next',
+      '/god-progress',
+      '/god-lifecycle',
+      '/god-locate',
+      '/god-resume-work',
+      '/god-pause-work'
+    ]
+  },
+  {
+    id: 'build',
+    label: 'Build',
+    purpose: 'Plan, implement, test, and ship product work.',
+    commands: [
+      '/god-build',
+      '/god-feature',
+      '/god-story',
+      '/god-stories',
+      '/god-story-build',
+      '/god-story-verify',
+      '/god-story-close',
+      '/god-fast',
+      '/god-quick',
+      '/god-debug',
+      '/god-add-tests',
+      '/god-refactor',
+      '/god-spike'
+    ]
+  },
+  {
+    id: 'verify',
+    label: 'Verify',
+    purpose: 'Check artifacts, code, runtime behavior, and release readiness.',
+    commands: [
+      '/god-lint',
+      '/god-standards',
+      '/god-review',
+      '/god-review-changes',
+      '/god-test-runtime',
+      '/god-audit',
+      '/god-agent-audit',
+      '/god-hygiene',
+      '/god-dogfood',
+      '/god-preflight'
+    ]
+  },
+  {
+    id: 'operate',
+    label: 'Operate',
+    purpose: 'Deploy, observe, harden, launch, and respond in production.',
+    commands: [
+      '/god-deploy',
+      '/god-observe',
+      '/god-harden',
+      '/god-launch',
+      '/god-hotfix',
+      '/god-postmortem',
+      '/god-logs',
+      '/god-metrics',
+      '/god-trace',
+      '/god-export-otel'
+    ]
+  },
+  {
+    id: 'maintain',
+    label: 'Maintain',
+    purpose: 'Keep artifacts, docs, dependencies, context, and repo surfaces current.',
+    commands: [
+      '/god-docs',
+      '/god-sync',
+      '/god-scan',
+      '/god-link',
+      '/god-reconcile',
+      '/god-reconstruct',
+      '/god-intel',
+      '/god-tech-debt',
+      '/god-update-deps',
+      '/god-upgrade',
+      '/god-context',
+      '/god-context-scan',
+      '/god-roadmap-check',
+      '/god-roadmap-update'
+    ]
+  },
+  {
+    id: 'capture',
+    label: 'Capture',
+    purpose: 'Save thoughts, tasks, backlog items, seeds, and learnings.',
+    commands: [
+      '/god-note',
+      '/god-add-todo',
+      '/god-check-todos',
+      '/god-add-backlog',
+      '/god-plant-seed',
+      '/god-extract-learnings',
+      '/god-thread',
+      '/god-graph'
+    ]
+  },
+  {
+    id: 'recover',
+    label: 'Recover',
+    purpose: 'Undo, repair, restore, skip, or diagnose broken state.',
+    commands: [
+      '/god-undo',
+      '/god-redo',
+      '/god-rollback',
+      '/god-restore',
+      '/god-repair',
+      '/god-skip',
+      '/god-smite',
+      '/god-doctor'
+    ]
+  },
+  {
+    id: 'extend',
+    label: 'Extend',
+    purpose: 'Install, inspect, test, remove, or author extension packs.',
+    commands: [
+      '/god-extension-scaffold',
+      '/god-extension-add',
+      '/god-extension-list',
+      '/god-extension-info',
+      '/god-extension-remove',
+      '/god-test-extension',
+      '/god-build-agent'
+    ]
+  },
+  {
+    id: 'collaborate',
+    label: 'Collaborate',
+    purpose: 'Coordinate people, workstreams, suites, sprints, and pull requests.',
+    commands: [
+      '/god-workstream',
+      '/god-suite-init',
+      '/god-suite-status',
+      '/god-suite-sync',
+      '/god-suite-patch',
+      '/god-suite-release',
+      '/god-party',
+      '/god-sprint',
+      '/god-pr-branch'
+    ]
+  },
+  {
+    id: 'configure',
+    label: 'Configure',
+    purpose: 'Tune settings, budgets, cache, profiles, help, and version info.',
+    commands: [
+      '/god-settings',
+      '/god-set-profile',
+      '/god-budget',
+      '/god-cost',
+      '/god-cache-clear',
+      '/god-automation-status',
+      '/god-automation-setup',
+      '/god-help',
+      '/god-version'
+    ]
+  }
+];
+
+const STATUS_VIEWS = [
+  { id: 'overview', command: '/god-status', label: 'Overview', purpose: 'Operational state, proactive checks, and blockers.' },
+  { id: 'progress', command: '/god-progress', label: 'Progress', purpose: 'Requirement and roadmap increment completion.' },
+  { id: 'lifecycle', command: '/god-lifecycle', label: 'Lifecycle', purpose: 'Project phase and fitting workflows.' },
+  { id: 'locate', command: '/god-locate', label: 'Locate', purpose: 'Resume orientation from checkpoint and disk state.' },
+  { id: 'next', command: '/god-next', label: 'Next', purpose: 'Single recommended command with reason.' }
+];
+
+const CAPTURE_LADDER = [
+  { id: 'note', command: '/god-note', signal: 'save only', purpose: 'Save a thought without priority or workflow impact.' },
+  { id: 'todo', command: '/god-add-todo', signal: 'actionable soon', purpose: 'Create a prioritized action item.' },
+  { id: 'backlog', command: '/god-add-backlog', signal: 'optional later', purpose: 'Park an idea for future roadmap review.' },
+  { id: 'seed', command: '/god-plant-seed', signal: 'conditional future trigger', purpose: 'Store an idea until a metric, date, or event happens.' }
+];
+
+const WORK_SIZE_LADDER = [
+  { id: 'fast', command: '/god-fast', signal: 'trivial direct edit', purpose: 'One tiny edit with existing verification.' },
+  { id: 'quick', command: '/god-quick', signal: 'small TDD task', purpose: 'Small task with TDD and review but no full planning tier.' },
+  { id: 'story', command: '/god-story', signal: 'fine-grained planned slice', purpose: 'Create a STORY.md before implementation.' },
+  { id: 'feature', command: '/god-feature', signal: 'existing-product feature', purpose: 'Feature workflow with mini-PRD, build, harden, and sync.' },
+  { id: 'build', command: '/god-build', signal: 'current milestone work', purpose: 'Build the planned roadmap increment.' },
+  { id: 'debug', command: '/god-debug', signal: 'non-urgent bug', purpose: 'Run the systematic debug loop.' },
+  { id: 'hotfix', command: '/god-hotfix', signal: 'production outage', purpose: 'Expedited production fix and postmortem trigger.' }
+];
+
+const VERIFY_LADDER = [
+  { id: 'lint', command: '/god-lint', signal: 'mechanical artifact check', purpose: 'Fast file-level artifact validation.' },
+  { id: 'standards', command: '/god-standards', signal: 'artifact quality gate', purpose: 'Substitution, labels, and have-nots for one artifact.' },
+  { id: 'review', command: '/god-review', signal: 'code diff review', purpose: 'Two-stage spec and quality review.' },
+  { id: 'runtime', command: '/god-test-runtime', signal: 'live behavior check', purpose: 'Browser-backed design and acceptance verification.' },
+  { id: 'audit', command: '/god-audit', signal: 'artifact set score', purpose: 'Score existing Godpowers artifacts.' },
+  { id: 'hygiene', command: '/god-hygiene', signal: 'ongoing project health', purpose: 'Composite audit, dependency, and docs check.' },
+  { id: 'preflight', command: '/god-preflight', signal: 'existing repo intake', purpose: 'Read-only readiness check before stronger workflows.' },
+  { id: 'dogfood', command: '/god-dogfood', signal: 'release fixture readiness', purpose: 'Messy-repo scenarios for release confidence.' }
+];
+
+const TRIGGER_PRECEDENCE = {
+  continue: {
+    default: '/god-next',
+    conditional: [
+      { command: '/god-resume-work', when: 'handoff-exists', reason: 'A handoff exists on disk.' }
+    ],
+    reason: 'Continue means resume a handoff when present, otherwise compute the next route.'
+  },
+  'think through': {
+    default: '/god-discuss',
+    conditional: [
+      { command: '/god-explore', when: 'broad-idea', reason: 'The request is broad ideation rather than a concrete decision.' }
+    ],
+    reason: 'Discussion handles concrete decisions while exploration handles broad ideation.'
+  },
+  'what happened': {
+    default: '/god-logs',
+    conditional: [
+      { command: '/god-postmortem', when: 'post-incident-pending', reason: 'The project is waiting on incident follow-up.' }
+    ],
+    reason: 'Logs answer run history unless an incident loop is open.'
+  },
+  "what's done": {
+    default: '/god-progress',
+    conditional: [
+      { command: '/god-status', when: 'operational-status-request', reason: 'The wording asks for operational state, not deliverables.' }
+    ],
+    reason: 'Progress answers deliverables while status answers operational state.'
+  },
+  'where am i': {
+    default: '/god-lifecycle',
+    conditional: [
+      { command: '/god-locate', when: 'checkpoint-or-handoff-exists', reason: 'Resume artifacts exist on disk.' }
+    ],
+    reason: 'Lifecycle explains the phase while locate orients a resumed session.'
+  }
+};
+
+function familyForCommand(command) {
+  return COMMAND_FAMILIES.find((family) => family.commands.includes(command)) || null;
+}
+
+function renderFamilyCards(families = COMMAND_FAMILIES) {
+  return families.map((family) => (
+    `${family.label}: ${family.purpose} (${family.commands.join(', ')})`
+  ));
+}
+
+function renderLadder(ladder) {
+  return ladder.map((step) => `${step.command}: ${step.signal} - ${step.purpose}`);
+}
+
+function detectCondition(condition, projectRoot, text = '') {
+  if (!condition) return false;
+  const root = projectRoot || process.cwd();
+  if (condition === 'handoff-exists') {
+    return fs.existsSync(path.join(root, '.godpowers', 'HANDOFF.md'));
+  }
+  if (condition === 'checkpoint-or-handoff-exists') {
+    return fs.existsSync(path.join(root, '.godpowers', 'CHECKPOINT.md'))
+      || fs.existsSync(path.join(root, '.godpowers', 'HANDOFF.md'));
+  }
+  if (condition === 'post-incident-pending') {
+    try {
+      const statePath = path.join(root, '.godpowers', 'state.json');
+      if (!fs.existsSync(statePath)) return false;
+      const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      return parsed['lifecycle-phase'] === 'post-incident-pending';
+    } catch (e) {
+      return false;
+    }
+  }
+  if (condition === 'broad-idea') {
+    return /\b(idea|brainstorm|explore|what if|possibilities|options)\b/i.test(text || '');
+  }
+  if (condition === 'operational-status-request') {
+    return /\b(status|state|blocked|sync|health|where)\b/i.test(text || '');
+  }
+  return false;
+}
+
+function resolveTrigger(trigger, opts = {}) {
+  const key = String(trigger || '').trim().toLowerCase();
+  const rule = TRIGGER_PRECEDENCE[key];
+  if (!rule) return null;
+  for (const branch of rule.conditional || []) {
+    if (detectCondition(branch.when, opts.projectRoot, opts.text)) {
+      return { trigger: key, command: branch.command, reason: branch.reason, rule };
+    }
+  }
+  return { trigger: key, command: rule.default, reason: rule.reason, rule };
+}
+
+function classifyCapture(text = '') {
+  if (/\b(when|if|after|in \d+|once)\b/i.test(text)) return CAPTURE_LADDER.find((item) => item.id === 'seed');
+  if (/\b(todo|task|remind|priority|p[0-3])\b/i.test(text)) return CAPTURE_LADDER.find((item) => item.id === 'todo');
+  if (/\b(backlog|later|someday|future)\b/i.test(text)) return CAPTURE_LADDER.find((item) => item.id === 'backlog');
+  return CAPTURE_LADDER.find((item) => item.id === 'note');
+}
+
+function classifyWorkSize(text = '') {
+  if (/\b(production|outage|down|urgent|hotfix)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'hotfix');
+  if (/\b(bug|debug|failing|error|regression)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'debug');
+  if (/\b(story|acceptance criteria)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'story');
+  if (/\b(feature|new capability|enhancement)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'feature');
+  if (/\b(milestone|roadmap|increment)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'build');
+  if (/\b(tiny|typo|one-line|config tweak|trivial)\b/i.test(text)) return WORK_SIZE_LADDER.find((item) => item.id === 'fast');
+  return WORK_SIZE_LADDER.find((item) => item.id === 'quick');
+}
+
+function classifyVerification(text = '') {
+  if (/\b(dogfood|release readiness|fixture)\b/i.test(text)) return VERIFY_LADDER.find((item) => item.id === 'dogfood');
+  if (/\b(preflight|intake|existing repo)\b/i.test(text)) return VERIFY_LADDER.find((item) => item.id === 'preflight');
+  if (/\b(hygiene|health|weekly|monthly)\b/i.test(text)) return VERIFY_LADDER.find((item) => item.id === 'hygiene');
+  if (/\b(audit|score artifacts)\b/i.test(text)) return VERIFY_LADDER.find((item) => item.id === 'audit');
+  if (/\b(runtime|browser|e2e|flow|render|design audit)\b/i.test(text)) return VERIFY_LADDER.find((item) => item.id === 'runtime');
+  if (/\b(review|diff|code review)\b/i.test(text)) return VERIFY_LADDER.find((item) => item.id === 'review');
+  if (/\b(standard|substitution|have-nots)\b/i.test(text)) return VERIFY_LADDER.find((item) => item.id === 'standards');
+  return VERIFY_LADDER.find((item) => item.id === 'lint');
+}
+
+module.exports = {
+  COMMAND_FAMILIES,
+  STATUS_VIEWS,
+  CAPTURE_LADDER,
+  WORK_SIZE_LADDER,
+  VERIFY_LADDER,
+  TRIGGER_PRECEDENCE,
+  familyForCommand,
+  renderFamilyCards,
+  renderLadder,
+  resolveTrigger,
+  classifyCapture,
+  classifyWorkSize,
+  classifyVerification
+};

package/lib/feature-awareness.js

@@ -51,7 +51,7 @@ const FEATURES = [
     id: 'route-quality-sync',
     since: '1.6.19',
     commands: ['/god-sync', '/god-doctor', '/god-status', '/god-mode'],
-    description: 'Detect symbolic route spawns, unresolved agent targets, and unapproved contextual route exits.'
+    description: 'Detect symbolic route spawns, unresolved agent targets, and untyped contextual route exits.'
   },
   {
     id: 'recipe-coverage-sync',

package/lib/quick-proof.js

@@ -10,6 +10,7 @@ const path = require('path');
 
 const dashboard = require('./dashboard');
 const hostCapabilities = require('./host-capabilities');
+const adoptionMetrics = require('./adoption-metrics');
 
 const FIXTURE_ROOT = path.join(__dirname, '..', 'fixtures', 'quick-proof', 'project');
 const MANIFEST_PATH = path.join(__dirname, '..', 'fixtures', 'quick-proof', 'manifest.json');
@@ -85,6 +86,8 @@ function compute(projectRoot = process.cwd(), opts = {}) {
     ]
   };
 
+  proof.metrics = adoptionMetrics.fromQuickProof(proof);
+
   return proof;
 }
 
@@ -111,7 +114,10 @@ function render(proof, opts = {}) {
       `  State on disk: ${proof.statePath}`,
       `  Fixture: ${proof.fixturePath}`,
       `  PRD: ${planning.prd ? planning.prd.status : 'unknown'}`,
-      `  Roadmap: ${planning.roadmap ? planning.roadmap.status : 'unknown'}`
+      `  Roadmap: ${planning.roadmap ? planning.roadmap.status : 'unknown'}`,
+      '',
+      'Outcome metrics:',
+      adoptionMetrics.render(proof.metrics)
     ].join('\n');
   }
 
@@ -138,6 +144,9 @@ function render(proof, opts = {}) {
     'Evidence:',
     ...proof.evidence.map((item, index) => `  ${index + 1}. ${item.label}: ${item.value}`),
     '',
+    'Outcome metrics:',
+    adoptionMetrics.render(proof.metrics),
+    '',
     'Try it on the fixture:',
     `  npx godpowers status --project=${proof.fixtureRoot} --brief`,
     `  npx godpowers next --project=${proof.fixtureRoot} --brief`,

package/lib/release-surface-sync.js

@@ -12,15 +12,18 @@ const path = require('path');
 const LOG_PATH = '.godpowers/surface/RELEASE-SURFACE-SYNC.md';
 
 const REQUIRED_PACKAGE_GUARDS = [
+  'lib/command-families.js',
   'lib/dogfood-runner.js',
   'lib/extension-authoring.js',
   'lib/host-capabilities.js',
   'lib/route-quality-sync.js',
   'lib/recipe-coverage-sync.js',
-  'lib/release-surface-sync.js'
+  'lib/release-surface-sync.js',
+  'lib/workflow-helper-groups.js'
 ];
 
 const REQUIRED_RELEASE_TESTS = [
+  'scripts/test-command-families.js',
   'scripts/test-dogfood-runner.js',
   'scripts/test-extension-authoring.js',
   'scripts/test-host-capabilities.js',

package/lib/route-quality-sync.js

@@ -2,8 +2,8 @@
  * Route quality sync.
  *
  * Detects disconnected route automation surfaces: symbolic spawn tokens,
- * unresolved agent targets, contextual exits without an approved reason,
- * missing standards coverage, and agent-spawn routes without trace events.
+ * unresolved agent targets, contextual exits without typed outcomes, missing
+ * standards coverage, and agent-spawn routes without trace events.
  */
 
 const fs = require('fs');
@@ -12,6 +12,21 @@ const path = require('path');
 const { parseSimpleYaml } = require('./intent');
 
 const LOG_PATH = '.godpowers/surface/ROUTE-QUALITY-SYNC.md';
+const CONTEXTUAL_NEXT_VALUES = new Set([
+  'varies',
+  'varies-by-verdict',
+  'steady-state',
+  'session-end'
+]);
+const OUTCOME_TYPES = new Set([
+  'contextual',
+  'verdict-based',
+  'steady-state',
+  'session-end',
+  'requires-selection',
+  'no-next-command',
+  'explicit-command'
+]);
 
 const CONTEXTUAL_NEXT_ALLOWED = new Set([
   '/god',
@@ -21,23 +36,30 @@ const CONTEXTUAL_NEXT_ALLOWED = new Set([
   '/god-check-todos',
   '/god-context-scan',
   '/god-cost',
+  '/god-design-impact',
   '/god-discuss',
   '/god-doctor',
   '/god-extension-add',
   '/god-extension-info',
   '/god-extension-list',
   '/god-extension-remove',
-  '/god-extension-scaffold',
   '/god-graph',
   '/god-help',
   '/god-lifecycle',
   '/god-list-assumptions',
   '/god-locate',
   '/god-logs',
+  '/god-launch',
   '/god-metrics',
+  '/god-mode',
   '/god-next',
+  '/god-pause-work',
   '/god-redo',
+  '/god-reconcile',
   '/god-resume-work',
+  '/god-roadmap-check',
+  '/god-sprint',
+  '/god-suite-status',
   '/god-test-extension',
   '/god-thread',
   '/god-trace',
@@ -141,7 +163,7 @@ function detect(projectRoot) {
     .map((file) => path.basename(file, '.md')));
   let symbolicCount = 0;
   let unresolvedCount = 0;
-  let contextualExitCount = 0;
+  let typedOutcomeCount = 0;
   let standardsExemptCount = 0;
   let traceEventMissingCount = 0;
 
@@ -194,18 +216,22 @@ function detect(projectRoot) {
       );
     }
 
-    const next = route['success-path'] && route['success-path']['next-recommended'];
+    const successPath = route['success-path'] || {};
+    const next = successPath['next-recommended'];
     const conditionalNext = route['success-path'] && arr(route['success-path']['conditional-next']);
-    if (next === 'varies' && conditionalNext.length === 0) {
-      if (CONTEXTUAL_NEXT_ALLOWED.has(command)) {
-        contextualExitCount++;
+    const outcome = successPath.outcome || {};
+    const needsTypedOutcome = next
+      && (CONTEXTUAL_NEXT_VALUES.has(String(next)) || /\s+or\s+/.test(String(next)));
+    if (needsTypedOutcome) {
+      if (outcome.type && OUTCOME_TYPES.has(String(outcome.type))) {
+        typedOutcomeCount++;
       } else {
         addCheck(
           checks,
-          `unapproved-varies-${command.replace(/[^a-z0-9]+/gi, '-')}`,
+          `missing-route-outcome-${command.replace(/[^a-z0-9]+/gi, '-')}`,
           'stale',
           routePath,
-          `${command} uses next-recommended: varies without an approved contextual-exit classification.`,
+          `${command} uses contextual next route ${next} without a typed success-path.outcome.`,
           { spawn: 'god-roadmap-reconciler' }
         );
       }
@@ -238,10 +264,10 @@ function detect(projectRoot) {
   addCheck(
     checks,
     'contextual-exit-policy',
-    checks.some((check) => check.id.startsWith('unapproved-varies-')) ? 'stale' : 'fresh',
+    checks.some((check) => check.id.startsWith('missing-route-outcome-')) ? 'stale' : 'fresh',
     'routing/',
-    `${contextualExitCount} contextual route exits are approved and all other next routes are explicit.`,
-    { spawn: checks.some((check) => check.id.startsWith('unapproved-varies-')) ? 'god-roadmap-reconciler' : null }
+    `${typedOutcomeCount} contextual route exits have typed outcomes and all other next routes are explicit.`,
+    { spawn: checks.some((check) => check.id.startsWith('missing-route-outcome-')) ? 'god-roadmap-reconciler' : null }
   );
   addCheck(
     checks,
@@ -309,6 +335,8 @@ function summary(report) {
 module.exports = {
   LOG_PATH,
   CONTEXTUAL_NEXT_ALLOWED,
+  CONTEXTUAL_NEXT_VALUES,
+  OUTCOME_TYPES,
   STANDARDS_EXEMPT_COMMANDS,
   detect,
   run,

package/lib/router.js

@@ -12,6 +12,7 @@ const fs = require('fs');
 const path = require('path');
 const { parseSimpleYaml } = require('./intent');
 const state = require('./state');
+const commandFamilies = require('./command-families');
 
 const ROUTING_DIR = path.join(__dirname, '..', 'routing');
 const SAFE_SYNC_PLAN = '.godpowers/sync/SAFE-SYNC-PLAN.md';
@@ -186,6 +187,33 @@ function getNextCommand(command, opts = {}) {
   return sp['next-recommended'] || null;
 }
 
+function inferOutcomeType(next) {
+  if (!next) return 'no-next-command';
+  if (next === 'varies') return 'contextual';
+  if (next === 'varies-by-verdict') return 'verdict-based';
+  if (next === 'steady-state') return 'steady-state';
+  if (next === 'session-end') return 'session-end';
+  if (/\s+or\s+/.test(next)) return 'requires-selection';
+  if (/^\/god(?:-[a-z-]+)?(?:\s.*)?$/.test(next)) return 'explicit-command';
+  return 'contextual';
+}
+
+function getRouteOutcome(command) {
+  const routing = getRouting(command);
+  if (!routing) return null;
+  const sp = routing['success-path'] || {};
+  const outcome = sp.outcome || {};
+  const next = sp['next-recommended'] || null;
+  const type = outcome.type || inferOutcomeType(next);
+  return {
+    type,
+    label: outcome.label || type,
+    reason: outcome.reason || 'Route outcome is inferred from success-path.next-recommended.',
+    next,
+    allowedNext: outcome['allowed-next'] || []
+  };
+}
+
 /**
  * Evaluate a routing condition against the project state.
  */
@@ -368,9 +396,13 @@ module.exports = {
   getRouting,
   checkPrerequisites,
   getNextCommand,
+  getRouteOutcome,
   getAlternatives,
   getStandards,
   getSpawnedAgents,
+  getCommandFamily: commandFamilies.familyForCommand,
+  resolveTrigger: commandFamilies.resolveTrigger,
+  commandFamilies,
   suggestNext,
   evaluateCheck,
   resolveProjectRelative,

package/lib/workflow-helper-groups.js

@@ -0,0 +1,50 @@
+/**
+ * Workflow helper groups.
+ *
+ * Workflow YAML can use these groups to avoid repeating long closeout helper
+ * lists. Plans still expand them into exact helper names for visibility.
+ */
+
+const HELPER_GROUPS = {
+  'standard-closeout': [
+    'repo-doc-sync',
+    'repo-surface-sync',
+    'checkpoint-sync',
+    'pillars-sync-plan'
+  ],
+  'repo-maintenance-closeout': [
+    'repo-doc-sync',
+    'repo-surface-sync'
+  ],
+  'runtime-awareness-closeout': [
+    'feature-awareness',
+    'host-capabilities'
+  ],
+  'release-readiness-closeout': [
+    'route-quality-sync',
+    'recipe-coverage-sync',
+    'release-surface-sync'
+  ],
+  'source-sync-closeout': [
+    'source-sync-back'
+  ]
+};
+
+function expand(groups = [], helpers = []) {
+  const expanded = [];
+  const names = Array.isArray(groups) ? groups : [groups].filter(Boolean);
+  for (const group of names) {
+    for (const helper of HELPER_GROUPS[group] || []) {
+      if (!expanded.includes(helper)) expanded.push(helper);
+    }
+  }
+  for (const helper of helpers || []) {
+    if (!expanded.includes(helper)) expanded.push(helper);
+  }
+  return expanded;
+}
+
+module.exports = {
+  HELPER_GROUPS,
+  expand
+};