audita/internal/cli/run.go

package cli

import (
	"context"
	"encoding/json"
	"errors"
	"flag"
	"fmt"
	"io"
	"os"
	"path/filepath"
	"strings"
	"time"

	"gitea.maximumdirect.net/eric/audita/internal/core/chunking"
	"gitea.maximumdirect.net/eric/audita/internal/core/config"
	"gitea.maximumdirect.net/eric/audita/internal/core/diagnostics"
	coreio "gitea.maximumdirect.net/eric/audita/internal/core/io"
	"gitea.maximumdirect.net/eric/audita/internal/core/normalization"
	"gitea.maximumdirect.net/eric/audita/internal/core/outputschema"
	"gitea.maximumdirect.net/eric/audita/internal/core/reporting"
	"gitea.maximumdirect.net/eric/audita/internal/core/schema"
	"gitea.maximumdirect.net/eric/audita/internal/framework/contracts"
	"gitea.maximumdirect.net/eric/audita/internal/framework/llm"
	"gitea.maximumdirect.net/eric/audita/internal/framework/modules"
	"gitea.maximumdirect.net/eric/audita/internal/framework/processreport"
	"gitea.maximumdirect.net/eric/audita/internal/framework/proposal_generation"
	"gitea.maximumdirect.net/eric/audita/internal/framework/runner"
	"gitea.maximumdirect.net/eric/audita/internal/framework/validators"
)

type noOpStructuredLLMClient struct{}

func (c noOpStructuredLLMClient) CompleteStructured(ctx context.Context, req contracts.StructuredCompletionRequest, out any) (contracts.StructuredCompletionResponse, error) {
	_ = ctx
	_ = req
	switch target := out.(type) {
	case *validators.LLMValidationResponse:
		*target = validators.LLMValidationResponse{Validations: []validators.LLMValidationDecision{}}
	case *proposal_generation.StructuredCorrectionSet:
		*target = proposal_generation.StructuredCorrectionSet{Corrections: nil}
	}
	return contracts.StructuredCompletionResponse{}, nil
}

func shouldUseNoOpLLMClientForTests() bool {
	return strings.HasSuffix(filepath.Base(os.Args[0]), ".test") || os.Getenv("GO_WANT_HELPER_PROCESS") == "1"
}

type processInvocation struct {
	TranscriptPath  string
	GlossaryPath    string
	OutputPath      string
	ReportJSONPath  string
	Config          config.Config
	ConfigPath      string
	ConfigSource    string
	ConfigVersion   *int
	ExplicitModules bool
}

var processModuleFactory runner.ModuleFactory
var processProposalLLMClient contracts.StructuredLLMClient
var processProposalLLMScheduler runner.ValidationScheduler
var processValidationLLMClient contracts.StructuredLLMClient
var processValidationLLMScheduler runner.ValidationScheduler
var processRunnerContext = func() (context.Context, context.CancelFunc) {
	return context.Background(), func() {}
}

