위키 · 찾아 쓰는 참조

용어와 코드 표기

이 대응표는 문서에서 같은 역할·작업 단계·코드 필드가 어떻게 불리는지 보여줍니다. 한국어 설명과 코드 식별자를 나누어 읽을 수 있습니다.

표의 로컬 경로와 명령은 특정 운영 설치의 좌표입니다. p-hermes 공개 구현 및 Hermes 엔진의 제품 API와 혼동하지 않습니다. 구성별 범위와 출처 →

1. 역할과 전달 문서

한국어 용어	코드·문서 표기	뜻
매니저	`orchestrator`, `POLICY.md`	요청의 목표와 경계를 정하고 직접 수행 또는 위임을 판단하며, 결과를 확인합니다.
워커	`worker`, `worker_dispatch.py`, `WORKER.md`	파일 요청 하나를 읽고 작업한 뒤 응답서를 씁니다. `worker_dispatch.py`는 실행 경로의 코드 이름이고, 워커라는 역할명 자체와 같지 않습니다.
요청서	Markdown handoff 요청	무엇을 끝낼지, 어떻게 확인할지, 무엇을 읽을지, 하지 않을 일을 전달하는 문서입니다.
응답서	Markdown handoff 응답	요청과 같은 식별자, 처리 상태, 산출물과 남은 항목을 적는 문서입니다.
공개 참조 계약	JSON contract	교육용 공개 구현이 쓰는 필드 계약입니다. Markdown 요청서·응답서의 문서 형식에 그대로 적용되는 스키마가 아닙니다.

2. 식별자와 요청·응답 필드

표기	대응하는 의미	적용 범위·주의
`request_id`	요청 시도 식별자	한 번의 시도를 식별합니다. 응답의 값은 원 요청과 같아야 합니다. 재시도는 새 ID를 씁니다.
`goal_id`	목표 식별자	같은 목적의 여러 요청 시도를 연결할 수 있습니다. 시도별 ID인 `request_id`와 다릅니다.
`intent_revision`	목표 의도 개정 번호	공개 JSON 참조 계약에서 의도 변경 차수를 나타냅니다.
`inputs`	입력 자료	공개 JSON 요청에서 수행에 사용할 입력을 지정합니다.
`acceptance`	완료 기준	공개 JSON 요청에서 결과를 판단할 기준입니다. Markdown 요청의 완성 기준과 개념상 대응하지만 직렬화 형식은 다릅니다.
`policy`	수행 정책·제약	공개 JSON 요청의 필드입니다. 로컬 운영 규칙 문서 `POLICY.md`와 이름이 같아도 서로 다른 항목입니다.
`request_sha256`	요청 내용 해시	공개 JSON 응답에서 결과가 연결된 요청 본문을 확인하는 값입니다.
`artifacts`	산출물 목록	공개 JSON 응답이 가리키는 결과 산출입니다.
`result`, `error`	결과 설명, 오류 정보	공개 JSON 응답의 선택 정보입니다. 오류 정보가 있으면 보고된 상태 및 보존 산출과 함께 읽습니다.

공개 JSON 계약에서 사용하는 위 필드가 전부 Markdown 요청서·응답서의 필수 필드는 아닙니다. Markdown 형식에서 핵심은 request_id와 응답 status이며, 나머지는 사람이 읽는 본문과 산출 경로로 표현됩니다.

3. 응답 상태와 JOB 단계

응답서의 status는 요청 시도 하나의 결과입니다. JOB 단계는 작업 기록의 진행 위치입니다. done이라는 문자열이 두 체계에 나오더라도 같은 필드나 의미로 읽지 않습니다.

응답 상태 값	한국어 대응	판정 기준
`done`	완료	필수 결과가 쓸 만하고 완료 기준을 충족합니다.
`partial`	일부 완료	일부 산출은 있으나 핵심 완료 조건이 남았습니다. 결과를 보존하고 남은 일을 적습니다.
`failed`	실행 실패	오류로 요청 작업 수행이 실패했습니다. 이미 만든 산출이 있다면 상태와 별개로 보존합니다.
`blocked`	진행 보류	필수 입력·권한 또는 경계 문제로 진행할 수 없습니다. 막힌 근거를 밝힙니다.

JOB 단계 표기	한국어 대응	뜻
`request`	요청	목표와 완료 조건을 고정합니다.
`execution`	실행	허용된 범위의 작업을 수행합니다.
`verification`	검증	실행 기록과 실제 결과를 대조합니다.
`done`	JOB 완료	단계 계약에 따라 결과를 종결 기록합니다. 응답 상태 `done`과 구별합니다.

simple은 JOB 없이 요청 범위에서 처리하는 경로이며, light는 JOB tier 표기입니다. 이 값은 단계나 응답 상태가 아닙니다.

4. 기록·게이트·승인 코드

