@urielsh/prodify 0.1.0

package/src/core/flow-state.ts

@@ -0,0 +1,333 @@
+import { ProdifyError } from './errors.js';
+import { isRuntimeProfileName } from './paths.js';
+import { RUNTIME_STATUS } from './state.js';
+import type {
+  ExecutionMode,
+  FlowStage,
+  ProdifyState,
+  ResumeDecision,
+  RuntimeProfileName,
+  StageValidationResult
+} from '../types.js';
+
+export const STAGE_ORDER: FlowStage[] = ['understand', 'diagnose', 'architecture', 'plan', 'refactor', 'validate'];
+
+const STAGE_TASK_IDS: Record<FlowStage, string> = {
+  understand: '01-understand',
+  diagnose: '02-diagnose',
+  architecture: '03-architecture',
+  plan: '04-plan',
+  refactor: '05-refactor',
+  validate: '06-validate'
+};
+
+function cloneState(state: ProdifyState): ProdifyState {
+  return {
+    ...state,
+    runtime: {
+      ...state.runtime,
+      completed_stages: [...state.runtime.completed_stages],
+      last_validated_contract_versions: {
+        ...state.runtime.last_validated_contract_versions
+      },
+      last_validation: state.runtime.last_validation
+        ? {
+          ...state.runtime.last_validation,
+          violated_rules: [...state.runtime.last_validation.violated_rules],
+          missing_artifacts: [...state.runtime.last_validation.missing_artifacts],
+          warnings: [...state.runtime.last_validation.warnings],
+          diagnostics: [...state.runtime.last_validation.diagnostics]
+        }
+        : null,
+      failure_metadata: state.runtime.failure_metadata
+        ? { ...state.runtime.failure_metadata }
+        : null,
+      bootstrap: {
+        ...state.runtime.bootstrap
+      },
+      timestamps: {
+        ...state.runtime.timestamps
+      }
+    }
+  };
+}
+
+function nextStage(currentStage: FlowStage): FlowStage | null {
+  const index = STAGE_ORDER.indexOf(currentStage);
+  if (index === -1) {
+    return null;
+  }
+
+  return STAGE_ORDER[index + 1] ?? null;
+}
+
+function pendingState(stage: FlowStage): ProdifyState['runtime']['current_state'] {
+  return `${stage}_pending` as ProdifyState['runtime']['current_state'];
+}
+
+function completeState(stage: FlowStage): ProdifyState['runtime']['current_state'] {
+  return `${stage}_complete` as ProdifyState['runtime']['current_state'];
+}
+
+function assertAgent(agent: RuntimeProfileName): void {
+  if (!isRuntimeProfileName(agent)) {
+    throw new ProdifyError(`Unknown target agent: ${agent}`, {
+      code: 'UNKNOWN_TARGET'
+    });
+  }
+}
+
+function assertMode(mode: ExecutionMode): void {
+  if (!['interactive', 'auto'].includes(mode)) {
+    throw new ProdifyError(`Unsupported runtime mode: ${mode}`, {
+      code: 'INVALID_RUNTIME_MODE'
+    });
+  }
+}
+
+function ensureStageCheckpoint(state: ProdifyState): FlowStage {
+  if (!state.runtime.current_stage) {
+    throw new ProdifyError('Cannot complete a runtime stage when no stage is active.', {
+      code: 'RUNTIME_STAGE_MISSING'
+    });
+  }
+
+  return state.runtime.current_stage;
+}
+
+export function stageToTaskId(stage: FlowStage): string {
+  return STAGE_TASK_IDS[stage];
+}
+
+export function bootstrapFlowState(
+  state: ProdifyState,
+  { agent, mode = 'interactive', now = null }: { agent: RuntimeProfileName; mode?: ExecutionMode; now?: string | null }
+): ProdifyState {
+  assertAgent(agent);
+  assertMode(mode);
+
+  const nextState = cloneState(state);
+  nextState.runtime.status = RUNTIME_STATUS.READY;
+  nextState.runtime.current_state = 'bootstrapped';
+  nextState.runtime.mode = mode;
+  nextState.runtime.current_stage = null;
+  nextState.runtime.current_task_id = null;
+  nextState.runtime.pending_stage = STAGE_ORDER[0];
+  nextState.runtime.completed_stages = [];
+  nextState.runtime.awaiting_user_validation = false;
+  nextState.runtime.last_validation_result = 'unknown';
+  nextState.runtime.last_validation = null;
+  nextState.runtime.last_validated_contract_versions = {};
+  nextState.runtime.resumable = true;
+  nextState.runtime.blocked_reason = null;
+  nextState.runtime.failure_metadata = null;
+  nextState.runtime.bootstrap = {
+    bootstrapped: true
+  };
+  nextState.runtime.next_action = mode === 'auto' ? '$prodify-execute --auto' : '$prodify-execute';
+  nextState.runtime.timestamps.bootstrapped_at = nextState.runtime.timestamps.bootstrapped_at ?? now;
+  nextState.runtime.timestamps.last_transition_at = now;
+  nextState.runtime.timestamps.completed_at = null;
+
+  return nextState;
+}
+
+export function startFlowExecution(
+  state: ProdifyState,
+  { mode = state.runtime.mode ?? 'interactive', now = null }: { mode?: ExecutionMode; now?: string | null } = {}
+): ProdifyState {
+  assertMode(mode);
+
+  const nextState = cloneState(state);
+  nextState.runtime.mode = mode;
+
+  if (nextState.runtime.current_state === 'validate_complete') {
+    nextState.runtime.status = RUNTIME_STATUS.COMPLETE;
+    nextState.runtime.current_state = 'completed';
+    nextState.runtime.current_stage = null;
+    nextState.runtime.current_task_id = null;
+    nextState.runtime.pending_stage = null;
+    nextState.runtime.awaiting_user_validation = false;
+    nextState.runtime.resumable = false;
+    nextState.runtime.next_action = 'none';
+    nextState.runtime.timestamps.completed_at = now;
+    nextState.runtime.timestamps.last_transition_at = now;
+    return nextState;
+  }
+
+  const stage = nextState.runtime.pending_stage;
+  if (!stage) {
+    throw new ProdifyError('Cannot start flow execution without a pending stage.', {
+      code: 'RUNTIME_STAGE_MISSING'
+    });
+  }
+
+  nextState.runtime.status = RUNTIME_STATUS.RUNNING;
+  nextState.runtime.current_state = pendingState(stage);
+  nextState.runtime.current_stage = stage;
+  nextState.runtime.current_task_id = stageToTaskId(stage);
+  nextState.runtime.pending_stage = null;
+  nextState.runtime.awaiting_user_validation = false;
+  nextState.runtime.blocked_reason = null;
+  nextState.runtime.failure_metadata = null;
+  nextState.runtime.next_action = '$prodify-resume';
+  nextState.runtime.resumable = true;
+  nextState.runtime.timestamps.last_transition_at = now;
+
+  return nextState;
+}
+
+export function completeFlowStage(
+  state: ProdifyState,
+  {
+    validation,
+    now = null
+  }: {
+    validation: StageValidationResult;
+    now?: string | null;
+  }
+): ProdifyState {
+  const currentStage = ensureStageCheckpoint(state);
+  if (validation.stage !== currentStage) {
+    throw new ProdifyError(`Validation result stage ${validation.stage} does not match active stage ${currentStage}.`, {
+      code: 'VALIDATION_STAGE_MISMATCH'
+    });
+  }
+
+  if (!validation.passed) {
+    return failFlowStage(state, {
+      reason: validation.violated_rules.map((issue) => issue.message).join('; ') || 'stage validation failed',
+      validation,
+      now
+    });
+  }
+
+  const nextState = cloneState(state);
+  if (!nextState.runtime.completed_stages.includes(currentStage)) {
+    nextState.runtime.completed_stages.push(currentStage);
+  }
+
+  nextState.runtime.last_validation_result = 'pass';
+  nextState.runtime.last_validation = validation;
+  nextState.runtime.last_validated_contract_versions[currentStage] = validation.contract_version;
+  nextState.runtime.blocked_reason = null;
+  nextState.runtime.failure_metadata = null;
+  nextState.runtime.timestamps.last_transition_at = now;
+
+  const upcomingStage = nextStage(currentStage);
+  if (!upcomingStage) {
+    nextState.runtime.current_state = 'validate_complete';
+    nextState.runtime.current_stage = currentStage;
+    nextState.runtime.current_task_id = stageToTaskId(currentStage);
+    nextState.runtime.pending_stage = null;
+
+    if (nextState.runtime.mode === 'interactive') {
+      nextState.runtime.status = RUNTIME_STATUS.AWAITING_VALIDATION;
+      nextState.runtime.awaiting_user_validation = true;
+      nextState.runtime.resumable = true;
+      nextState.runtime.next_action = '$prodify-resume';
+      return nextState;
+    }
+
+    return startFlowExecution(nextState, {
+      mode: nextState.runtime.mode ?? 'auto',
+      now
+    });
+  }
+
+  if (nextState.runtime.mode === 'interactive') {
+    nextState.runtime.status = RUNTIME_STATUS.AWAITING_VALIDATION;
+    nextState.runtime.current_state = completeState(currentStage);
+    nextState.runtime.current_stage = currentStage;
+    nextState.runtime.current_task_id = stageToTaskId(currentStage);
+    nextState.runtime.pending_stage = upcomingStage;
+    nextState.runtime.awaiting_user_validation = true;
+    nextState.runtime.resumable = true;
+    nextState.runtime.next_action = '$prodify-resume';
+    return nextState;
+  }
+
+  nextState.runtime.status = RUNTIME_STATUS.READY;
+  nextState.runtime.current_state = pendingState(upcomingStage);
+  nextState.runtime.current_stage = upcomingStage;
+  nextState.runtime.current_task_id = stageToTaskId(upcomingStage);
+  nextState.runtime.pending_stage = null;
+  nextState.runtime.awaiting_user_validation = false;
+  nextState.runtime.resumable = true;
+  nextState.runtime.next_action = '$prodify-execute --auto';
+  return nextState;
+}
+
+export function failFlowStage(
+  state: ProdifyState,
+  {
+    reason,
+    validation = null,
+    now = null
+  }: {
+    reason: string;
+    validation?: StageValidationResult | null;
+    now?: string | null;
+  }
+): ProdifyState {
+  const nextState = cloneState(state);
+  nextState.runtime.status = RUNTIME_STATUS.FAILED;
+  nextState.runtime.current_state = 'failed';
+  nextState.runtime.blocked_reason = reason;
+  nextState.runtime.awaiting_user_validation = false;
+  nextState.runtime.resumable = false;
+  nextState.runtime.next_action = 'repair runtime state';
+  nextState.runtime.last_validation_result = validation ? 'fail' : nextState.runtime.last_validation_result;
+  nextState.runtime.last_validation = validation;
+  nextState.runtime.failure_metadata = {
+    stage: validation?.stage ?? nextState.runtime.current_stage,
+    contract_version: validation?.contract_version ?? null,
+    reason
+  };
+  nextState.runtime.timestamps.last_transition_at = now;
+  return nextState;
+}
+
+export function getResumeDecision(state: ProdifyState): ResumeDecision {
+  const runtime = state.runtime;
+
+  if (runtime.current_state === 'completed' || runtime.status === RUNTIME_STATUS.COMPLETE) {
+    return {
+      resumable: false,
+      command: null,
+      reason: 'flow complete'
+    };
+  }
+
+  if (runtime.current_state === 'failed' || runtime.current_state === 'blocked') {
+    return {
+      resumable: false,
+      command: null,
+      reason: runtime.blocked_reason ?? 'runtime is blocked'
+    };
+  }
+
+  if (!runtime.resumable) {
+    return {
+      resumable: false,
+      command: null,
+      reason: runtime.blocked_reason ?? 'runtime not bootstrapped'
+    };
+  }
+
+  if (runtime.status === RUNTIME_STATUS.READY) {
+    return {
+      resumable: true,
+      command: runtime.mode === 'auto' ? '$prodify-execute --auto' : '$prodify-execute',
+      reason: runtime.pending_stage
+        ? `ready for ${runtime.pending_stage}`
+        : runtime.current_state
+    };
+  }
+
+  return {
+    resumable: true,
+    command: '$prodify-resume',
+    reason: runtime.current_state
+  };
+}

