개발 담당자용 설치·실행 안내

파일럿에 참여해 주세요. 본 프로젝트는 Apache-2.0 조건에 따라 라이선스 비용이나 로열티 없이 사용할 수 있습니다. 실행 경험이나 문서 의견은 피드백·기여 안내에서 남겨 주세요.

우리 팀의 개발 흐름부터 살펴보세요

보안이 내재화된 개발 하네스는 팀의 보안 기준을 작업·검사·수정 지원·승인·증적으로 연결하는 실행 기반입니다. GovCode Harness는 이를 공공 프로젝트에 적용하는 것을 지향합니다. 먼저 다음 질문으로 도입 범위를 정리하세요.

어떤 개발 단계와 저장소에 적용할까요? 프로젝트 유형·기관 조건·적용 후보 기준을 정리합니다.
개발팀이 무엇을 해야 할까요? 기준의 출처·버전·적용 조건을 확인하고 작업·산출물·담당자를 연결합니다.
어디까지 자동화할까요? 검사·수정 지원과 담당자 판단·승인의 역할을 정합니다.
무엇을 완료 근거로 삼을까요? 검사 결과·검토 기록·증적과 다음 작업을 정합니다.

목표와 현재 기능 공개 v0.11.0에는 기존 프로필·규정 팩·문서 초안에 더해 요구·산출물 추적 검사, 제한된 문서 보완, 프로젝트 화면·현재 단계 판정·서명 증적 보관이 포함됩니다. 아래 명령은 이 공개 태그 기준입니다. 개발 상태와 공개 범위 확인

제품 전체 범위와 다음 설계

1. 준비와 지원 범위

개발자 또는 플랫폼 담당자가 로컬 환경에서 시작할 수 있습니다. 실제 민원 원문·운영 비밀값을 준비할 필요가 없습니다.

경로	필요 환경	확인하는 것
기본 데모	Python 3.10 이상, Git	표준 라이브러리 경로의 탐지·차단·수정·재검사. 서명 없음.
전체 참조 데모	macOS, Python 3.12 이상, Git, uv, sandbox-exec 사용 가능 환경	서명 정책·격리 수정·증적·보관·복구·관리 API. 로컬 HTTP와 프로세스 실행 허용 필요.
패키지 설치	최초 의존성 다운로드용 네트워크	버전·해시 잠금 의존성을 전용 .runtime 환경에 설치. 전역 Python은 변경하지 않음.

전체 참조 검증 환경은 macOS와 Python 3.12입니다. 다른 OS에서 기본 검사를 시도할 수 있지만, 전체 격리 검증의 지원을 보장하지 않습니다.

환경 도구: Python 공식 다운로드 · uv 공식 설치 안내. 기관에서 승인한 설치 경로를 사용하세요.

2. 고정 버전의 소스 받기

가이드의 기준 소스는 공개 프리릴리스 v0.11.0입니다. 이전 버전에서 사용한 작업 폴더와 구분해 새 폴더에 받으세요. 이미 같은 이름의 폴더가 있다면 새 작업 경로를 사용하세요.

git clone --branch v0.11.0 --depth 1 https://github.com/roboco-io/govcode-harness.git
cd govcode-harness

라이선스 포함 소스 ZIP 다운로드도 가능합니다. 압축을 푼 경우 해당 폴더로 이동하세요. 검사 대상 저장소는 Git commit이 필요하지만, Harness 자체는 ZIP에서 실행할 수도 있습니다.

본 프로젝트와 이 가이드는 독립 저장소입니다. 가이드 수정에 서브모듈 갱신이 필요하지 않습니다. 가이드 소스의 버전 대응표에서 기준 코드를 확인할 수 있습니다.

v0.11 전체 프로젝트 참조 실행

이 경로는 사업 산출물·요구사항 추적과 기존 코드 검사를 연결합니다. 앞에서 받은 v0.11.0 프로젝트 루트에서 전용 환경을 준비하세요. 아래 Python·uv 경로는 실제 설치 경로로 바꿉니다. 이미 설치한 참조 환경이 있으면 설치 단계를 건너뜁니다.

python3 scripts/setup_reference.py \
  --python /absolute/path/to/python3.12 \
  --uv /absolute/path/to/uv

새 비공개 폴더에 실행

.runtime/reference-venv/bin/python -m govcode_harness project-demo --output .runtime/my-project-demo

