gstack/scripts/declared-annotation.ts

/**
 * Declared-profile annotation helper (plan-tune cathedral T7).
 *
 * Given a kebab signal_key from scripts/question-registry.ts, returns a
 * one-line plain-English annotation when the user's declared profile is in
 * a strong band on the matching dimension, else null. Read-only — never
 * mutates the profile.
 *
 * Signature uses kebab signal_key per D2/Codex correction. Internally maps
 * to the underscore Dimension key by consulting SIGNAL_MAP and picking the
 * dimension this signal influences most strongly.
 *
 * Used by:
 *   - hosts/claude/hooks/question-preference-hook (Layer 3 injection path,
 *     when AUQ mutation lands)
 *   - scripts/resolvers/question-tuning.ts preamble (Layer 9 fallback,
 *     host-portable path on Codex / older Claude Code)
 *
 * NOT used for AUTO_DECIDE. Annotation is advisory only — declared-only
 * per TODOS.md E1 substrate-risk guidance. Inferred-driven AUTO_DECIDE
 * remains v2.
 */
import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';

import { SIGNAL_MAP, type Dimension, ALL_DIMENSIONS } from './psychographic-signals';

const STRONG_HIGH = 0.7;
const STRONG_LOW = 0.3;

/**
 * Plain-English phrasing per dimension + band. Keep one sentence each.
 * Used directly in question prose, so phrasing matters.
 */
const DIMENSION_PHRASING: Record<Dimension, { high: string; low: string }> = {
  scope_appetite: {
    high: 'Your declared profile leans complete-implementation (boil the ocean).',
    low: 'Your declared profile leans ship-small-fast.',
  },
  risk_tolerance: {
    high: 'Your declared profile leans move-fast.',
    low: 'Your declared profile leans check-carefully.',
  },
  detail_preference: {
    high: 'Your declared profile leans verbose-with-tradeoffs.',
    low: 'Your declared profile leans terse, just-do-it.',
  },
  autonomy: {
    high: 'Your declared profile leans delegate-and-trust.',
    low: 'Your declared profile leans consult-me-first.',
  },
  architecture_care: {
    high: 'Your declared profile leans get-the-design-right.',
    low: 'Your declared profile leans pragmatic-ship-it.',
  },
};

interface DeveloperProfile {
  declared?: Partial<Record<Dimension, number>>;
}

function stateRoot(): string {
  return (
    process.env.GSTACK_STATE_ROOT ||
    process.env.GSTACK_HOME ||
    path.join(os.homedir(), '.gstack')
  );
}

function readProfile(): DeveloperProfile | null {
  try {
    const p = path.join(stateRoot(), 'developer-profile.json');
    if (!fs.existsSync(p)) return null;
    return JSON.parse(fs.readFileSync(p, 'utf-8'));
  } catch {
    return null;
  }
}

/**
 * Determine which dimension a signal_key influences most strongly.
 * Sums |delta| across all user_choice → DimensionDelta[] entries for that
 * signal, returns the dimension with the largest total influence.
 * Returns null if the signal_key isn't in the map.
 */
export function primaryDimensionFor(signalKey: string): Dimension | null {
  const entry = SIGNAL_MAP[signalKey];
  if (!entry) return null;
  const totals: Partial<Record<Dimension, number>> = {};
  for (const choice of Object.keys(entry)) {
    for (const dd of entry[choice]) {
      totals[dd.dim] = (totals[dd.dim] ?? 0) + Math.abs(dd.delta);
    }
  }
  let best: Dimension | null = null;
  let bestVal = -Infinity;
  for (const d of ALL_DIMENSIONS) {
    const v = totals[d] ?? 0;
    if (v > bestVal) {
      bestVal = v;
      best = d;
    }
  }
  return bestVal > 0 ? best : null;
}

/**
 * Given a signal_key, return a one-line plain-English annotation when
 * the user's declared profile is in a strong band on the primary dim,
 * else null.
 */
export function getDeclaredAnnotation(signalKey: string): string | null {
  if (!signalKey || typeof signalKey !== 'string') return null;
  const dim = primaryDimensionFor(signalKey);
  if (!dim) return null;

  const profile = readProfile();
  const declared = profile?.declared?.[dim];
  if (typeof declared !== 'number') return null;

  if (declared >= STRONG_HIGH) return DIMENSION_PHRASING[dim].high;
  if (declared <= STRONG_LOW) return DIMENSION_PHRASING[dim].low;
  return null;
}