/**
 * Self-Reflector — 답변 산출물의 *자기 검증* 레이어.
 *
 * Memory(기억) 단계는 이미 충분히 강하지만 Verification(검증) 단계는 사용자
 * 피드백에 의존적이다. 이 모듈은 그 격차를 메꾸는 3단 구조:
 *
 *   Phase A (이 파일) ─ 시스템 프롬프트에 self-check 체크리스트 룰을 박아
 *      LLM이 *응답 마지막에* [Self-Reflector Check] 섹션을 자동으로 붙이게
 *      한다. 추가 LLM 콜 비용 0, constraint-driven generation 효과로 응답
 *      품질 자체가 올라간다.
 *
 *   Phase B (selfReflectorVerifier.ts) ─ 응답 직후 *분리된 콘텍스트*에서
 *      LLM 한 번 더 호출해 외부 시각으로 검증. 같은 모델·같은 콘텍스트의
 *      한계를 보완. 회사 모드 specialist 응답에만 옵션으로 적용.
 *
 *   Phase C (selfReflectorExecution.ts) ─ 코드 답변에 한해 syntax/lint를
 *      실제로 돌려 *실행 기반* 검증. 텍스트 검증으로는 잡지 못하는
 *      undefined variable, 잘못된 import 등을 잡아낸다.
 *
 * 세 phase 모두 사용자가 설정 토글로 끌 수 있어야 한다. 본질적으로 *추측을
 * 자기 검증으로 누르는* 안전망이라 끌 이유는 별로 없지만, 비용이나 latency가
 * 부담스러운 경우(특히 Phase B/C)는 OFF 권장.
 */

/**
 * 모든 LLM 응답 끝에 자동으로 붙는 self-check 룰 블록. 시스템 프롬프트의
 * 가장 끝에 prepend 되어 다른 어떤 룰보다도 *마지막에* 적용된다.
 *
 * 작성 원칙:
 *   - 항목은 4개 이내 — 너무 많으면 LLM이 무성의하게 채움
 *   - 코드 답변에는 추가 항목 (References / Paths) — 결과가 디스크에 떨어지는
 *     케이스의 가장 흔한 실수 두 가지를 직접 잡는다
 *   - "Yes/Checked/N-A" 같은 일관된 마커를 강제해서 사용자가 시선 흐름으로
 *     스캔 가능하게
 *   - 자기 비판이 아니라 *사실 확인*. 본문에서 이미 했더라도 한 번 더 명시.
 */
export const SELF_REFLECTOR_RULE_BLOCK = `
## [Self-Reflector Check — 매 답변 끝에 *반드시* 추가]

답변 본문이 끝난 직후, 빈 줄 한 줄을 두고 아래 형식의 self-check 블록을 *마지막 출력*으로 붙이세요. 본문이 한 줄짜리 잡담(인사·동의)인 경우는 생략 가능하지만, 코드·구조 설명·결정 사항이 포함된 답변은 *예외 없이* 붙입니다.

\`\`\`
[Self-Reflector Check]
- Consistency: <Yes / 해당 없음 / 충돌 항목 1줄>
- Completeness: <Yes / 누락 항목 1줄>
- Accuracy: <Checked / 의심 항목 1줄>
\`\`\`

답변에 *코드 / 파일 경로 / 명령*이 포함됐다면 아래 두 줄을 추가:
\`\`\`
- References: <Verified / 정의되지 않은 변수·함수 의심 1줄>
- Paths: <Verified / 의심 경로 1줄>
\`\`\`

규칙:
- 항목 값은 짧게(한 줄). 본문 반복 금지.
- "Checked"는 *방금 검토했다*는 뜻이지 "완벽하다"는 뜻이 아닙니다. 의심이 있으면 그 의심을 적으세요.
- 자기 평가를 부드럽게 포장하지 마세요. 누락이 있으면 누락이라고 적습니다.
- 이 블록은 사용자를 위한 *투명성 장치*입니다 — 사용자가 답변 신뢰도를 빠르게 가늠할 수 있어야 합니다.
`.trim();

/**
 * 코드 답변에 한해 추가하는 강한 가드. promptBuilder가 stage의 직군이
 * developer면 specialist prompt에 추가로 prepend 한다.
 */
export const SELF_REFLECTOR_CODE_GUARD = `
## [Code Self-Verification — 코드 작성 시 추가 검증]

코드 / 파일을 작성하기 *전에* 다음을 머릿속에서 한 번 더 점검:
1. 참조하는 변수·함수·import가 *실제로 존재*하거나 *이 응답 안에서 정의*되는가
2. 파일 경로가 워크스페이스 안인가 (절대 경로는 워크스페이스 루트 하위여야 함)
3. 기존 파일을 수정하는 경우 \`<read_file>\` 으로 먼저 *현재 내용을 확인*한 뒤 \`<edit_file>\`로 부분 변경
4. 새 파일이 의존하는 패키지가 프로젝트에 이미 있는지 (없으면 답변 본문에 "추가 설치 필요" 명시)

🛑 **빈 깡통 코드 절대 금지 (이 룰을 어기면 즉시 재작업)**
   다음 패턴 중 하나라도 만든 파일에 있으면 *완성된 코드가 아닙니다*:
   - 본문이 \`pass\` 한 줄뿐인 함수
   - 본문이 \`return None\` / \`return null\` / \`return\` 한 줄뿐인 함수 (의도된 stub 아닌 한)
   - 본문이 주석/TODO/FIXME/placeholder 텍스트뿐인 함수
   - 클래스 정의 안이 \`pass\` 뿐
   - import만 있고 *실제 로직이 한 줄도 없는 모듈*
   - "여기에 X를 구현하세요" 같은 자리표시 문자열
   - 함수 시그니처만 있고 본문이 \`...\` 뿐

   "완료했습니다"라고 말하기 전에 *생성한 모든 파일의 내용*을 다시 보고 위 패턴이 없는지 확인하세요.
   진짜로 stub이 *의도된* 경우(예: 인터페이스 정의)는 \`# stub: 이유\` 주석으로 명시해야 합니다.
   사용자는 빈 깡통 파일을 가장 싫어합니다 — 완성된 로직이 들어가야 답변이 끝납니다.

체크 결과는 [Self-Reflector Check]의 References / Paths 줄에 한 줄로 요약하고, 빈 깡통 의심 항목이 있다면 거기에 명시하세요.
`.trim();

/**
 * 시스템 프롬프트 끝에 self-reflector 룰을 *조건부로* 추가하는 헬퍼.
 *
 * @param baseSystem   원본 시스템 프롬프트
 * @param opts.enabled 사용자 설정 — false면 원본 그대로 반환 (룰 미추가)
 * @param opts.includeCodeGuard true면 코드 가드 블록도 추가 (developer 직군 등)
 */
export function appendSelfReflectorRule(
    baseSystem: string,
    opts: { enabled: boolean; includeCodeGuard?: boolean } = { enabled: true },
): string {
    if (!opts.enabled) return baseSystem;
    const parts = [baseSystem.trimEnd()];
    if (opts.includeCodeGuard) parts.push('', SELF_REFLECTOR_CODE_GUARD);
    parts.push('', SELF_REFLECTOR_RULE_BLOCK);
    return parts.join('\n');
}
