폴리데우케스 문제 해결

정책을 바꾸기 전에 어느 단계에서 실패했는지 확인하세요. 세션이 복구 명령까지 차단한다면 본인의 터미널에서 실행합니다. pdks docs는 동봉 문서가 온전하면 프로젝트 설정이나 판정 관련 패키지가 없어도 사용할 수 있습니다.

설정 파일이 없을 때

프로젝트 루트 바로 아래에 polydeukes.config.yaml, polydeukes.config.yml, polydeukes.config.json 중 하나도 없으면 설정이 필요한 명령은 종료 코드 2를 반환합니다. Git에서 원래 파일을 복원하세요. 새 프로젝트라면 pdks init, pdks-claude-code init, pdks-grok init, pdks-codex init로 만들 수 있습니다. 이후 pdks explain을 실행합니다. 설정이 없다고 기본 정책으로 대신 실행하지는 않습니다.

설정 파일이 여러 개일 때

오류 메시지에 중복된 파일명이 나옵니다. 필요한 내용을 합친 뒤 허용되는 파일명 하나만 남기세요. 로더는 어느 파일을 사용할지 임의로 선택하지 않습니다. 정리한 뒤 pdks explain을 다시 실행합니다.

설정 오류

구문이나 스키마 오류가 있으면 종료 코드 2와 함께 파일명을 알립니다. 스키마 오류는 문제가 있는 필드도 알려 줍니다. 잘못된 YAML, 사용자 정의 태그, 알 수 없는 필드, 비어 있는 languages 객체를 고치세요. YAML 태그는 파서가 실행할 수 없더라도 거부합니다. 설정은 실행할 코드가 아니라 데이터이기 때문입니다.

protectedPath:나 adaptors: 같은 오타는 거부합니다. 다만 어댑터 이름에는 확장 가능성을 남겨 두었습니다. 아무도 구현하지 않은 네임스페이스도 설정으로 읽히지만 읽는 쪽이 없습니다. 수정한 뒤 pdks explain에서 실제 등록 내용을 확인하세요.

세션 안에서는 수정 자체가 막히지 않습니다. 설정이 로드되지 않는 동안 모든 호출은 차단되지만 하나는 예외입니다. 대상이 설정 파일 하나뿐이고, 시작 텍스트가 디스크에 있는 파일 그대로이며, 그 결과가 로드되는 Edit 또는 Write는 종료 코드 0으로 통과하며, covenant-check 라벨의 advised 행 하나를 고쳐진 설정 자신의 telemetry.logPath에 남기고 stderr에 고친 오류를 알립니다. 이 통과는 --enforce 기본 자세를 읽지 않습니다. 세션 훅은 항상 --enforce block으로 실행되므로, 그 아래에서 차단되는 수정은 어디에서도 실행되지 못하기 때문입니다. 결과가 여전히 로드되지 않는 수정은 다른 호출처럼 차단되고, 설정 파일과 다른 파일을 함께 건드리는 호출이나 디스크의 바이트에서 시작하지 않는 증거를 실은 호출도 차단됩니다. 변경 집합 표면에는 이런 경로가 없습니다. 설정을 고치는 커밋은 오류를 볼 수 있는 터미널에서 사람이 만드는 커밋이기 때문입니다.

Grok 증인

훅을 아직 읽지 않은 문제와 증인(witness) 밸브를 사용할 수 없는 문제는 구별해야 합니다.

pdks-grok init 실행 뒤 Hooks 탭을 다시 불러오거나 새 세션을 시작하세요. 실제 도구를 호출하고 텔레메트리를 확인합니다. 설치기가 성공했다고 해서 열린 세션에 훅이 적용됐다는 뜻은 아닙니다.
Grok의 ACP 대화 기록에는 현재 세션 증인 밸브가 요구하는 Claude 형식의 인간 메시지가 없습니다. 다시 불러와도 이 기능이 생기지는 않습니다. 복구가 필요하면 Grok에 Claude용 증인 토큰을 보내려 하지 말고 본인의 터미널에서 작업하세요.

커밋 증인은 해당 스테이징 검사만 허용합니다. 차단된 Grok 도구 호출까지 허용하지 않습니다.

Codex 증인

