godpowers 2.3.1 → 2.4.0

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/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
+};

package/lib/workflow-runner.js

@@ -31,6 +31,7 @@ const path = require('path');
 const parser = require('./workflow-parser');
 const asyncFs = require('./fs-async');
 const agentRefs = require('./agent-refs');
+const helperGroups = require('./workflow-helper-groups');
 
 /**
  * @typedef {Object} WorkflowPlanStep
@@ -134,7 +135,8 @@ function plan(workflow, ctx = {}) {
         review: job.review || null,
         'on-pass': job['on-pass'] || null,
         'on-fail': job['on-fail'] || null,
-        localHelpers: job['local-helpers'] || [],
+        localHelperGroups: job['local-helper-groups'] || [],
+        localHelpers: helperGroups.expand(job['local-helper-groups'] || [], job['local-helpers'] || []),
         with: job.with || null
       });
     }
@@ -221,6 +223,9 @@ function serializePlan(p) {
       if (step.tier) lines.push(`        tier: ${step.tier}`);
       if (step.agent) lines.push(`        agent: ${step.agent}`);
       if (step.uses)  lines.push(`        uses: ${step.uses}`);
+      if (step.localHelperGroups && step.localHelperGroups.length) {
+        lines.push(`        local-helper-groups: [${step.localHelperGroups.join(', ')}]`);
+      }
       if (step.localHelpers && step.localHelpers.length) {
         lines.push(`        local-helpers: [${step.localHelpers.join(', ')}]`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "AI-powered development system: 112 slash commands and 40 specialist agents that take a project from raw idea to hardened production. Runs inside Claude Code, Codex, Cursor, Windsurf, Gemini, and 10+ other AI coding tools.",
   "bin": {
     "godpowers": "./bin/install.js"

package/routing/god-add-backlog.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-add-backlog
   description: Add idea to backlog (less urgent than todo)
   tier: 0
+  family: capture
 
 prerequisites:
   required: []

package/routing/god-add-tests.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-add-tests
   description: Add tests to legacy code
   tier: 0
+  family: build
 
 prerequisites:
   required:

package/routing/god-add-todo.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-add-todo
   description: Capture a todo from current context
   tier: 0
+  family: capture
 
 prerequisites:
   required: []

package/routing/god-agent-audit.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-agent-audit
   description: Validate agents/*.md against agent contract
   tier: 0
+  family: verify
 
 prerequisites:
   required: []
@@ -15,6 +16,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-arch.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-arch
   description: Design system architecture
   tier: 1
+  family: start
 
 prerequisites:
   required:

package/routing/god-archaeology.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-archaeology
   description: Deep brownfield code archaeology
   tier: 0
+  family: start
 
 prerequisites:
   required: []

package/routing/god-audit.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-audit
   description: Score artifacts against have-nots
   tier: 0
+  family: verify
 
 prerequisites:
   required:

package/routing/god-automation-setup.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-automation-setup
   description: Prepare opt-in host automation setup
   tier: 0
+  family: configure
 
 prerequisites:
   required: []

package/routing/god-automation-status.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-automation-status
   description: Show host automation provider support
   tier: 0
+  family: configure
 
 prerequisites:
   required: []

package/routing/god-budget.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-budget
   description: 
   tier: 0
+  family: configure
 
 prerequisites:
   required: []
@@ -15,6 +16,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-build-agent.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-build-agent
   description: Generate custom specialist agent
   tier: 0
+  family: extend
 
 prerequisites:
   required: []

package/routing/god-build.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-build
   description: Build slices with TDD enforcement and two-stage review
   tier: 2
+  family: build
 
 prerequisites:
   required:

package/routing/god-cache-clear.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-cache-clear
   description: 
   tier: 0
+  family: configure
 
 prerequisites:
   required: []
@@ -15,6 +16,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-check-todos.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-check-todos
   description: List pending todos; optionally route to one
   tier: 0
+  family: capture
 
 prerequisites:
   required: []
@@ -15,6 +16,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-context-scan.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-context-scan
   description: 
   tier: 0
+  family: maintain
 
 prerequisites:
   required: []
@@ -15,6 +16,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-context.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-context
   description: Manage Godpowers fence in AGENTS.md / CLAUDE.md / GEMINI.md / others
   tier: 0
+  family: maintain
 
 prerequisites:
   required:

package/routing/god-cost.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-cost
   description: 
   tier: 0
+  family: configure
 
 prerequisites:
   required: []
@@ -15,6 +16,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-debug.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-debug
   description: 4-phase systematic debug
   tier: 0
+  family: build
 
 prerequisites:
   required:

package/routing/god-deploy.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-deploy
   description: Set up deploy pipeline
   tier: 3
+  family: operate
 
 prerequisites:
   required:

package/routing/god-design-impact.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-design-impact
   description: What-if analysis on DESIGN.md change
   tier: 1
+  family: start
 
 prerequisites:
   required:
@@ -16,6 +17,11 @@ execution:
 
 success-path:
   next-recommended: /god-design or /god-sync
+  outcome:
+    type: requires-selection
+    label: User selection required
+    reason: The route offers multiple valid next commands and the user should choose one.
+    allowed-next: [/god-design, /god-sync]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-design.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-design
   description: Design lifecycle (DESIGN.md + PRODUCT.md) bridged to impeccable
   tier: 1
+  family: start
 
 prerequisites:
   required:

package/routing/god-discuss.yaml

@@ -4,6 +4,13 @@ metadata:
   command: /god-discuss
   description: Pre-planning discussion
   tier: 0
+  family: start
+  trigger-precedence:
+    - trigger: think through
+      prefer: /god-explore
+      when: broad-idea
+      fallback: /god-discuss
+      reason: Broad ideation starts in explore while concrete decisions stay in discuss.
 
 prerequisites:
   required:
@@ -18,6 +25,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-docs.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-docs
   description: Documentation work
   tier: 0
+  family: maintain
 
 prerequisites:
   required:

package/routing/god-doctor.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-doctor
   description: Diagnose install + state
   tier: 0
+  family: recover
 
 prerequisites:
   required:
@@ -18,6 +19,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor

package/routing/god-dogfood.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-dogfood
   description: Run messy-repo dogfood scenarios for release and autonomy readiness.
   tier: 0
+  family: verify
 
 prerequisites:
   required: []

package/routing/god-explore.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-explore
   description: Pre-init Socratic ideation
   tier: 0
+  family: start
 
 prerequisites:
   required:

package/routing/god-export-otel.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-export-otel
   description: Export Godpowers events to OpenTelemetry OTLP JSON traces
   tier: 0
+  family: operate
 
 prerequisites:
   required: []

package/routing/god-extension-add.yaml

@@ -4,6 +4,7 @@ metadata:
   command: /god-extension-add
   description: 
   tier: 0
+  family: extend
 
 prerequisites:
   required: []
@@ -15,6 +16,11 @@ execution:
 
 success-path:
   next-recommended: varies
+  outcome:
+    type: contextual
+    label: Context-specific next route
+    reason: The next route depends on current disk state, command arguments, or user choice.
+    allowed-next: [/god-status, /god-next, /god-help]
 
 failure-path:
   on-error: /god-doctor