합성 자료와 시험용 키를 만들고, 요구·설계·시험·검토의 연결을 검사합니다. 독립 승인한 제한된 문서 변경을 원본을 보존한 새 commit에 적용하고, 재검사·현재 단계 판정·증적 보관·백업·복구까지 확인합니다. 데모가 만든 원래 보관소를 제거해 상실을 모사한 뒤 복구 결과로 다시 확인합니다.

요약 파일은 project-reference-result.json입니다. 확인 항목 34개가 모두 true이고, 전체 요구 8개 중 현재 단계 충족 5개·후속 1개·승인 제외 2개가 기대 결과입니다. 현재 단계의 allow는 전체 프로젝트 완료나 기관 운영 승인이 아닙니다.

역할별 프로젝트 화면

.runtime/reference-venv/bin/python -m govcode_harness control --config .runtime/my-project-demo/control-config.json --port 8766

http://127.0.0.1:8766/project.html에서 확인합니다. 역할별 토큰은 출력 폴더의 tokens/author.token, tokens/approver.token, tokens/operator.token, tokens/auditor.token에 있습니다. 토큰·키·설정·백업·출력 폴더 전체를 공개하지 마세요.

서버 종료는 실행한 터미널에서 Ctrl+C를 누릅니다. 기존 로깅 참조 화면과 프로젝트 화면은 출력 설정과 토큰 경로가 다릅니다.

전체 실행과 화면 안내 · 평가·문서 보완 안내 · 현재 단계·보관 안내

3. 기본 흐름 먼저 확인하기

프로젝트 루트에서 실행합니다. 명령은 새 합성 Git 저장소와 예시 자료를 출력 폴더 안에 만듭니다. 기존 업무 저장소는 수정하지 않습니다.

python3 -m govcode_harness demo --output .runtime/first-onboarding

정상 완료 시 명령의 종료 코드는 0이며 결과에는 before: deny, after: allow, signature_status: not_signed가 표시됩니다.

응답 보존, 민원 본문의 일반 로그 제거, 필요한 감사 호출 보존을 함께 확인합니다. 이 경로의 증적은 서명된 운영 증적이 아닙니다.

4. 서명과 관리까지 전체 참조 실행하기

전용 환경 설치

아래 두 경로는 설치된 Python 3.12 이상과 uv의 실제 절대 경로로 바꾸세요. command -v python3.12와 command -v uv로 경로를 확인할 수 있습니다.

python3 scripts/setup_reference.py \
  --python /absolute/path/to/python3.12 \
  --uv /absolute/path/to/uv

버전·해시 잠금 파일에 따라 별도 환경을 만들고 정책·UI 자원을 포함한 Harness 패키지를 설치합니다. 기존 환경은 덮어쓰지 않습니다.

새 출력 폴더에 실행

.runtime/reference-venv/bin/python -m govcode_harness reference-demo \
  --output .runtime/onboarding-reference

합성 작성자와 독립 승인자의 키 생성 → 예시 정책 서명 → 위험 commit 차단 → fixture 수정 제안과 승인 → 실제 OS 격리 검사 → 별도 알려진 수정 commit의 통과 → 증적 보관·복구 → 관리 API 확인 순서로 실행합니다.

중요한 구분 격리된 제안 수정의 검사와 별도 알려진 수정 commit의 게이트 통과를 함께 확인하는 참조 흐름입니다. 실제 LLM이 자동으로 코드를 고쳐 운영 배포했다는 뜻이 아닙니다.

프로필·규정 팩·문서 초안 개별 실행

위의 전용 환경 설치를 마친 뒤 아래 명령을 각각 실행하세요. 기존 전체 참조 데모 실행은 이 세 명령의 선행 조건이 아닙니다. 출력 폴더는 매번 새 경로를 사용합니다.

사업 정보의 버전과 승인 확인

.runtime/reference-venv/bin/python -m govcode_harness project profile-demo --output .runtime/onboarding-profile

서로 다른 담당자의 승인으로 정보 두 버전을 만들고, 미확정 정보를 유지하며 자기 승인을 거부하는지 확인합니다. 결과 파일 profile-demo-result.json의 active_revision은 2, 확인 항목 6개는 모두 true가 기대 결과입니다.

규정 묶음과 적용 대상 확인

.runtime/reference-venv/bin/python -m govcode_harness project pack-demo --output .runtime/onboarding-pack