var processRunner = func(inv processInvocation, stdout io.Writer) (*normalization.NormalizationSummary, *chunking.Summary, *runner.RunOutput, *diagnostics.RunDirectory, error) {
	runDir, err := diagnostics.NewRunDirectory(inv.Config.WorkDir, string(inv.Config.WorkDirRetention))
	if err != nil {
		return nil, nil, nil, nil, fmt.Errorf("run_dir_creation: %w", err)
	}

	fail := func(phase string, err error, runOutput *runner.RunOutput) (*normalization.NormalizationSummary, *chunking.Summary, *runner.RunOutput, *diagnostics.RunDirectory, error) {
		_ = runDir.WriteErrorLog(fmt.Sprintf("%s: %v", phase, err))
		return nil, nil, runOutput, runDir, fmt.Errorf("%s: %w", phase, err)
	}

	if err := runDir.WriteInvocationMetadata(diagnostics.InvocationMetadata{
		Operation:             "process",
		TranscriptPath:        inv.TranscriptPath,
		GlossaryPath:          inv.GlossaryPath,
		OutputPath:            inv.OutputPath,
		ReportJSONPath:        inv.ReportJSONPath,
		ConfigPath:            inv.ConfigPath,
		ConfigSource:          inv.ConfigSource,
		ConfigVersion:         inv.ConfigVersion,
		TranscriptDescription: inv.Config.TranscriptDescription,
		Modules:               append([]string(nil), inv.Config.Modules...),
	}); err != nil {
		_ = runDir.WriteErrorLog(fmt.Sprintf("invocation_metadata: %v", err))
	}
	if err := runDir.WriteEffectiveConfig(inv.Config); err != nil {
		_ = runDir.WriteErrorLog(fmt.Sprintf("effective_config: %v", err))
	}

	transcriptBytes, err := coreio.ReadRequiredFile(inv.TranscriptPath, "transcript")
	if err != nil {
		return fail("transcript_read", err, nil)
	}

	glossaryBytes, err := coreio.ReadRequiredFile(inv.GlossaryPath, "glossary")
	if err != nil {
		return fail("glossary_read", err, nil)
	}

	sourceTranscript, err := schema.ParseSourceTranscriptJSON(transcriptBytes)
	if err != nil {
		return fail("transcript_schema", err, nil)
	}

	glossary, err := schema.ParseGlossaryYAML(glossaryBytes)
	if err != nil {
		return fail("glossary_schema", err, nil)
	}

	if err := runDir.WriteSourceTranscript(sourceTranscript, transcriptBytes); err != nil {
		_ = runDir.WriteErrorLog(fmt.Sprintf("source_artifact: %v", err))
	}

	canonical := sourceToCanonicalTranscript(sourceTranscript)
	normalizer := normalization.NewNormalizer(normalization.NormalizationConfig{
		MaxSegmentGap:      inv.Config.Normalization.MaxSegmentGap,
		EllipsisGap:        inv.Config.Normalization.EllipsisGap,
		MaxSegmentDuration: inv.Config.Normalization.MaxSegmentDuration,
		MaxSegmentTokens:   inv.Config.Normalization.MaxSegmentTokens,
	})

	normalizedTranscript, normSummary := normalizer.Normalize(canonical)

	if err := runDir.WriteNormalizedTranscript(normalizedTranscript); err != nil {
		_ = runDir.WriteErrorLog(fmt.Sprintf("normalized_artifact: %v", err))
	}
	if err := runDir.WriteNormalizationSummary(normSummary); err != nil {
		_ = runDir.WriteErrorLog(fmt.Sprintf("normalization_summary: %v", err))
	}

	// Compute chunks after normalization
	chunker := chunking.NewChunker(chunking.ChunkingConfig{
		MaxSectionTokens: inv.Config.MaxSectionTokens,
		MinSectionTokens: inv.Config.MinSectionTokens,
		TargetSections:   inv.Config.TargetSections,
	})

	sections, chunkErr := chunker.ChunkTranscript(normalizedTranscript)
	if chunkErr != nil {
		return fail("chunking", chunkErr, nil)
	}

	chunkConfig := chunking.ChunkingConfig{
		MaxSectionTokens: inv.Config.MaxSectionTokens,
		MinSectionTokens: inv.Config.MinSectionTokens,
		TargetSections:   inv.Config.TargetSections,
	}
	chunkSummary := chunking.ComputeSummary(sections, chunkConfig)
	chunkDetailedSummary := chunking.ComputeDetailedSummary(sections, chunkConfig)

	if err := runDir.WriteChunkingSummary(&chunkDetailedSummary); err != nil {
		_ = runDir.WriteErrorLog(fmt.Sprintf("chunking_summary: %v", err))
	}

	workingTranscript := normalizedTranscript
	var runOutput *runner.RunOutput
	moduleFactory := processModuleFactory
	if moduleFactory == nil {
		moduleFactory = modules.NewFactory(modules.Dependencies{
			Config:         &inv.Config,
			Glossary:       glossary,
			DiagnosticsDir: runDir.Path(),
		})
	}
	if moduleFactory != nil {
		proposalLLMClient := processProposalLLMClient
		validationLLMClient := processValidationLLMClient
		proposalScheduler := processProposalLLMScheduler
		validationScheduler := processValidationLLMScheduler

		if processModuleFactory == nil {
			// Production runtime path: construct clients/schedulers from config.
			if proposalLLMClient == nil {
				if shouldUseNoOpLLMClientForTests() {
					proposalLLMClient = noOpStructuredLLMClient{}
				} else {
					primaryCfg := llm.ResolvePrimaryConfig(inv.Config)
					client, clientErr := llm.NewOpenAICompatibleClient(primaryCfg.ToOpenAICompatibleClientConfig(nil))
					if clientErr != nil {
						return fail("runner_setup", clientErr, nil)
					}
					proposalLLMClient = client
				}
			}
			if validationLLMClient == nil {
				if shouldUseNoOpLLMClientForTests() {
					validationLLMClient = noOpStructuredLLMClient{}
				} else {
					validationCfg := llm.ResolveValidationConfig(inv.Config)
					client, clientErr := llm.NewOpenAICompatibleClient(validationCfg.ToOpenAICompatibleClientConfig(nil))
					if clientErr != nil {
						return fail("runner_setup", clientErr, nil)
					}
					validationLLMClient = client
				}
			}
			globalScheduler := proposalScheduler
			if globalScheduler == nil {
				s, sErr := llm.NewScheduler(inv.Config.TotalLLMConcurrency)
				if sErr != nil {
					return fail("runner_setup", sErr, nil)
				}
				globalScheduler = s
			}
			if proposalScheduler == nil {
				proposalScheduler = globalScheduler
				if inv.Config.EffectiveProposalLLMConcurrency() < inv.Config.TotalLLMConcurrency {
					s, sErr := llm.NewScheduler(inv.Config.EffectiveProposalLLMConcurrency())
					if sErr != nil {
						return fail("runner_setup", sErr, nil)
					}
					proposalScheduler = composeSchedulers(globalScheduler, s)
				}
			}
			if validationScheduler == nil {
				validationScheduler = globalScheduler
				if inv.Config.ValidationLLMConcurrency != nil && inv.Config.EffectiveValidationLLMConcurrency() < inv.Config.TotalLLMConcurrency {
					s, sErr := llm.NewScheduler(inv.Config.EffectiveValidationLLMConcurrency())
					if sErr != nil {
						return fail("runner_setup", sErr, nil)
					}
					validationScheduler = composeSchedulers(globalScheduler, s)
				}
			}
		}

		moduleSpecs, err := contracts.ResolveModuleRunSpecs(inv.Config.Modules)
		if err != nil {
			return fail("runner_setup", err, nil)
		}

		runCtx, cancelRun := processRunnerContext()
		defer cancelRun()
		runnerResult, runErr := runner.New(moduleFactory).Run(runCtx, runner.RunInput{
			Config:      &inv.Config,
			Transcript:  normalizedTranscript,
			Glossary:    glossary,
			ModuleSpecs: moduleSpecs,
			EffectiveConcurrency: runner.EffectiveConcurrencyLimits{
				TotalLLM:      inv.Config.TotalLLMConcurrency,
				ProposalLLM:   inv.Config.EffectiveProposalLLMConcurrency(),
				ValidationLLM: inv.Config.EffectiveValidationLLMConcurrency(),
			},
			ProposalLLMClient:        proposalLLMClient,
			ProposalLLMScheduler:     proposalScheduler,
			ProposalDiagnosticsDir:   runDir.Path(),
			ValidationLLMClient:      validationLLMClient,
			ValidationLLMScheduler:   validationScheduler,
			ValidationDiagnosticsDir: runDir.Path(),
		})
		runOutput = &runnerResult
		if runErr != nil {
			return fail("runner_execution", runErr, runOutput)
		}
		workingTranscript = runnerResult.FinalTranscript
	}

	encoderDef, err := outputschema.Resolve(inv.Config.OutputSchema)
	if err != nil {
		return fail("output_schema", err, runOutput)
	}
	outputBytes, err := encoderDef.Encoder(workingTranscript)
	if err != nil {
		return fail("serialization", err, runOutput)
	}

	if strings.TrimSpace(inv.OutputPath) != "" {
		if err := coreio.WriteFile(inv.OutputPath, outputBytes); err != nil {
			return fail("output_write", err, runOutput)
		}
		return normSummary, &chunkSummary, runOutput, runDir, nil
	}

	if _, err := stdout.Write(outputBytes); err != nil {
		return fail("stdout_write", err, runOutput)
	}

	return normSummary, &chunkSummary, runOutput, runDir, nil
}