package/src/core/fs.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { FileEntry } from '../types.js';
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(targetPath: string): Promise<void> {
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+export async function writeFileEnsuringDir(targetPath: string, content: string): Promise<void> {
+  await ensureDir(path.dirname(targetPath));
+  await fs.writeFile(targetPath, content, 'utf8');
+}
+
+export async function copyTree(sourceDir: string, destinationDir: string): Promise<void> {
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  await ensureDir(destinationDir);
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyTree(sourcePath, destinationPath);
+    } else if (entry.isFile()) {
+      await writeFileEnsuringDir(destinationPath, await fs.readFile(sourcePath, 'utf8'));
+    }
+  }
+}
+
+export async function listFilesRecursive(rootDir: string, prefix = ''): Promise<FileEntry[]> {
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+  const files: FileEntry[] = [];
+
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const nextPrefix = prefix ? path.posix.join(prefix, entry.name) : entry.name;
+    const fullPath = path.join(rootDir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(fullPath, nextPrefix)));
+    } else if (entry.isFile()) {
+      files.push({
+        fullPath,
+        relativePath: nextPrefix
+      });
+    }
+  }
+
+  return files;
+}

package/src/core/paths.ts

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import type { RuntimeProfileName } from '../types.js';
+
+export const RUNTIME_PROFILE_NAMES = ['codex', 'claude', 'copilot', 'opencode'] as const satisfies readonly RuntimeProfileName[];
+export const USER_OWNED_CANONICAL_PATHS = [
+  '.prodify/AGENTS.md',
+  '.prodify/project.md',
+  '.prodify/planning.md'
+ ] as const;
+export const USER_OWNED_CANONICAL_PREFIXES = [
+  '.prodify/contracts-src/'
+] as const;
+
+export const REQUIRED_CANONICAL_PATHS = [
+  '.prodify/AGENTS.md',
+  '.prodify/artifacts/README.md',
+  '.prodify/contracts-src/README.md',
+  '.prodify/contracts-src/architecture.contract.md',
+  '.prodify/contracts-src/diagnose.contract.md',
+  '.prodify/contracts-src/plan.contract.md',
+  '.prodify/contracts-src/refactor.contract.md',
+  '.prodify/contracts-src/understand.contract.md',
+  '.prodify/contracts-src/validate.contract.md',
+  '.prodify/metrics/README.md',
+  '.prodify/project.md',
+  '.prodify/planning.md',
+  '.prodify/runtime-commands.md',
+  '.prodify/skills/README.md',
+  '.prodify/skills/registry.json',
+  '.prodify/skills/domain/react-frontend.skill.json',
+  '.prodify/skills/domain/typescript-backend.skill.json',
+  '.prodify/skills/quality-policy/maintainability-review.skill.json',
+  '.prodify/skills/quality-policy/security-hardening.skill.json',
+  '.prodify/skills/quality-policy/test-hardening.skill.json',
+  '.prodify/skills/stage-method/architecture-method.skill.json',
+  '.prodify/skills/stage-method/codebase-scanning.skill.json',
+  '.prodify/skills/stage-method/diagnosis-method.skill.json',
+  '.prodify/skills/stage-method/planning-method.skill.json',
+  '.prodify/skills/stage-method/refactoring-method.skill.json',
+  '.prodify/skills/stage-method/validation-method.skill.json',
+  '.prodify/state.json',
+  '.prodify/tasks/README.md',
+  '.prodify/rules/README.md',
+  '.prodify/templates/README.md',
+  '.prodify/version.json'
+ ] as const;
+
+export function isRuntimeProfileName(value: unknown): value is RuntimeProfileName {
+  return typeof value === 'string' && (RUNTIME_PROFILE_NAMES as readonly string[]).includes(value);
+}
+
+export function normalizeRepoRelativePath(relativePath: string): string {
+  const normalized = relativePath.replaceAll('\\', '/');
+  return path.posix.normalize(normalized).replace(/^\/+/, '');
+}
+
+export function resolveRepoPath(repoRoot: string, relativePath: string): string {
+  return path.join(repoRoot, ...normalizeRepoRelativePath(relativePath).split('/'));
+}
+
+export function resolveCanonicalPath(repoRoot: string, relativePath: string): string {
+  return resolveRepoPath(repoRoot, relativePath);
+}