서명된 규정 묶음의 발행·버전 고정, 독립 검토, 취소된 자료의 사용 거부를 확인합니다. 확인 항목 7개가 모두 true이고 최종 적용·제외·검토 필요 항목은 2·1·0입니다. 적용 대상 판단 완료는 요구 충족이나 운영 승인을 뜻하지 않습니다.

설계 문서 초안 만들기

.runtime/reference-venv/bin/python -m govcode_harness project document-kit --output .runtime/onboarding-documents

PRD·아키텍처·데이터 모델·규정 추적 매트릭스·ADR·백로그와 AGENTS.md·작성 정책, 별도의 검토 메모를 만듭니다. 정보가 없으면 미제공으로 표시합니다. 생성 성공은 사실 검증이나 문서 승인이 아닙니다. AI Doc Ready를 자동 설치·실행하지 않으며 사실·수치·의미는 원문과 대조해야 합니다.

프로필 상세 안내 · 규정 팩·적용성 안내 · 문서 생성과 선택적 구조 검사

데모 출력에는 시험용 개인 키가 포함될 수 있습니다. 출력 폴더 전체를 공개하지 마세요.

5. 결과를 읽고 성공 여부 확인하기

python3 -m json.tool .runtime/onboarding-reference/reference-result.json

항목	기대 결과·의미
before.outcome / after.outcome	deny / allow. 위험본과 수정본은 서로 다른 commit입니다.
model_checks	verdict=verified, sandbox_verified=true, checks의 모든 값 true. backend=fixture, real_model_executed=false.
store_checks / control_checks	각각 4개 / 5개의 확인 항목이 모두 true. 보관·복구와 실제 loopback API의 합성 역할 경계를 확인합니다.
operational_approval / legal_records	false / pending. 실제 기관 승인과 법령 적용 판단을 대신하지 않습니다.

종료 코드	처리
전체 참조 0	필수 합성 확인 완료. 실제 운영 승인으로 해석하지 않습니다.
전체 참조 3	격리 불가 등으로 일부 필수 검증 미완료. 우회하여 완료 처리하지 않습니다.
오류 4	설정·파일·정책 등 오류. 문제를 해결하고 새 출력 경로로 재실행합니다.
scan / gate의 2 또는 3	각각 deny / review. 참조 데모의 완료 코드와 개별 판정 코드를 구분하세요.

공유 가능한 요약은 reference-result.json입니다. 출력 폴더 전체를 업로드하지 마세요. 개인 키가 들어 있는 역할별 폴더(author/·approver/·operator/·auditor/)와 control-bootstrap.json, 로컬 설정은 공개 대상이 아닙니다.

6. 로컬 관리 화면 열기

.runtime/reference-venv/bin/python -m govcode_harness control \
  --config .runtime/onboarding-reference/control-config.json \
  --port 8766

명령이 표시하는 http://127.0.0.1:8766/에 접속합니다. 터미널에서 서버를 실행한 상태로 유지하세요. 새 터미널 또는 로컬 편집기로 control-bootstrap.json의 필요한 역할 토큰을 확인해 화면에 입력합니다. 토큰을 채팅·이슈·화면 공유에 붙이지 마세요.

역할	확인할 기능
author	정책 초안·검토 제출·등록된 실행에 대한 예외 요청
approver	다른 작성자가 제출한 정책·예외의 독립 승인
operator	승인 정책 묶음 발급·보관 잠금 관리
auditor	자기 기관·프로젝트의 실행·정책·증적 열람

역할은 합성 참조 신원입니다. 운영 OIDC·LDAP 연결이 아닙니다. 데모 이후 화면은 복구한 보관소를 사용하므로 보존 잠금된 합성 증적을 확인할 수 있습니다. 종료하려면 서버 터미널에서 Ctrl+C를 누릅니다.

GitHub Pages는 이 안내 사이트만 호스팅합니다. 검사 엔진·민원 API·관리 서버는 로컬 환경에서 실행합니다.

7. CI 적용을 준비하기

먼저 로컬 시험과 게이트 사용법을 확인하세요.

.runtime/reference-venv/bin/python -m unittest discover -s tests -p 'test_*.py' -q
.runtime/reference-venv/bin/python -m govcode_harness gate --help