표기	한국어 대응	사용 맥락
`ensure_request.py`, `orchestration/glm/scripts/ensure_request.py`	요청 등록기	본문을 확인하고 요청을 등록하며, 등록 결과를 JSON으로 돌려줍니다. 등록 결과는 dispatcher 실행 완료를 뜻하지 않습니다.
`created`, `reused`, `superseded`	생성·재사용·대체 등록 결과	각각 새 요청 생성, 유효한 기존 요청 재사용, 기존 목표에 새 요청 등록을 뜻합니다. 재사용은 새 실행 시도를 시작했다는 의미가 아닙니다.
`orchestration/worker_dispatch.py`, `orchestration/glm/executor/state.py`, `orchestration/tasks/<request_id>/state.json`	dispatcher와 요청별 실행 상태 기록	요청 중복·시도 상태를 추적하고 상태형 실행 경로의 attempt 정보를 기록합니다.
`orchestration/glm/goals/`, `goals/<goal_id>.json`, `inbox/<request_id>-request.md`	목표 정보와 대기 요청서	등록기의 목표 기록과 워커가 받을 요청 파일입니다.
`orchestration/glm/inbox/`, `orchestration/glm/outbox/`, `-request.md`, `-response.md`, `done/`	요청 수신·응답 전달·완료 보관 위치	파일 handoff 흐름의 설치별 경로와 파일명 패턴입니다.
`queued`, `running`, `verifying`, `succeeded`, `waiting`	대기·실행·검증·성공·이어갈 작업	dispatcher 작업 상태의 주요 전이·대기 값입니다. 응답서의 `status`와 다른 상태 체계입니다.
`partial-with-artifacts`	일부 완료, 산출 보존 표시	응답 결과의 `partial`에 확인 가능한 산출이 보존됐음을 요약할 때 쓰는 표기입니다. JOB 단계나 dispatcher 상태 값이 아닙니다.
`created_by`	요청 작성 주체 필드	`orchestrator` 또는 `heartbeat` 등 요청을 만든 주체를 나타냅니다.
`approved_by`	승인자	JOB의 승인 기록에서 승인 주체를 적습니다.
`evidence`	승인 근거	실제 사용자 승인 원문이나 메시지 식별 근거를 기록합니다.
`approval.md`	JOB 승인 기록	승인 주체와 근거를 저장하는 문서입니다.
`request.md`, `execution.md`, `verification.md`, `result.md`	요청·실행·검증·결과 기록	JOB 단계별 필수 기록 파일 이름입니다.
`work-history.md`, `artifacts/`, `pre-change/`, `workspace/jobs/<JOB>/`	결정 이력·작업 산출·복구 원본·JOB 위치	JOB 폴더의 기록과 복구 자료를 구분합니다.
`.bak-<날짜>`, `orchestration/records/manager-actions.md`	직접 수정 백업·변경 이력	JOB 없이 작은 변경을 기록할 때 쓰는 백업 이름과 변경 기록 파일입니다.
`cron/`, `knowledge/`	예약 실행·지식 저장소	운영 확장의 위치 계열입니다. 일정 정의와 실행 컨텍스트는 같은 뜻이 아닙니다.
`contract.yaml`, `registry-v2.json`, `tiers/light.yaml`	단계 계약·활성 상태·tier 설정	JOB 흐름의 정의, 등록 상태, light tier 조건을 담는 운영 파일 표기입니다.
`runner.py`, `check.sh`	실행기·검사기	작업 흐름의 전이와 조건 점검에 사용하는 구현 이름입니다.
`workflow-gate.sh`, `create-job.sh`, `start`, `advance`, `-g`	JOB 생성·게이트 전이·목표 인자	운영 명령의 실행 파일과 인자 표기입니다. 안내 명령은 설명용이며 이 페이지에서 실제 실행하지 않습니다.
`light-v2`, `simple-v2-prototype`, `.workflow-state`, `approval-policy.json`, `manifest.yaml`	graph 이름·비활성 metadata·JOB 상태·승인 정책·manifest	`light-v2`는 신규 light JOB graph, `simple-v2-prototype`은 비활성 metadata 표기입니다. 나머지는 JOB별 상태·승인·설정 기록 이름입니다.
`approved_by:`, `evidence:`, `steps/complete/SKILL.md`	승인 기록 필드와 완료 단계 안내	승인 주체·근거 필드 및 단계별 절차 파일입니다. 사용자 승인 범주는 별도 원문 근거가 필요합니다.

5. 지식·교훈 출처 표기

표기	한국어 대응	뜻
자료 묶음 · `CONTEXT_PACK`	context pack	요청에 맞춰 검색된 교훈·결정 후보와 검색 상태를 담습니다. 후보 목록은 검증된 결론이 아닙니다.
`found`, `no_match`	후보 있음, 일치 후보 없음	검색 결과 상태입니다. `no_match`는 지식 자체가 없다는 증거가 아닙니다.
`search_error`, `source_missing`	검색 오류, 원본 저장소 없음	후보 검색의 실행·입력 상태입니다.
`validation_status: candidate`	검토 후보	교훈 초안이 후보로 기록된 상태입니다. 검증·정본 채택을 의미하지 않습니다.
`body_status`, `acquisition_scope`	본문 확보 상태, 수집 범위	출처 문서에 본문이 있는지와 원문·요약 등 확보 범위를 구분합니다.
`knowledge_status`, `source_state`	지식 상태, 출처 상태	후보·현재·대체·충돌 및 출처 판정을 표현합니다. `unknown`은 확인하지 못한 상태입니다.
`source_resolution`, `source_locator_resolution`, `superseded_by`	원문 경로 판정, 참조 경로 판정, 대체 문서	출처와 대체 대상에 대한 연결 상태를 나타냅니다. 경로 해석 성공은 사실성 검증이 아닙니다.
`write-lesson.py`, `--id`, `--body-file`	교훈 기록 스크립트·ID·원고 파일 인자	새 후보를 작성하고 색인을 갱신하는 운영 도구 표기입니다. 원고에는 검색 단서가 되는 `언제 쓰나` 절이 필요합니다.