func sourceToCanonicalTranscript(source *schema.SourceTranscript) *schema.Transcript {
	segments := make([]schema.Segment, len(source.Segments))
	for i, s := range source.Segments {
		id := i + 1
		if s.ID != nil {
			id = *s.ID
		}
		segments[i] = schema.Segment{
			ID:         id,
			Speaker:    s.Speaker,
			Start:      s.Start,
			End:        s.End,
			Text:       s.Text,
			Categories: s.Categories,
		}
	}
	return &schema.Transcript{Segments: segments}
}

type chainedScheduler struct {
	schedulers []runner.ValidationScheduler
}

func (s chainedScheduler) Run(ctx context.Context, fn func(context.Context) error) error {
	if len(s.schedulers) == 0 {
		return fn(ctx)
	}
	run := fn
	for i := len(s.schedulers) - 1; i >= 0; i-- {
		scheduler := s.schedulers[i]
		next := run
		run = func(callCtx context.Context) error {
			return scheduler.Run(callCtx, next)
		}
	}
	return run(ctx)
}

func composeSchedulers(schedulers ...runner.ValidationScheduler) runner.ValidationScheduler {
	filtered := make([]runner.ValidationScheduler, 0, len(schedulers))
	for _, scheduler := range schedulers {
		if scheduler != nil {
			filtered = append(filtered, scheduler)
		}
	}
	switch len(filtered) {
	case 0:
		return nil
	case 1:
		return filtered[0]
	default:
		return chainedScheduler{schedulers: filtered}
	}
}