ci/reference-gate.sh는 기본 입력 게이트, ci/reference-signed-gate.sh는 서명 정책 참조 예제입니다.
신뢰한 전체 expected commit, 현재 HEAD, 증적 commit, 프로필과 receipt를 대조합니다. expected commit을 검사 대상 저장소의 사용자 파일에서 읽지 않습니다.
서명 묶음·신뢰 목록·기관·프로젝트·최소 순번과 철회 자료는 검사 checkout 밖의 신뢰 경로에서 제공합니다.
승인 예외는 정확한 commit·도구·정책·탐지 의미에 결합합니다. 오류·미분석·review를 예외로 통과시키지 않습니다.
과거 archive 무결성 성공을 현재 commit의 통과 결과로 재사용하지 않습니다.

CI 예제는 비활성 상태입니다. 대상 저장소와 담당자를 정한 뒤 필수 검사와 보호 브랜치를 설정해야 실제 병합·배포를 막을 수 있습니다. 운영 중인 민원 요청을 차단하는 기능이 아닙니다.

8. 기관 파일럿을 준비하기

이 체크리스트는 준비 상태를 살펴보기 위한 도구입니다. 선택 결과는 저장되거나 전송되지 않으며 기관 승인 기록이 되지 않습니다.

대상 저장소·Python 지원 구문·제외 범위를 정했습니다.
개인정보·보안 담당자와 규정 적용성 및 미확정 항목을 확인했습니다.
정책 작성자·승인자·운영자·감사 열람자와 운영 신원을 정했습니다.
서명키·신뢰 루트·철회 전파·최소 순번 관리 책임을 정했습니다.
증적 보존 분류·접근·보관 잠금·파기·복구 책임을 정했습니다.
CI의 신뢰한 expected commit과 필수 검사·보호 브랜치 설정을 정했습니다.
모델 사용 여부와 허용 입력·반출 범위를 정했습니다.
파일럿 기간·표본·정답·성공 기준·중단 조건·책임자를 정했습니다.

권장 순서는 합성 데모 → 승인된 제한 저장소의 관찰 검사 → 독립 정답과 탐지·오탐·검토 부담 측정 → 기관 검토 후 필수 게이트 적용입니다. 일정·비용·성능을 미리 보장하지 않습니다.

법령상 확정 의무, 기관 정책, 예시 정책, 미확인 요구를 각각 기록하세요. 예시 정책을 운영 의무로 자동 승격하지 마세요. REG-LOG-008 등 미확정 법령 적용 항목은 원문·부칙·기준일 대조와 담당자 판단이 필요합니다.

문제 해결

증상	조치
ENVIRONMENT_EXISTS_USE_EXISTING_OR_NEW_PATH	기존 환경을 사용하거나 설치 명령에 --environment .runtime/reference-new를 지정합니다. 이후 명령의 인터프리터 경로도 함께 바꿉니다.
출력 폴더가 이미 있음	기존 결과를 보존하고 새로운 --output 경로로 실행합니다. 자동 덮어쓰기는 하지 않습니다.
격리 불가 / undeterminable / exit 3	macOS의 sandbox-exec와 로컬 실행 권한을 확인합니다. 다른 OS 또는 제한 실행기에서 완전 성공을 표시하지 않습니다.
crypto·jsonschema 모듈 없음	전용 참조 환경 설치가 완료됐는지 확인하고 .runtime/reference-venv/bin/python으로 실행합니다.
관리 화면 401 / 403	현재 데모의 올바른 역할 토큰과 기관·프로젝트를 확인합니다. 다른 역할로 차단을 우회하지 않습니다.
게이트 오류·commit 불일치	신뢰한 expected commit·현재 HEAD·증적·프로필을 대조하고 수정 후 새 commit을 검사합니다.
포트가 이미 사용 중	--port로 사용하지 않는 로컬 포트를 지정하고 접속 주소도 같은 포트로 바꿉니다.

검증 근거와 자세한 자료

v0.11.0 배포 검증 기록은 전체 시험 739개 통과와 설치 패키지의 통합 확인 34개 통과를 보고합니다. 최종 요구 8개는 현재 충족 5개·후속 1개·승인 제외 2개입니다. 실제 기관 운영이나 실제 AI의 생성 품질 검증을 뜻하지 않습니다.

문서 구조 검사와 사실·의미 검토를 구분합니다. 규정의 적용 대상 판단도 요구 충족 평가와 다릅니다. v0.11.0 검증 기록과 릴리스 노트를 함께 확인하세요.

프로젝트 코드는 Apache-2.0, 이 가이드·브로슈어는 CC BY 4.0입니다. 출처 표시 예와 라이선스 범위를 확인하세요. 제3자 라이선스 표시는 유지합니다.