# PR-Hermes-Skill-Polish-1 Closure Report

**Date**: 2026-05-17
**선행 PR**: PR-Hermes-Docsrv-Search-1 + ToolCall-Adapter-1 + Sandbox-Env-Propagation-1
**범위**: 3 SKILL.md frontmatter 표준화 + docsrv_ask 본문 refinement 차단 강화
**파일**: `~/.hermes/skills/personal/{docsrv_memo,docsrv_search,docsrv_ask}/SKILL.md`

## Summary

PR-Hermes-Sandbox-Env-Propagation-1 closure 시 발견된 2건 후속:
1. **frontmatter legacy `prerequisites.env`** — 표준 `required_environment_variables` (agentskills.io schema) 로 마이그레이션. `skill_view` tool_call 시 자동 `register_env_passthrough` 발화 ⇒ config-level `terminal.env_passthrough` 와 이중 안전망.
2. **Hermes chat multi-turn refinement 루프** — Gemma 가 첫 docsrv_ask 결과 만족 못 하면 query 변형 후 재호출. SKILL.md 본문에 "1회 호출 후 verbatim, refinement 재호출 금지" 정책 강조.

## Skill-Curl-Refine-1 변경 (frontmatter 표준화)

3 SKILL 모두 동일 패턴:

```diff
 prerequisites:
   commands: [curl, jq]
-  env: [HERMES_DOCSRV_TOKEN]
+required_environment_variables:
+  - name: HERMES_DOCSRV_TOKEN
+    prompt: Document Server JWT (voice-memo-bot 365d access token)
+    help: "voice-memo-bot user (id=4) 가 발급한 long-lived JWT. LaunchAgent ai.hermes.gateway 의 EnvironmentVariables 에 이미 주입됨."
```

**`prerequisites.commands`** 는 유지 (advisory only, Hermes 의 `_collect_prerequisite_values` 가 legacy_env_vars 로 그대로 변환).

**효과**:
- `skill_view` tool_call 호출 시 자동 `register_env_passthrough(["HERMES_DOCSRV_TOKEN"])` (`tools/skills_tool.py:1336`)
- agentskills.io 표준 (Shopify / Notion skill 등 동일 패턴) — Hermes 공식 marketplace 호환

## Multi-Turn-Refinement-1 변경 (본문 강화, docsrv_ask)

신규 섹션 추가 (`docsrv_ask/SKILL.md`):

```markdown
## Multi-Turn / Refinement 차단 정책

- 같은 query 또는 의미적 동일 query 를 본 skill 로 재호출 금지. 한 사용자 turn 당 docsrv_ask 1회만.
- confidence=medium 또는 completeness=partial 도 만족 — refinement 욕구로 query 변형 후 재호출 X.
- 사용자가 명시적으로 "더 자세히" / "다른 측면" 요청 시에만 다른 query 로 재호출 (그것도 1회).
- 본 정책 위반 시 Mac mini 26B 가 동일 corpus 에 동일 LLM 추론 반복 → 가치 ↓ + 부하 ↑ + Hermes 응답 시간 ↑↑.
```

기존 "Response Format — 재합성 최소화 정책" 도 강화:
- "ai_answer 그대로 사용" → "**verbatim** (한 글자도 재작성 X — paraphrase 금지, summarization 금지)"

docsrv_search 도 동일 1회 호출 정책 1단락 추가.

## 검증

### Regression: Layer 1 fixture (Adapter A)

```
memo-search     | 1.06s | raw_leak=0 | tool_calls=1(docsrv_ask) | finish=[stop,tool_calls]  ✅
asme-search     | 11.33s| raw_leak=0 | tool_calls=0          | finish=[stop]          (Gemma 직접 답변)
today-tasks     | n/a   | raw_leak=0 | tool_calls=0          | finish=[stop]          (Gemma 직접 답변)
multi-tool      | n/a   | raw_leak=0 | tool_calls=1(docsrv_ask) | finish=[stop,tool_calls]  ✅
explicit-call   | 0.74s | raw_leak=0 | tool_calls=1(docsrv_ask) | finish=[stop,tool_calls]  ✅

raw_token leak suppressed: 5/5
finish_reason override:    3/3 (tool 사용한 case)
```

**SKILL.md polish 가 Adapter A 회귀 0** — pre-polish 와 동일 결과 (1.06s / 11.33s / 0.74s 동일).

### E2E (Hermes chat — multi-turn 차단 검증)

`hermes chat -s docsrv_ask -q 'docsrv_ask 으로 내 자료에서 voice memo 관련 자료 찾아줘'`

**측정 결과 (kill 시점)**:
- DS API 호출 횟수: pre-polish 4회 → **post-polish 3회** (1회 감소, but **목표 1회 도달 X**)
- Hermes turn count: 3 turn 진행 중 kill (max-turns=4)
- 매 turn 마다 같은 `voice memo` exact query 로 docsrv_ask 재호출 (refinement variation 도 없음 — 그냥 동일 query 반복)
- DS 응답: 매번 동일 `conf=medium completeness=full refused=False` → 그래도 Gemma 가 만족 못 함