// Run executes the Audita CLI with the provided arguments and streams.
func Run(args []string, stdout, stderr io.Writer) int {
	if len(args) == 0 {
		writeRootUsage(stdout)
		return 0
	}

	if isHelpCommand(args) {
		writeRootUsage(stdout)
		return 0
	}

	if args[0] == "process" {
		return runProcess(args[1:], stdout, stderr)
	}
	if args[0] == "config" {
		return runConfig(args[1:], stdout, stderr)
	}

	fmt.Fprintf(stderr, "audita: unknown command %q\n\n", args[0])
	writeRootUsage(stderr)
	return 2
}

func runProcess(args []string, stdout, stderr io.Writer) int {
	startedAt := time.Now().UTC()

	configPathOverride, configPathOverrideSet, err := findConfigPathOverride(args)
	if err != nil {
		fmt.Fprintf(stderr, "audita process: invalid CLI configuration: %v\n", err)
		return 2
	}
	effectiveConfig, err := config.LoadEffectiveConfig(configPathOverride, configPathOverrideSet)
	if err != nil {
		var effectiveConfigErr *config.EffectiveConfigError
		if errors.As(err, &effectiveConfigErr) {
			switch effectiveConfigErr.Kind {
			case config.EffectiveConfigErrorLoadFile, config.EffectiveConfigErrorApplyFile:
				fmt.Fprintf(stderr, "audita process: invalid config file: %v\n", effectiveConfigErr)
			case config.EffectiveConfigErrorApplyEnv:
				fmt.Fprintf(stderr, "audita process: invalid environment configuration: %v\n", effectiveConfigErr)
			default:
				fmt.Fprintf(stderr, "audita process: %v\n", effectiveConfigErr)
			}
		} else {
			fmt.Fprintf(stderr, "audita process: %v\n", err)
		}
		return 2
	}

	cfg := effectiveConfig.Config
	configPath := effectiveConfig.ConfigPath
	configSource := effectiveConfig.ConfigSource
	configVersion := effectiveConfig.ConfigVersion

	fs, pFlags := newProcessFlagSet(cfg, stderr)

	if isHelpCommand(args) || hasHelpFlag(args) {
		writeProcessUsage(stdout, fs)
		return 0
	}

	parseArgs := args
	transcriptFromFront := ""
	if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
		transcriptFromFront = args[0]
		parseArgs = args[1:]
	}

	if err := fs.Parse(parseArgs); err != nil {
		if errors.Is(err, flag.ErrHelp) {
			writeProcessUsage(stdout, fs)
			return 0
		}
		return 2
	}

	overrides, explicitModules := processCLIOverrides(fs, pFlags)

	if err := cfg.ApplyCLIOverrides(overrides); err != nil {
		fmt.Fprintf(stderr, "audita process: invalid CLI configuration: %v\n", err)
		return 2
	}

	remaining := fs.Args()
	positional := make([]string, 0, len(remaining)+1)
	if transcriptFromFront != "" {
		positional = append(positional, transcriptFromFront)
	}
	positional = append(positional, remaining...)

	if len(positional) != 1 {
		fmt.Fprintln(stderr, "audita process: expected exactly 1 transcript JSON path argument")
		return 2
	}
	if strings.TrimSpace(*pFlags.glossaryPath) == "" {
		fmt.Fprintln(stderr, "audita process: --glossary is required")
		return 2
	}

	inv := processInvocation{
		TranscriptPath:  positional[0],
		GlossaryPath:    *pFlags.glossaryPath,
		OutputPath:      *pFlags.outputPath,
		ReportJSONPath:  *pFlags.reportJSONPath,
		Config:          cfg,
		ConfigPath:      configPath,
		ConfigSource:    configSource,
		ConfigVersion:   configVersion,
		ExplicitModules: explicitModules,
	}

	normSummary, chunkSummary, runOutput, runDir, runErr := processRunner(inv, stdout)
	completedAt := time.Now().UTC()

	if runErr != nil {
		if runDir != nil && runOutput != nil {
			if runOutput.Utilization != nil {
				_ = runDir.WriteJSONArtifact(diagnostics.ArtifactUtilizationSummary, runOutput.Utilization)
			}
			_ = runDir.WriteJSONArtifact(diagnostics.ArtifactCorrectionLedger, processreport.BuildCorrectionLedger(processreport.CorrectionLedgerInput{
				RunDirectoryPath: runDir.Path(),
				RunOutput:        runOutput,
			}))
		}
		errorPhase, errorMessage := extractErrorPhase(runErr)
		report := processreport.Build(processReportInput("failed", inv, runDir, startedAt, completedAt, errorMessage, errorPhase, nil, nil, runOutput))

		if strings.TrimSpace(inv.ReportJSONPath) != "" {
			if err := reporting.WriteProcessReport(inv.ReportJSONPath, report); err != nil {
				fmt.Fprintf(stderr, "audita process: %v\n", err)
			}
		}

		if runDir != nil {
			_ = runDir.WriteReport(report)
			_ = runDir.ApplyRetention(diagnostics.RetentionDecisionInput{
				RunSucceeded: false,
			})
		}

		fmt.Fprintf(stderr, "audita process: %v\n", runErr)
		if runDir != nil {
			fmt.Fprintf(stderr, "audita process: diagnostics: %s\n", runDir.Path())
		}
		return 1
	}

	if runDir != nil && runOutput != nil {
		if runOutput.Utilization != nil {
			_ = runDir.WriteJSONArtifact(diagnostics.ArtifactUtilizationSummary, runOutput.Utilization)
		}
		_ = runDir.WriteJSONArtifact(diagnostics.ArtifactCorrectionLedger, processreport.BuildCorrectionLedger(processreport.CorrectionLedgerInput{
			RunDirectoryPath: runDir.Path(),
			RunOutput:        runOutput,
		}))
	}

	report := processreport.Build(processReportInput("success", inv, runDir, startedAt, completedAt, "", "", normSummary, chunkSummary, runOutput))

	if strings.TrimSpace(inv.ReportJSONPath) != "" {
		if err := reporting.WriteProcessReport(inv.ReportJSONPath, report); err != nil {
			if runDir != nil {
				_ = runDir.WriteErrorLog(fmt.Sprintf("report_write: %v", err))
				_ = runDir.ApplyRetention(diagnostics.RetentionDecisionInput{
					RunSucceeded: false,
				})
			}
			fmt.Fprintf(stderr, "audita process: %v\n", err)
			return 1
		}
	}

	if runDir != nil {
		_ = runDir.WriteReport(report)
		if err := runDir.ApplyRetention(diagnostics.RetentionDecisionInput{
			RunSucceeded:          true,
			HasSkippedCorrections: processreport.HasSkippedCorrections(runOutput),
		}); err != nil {
			fmt.Fprintf(stderr, "audita process: failed to apply work-dir retention: %v\n", err)
			return 1
		}
	}

	return 0
}