여기서도 두 문제는 구별해야 하며, 첫 번째는 원인이 다릅니다.

pdks-codex init 실행 뒤 훅 신뢰는 훅 정의의 해시에 묶입니다. .codex/hooks.json이 바뀌면 /hooks에서 승인하기 전까지 신뢰하지 않으므로, 설치기가 성공해도 실행되는 훅이 없을 수 있습니다. 실제 도구를 호출하고 텔레메트리를 확인하세요.
Codex는 대화 기록 경로를 알려 주지만 그 형식을 안정된 것으로 문서화하지 않으므로 어떤 판정도 읽지 않습니다. 대신 어댑터가 UserPromptSubmit과 PostToolUse를 자기 세션 증거 파일에 기록하고 SessionEnd에서 지웁니다. IR은 이 session을 싣되 actor를 합성하지 않습니다.
의도한 차단 뒤에는 설정된 증인 토큰을 첫 줄에 단독으로 보내고 다시 시도합니다. stderr가 UserPromptSubmit 증거가 없다고 알리면 생명주기 항목 넷이 모두 승인됐는지 확인합니다. 그래도 증거가 없다면 토큰을 반복해도 관측되지 않은 호출을 풀 수 없으므로 본인의 터미널에서 작업합니다.

커밋 증인은 스테이징 검사만 허용하며 Codex 세션 증인을 대신하지 않습니다.

선언을 판정으로 구성하지 못할 때

설정은 읽었지만 어떤 항목을 판정할 수 있는 형태로 컴파일하지 못한 경우입니다. 적용 범위가 일치하면 skipped와 사유 config-fault를 기록합니다. pdks explain에서도 원인을 볼 수 있습니다. 추출 단계 이름, 인수, 정규식 문법, 쌍과 단일 추출 결과의 사용을 확인하세요. 지목된 선언을 고친 뒤 같은 관측으로 다시 검사합니다. 미판정은 정상 판정이 아닙니다.

판정기를 불러올 수 없을 때

패키지나 판정 모듈이 빠져 있으면 작업을 차단합니다. 본인의 터미널에서 패키지를 다시 설치하거나 워크스페이스 전체를 빌드하세요. 생성된 훅은 설치된 패키지에 판정을 맡기며, 판정기를 별도로 복사해 가지고 있지 않습니다. 복구 뒤 실제 호출로 다시 확인합니다. 텔레메트리를 불러오기 전에 실패했다면 기록이 전혀 남지 않을 수도 있습니다.

판정기 자신이 거부하는 실패(설정 없음 · 잘못된 설정 · 빌드되지 않은 판정기)는 두 표면 모두 covenant check failed closed:를 붙입니다. 훅이 pdks covenant check에 판정을 맡기고 그 메시지를 그대로 전달하기 때문입니다. 판정기를 스폰하기 전에 실패한 경우 — 어댑터가 polydeukes를 찾지 못하거나 자식이 판정 없이 종료한 경우 — 만 covenant hook failed closed:를 붙입니다. 실제로 보게 되는 두 형태는 다음과 같습니다.

covenant hook failed closed: Cannot find package 'polydeukes' imported from …
covenant check failed closed: the covenant judges could not be loaded from … — run 'pnpm build' to rebuild them: Cannot find module './self-mod.js' …
covenant check failed closed: invalid config in polydeukes.config.yaml: … — fix polydeukes.config.yaml in one Edit or Write whose result loads; every other call stays blocked until it does

첫째는 설치된 패키지가 없는 경우이고, 둘째는 소스 체크아웃에서 판정기 빌드 산출물이 없거나 일부만 있는 경우이며, 셋째는 세션 표면에서 설정이 로드되지 않는 경우로 그 줄이 설정을 고칠 호출 하나를 알려 줍니다.

판정 결과 읽기

기록	의미
`passed`	관측한 입력을 판정했으며 약속(covenant)을 지켰습니다.
`blocked`	위반 때문에 작업을 멈췄습니다.
`witnessed`	차단 결과가 나왔지만 증인 밸브를 통해 작업을 허용했습니다.
`advised`	위반을 기록하되 작업을 멈추지 않았습니다. 두 표면 모두에서 나올 수 있습니다.
`skipped`	적용 범위가 일치한 등록을 판정할 수 없었습니다. 정상 판정이 아닙니다.
`unattributed`	기준 상태와 비교해 판정으로 설명되지 않는 보호 대상의 변경을 발견했거나, 유효한 기준 상태를 읽지 못했습니다. 판정 결과가 아니라 관측 기록입니다.