package/src/core/preset-validation.ts

@@ -0,0 +1,47 @@
+import { ProdifyError } from './errors.js';
+import type { PresetEntry } from '../types.js';
+
+const REQUIRED_PRESET_ENTRIES = [
+  '.prodify/AGENTS.md',
+  '.prodify/artifacts/README.md',
+  '.prodify/contracts-src/README.md',
+  '.prodify/contracts-src/architecture.contract.md',
+  '.prodify/contracts-src/diagnose.contract.md',
+  '.prodify/contracts-src/plan.contract.md',
+  '.prodify/contracts-src/refactor.contract.md',
+  '.prodify/contracts-src/understand.contract.md',
+  '.prodify/contracts-src/validate.contract.md',
+  '.prodify/metrics/README.md',
+  '.prodify/project.md',
+  '.prodify/planning.md',
+  '.prodify/runtime-commands.md',
+  '.prodify/skills/README.md',
+  '.prodify/skills/registry.json',
+  '.prodify/skills/domain/react-frontend.skill.json',
+  '.prodify/skills/domain/typescript-backend.skill.json',
+  '.prodify/skills/quality-policy/maintainability-review.skill.json',
+  '.prodify/skills/quality-policy/security-hardening.skill.json',
+  '.prodify/skills/quality-policy/test-hardening.skill.json',
+  '.prodify/skills/stage-method/architecture-method.skill.json',
+  '.prodify/skills/stage-method/codebase-scanning.skill.json',
+  '.prodify/skills/stage-method/diagnosis-method.skill.json',
+  '.prodify/skills/stage-method/planning-method.skill.json',
+  '.prodify/skills/stage-method/refactoring-method.skill.json',
+  '.prodify/skills/stage-method/validation-method.skill.json',
+  '.prodify/state.json',
+  '.prodify/version.json',
+  '.prodify/tasks/README.md',
+  '.prodify/rules/README.md',
+  '.prodify/templates/README.md'
+];
+
+export function validatePresetEntries(entries: PresetEntry[]): void {
+  const entryPaths = new Set(entries.map((entry) => entry.relativePath));
+  const missing = REQUIRED_PRESET_ENTRIES.filter((requiredPath) => !entryPaths.has(requiredPath));
+
+  if (missing.length > 0) {
+    throw new ProdifyError(`Default preset is missing required canonical files: ${missing.join(', ')}`, {
+      code: 'PRESET_INVALID'
+    });
+  }
+}