func runConfig(args []string, stdout, stderr io.Writer) int {
	if len(args) == 0 || isHelpCommand(args) || hasHelpFlag(args) {
		writeConfigUsage(stdout)
		return 0
	}

	switch args[0] {
	case "validate":
		return runConfigValidate(args[1:], stdout, stderr)
	case "print-effective":
		return runConfigPrintEffective(args[1:], stdout, stderr)
	default:
		fmt.Fprintf(stderr, "audita config: unknown command %q\n\n", args[0])
		writeConfigUsage(stderr)
		return 2
	}
}

func runConfigValidate(args []string, stdout, stderr io.Writer) int {
	fs := flag.NewFlagSet("config validate", flag.ContinueOnError)
	fs.SetOutput(stderr)
	configPath := fs.String("config", "", "Path to versioned YAML config file")

	if err := fs.Parse(args); err != nil {
		if errors.Is(err, flag.ErrHelp) {
			writeConfigValidateUsage(stdout)
			return 0
		}
		return 2
	}
	if strings.TrimSpace(*configPath) == "" {
		fmt.Fprintln(stderr, "audita config validate: --config is required")
		return 2
	}
	if len(fs.Args()) != 0 {
		fmt.Fprintln(stderr, "audita config validate: unexpected positional arguments")
		return 2
	}

	fileCfg, err := config.LoadFileConfig(strings.TrimSpace(*configPath))
	if err != nil {
		fmt.Fprintf(stderr, "audita config validate: %v\n", err)
		return 2
	}
	cfg := config.Default()
	if err := cfg.ApplyFileConfig(fileCfg); err != nil {
		fmt.Fprintf(stderr, "audita config validate: %v\n", err)
		return 2
	}
	if err := cfg.Validate(); err != nil {
		fmt.Fprintf(stderr, "audita config validate: %v\n", err)
		return 2
	}
	fmt.Fprintln(stdout, "config is valid")
	return 0
}

