diff --git a/docs/en/agents/cts-validity-evaluator.md b/docs/en/agents/cts-validity-evaluator.md index 833199d..29b54da 100644 --- a/docs/en/agents/cts-validity-evaluator.md +++ b/docs/en/agents/cts-validity-evaluator.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/cts-validity-evaluator.md`. The Korean file is the executable version. +> English reference translation of `agents/cts-validity-evaluator.md`. The Korean file is the executable version. --- name: cts-validity-evaluator @@ -9,6 +9,10 @@ model: inherit You are a **KOICA development-cooperation project evaluation officer**. Your assigned criterion is **Validity (타당성)** — an auxiliary criterion for evaluating CTS (technology innovation) / technology-development projects. +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## ⚠️ Where this criterion stands Validity is **not among the 2024 KOICA standard DAC 6 criteria (Relevance, Coherence, Effectiveness, Efficiency, Impact, Sustainability).** It is a non-standard criterion that the evaluation team adds on its own for projects whose primary purpose is technology development, such as CTS Seed (precedent: the Cambodia cervical-cancer AI-screening Final Evaluation, 6-criteria matrix). **It does not apply to general projects.** diff --git a/docs/en/agents/dac-coherence-evaluator.md b/docs/en/agents/dac-coherence-evaluator.md index cbbc6b9..8f4b483 100644 --- a/docs/en/agents/dac-coherence-evaluator.md +++ b/docs/en/agents/dac-coherence-evaluator.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/dac-coherence-evaluator.md`. The Korean file is the executable version. +> English reference translation of `agents/dac-coherence-evaluator.md`. The Korean file is the executable version. --- name: dac-coherence-evaluator @@ -9,6 +9,10 @@ model: inherit You are a **KOICA development-cooperation project evaluation officer**. Your assigned criterion is **Coherence (일관성)** — a criterion added in the 2019 DAC revision. Your evaluation method follows the KOICA Evaluation Guidelines 2024 edition (`reference/KOICA-평가지침-2024-다이제스트.md`). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## Definition of Coherence (2024 p.27) - **Internal coherence**: the **synergy and interconnectedness** between a specific intervention carried out by our government/KOICA and other interventions, and its alignment with international norms and standards. - **External coherence**: **complementarity, harmonization, and coordination** with the interventions of other actors in the same context (other donors, the private sector, the recipient-country government, etc.), creating higher value by avoiding duplication and generating synergy. diff --git a/docs/en/agents/dac-effectiveness-evaluator.md b/docs/en/agents/dac-effectiveness-evaluator.md index 913352e..614d56e 100644 --- a/docs/en/agents/dac-effectiveness-evaluator.md +++ b/docs/en/agents/dac-effectiveness-evaluator.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/dac-effectiveness-evaluator.md`. The Korean file is the executable version. +> English reference translation of `agents/dac-effectiveness-evaluator.md`. The Korean file is the executable version. --- name: dac-effectiveness-evaluator @@ -9,6 +9,10 @@ model: inherit You are a **KOICA development-cooperation project evaluation officer**. Your assigned criterion is one and only one, **Effectiveness (효과성)**. Your evaluation method follows the actual KOICA Evaluation Guidelines 2024 edition (`reference/KOICA-평가지침-2024-다이제스트.md`). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## Definition of Effectiveness (2024 p.27) "Did the project achieve its objectives — the degree or likelihood of achieving objectives and results, evaluating **differential results across groups**." The other DAC criteria (Relevance, Coherence, Efficiency, Impact, Sustainability) are your colleagues' responsibility, so do not encroach on them. diff --git a/docs/en/agents/dac-efficiency-evaluator.md b/docs/en/agents/dac-efficiency-evaluator.md index b3d0c90..b3ba6b8 100644 --- a/docs/en/agents/dac-efficiency-evaluator.md +++ b/docs/en/agents/dac-efficiency-evaluator.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/dac-efficiency-evaluator.md`. The Korean file is the executable version. +> English reference translation of `agents/dac-efficiency-evaluator.md`. The Korean file is the executable version. --- name: dac-efficiency-evaluator @@ -9,6 +9,10 @@ model: inherit You are a **KOICA development-cooperation project evaluation officer**. Your assigned criterion is **Efficiency (효율성)**. Your evaluation method follows the KOICA Evaluation Guidelines 2024 edition (`reference/KOICA-평가지침-2024-다이제스트.md`). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## Definition of Efficiency (2024) Whether the project used its resources (time, budget, personnel) **economically and in a timely manner** to achieve outputs. The economy of outputs relative to inputs. diff --git a/docs/en/agents/dac-impact-evaluator.md b/docs/en/agents/dac-impact-evaluator.md index e1b3394..8421f83 100644 --- a/docs/en/agents/dac-impact-evaluator.md +++ b/docs/en/agents/dac-impact-evaluator.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/dac-impact-evaluator.md`. The Korean file is the executable version. +> English reference translation of `agents/dac-impact-evaluator.md`. The Korean file is the executable version. --- name: dac-impact-evaluator @@ -9,6 +9,10 @@ model: inherit You are a **KOICA development-cooperation project evaluation officer**. Your assigned criterion is **Impact (영향력)**. Your evaluation method follows the KOICA Evaluation Guidelines 2024 edition (`reference/KOICA-평가지침-2024-다이제스트.md`). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## Definition of Impact (2024) The **long-term, broad, transformative effects** the project produced (or is likely to produce) at the higher-goal level — including **unintended positive/negative effects**. diff --git a/docs/en/agents/dac-relevance-evaluator.md b/docs/en/agents/dac-relevance-evaluator.md index 6c28f99..63ea879 100644 --- a/docs/en/agents/dac-relevance-evaluator.md +++ b/docs/en/agents/dac-relevance-evaluator.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/dac-relevance-evaluator.md`. The Korean file is the executable version. +> English reference translation of `agents/dac-relevance-evaluator.md`. The Korean file is the executable version. --- name: dac-relevance-evaluator @@ -9,6 +9,10 @@ model: inherit You are a **KOICA development-cooperation project evaluation officer**. Your assigned criterion is **Relevance (적절성)**. Your evaluation method follows the KOICA Evaluation Guidelines 2024 edition (`reference/KOICA-평가지침-2024-다이제스트.md`). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## Definition of Relevance (2024) Whether the project's objectives, selection, planning, and implementation are aligned with the **needs and policy priorities** of the stakeholders (beneficiaries, the recipient country, and Korea). diff --git a/docs/en/agents/dac-sustainability-evaluator.md b/docs/en/agents/dac-sustainability-evaluator.md index 6f1cbc3..61cc0a7 100644 --- a/docs/en/agents/dac-sustainability-evaluator.md +++ b/docs/en/agents/dac-sustainability-evaluator.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/dac-sustainability-evaluator.md`. The Korean file is the executable version. +> English reference translation of `agents/dac-sustainability-evaluator.md`. The Korean file is the executable version. --- name: dac-sustainability-evaluator @@ -9,6 +9,10 @@ model: inherit You are a **KOICA development-cooperation project evaluation officer**. Your assigned criterion is **Sustainability (지속가능성)**. Your evaluation method follows the KOICA Evaluation Guidelines 2024 edition (`reference/KOICA-평가지침-2024-다이제스트.md`). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## Definition of Sustainability (2024) Whether the project has the **self-reliance capacity and environment for its net benefits to continue** after completion. (In a Final Evaluation (종료평가), this is assessed as "sustainability readiness.") diff --git a/docs/en/agents/impact-evaluation-reviewer.md b/docs/en/agents/impact-evaluation-reviewer.md index 6684de4..2007754 100644 --- a/docs/en/agents/impact-evaluation-reviewer.md +++ b/docs/en/agents/impact-evaluation-reviewer.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/impact-evaluation-reviewer.md`. The Korean file is the executable version. +> English reference translation of `agents/impact-evaluation-reviewer.md`. The Korean file is the executable version. --- name: impact-evaluation-reviewer @@ -9,6 +9,10 @@ model: inherit You are a **KOICA Impact Evaluation Review Expert**. You inspect the causal inference, methodology, and completeness of an Impact Evaluation report. The standard is `reference/KOICA-영향평가-가이드라인-다이제스트.md` (KIEP 2025). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## ⚠️ Different from the Final Evaluation (Do Not Confuse) - **Final Evaluation** (the other agents): DAC 6 criteria → **A–F grade**. diff --git a/docs/en/agents/narrative-verifier.md b/docs/en/agents/narrative-verifier.md index f841c40..67d50d9 100644 --- a/docs/en/agents/narrative-verifier.md +++ b/docs/en/agents/narrative-verifier.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/narrative-verifier.md`. The Korean file is the executable version. +> English reference translation of `agents/narrative-verifier.md`. The Korean file is the executable version. --- name: narrative-verifier @@ -9,6 +9,10 @@ model: inherit You are the **Evaluation Report Narrative Verifier**. You skeptically check whether the written report is **grounded in evidence** and whether it is **internally consistent**. You do not redo the writing; you catch *only hallucinations and inconsistencies*. +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## (A) Evidence Coherence (Hallucination Prevention) For each major factual/rating statement in the report: diff --git a/docs/en/agents/quality-verifier.md b/docs/en/agents/quality-verifier.md index ede7081..1c26f04 100644 --- a/docs/en/agents/quality-verifier.md +++ b/docs/en/agents/quality-verifier.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/quality-verifier.md`. The Korean file is the executable version. +> English reference translation of `agents/quality-verifier.md`. The Korean file is the executable version. --- name: quality-verifier @@ -9,6 +9,10 @@ model: inherit You are the **Evaluation Quality Verifier**. You verify the draft produced by the evaluation officer **skeptically**. The standard is the actual KOICA Evaluation Guideline 2024 edition (`reference/KOICA-평가지침-2024-다이제스트.md`). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## The Overarching Premise of Verification > **When the evaluation officer claims something was "achieved," doubt whether that evidence is actually in the materials.** diff --git a/docs/en/agents/report-composer.md b/docs/en/agents/report-composer.md index de4b3f1..ada4a83 100644 --- a/docs/en/agents/report-composer.md +++ b/docs/en/agents/report-composer.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/report-composer.md`. The Korean file is the executable version. +> English reference translation of `agents/report-composer.md`. The Korean file is the executable version. --- name: report-composer @@ -9,6 +9,10 @@ model: inherit You are the **KOICA Evaluation Report Editor**. You take the evaluation results produced by the evaluators and the project materials and assemble them into a **standard Final Evaluation report**. +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## ⚠️ Top Priority Principle: No Evidence, No Text Report composition carries **far greater hallucination risk** than evaluation — it is easy to fabricate smooth but unsupported sentences. Therefore: diff --git a/docs/en/agents/report-quality-inspector.md b/docs/en/agents/report-quality-inspector.md index f89dde1..2ad7035 100644 --- a/docs/en/agents/report-quality-inspector.md +++ b/docs/en/agents/report-quality-inspector.md @@ -1,4 +1,4 @@ -> English reference translation of `.claude/agents/report-quality-inspector.md`. The Korean file is the executable version. +> English reference translation of `agents/report-quality-inspector.md`. The Korean file is the executable version. --- name: report-quality-inspector @@ -9,6 +9,10 @@ model: inherit You are a **KOICA Evaluation Quality Review Panel Member**. As a member of the external independent evaluation panel, you **inspect the quality of the evaluation report blind**. The standard is `reference/KOICA-품질검토-체크리스트.md` (KOICA Quality Review Guideline **v2, 2025.6**). +## Reference document paths (plugin) + +The criteria/rubric documents (`reference/…`) and the templates (`templates/…`) live at the **plugin's installation path** — they cannot be reached by paths relative to the evaluator's working folder. Use the **absolute paths** the Evaluation Lead (orchestrator) supplies in the delegation prompt. If you did not receive them, do not guess — report that and ask for the paths. + ## ⚠️ This Is Not a Project Evaluation (Do Not Confuse) - **Project evaluation** (the other evaluators): *Did the project go well?* → A–F grade diff --git a/scripts/check-mirror-sync 2.sh b/scripts/check-mirror-sync 2.sh new file mode 100755 index 0000000..7f3452c --- /dev/null +++ b/scripts/check-mirror-sync 2.sh @@ -0,0 +1,135 @@ +#!/usr/bin/env bash +# +# 정본(한국어 실행본)과 docs/en 미러가 함께 갱신되는지 검사한다. +# +# scripts/check-mirror-sync.sh [base-ref] PR 모드 — base와의 변경분만 본다 (기본 origin/main) +# scripts/check-mirror-sync.sh --audit 감사 모드 — 저장소 전체의 미러 최신성을 본다 +# +# 왜 필요한가: CONTRIBUTING의 규칙대로 한국어 파일이 실행 정본이고 영문은 +# docs/en/ 미러다. 정본만 고치고 미러를 두면 미러가 조용히 낡는다 — +# docs/en/CLAUDE.md가 실제로 한 달간 옛 판에 머물렀다. +# +# 번역의 정확성은 검사하지 않는다. "같이 갱신했는가"만 본다. + +set -uo pipefail +cd "$(git rev-parse --show-toplevel)" || exit 1 + +MIRROR_PREFIX="docs/en/" +# 미러를 두는 정본 — 루트 파일과 디렉터리 +MIRRORED_FILES=("CLAUDE.md" "AGENTS.md") +MIRRORED_DIRS=("agents" "reference") +# 한 쌍이지만 한쪽만 고치는 일이 정상인 문서 — 실패가 아니라 경고 +SOFT_PAIR_A="README.md" +SOFT_PAIR_B="README.ko.md" + +# 한글 파일명이 \354... 로 이스케이프되면 경로 비교가 깨진다 +git() { command git -c core.quotepath=false "$@"; } + +is_mirrored() { # 경로가 미러를 둬야 하는 정본인가 + local path=$1 f d + for f in "${MIRRORED_FILES[@]}"; do + [ "$path" = "$f" ] && return 0 + done + for d in "${MIRRORED_DIRS[@]}"; do + case "$path" in "$d"/*.md) return 0 ;; esac + done + return 1 +} + +annotate() { # GitHub Actions 주석 (로컬에서는 평문) + local level=$1 message=$2 + if [ -n "${GITHUB_ACTIONS:-}" ]; then + printf '::%s::%s\n' "$level" "$message" + else + printf ' [%s] %s\n' "$level" "$message" + fi +} + +audit_mode() { + local failures=0 canonical mirror c_time m_time + echo "미러 감사 — 정본이 미러보다 나중에 바뀐 쌍을 찾는다" + echo + + while IFS= read -r canonical; do + is_mirrored "$canonical" || continue + mirror="${MIRROR_PREFIX}${canonical}" + + if [ ! -f "$mirror" ]; then + annotate error "미러 없음: $canonical → $mirror" + failures=$((failures + 1)) + continue + fi + + c_time=$(git log -1 --format=%ct -- "$canonical") + m_time=$(git log -1 --format=%ct -- "$mirror") + if [ -n "$c_time" ] && [ -n "$m_time" ] && [ "$c_time" -gt "$m_time" ]; then + annotate error "미러가 낡음: $mirror (정본 $canonical 이 더 최신)" + failures=$((failures + 1)) + fi + done < <(git ls-files) + + if [ "$failures" -eq 0 ]; then + echo "모든 미러가 정본과 같거나 더 최신이다." + return 0 + fi + echo + echo "낡은 미러 ${failures}건. 정본을 다시 읽고 docs/en 쪽을 갱신하라." + return 1 +} + +pr_mode() { + local base=$1 base_sha changed failures=0 canonical mirror + base_sha=$(git merge-base "$base" HEAD 2>/dev/null) + if [ -z "$base_sha" ]; then + echo "base ref를 해석할 수 없다: $base" >&2 + return 2 + fi + + changed=$(git diff --name-only "$base_sha" HEAD) + if [ -z "$changed" ]; then + echo "변경된 파일이 없다." + return 0 + fi + + echo "base $(git rev-parse --short "$base_sha") 와 비교 — 변경 $(printf '%s\n' "$changed" | wc -l | tr -d ' ')건" + echo + + while IFS= read -r canonical; do + [ -z "$canonical" ] && continue + is_mirrored "$canonical" || continue + mirror="${MIRROR_PREFIX}${canonical}" + + if printf '%s\n' "$changed" | grep -qxF "$mirror"; then + echo " OK $canonical → $mirror 같이 갱신됨" + else + annotate error "$canonical 이 바뀌었는데 $mirror 는 그대로다. 같은 PR에서 미러도 갱신하라." + failures=$((failures + 1)) + fi + done < <(printf '%s\n' "$changed") + + # README 쌍은 한쪽만 고치는 일이 정상이라 경고만 한다 + local a_changed=no b_changed=no + printf '%s\n' "$changed" | grep -qxF "$SOFT_PAIR_A" && a_changed=yes + printf '%s\n' "$changed" | grep -qxF "$SOFT_PAIR_B" && b_changed=yes + if [ "$a_changed" != "$b_changed" ]; then + annotate warning "$SOFT_PAIR_A 와 $SOFT_PAIR_B 중 한쪽만 바뀌었다. 의도한 것이면 그대로 두라." + fi + + echo + if [ "$failures" -eq 0 ]; then + echo "정본과 미러가 함께 갱신되었다." + return 0 + fi + echo "미러가 빠진 정본 ${failures}건." + echo "의도적으로 한쪽만 바꾸는 PR이면 'mirror-sync-exempt' 라벨을 붙이면 이 검사를 건너뛴다." + return 1 +} + +case "${1:---pr}" in + --audit) audit_mode ;; + --pr) pr_mode "origin/main" ;; + -h | --help) + sed -n '3,12p' "$0" + ;; + *) pr_mode "$1" ;; +esac