판정은 기본적으로 .polydeukes/roi.log에 추가됩니다. telemetry.logPath로 위치를 바꿀 수 있습니다. 로그 쓰기에 실패하더라도 판정 결과는 바뀌지 않습니다. 종료 코드 0은 작업을 계속해도 된다는 뜻이지 모든 규율을 지켰다는 뜻은 아닙니다.

차단된 호출을 증언으로 허용하기

지원되는 Claude Code 세션에서 설정된 증인 토큰을 인간 메시지의 첫 줄에 단독으로 입력한 뒤, 유효 시간 안에 다시 시도합니다. 보호 대상을 의도적으로 편집하기 전에 입력해도 됩니다. 먼저 한 번 차단돼야 하는 것은 아닙니다. 토큰은 비밀이 아니며, 밸브는 사람이 직접 입력했는지 확인하고 차단 판정에만 적용됩니다. 증언으로 허용한 호출은 witnessed 행을 새로 남깁니다. 앞서 기록한 blocked 행을 고치는 것이 아닙니다.

모듈 누락처럼 판정기를 조립하지 못하게 하는 오류는 증인으로 해결할 수 없습니다.

커밋이 차단됐을 때

변경 집합 표면은 사람에게 묻지 않습니다. 기본값에서는 모든 판정에 종료 코드 0을 내고 위반을 advised로 기록합니다. 종료 코드 2는 검사를 --enforce block으로 실행했을 때(보호 경로나 enforce: block 항목의 위반) 또는 판정 자체가 불가능할 때만 냅니다. 커밋을 멈출지는 훅 배선이 정합니다. 종료 코드를 따르는 훅은 커밋을 멈추고, 무시하는 훅은 멈추지 않습니다. Git은 커밋 실패를 다른 0이 아닌 코드로 알릴 수도 있습니다.

일반 규율 항목은 자신이 enforce: block을 적고 검사가 --enforce block으로 실행될 때만 작업을 멈춥니다. 설정에는 기본값 advise인 항목을 승격하는 것이 없습니다. 수준 변경은 정책을 바꾸는 결정이지 필수 복구 절차가 아닙니다. 판정된 위반을 통과시키려면 설정이 아니라 훅 명령에서 --enforce block을 빼세요. 행은 그대로 남습니다.

변경 집합 표면의 미판정 기록

변경 집합 표면은 disciplines와 changeSetDisciplines를 컴파일합니다. 대화 기록이나 명령줄을 읽는 항목은 sessionDisciplines에 속하며 diff 판정에는 포함되지 않습니다. 이런 항목을 공용 목록이나 변경 집합 목록에 넣으면 설정 오류가 발생합니다.

변경 집합 항목이 읽는 소스가 없고 supply 정책이 pass이면 supply-pass를 기록합니다. 선언을 컴파일할 수 없으면 config-fault를 기록합니다. pdks explain과 로그의 사유를 확인하세요. 미판정은 규율을 지켰다는 증거가 아닙니다.

세션 표면에서는 호스트가 대화 기록을 공급하지 않을 때 supply: { session: 'pass' }로 건너뛸 수 있습니다. 규율 목록 셋을 참고하세요.

다른 컴퓨터로 프로젝트를 옮길 때

텔레메트리와 .polydeukes/baseline.json은 로컬 상태이며 Git이 옮겨 주는 판정 이력이 아닙니다. 이 파일 없이 저장소를 복제해도 과거 판정이 복원되지는 않습니다. 세션 훅은 기준 상태가 없거나 유효하지 않으면 이를 기록하고 다음 비교에 쓸 기준을 만듭니다. 과거 변경을 판정했다는 증거가 생기는 것은 아닙니다. 필요한 로그는 따로 보관해 옮기세요. telemetry.logPath를 바꿨다면 모든 기록이 .polydeukes/에 있다고 가정해서는 안 됩니다.