func runConfigPrintEffective(args []string, stdout, stderr io.Writer) int {
	fs := flag.NewFlagSet("config print-effective", flag.ContinueOnError)
	fs.SetOutput(stderr)
	configPath := fs.String("config", "", "Path to versioned YAML config file")
	if err := fs.Parse(args); err != nil {
		if errors.Is(err, flag.ErrHelp) {
			writeConfigPrintEffectiveUsage(stdout)
			return 0
		}
		return 2
	}
	if len(fs.Args()) != 0 {
		fmt.Fprintln(stderr, "audita config print-effective: unexpected positional arguments")
		return 2
	}

	configPathValue := strings.TrimSpace(*configPath)
	configPathSet := configPathValue != ""
	effectiveConfig, err := config.LoadEffectiveConfig(configPathValue, configPathSet)
	if err != nil {
		fmt.Fprintf(stderr, "audita config print-effective: %v\n", err)
		return 2
	}

	cfg := effectiveConfig.Config

	redacted := cfg.Redacted()
	out, err := json.MarshalIndent(redacted, "", "  ")
	if err != nil {
		fmt.Fprintf(stderr, "audita config print-effective: %v\n", err)
		return 1
	}
	out = append(out, '\n')
	if _, err := stdout.Write(out); err != nil {
		fmt.Fprintf(stderr, "audita config print-effective: %v\n", err)
		return 1
	}
	return 0
}

func extractErrorPhase(err error) (phase string, message string) {
	msg := err.Error()
	if strings.Contains(msg, ": ") {
		parts := strings.SplitN(msg, ": ", 2)
		if len(parts) == 2 {
			return parts[0], parts[1]
		}
	}
	return "", msg
}

func processReportInput(status string, inv processInvocation, runDir *diagnostics.RunDirectory, startedAt, completedAt time.Time, errorMessage string, errorPhase string, normalizationSummary *normalization.NormalizationSummary, chunkingSummary *chunking.Summary, runOutput *runner.RunOutput) processreport.BuildInput {
	runDirectoryPath := ""
	if runDir != nil {
		runDirectoryPath = runDir.Path()
	}
	return processreport.BuildInput{
		Status:               status,
		TranscriptPath:       inv.TranscriptPath,
		GlossaryPath:         inv.GlossaryPath,
		OutputPath:           inv.OutputPath,
		Modules:              inv.Config.Modules,
		OutputSchema:         inv.Config.OutputSchema,
		ConfigVersion:        inv.ConfigVersion,
		StartedAt:            startedAt,
		CompletedAt:          completedAt,
		ErrorMessage:         errorMessage,
		ErrorPhase:           errorPhase,
		RunDirectoryPath:     runDirectoryPath,
		NormalizationSummary: normalizationSummary,
		ChunkingSummary:      chunkingSummary,
		RunOutput:            runOutput,
	}
}

type processFlags struct {
	configPath                    *string
	glossaryPath                  *string
	outputPath                    *string
	reportJSONPath                *string
	modules                       *string
	outputSchema                  *string
	llmAPIKey                     *string
	validationLLMAPIKey           *string
	model                         *string
	validationModel               *string
	baseURL                       *string
	validationBaseURL             *string
	llmTimeoutSeconds             *int
	totalLLMConcurrency           *int
	proposalLLMConcurrency        *int
	llmConcurrency                *int
	validationLLMTimeoutSeconds   *int
	validationMaxPromptTokens     *int
	targetSections                *int
	maxRetries                    *int
	validationMaxRetries          *int
	validationLLMConcurrency      *int
	maxSectionTokens              *int
	minSectionTokens              *int
	glossaryConfidenceThreshold   *float64
	grammarConfidenceThreshold    *float64
	homophonesConfidenceThreshold *float64
	spokenWordConfidenceThreshold *float64
	normalizeMaxSegmentGap        *float64
	normalizeEllipsisGap          *float64
	normalizeMaxSegmentDuration   *float64
	normalizeMaxSegmentTokens     *int
	transcriptDescription         *string
	workDir                       *string
	workDirRetention              *string
}