**해석 — prompt-only enforcement 의 한계**:
- SKILL.md 본문에 "1회 호출 후 verbatim 사용, refinement 재호출 금지" 명시했으나 Gemma 4 26B 가 follow 안 함
- 원인 후보: (a) 23000+ input tokens 의 페르소나/skills/tools prompt 사이에 SKILL.md instruction 이 묻혀 weight 낮음 (b) Gemma 4 의 agentic loop training 이 "fixed point 후 stop" 보다 "더 정보 fetch" 쪽 bias (c) Hermes agent loop 자체가 verdict=partial 같은 부분 만족 신호 보면 자동 retry
- 결론: **prompt-only multi-turn 차단은 약한 enforcement**. 진짜 1회 호출 보장은 plugin-level (Phase 2 Answer-Policy-1) 또는 Hermes agent loop config (max_tool_calls_per_skill) 필요

**부분 효과는 있음**: pre-polish 4 turn → post-polish 3 turn (25% 감소). SKILL.md 강조가 weight 0 은 아니지만 hard guarantee 못 됨.

## 결정 사항

1. **Skill-Curl-Refine-1 (frontmatter 마이그레이션) = SHIPPED**:
   - Layer 1 fixture 회귀 0 (5/5 raw_leak suppressed, 3/3 finish_reason override 유지)
   - 3 SKILL 모두 agentskills.io 표준 호환
   - `terminal.env_passthrough` config-level fix 와 이중 안전망 확보
2. **Multi-Turn-Refinement-1 (SKILL.md 본문 정책) = PARTIAL** (정직히 보고):
   - prompt-only enforcement 가 약함 — Gemma 4 26B 가 SKILL.md 의 "1회 호출 후 verbatim, 재호출 금지" instruction 무시
   - 효과: 4 turn → 3 turn (25% 감소), but 목표 1 turn 도달 못 함
   - **결론**: hard guarantee 는 plugin-level enforcement 필요. PR-Hermes-Answer-Policy-1 (Phase 2) 또는 Hermes agent loop config (`max_tool_calls_per_skill: 1`) 별 트랙으로 escalate
3. **묶음 closure 보다 분리**: Skill-Curl-Refine-1 만 SHIPPED, Multi-Turn-Refinement-1 은 "prompt-only attempt 실패 기록" 으로 closure + 별 PR (plugin-level) 진입 조건 박힘

## File changes

### Mac mini
- `~/.hermes/skills/personal/docsrv_ask/SKILL.md` — frontmatter 표준화 + Multi-Turn 차단 섹션 추가 + Response Format verbatim 강화 (v0.1.0 → v0.2.0)
- `~/.hermes/skills/personal/docsrv_search/SKILL.md` — frontmatter 표준화 + 1회 호출 정책 1단락 (v0.1.0 → v0.2.0)
- `~/.hermes/skills/personal/docsrv_memo/SKILL.md` — frontmatter 표준화 (v0.1.0 그대로, 본문 변경 0)
- `*.SKILL.md.pre-polish.20260517` 3개 (7일 안전망)

### 변경 없음
- `~/.hermes/config.yaml` (env_passthrough 와 channel_prompts 그대로)
- `~/scripts/mlx-proxy.py` (Adapter A 그대로)
- DS code

## 7일 안전망 (2026-05-24)

- Mac mini `~/.hermes/skills/personal/docsrv_{memo,search,ask}/SKILL.md.pre-polish.20260517` 3개
- 복귀 시: `ssh macmini "for s in docsrv_memo docsrv_search docsrv_ask; do cp ~/.hermes/skills/personal/$s/SKILL.md.pre-polish.20260517 ~/.hermes/skills/personal/$s/SKILL.md; done && launchctl bootout/bootstrap"`

## 검증 commands (재실행)

```bash
# Layer 1 fixture regression
ssh macmini "python3 ~/.hermes/fixtures/pr_adapter_a_fixture.py"

# Hermes E2E (multi-turn 차단 검증)
ssh macmini "HERMES_DOCSRV_TOKEN=... && ~/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main chat -Q -s docsrv_ask -q '<query>'"

# DS API 호출 횟수 측정 (1회 기대)
ssh gpu "cd ~/Documents/code/hyungi_Document_Server && docker compose logs --since=5m fastapi | grep -c 'ask query'"
```

## 후속 트랙

| 우선 | 트랙 | 비고 |
|---|---|---|
| **P2 (escalated)** | **PR-Hermes-MultiTurn-Hard-Enforcement-1** | 본 PR 의 Multi-Turn-Refinement-1 prompt-only attempt 실패 → plugin-level 강제. 후보: (a) Hermes agent loop config `max_tool_calls_per_skill: 1` (b) `tools/skills_tool.py` 의 tool dispatcher 에 per-skill 호출 카운터 (c) PR-Hermes-Answer-Policy-1 (Phase 2) 의 일부로 통합 |
| **P3** | PR-Hermes-MaxTokens-Followup | 23320 input tokens 대응 — Hermes tools/skills 선택 로딩 mechanism 조사 (별 PR) |
| 별 트랙 | PR-Hermes-Answer-Policy-1 (Phase 2) | 출처 라벨 plugin-level 강제. MultiTurn-Hard-Enforcement 와 통합 검토 |
| 별 트랙 | PR-Hermes-WebSearch-2B-SearXNG | ddgs 1주 baseline 후 |
| 별 트랙 | PR-D (P2 강등) | Adapter A 1주 측정 + 가족 onboarding 시점 재평가 |