package/src/core/prompt-builder.ts

@@ -0,0 +1,73 @@
+import { STAGE_ORDER, stageToTaskId } from './flow-state.js';
+import { getRuntimeProfile } from './targets.js';
+import type { ProdifyState, RuntimeProfileName } from '../types.js';
+
+export function buildBootstrapPrompt(profileName: RuntimeProfileName | null | undefined = 'codex'): string {
+  return (getRuntimeProfile(profileName ?? 'codex') ?? getRuntimeProfile('codex'))!.bootstrapPrompt;
+}
+
+export function hasManualBootstrapGuidance(markdown: string): boolean {
+  return markdown.includes('.prodify/AGENTS.md') && markdown.includes('$prodify-init');
+}
+
+export function buildRuntimeCommandReference(options: {
+  concise?: boolean;
+  profileName?: RuntimeProfileName | null;
+} = {}): string {
+  const concise = options.concise ?? false;
+  const profile = getRuntimeProfile(options.profileName ?? 'codex') ?? getRuntimeProfile('codex');
+  const bootstrapPrompt = profile?.bootstrapPrompt ?? buildBootstrapPrompt('codex');
+  const lines = [
+    '# Runtime Commands',
+    '',
+    'Manual bootstrap:',
+    `- First tell the agent: "${bootstrapPrompt}"`,
+    '- Before using `$prodify-*` in a new agent environment, run `prodify setup-agent <agent>` once outside the repo.',
+    '- Keep the workflow anchored to `.prodify/` files only.',
+    '- Humans edit `.prodify/contracts-src/`; runtime reads only `.prodify/contracts/*.contract.json`.',
+    '- Stage skill definitions live under `.prodify/skills/` and can assist a stage without overriding its contract or validator.',
+    '',
+    'Run these commands inside your coding agent after `prodify init` has created the repo scaffolding.',
+    '',
+    '- `$prodify-init`: inspect `.prodify/`, detect or resolve the active agent runtime, initialize `.prodify/state.json`, and prepare the bootstrapped state without locking the repo to one agent.',
+    '- `$prodify-execute`: run one stage, write stage artifacts, validate them against compiled contracts, then pause in interactive mode.',
+    '- `$prodify-execute --auto`: continue through the full workflow without pausing unless there is a hard failure, policy block, required approval threshold, or invalid state.',
+    '- `$prodify-resume`: continue from `.prodify/state.json` after a pause, interruption, or validation checkpoint.',
+    '',
+    'Stage order:',
+    `- ${STAGE_ORDER.map((stage) => `${stage} (${stageToTaskId(stage)})`).join(' -> ')}`,
+    '',
+    'Resume rules:',
+    '- interactive mode pauses between stages and expects validation before resume',
+    '- auto mode keeps advancing while state remains valid',
+    '- failed or corrupt state must stop with a clear reason'
+  ];
+
+  if (concise) {
+    return [
+      '# Runtime Commands',
+      '',
+      `- First prompt: "${bootstrapPrompt}"`,
+      '- Run `prodify setup-agent <agent>` once per machine before using agent runtime commands.',
+      '- `$prodify-init`: bootstrap `.prodify/state.json` for the active agent runtime without repo-level locking.',
+      '- `$prodify-execute`: run one stage, then pause.',
+      '- `$prodify-execute --auto`: continue until a hard stop.',
+      '- `$prodify-resume`: continue from saved state.'
+    ].join('\n') + '\n';
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+export function buildExecutionPrompt(state: ProdifyState): string {
+  const stage = state.runtime.current_stage ?? state.runtime.pending_stage ?? 'none';
+  const task = state.runtime.current_task_id ?? (state.runtime.pending_stage ? stageToTaskId(state.runtime.pending_stage) : 'none');
+  return [
+    `Current stage: ${stage}`,
+    `Current task: ${task}`,
+    `Current state: ${state.runtime.current_state}`,
+    `Mode: ${state.runtime.mode ?? 'unset'}`,
+    `Status: ${state.runtime.status}`,
+    `Next action: ${state.runtime.next_action}`
+  ].join('\n');
+}

package/src/core/repo-context.ts

@@ -0,0 +1,93 @@
+import fs from 'node:fs/promises';
+
+import { listFilesRecursive, pathExists } from './fs.js';
+import { resolveRepoPath } from './paths.js';
+import type { RepoContextSnapshot } from '../types.js';
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+async function readPackageJson(repoRoot: string): Promise<Record<string, unknown> | null> {
+  const packageJsonPath = resolveRepoPath(repoRoot, 'package.json');
+  if (!(await pathExists(packageJsonPath))) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(await fs.readFile(packageJsonPath, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function dependencyEntries(packageJson: Record<string, unknown> | null): string[] {
+  if (!packageJson) {
+    return [];
+  }
+
+  const sections = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+  const names = [];
+  for (const section of sections) {
+    const record = packageJson[section];
+    if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+      continue;
+    }
+
+    names.push(...Object.keys(record as Record<string, unknown>));
+  }
+
+  return sortedUnique(names);
+}
+
+export async function detectRepoContext(repoRoot: string): Promise<RepoContextSnapshot> {
+  const packageJson = await readPackageJson(repoRoot);
+  const dependencies = dependencyEntries(packageJson);
+  const files = await listFilesRecursive(repoRoot);
+  const relativePaths = files.map((entry) => entry.relativePath.replaceAll('\\', '/'));
+
+  const hasTsConfig = relativePaths.includes('tsconfig.json');
+  const hasTypeScriptSources = relativePaths.some((relativePath) => relativePath.endsWith('.ts') || relativePath.endsWith('.tsx'));
+  const hasJavaScriptSources = relativePaths.some((relativePath) => relativePath.endsWith('.js') || relativePath.endsWith('.jsx'));
+  const hasTests = relativePaths.some((relativePath) => relativePath.startsWith('tests/') || relativePath.includes('.test.'));
+  const hasCliEntrypoint = relativePaths.includes('src/cli.ts')
+    || relativePaths.includes('src/cli.js')
+    || relativePaths.includes('bin/prodify');
+  const hasCoreDir = relativePaths.some((relativePath) => relativePath.startsWith('src/core/'));
+  const hasCommandsDir = relativePaths.some((relativePath) => relativePath.startsWith('src/commands/'));
+
+  const languages = sortedUnique([
+    ...(hasTypeScriptSources || hasTsConfig ? ['typescript'] : []),
+    ...(hasJavaScriptSources || packageJson ? ['javascript'] : [])
+  ]);
+
+  const frameworks = sortedUnique([
+    ...(dependencies.includes('react') || dependencies.includes('react-dom') ? ['react'] : [])
+  ]);
+
+  const projectTypes = sortedUnique([
+    ...(packageJson ? ['node-package'] : []),
+    ...(hasCliEntrypoint ? ['cli'] : []),
+    ...(frameworks.includes('react') ? ['frontend-app'] : []),
+    ...(!frameworks.includes('react') && hasCoreDir ? ['backend-service'] : [])
+  ]);
+
+  const architecturePatterns = sortedUnique([
+    ...(hasCoreDir && hasCommandsDir ? ['layered-cli'] : []),
+    ...(relativePaths.some((relativePath) => relativePath.startsWith('src/contracts/')) ? ['contract-driven-runtime'] : [])
+  ]);
+
+  const riskSignals = sortedUnique([
+    ...(dependencies.length > 0 ? ['external-dependencies'] : []),
+    ...(hasCliEntrypoint ? ['cli-surface'] : []),
+    ...(!hasTests ? ['missing-tests'] : [])
+  ]);
+
+  return {
+    languages,
+    frameworks,
+    project_types: projectTypes,
+    architecture_patterns: architecturePatterns,
+    risk_signals: riskSignals
+  };
+}