func newProcessFlagSet(cfg config.Config, stderr io.Writer) (*flag.FlagSet, processFlags) {
	fs := flag.NewFlagSet("process", flag.ContinueOnError)
	fs.SetOutput(stderr)

	validationTimeoutSecondsDefault := cfg.PrimaryLLM.TimeoutSeconds
	if cfg.ValidationLLM.TimeoutSeconds != nil {
		validationTimeoutSecondsDefault = *cfg.ValidationLLM.TimeoutSeconds
	}

	validationMaxRetriesDefault := cfg.PrimaryLLM.MaxRetries
	if cfg.ValidationLLM.MaxRetries != nil {
		validationMaxRetriesDefault = *cfg.ValidationLLM.MaxRetries
	}

	validationLLMConcurrencyDefault := cfg.TotalLLMConcurrency
	if cfg.ValidationLLMConcurrency != nil {
		validationLLMConcurrencyDefault = *cfg.ValidationLLMConcurrency
	}

	targetSectionsDefault := 0
	if cfg.TargetSections != nil {
		targetSectionsDefault = *cfg.TargetSections
	}

	pFlags := processFlags{
		configPath:                    fs.String("config", "", "Path to versioned YAML config file"),
		glossaryPath:                  fs.String("glossary", "", "Path to glossary YAML file"),
		outputPath:                    fs.String("output", "", "Path to corrected transcript JSON output file"),
		reportJSONPath:                fs.String("report-json", "", "Path to machine-readable report JSON output file"),
		modules:                       fs.String("modules", strings.Join(cfg.Modules, ","), "Comma-separated module sequence override"),
		outputSchema:                  fs.String("output-schema", cfg.OutputSchema, "Output schema: bare-segments|audita-v1"),
		llmAPIKey:                     fs.String("llm-api-key", cfg.PrimaryLLM.APIKey, "Primary LLM API key"),
		validationLLMAPIKey:           fs.String("validation-llm-api-key", cfg.ValidationLLM.APIKey, "Validation LLM API key"),
		model:                         fs.String("model", cfg.PrimaryLLM.Model, "Primary LLM model name"),
		validationModel:               fs.String("validation-model", cfg.ValidationLLM.Model, "Validation LLM model name"),
		baseURL:                       fs.String("base-url", cfg.PrimaryLLM.BaseURL, "Primary OpenAI-compatible base URL"),
		validationBaseURL:             fs.String("validation-base-url", cfg.ValidationLLM.BaseURL, "Validation OpenAI-compatible base URL"),
		llmTimeoutSeconds:             fs.Int("llm-timeout-seconds", cfg.PrimaryLLM.TimeoutSeconds, "Primary LLM timeout in seconds"),
		totalLLMConcurrency:           fs.Int("total-llm-concurrency", cfg.TotalLLMConcurrency, "Total concurrent LLM calls across proposal and validation"),
		proposalLLMConcurrency:        fs.Int("proposal-llm-concurrency", cfg.EffectiveProposalLLMConcurrency(), "Concurrent proposal-generation LLM calls"),
		llmConcurrency:                fs.Int("llm-concurrency", cfg.TotalLLMConcurrency, "Alias for --total-llm-concurrency"),
		validationLLMTimeoutSeconds:   fs.Int("validation-llm-timeout-seconds", validationTimeoutSecondsDefault, "Validation LLM timeout in seconds"),
		validationMaxPromptTokens:     fs.Int("validation-max-prompt-tokens", cfg.ValidationMaxPromptTokens, "Validation max prompt tokens"),
		targetSections:                fs.Int("target-sections", targetSectionsDefault, "Target number of transcript sections"),
		maxRetries:                    fs.Int("max-retries", cfg.PrimaryLLM.MaxRetries, "Maximum structured-output retries"),
		validationMaxRetries:          fs.Int("validation-max-retries", validationMaxRetriesDefault, "Validation structured-output retries"),
		validationLLMConcurrency:      fs.Int("validation-llm-concurrency", validationLLMConcurrencyDefault, "Concurrent validation LLM calls (inherits total when unset)"),
		maxSectionTokens:              fs.Int("max-section-tokens", cfg.MaxSectionTokens, "Maximum section tokens"),
		minSectionTokens:              fs.Int("min-section-tokens", cfg.MinSectionTokens, "Minimum section tokens"),
		glossaryConfidenceThreshold:   fs.Float64("glossary-confidence-threshold", cfg.Thresholds.Glossary, "Glossary confidence threshold"),
		grammarConfidenceThreshold:    fs.Float64("grammar-confidence-threshold", cfg.Thresholds.Grammar, "Grammar confidence threshold"),
		homophonesConfidenceThreshold: fs.Float64("homophones-confidence-threshold", cfg.Thresholds.Homophones, "Homophones confidence threshold"),
		spokenWordConfidenceThreshold: fs.Float64("spoken-word-confidence-threshold", cfg.Thresholds.SpokenWord, "Spoken-word confidence threshold"),
		normalizeMaxSegmentGap:        fs.Float64("normalize-max-segment-gap", cfg.Normalization.MaxSegmentGap, "Maximum same-speaker merge gap"),
		normalizeEllipsisGap:          fs.Float64("normalize-ellipsis-gap", cfg.Normalization.EllipsisGap, "Gap threshold for ellipsis insertion"),
		normalizeMaxSegmentDuration:   fs.Float64("normalize-max-segment-duration", cfg.Normalization.MaxSegmentDuration, "Maximum merged segment duration"),
		normalizeMaxSegmentTokens:     fs.Int("normalize-max-segment-tokens", cfg.Normalization.MaxSegmentTokens, "Maximum merged segment token estimate"),
		transcriptDescription:         fs.String("transcript-description", cfg.TranscriptDescription, "Brief background context for LLM prompts; does not override transcript content"),
		workDir:                       fs.String("work-dir", cfg.WorkDir, "Per-run work directory"),
		workDirRetention:              fs.String("work-dir-retention", string(cfg.WorkDirRetention), "Work-dir retention policy: auto|always|never"),
	}

	return fs, pFlags
}