6. 공개 참조 코드와 예제 표기

코드 표기	한국어 대응·경계
`reference/orchestrator.py`: `request_digest(request)`, `submit(request, inbox)`, `collect(request_id, outbox)`	요청 digest 계산, inbox 제출, outbox 응답 수집을 담당하는 공개 예제 코드입니다.
`reference/worker.py`: `resolve_inputs(root, names)`, `process_one(request_path, outbox, allowed_root, handler)`, `_response(...)`, `_publish(...)`	입력 경계 확인, 요청 한 건 처리, 응답 구성과 게시를 나눕니다. `allowed_root`는 허용 입력 루트입니다.
`reference/filesystem_transport.py`: `encode_json(value)`, `read_json(path)`, `write_json_atomic(path, value, replace=False)`	JSON 인코딩·읽기·원자적 쓰기를 제공합니다. `replace=False`는 기존 파일을 보존하며 `replace=True`만 교체를 허용합니다.
`tests/test_contracts.py`	공개 계약의 파일 handoff, 경계·오류·재처리 동작을 검사하는 테스트입니다.
`LIGHT_FILES`, `examples/integration-check/`	단계별 필수 파일 fixture와 누락 조건을 확인하는 합성 예제이며 실제 JOB 게이트를 실행하지 않습니다.
`inspect(request_path, lessons_path)`, `claim_verified: false`, `promotion_performed: false`	제공된 교훈 목록을 찾고 출처·상태를 정규화하는 예제입니다. 주장을 검증하거나 교훈을 승격하지 않았음을 두 boolean 필드가 나타냅니다.
`examples/knowledge-context-check/`, `examples/integration-check/tests/`, `examples/knowledge-context-check/tests/`	합성 입력만 사용하는 지식 상태·통합 예제의 소스와 테스트 경로입니다.
`examples/integration-check/src/integration_check.py`, `examples/integration-check/tests/test_integration_check.py`, `examples/knowledge-context-check/src/knowledge_check.py`, `examples/knowledge-context-check/tests/test_knowledge_check.py`	두 합성 예제의 구현과 테스트입니다. 실제 gate나 지식 저장소를 운영하지 않습니다.
`make test`, `make example NAME=portable-worker`, `make example NAME=integration-check`, `make example NAME=knowledge-context-check`, `make build`, `make check`, `Makefile`, `README.md`	저장소 루트에서 공개 참조 계약·예제·사이트를 시험·빌드·점검하는 명령과 안내 파일입니다. 로컬 운영 확장의 JOB·dispatcher를 실행하지 않습니다.

7. 승인 범주와 근거 파일

식별자	한국어 대응	승인 기준
`permanent_deletion`	구조·이력 데이터 영구 삭제	행동을 명시한 사용자 승인 원문이 필요합니다.
`external_publication`	외부 전송·게시	외부 효과가 명시된 사용자 승인 원문이 필요합니다.
`credential_security`	자격증명·보안 설정 변경	대상 변경을 명시한 사용자 승인 원문이 필요합니다.
`policy_amendment`	정책 정본 개정	정책 개정 행동을 명시한 사용자 승인 원문이 필요합니다.

각 식별자는 승인 범주의 이름이며, 확인되지 않은 별도 승인을 만들어 내지 않습니다. 용어의 출처와 현재 계약은 아래 파일에서 확인합니다.

내용	근거 파일
역할·권한·응답 상태	`orchestration/POLICY.md`, `orchestration/WORKER.md`
공개 JSON 계약과 Markdown handoff 구분	`site/wiki/reference/contracts.html`, `content/reference/contracts.md`
JOB 단계·파일·게이트	`site/wiki/reference/workflow.html`, `core/skills/custom/workflow/v2/contract.yaml`
교훈·출처 필드	`core/scripts/context_pack.py`, `core/scripts/knowledge_source_status.py`, `core/scripts/write-lesson.py`, `core/scripts/daily-knowledge-process.sh`
변경 기록·복구	`orchestration/records/manager-actions.md`, `.bak-<날짜>`, `pre-change/`
개념 용례	공개 사이트의 교육용 HTML 원고와 위키 요청·응답, 통합, 지식 참조 페이지

확인 기준: 2026-10-13. 문서의 한국어 설명은 읽기용 대응이고, 코드·경로·필드 식별자는 원래 표기를 유지합니다.