chore(#17): recommendation document for code validation layer

[sugat009]

Summary

• Evaluate validation tools for the Code Validation Layer (ESLint, tsc, Prettier, ShellCheck, custom CHT checks)
• Recommend a thin wrapper approach that shells out to existing tools and parses structured output
• All validation runs against cht-core's config, not cht-agent's

Details

• Tool evaluation with programmatic usage for each
• Recommended validation pipeline (ESLint -> tsc -> Prettier -> ShellCheck)
• Error categorization: blocking vs warning vs auto-fixable
• Proposed TypeScript interfaces (ValidationIssue, ValidationResult, CodeValidator)
• Integration flow with Code Generation Layer (Implement Code Generation Layer #62) and QA Supervisor (Create QA Supervisor #64)
• Complexity assessment: Low to Medium

Test plan

• Review recommendation document for accuracy
• Verify tool evaluation matches current cht-core and cht-agent configs
• Confirm proposed interfaces align with Code Generation Layer ([Phase 2] Discovery: Code Generation Layer — Module Interface Specification #14) patterns

Fixes #17

[Hareet]

Review

Test Plan

1. Review recommendation document for accuracy ✅ (with one exception)

The document is accurate with one significant exception: the tsc implementation sketch would silently produce false negatives. cht-core's tsconfig has rootDir: "./src" and include: ["src/**/*"] — files in a temp directory outside src/ are silently excluded. tsc reports 0 errors without actually type-checking anything.

Two options to consider:

• Wrapper tsconfig — create a temp tsconfig.validation.json extending the target's, with include overridden to add the temp directory. Clean up after validation.
• Stage inside the project tree — write generated files into a .gitignored directory within rootDir (e.g., src/.validation-staging/), so the existing tsconfig picks them up naturally.

Either way, the doc should specify the chosen approach since it affects whether imports, type declarations, and per-directory tsconfig overrides resolve correctly.

2. Verify tool evaluation matches current cht-core and cht-agent configs ✅

Verified against the actual files:

• .eslintrc — ESLint v8.31.0, legacy config, extends @medic/eslint-config + @typescript-eslint/recommended + prettier ✅
• tsconfig.json — strict: true, noUnusedLocals, noUnusedParameters, noImplicitReturns ✅
• .prettierrc — single quotes, 2-space indent, trailing comma es5, 100 char width ✅

All claims in the document match the codebase.

3. Confirm proposed interfaces align with Code Generation Layer patterns ✅ (minor note)

CodeValidator consumes GeneratedFile[] which is defined in GITHUB_ISSUES_DRAFT.md but not yet in src/types/index.ts. The doc should either inline the type definition or reference where it's specified.

Minor notes

• Issue numbers #62, #64, #65 in the integration diagram only appear in this file — consider using layer names instead of (or alongside) issue numbers for clarity.
• usesPrettier(targetProject) in the sketch is unspecified — checking for .prettierrc existence is sufficient, worth a one-liner note.