func findConfigPathOverride(args []string) (path string, set bool, err error) {
	for i := 0; i < len(args); i++ {
		arg := strings.TrimSpace(args[i])
		if arg == "" {
			continue
		}
		if arg == "--config" {
			if i+1 >= len(args) {
				return "", false, fmt.Errorf("--config requires a path")
			}
			return strings.TrimSpace(args[i+1]), true, nil
		}
		if strings.HasPrefix(arg, "--config=") {
			return strings.TrimSpace(strings.TrimPrefix(arg, "--config=")), true, nil
		}
	}
	return "", false, nil
}

func isHelpCommand(args []string) bool {
	if len(args) == 0 {
		return false
	}
	if len(args) == 1 {
		switch args[0] {
		case "help", "-h", "--help":
			return true
		}
	}
	if len(args) == 2 && args[0] == "help" {
		switch args[1] {
		case "process":
			return true
		}
	}
	return false
}

func hasHelpFlag(args []string) bool {
	for _, arg := range args {
		if arg == "-h" || arg == "--help" {
			return true
		}
	}
	return false
}

func writeRootUsage(w io.Writer) {
	fmt.Fprintln(w, "Audita is a transcript processing CLI.")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Usage:")
	fmt.Fprintln(w, "  audita <command> [options]")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Commands:")
	fmt.Fprintln(w, "  process    Process a transcript JSON file")
	fmt.Fprintln(w, "  config     Validate and inspect config")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Example:")
	fmt.Fprintln(w, "  audita process transcript.json --glossary glossary.yaml --output corrected.json")
}

func writeConfigUsage(w io.Writer) {
	fmt.Fprintln(w, "Validate and inspect Audita config.")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Usage:")
	fmt.Fprintln(w, "  audita config <command> [flags]")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Commands:")
	fmt.Fprintln(w, "  validate         Validate a versioned YAML config file")
	fmt.Fprintln(w, "  print-effective  Print redacted effective config JSON (defaults + config file + env)")
}

func writeConfigValidateUsage(w io.Writer) {
	fmt.Fprintln(w, "Validate a versioned YAML config file.")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Usage:")
	fmt.Fprintln(w, "  audita config validate --config <path>")
}

func writeConfigPrintEffectiveUsage(w io.Writer) {
	fmt.Fprintln(w, "Print redacted effective config JSON.")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Usage:")
	fmt.Fprintln(w, "  audita config print-effective [--config <path>]")
}

func writeProcessUsage(w io.Writer, fs *flag.FlagSet) {
	fmt.Fprintln(w, "Process a transcript JSON file.")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Usage:")
	fmt.Fprintln(w, "  audita process <transcript.json> [flags]")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Flags:")
	fs.VisitAll(func(f *flag.Flag) {
		fmt.Fprintf(w, "  --%s\n", f.Name)
	})
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Example:")
	fmt.Fprintln(w, "  audita process transcript.json --glossary glossary.yaml --output corrected.json")
}