폴리데우케스 문제 해결

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

설정 파일이 없을 때

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

설정 파일이 여러 개일 때

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

설정 오류

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

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

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

Codex 증인

/hooks에서 등록을 승인한 뒤 실제 호출과 telemetry를 확인하세요. 신뢰는 정의의 hash에 연결되므로 경로가 바뀌면 재승인이 필요할 수 있습니다. 현재 UserPromptSubmit은 사람 출처를 증명하지 않으므로 토큰을 보내도 증인(witness) 밸브를 열지 않습니다. PostToolUse 증거는 세션·하위 에이전트별로 분리하고 SessionEnd에 정리합니다. 불안정한 대화 기록 파일은 읽지 않습니다. 필요한 보호 변경은 사용자 터미널에서 수행하세요.

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

어떤 선언을 판정할 수 있는 형태로 컴파일하지 못하면 설정 전체가 오류가 됩니다. 등록되지 않은 추출 단계, 그 단계가 받지 않는 인수나 형식이 잘못된 인수, source나 결합자로 시작하지 않는 파이프라인, 단일 추출 결과가 필요한 자리에 쓴 쌍 추출 결과가 여기에 해당합니다. 로드는 설정 오류에서 설명한 대로 실패하고, 메시지가 항목과 파이프라인 또는 relate 항목, 그리고 사유를 알립니다. 지목된 선언을 고친 뒤 pdks explain을 다시 실행하세요.

판정기를 실행할 수 없음

등록의 판정기·어댑터 절대 경로가 존재하고 실행 가능한지 확인합니다. 두 실행 파일은 별도 설치입니다. 경로나 프로젝트를 옮겼다면 소유자 터미널에서 pdks-claude-code init 또는 pdks-codex init을 다시 실행하고 호스트 신뢰를 확인하세요.

어댑터가 시작되지 않으면 호스트가 메시지 없이 호출을 진행할 수 있습니다. 어댑터가 시작했지만 판정기를 찾지 못하면 설치 안내를 출력하고 진행합니다. 이때 새 판정 행이 없다는 사실을 정상 판정으로 읽으면 안 됩니다. 경로를 고친 뒤 실제 일반 호출과 직접 보호 경로 검사에서 새 텔레메트리를 확인하세요. 첫 판정이 두 검사를 설명합니다.

판정 결과 읽기

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

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

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

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

밸브가 열 수 있었던 차단을 열지 않았다면, 차단 메시지의 마지막 줄이 그 이유를 알려 줍니다. no witness is configured는 witness: { token, ttlMinutes }를 추가할 설정 파일을 알려 주며, 추가하기 전까지는 어떤 메시지로도 차단을 허용할 수 없습니다. a person can open this for <n> minutes는 밸브가 설정돼 있지만 유효 시간 안에 토큰 메시지가 없다는 뜻입니다. 여기에 the last witness expired at <time>이 붙으면 토큰을 보낸 적은 있지만 유효 시간이 지났으므로 다시 보내야 합니다. 이 줄에는 토큰이 들어가지 않습니다.

실행 파일 누락이나 잘못된 설정처럼 판정을 시작하지 못하게 하는 오류는 증인으로 해결할 수 없습니다.

커밋이 차단됐을 때

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

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

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

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

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

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

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

텔레메트리와 .polydeukes/baseline.json은 로컬 상태이며 Git이 옮겨 주는 판정 이력이 아닙니다. 이 파일 없이 저장소를 복제해도 과거 판정이 복원되지는 않습니다. memory 조회 로그 .polydeukes/memory-log.jsonl도 로컬 상태입니다. 기억 검색은 현재 Markdown 문서를 매번 읽으므로 옮길 색인 파일은 없습니다. 과거 조회가 무엇을 돌려줬는지 적은 로그는 문서에서 다시 만들 수 없습니다. 세션 훅은 기준 상태가 없거나 유효하지 않으면 이를 기록하고 다음 비교에 쓸 기준을 만듭니다. 과거 변경을 판정했다는 증거가 생기는 것은 아닙니다. 필요한 로그는 따로 보관해 옮기세요. telemetry.logPath를 바꿨다면 모든 기록이 .polydeukes/에 있다고 가정해서는 안 됩니다.

명령이나 확장을 찾지 못할 때

pdks: command not found 또는 no pdks executable on PATH라면 판정기를 설치하고, 명령을 실행하는 터미널이나 호스트의 PATH에 설치 디렉터리가 있는지 확인하세요. no pdks-<name> executable is on PATH라면 해당 확장도 따로 설치해야 합니다. 예를 들어 pdks memory에는 pdks-memory가 필요합니다.

command -v pdks
command -v pdks-memory

로컬 npm 설치는 프로젝트 루트에서 npx --no-install pdks --version으로 확인하세요. 셸의 command -v나 SDK에서도 사용하려면 그 프로젝트의 node_modules/.bin 절대 경로를 PATH에 추가합니다. 호스트는 시작할 때 받은 환경을 쓰므로 환경을 바꾼 뒤 다시 시작하세요. 설치 경로별 안내와 등록 복구를 참고하세요.