# 설치 > Orca, agent CLI, git, gh, python3, bd, redaction rules, 선택 skill stack을 설치 전 측정하는 경로와 실패 신호를 설명합니다. - Repository: local/master-ops-with-local-mogui-ADE-orchestrator - Human docs: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3 - Complete Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms-full.txt ## Source Files - `local-mogui-ade-orchestrator:docs/public/getting-started.md` - `local-mogui-ade-orchestrator:scripts/onboarding-preflight.sh` - `local-mogui-ade-orchestrator:tests/test_onboarding_preflight.py` - `local-mogui-ade-orchestrator:README.md` - `local-master-ops:onboarding/01-preflight.md` --- --- title: "설치" description: "Orca, agent CLI, git, gh, python3, bd, redaction rules, 선택 skill stack을 설치 전 측정하는 경로와 실패 신호를 설명합니다." --- `scripts/onboarding-preflight.sh`가 설치 전 필수 표면을 측정한다. no-flag 실행은 읽기 전용이며, `--fix`는 승인된 알려진 설치 명령을 실행한 뒤 결과물을 다시 측정한다. `FAIL`은 founding을 막고 `BLOCKED`로 종료하며, `WARN`은 단독으로 exit 1을 만들지 않지만 필수 성격의 경고는 요약에서 다시 출력된다. ## 실행 위치와 기본 명령 preflight는 오케스트레이터 런타임 저장소 루트에서 실행한다. 이 스크립트는 Orca 앱 상태만 보지 않고, 현재 터미널에 non-legacy orchestration Run이 바인딩되어 있는지도 확인한다. ```console $ cd $ ORCA_AGENT_CLI="" bash scripts/onboarding-preflight.sh ``` `ORCA_AGENT_CLI`가 비어 있으면 `agent-cli`가 `FAIL`이다. 예: `claude`, `codex`, `grok`처럼 실제 master 세션을 실행할 CLI 이름을 넣는다. 승인된 의존성 설치까지 맡길 때만 `--fix`를 사용한다. ```console $ ORCA_AGENT_CLI="" bash scripts/onboarding-preflight.sh --fix ``` `--fix`가 다루는 범위는 제한적이다. 알려진 경로가 있는 Orca, `ctx`, `gitleaks`, 전역 Orca skills 설치 또는 갱신을 시도하고, 설치 명령의 exit code만 믿지 않고 다시 측정한다. ## 필수 설치 표면 | 항목 | 측정 방법 | 실패 신호 | | --- | --- | --- | | Orca CLI | `orca status --json` 또는 선택된 `ORCA_CLI_COMMAND` | CLI 없음, 지원되지 않는 basename, `ok:true` 아님 | | Orca orchestration Run | `orca orchestration run-current --json` | legacy read-only, Run 미바인딩, legacy Run | | Orca skills | skill root의 `orca-cli`, `orchestration` 또는 `skills list -g` | 둘 중 하나라도 없음 | | master agent CLI | `ORCA_AGENT_CLI`와 `command -v` | unset 또는 PATH 미해결 | | worker runtime | `codex`, `cursor-agent` | 둘 다 없으면 `FAIL`; 하나만 없으면 `WARN` | | `git` | `command -v git` | PR 기반 저장소 운영 불가 | | `gh` | `command -v gh`, `gh auth status` | binary 없음은 `FAIL`; auth 또는 `workflow` scope 부족은 `WARN` | | `python3` | `python3` 존재와 버전 문자열 | binary 없음 | | `bd` | `bd where` | binary 없음, ops repo 밖으로 resolve, `.beads` marker는 있는데 `bd where` 실패 | | redaction rules | `REDACTION_EXTRA_PATTERNS` 또는 `~/.config/redaction-extra.txt` | 파일 없음, usable rule 0개, malformed rule 존재 | | dispatch ledger | `DISPATCH_GATE_LEDGER` 디렉터리 쓰기 가능성 | ledger 디렉터리 생성 또는 쓰기 불가 | Python은 preflight에서 별도 version floor를 강제하지 않는다. 도구별 더 높은 interpreter 요구사항은 각 도구가 런타임에서 처리한다. ## Orca 설치와 CLI 등록 macOS에서 알려진 설치 명령은 Homebrew cask다. ```console $ brew install --cask stablyai/orca/orca ``` Linux와 Windows는 Orca 공식 다운로드 경로를 사용한다. Linux에서는 binary 이름이 `orca-ide`일 수 있다. preflight가 지원하는 basename은 `orca`, `orca-dev`, `orca-ide`다. 설치 후 Orca 앱에서 Shell command를 등록해야 터미널의 `orca` 호출이 동작한다. 성공 조건은 UI 라벨이 아니라 이 명령의 결과다. ```console $ command -v orca $ orca status --json ``` Run이 바인딩되지 않았거나 legacy라면 새 Run을 만든 뒤 다시 측정한다. ```console $ orca orchestration run-create $ bash scripts/onboarding-preflight.sh ``` ## Beads와 ops 저장소 `bd`는 execution state를 저장하는 tracker 표면이다. preflight는 단순히 binary만 보지 않는다. `bd where`가 `.beads` 경로를 반환하면 그 상위가 ops 저장소인지 확인하고, `docs/MASTER-OPERATIONS.md`가 없으면 ops repo 밖으로 resolve된 것으로 본다. ```console $ command -v bd $ bd where ``` ops repository가 아직 만들어지지 않은 위치에서는 `bd` binary present만으로 통과할 수 있다. 하지만 `.beads` marker가 감지되는데 `bd where`가 실패하면 fix 대상이다. ## Redaction rules 설치 조직별 redaction 규칙은 저장소에 커밋하지 않는다. 기본 위치는 `~/.config/redaction-extra.txt`이고, 다른 위치를 쓰려면 `REDACTION_EXTRA_PATTERNS`를 지정한다. ```text id|description|regex ``` 규칙 파일 제약은 다음과 같다. | 규칙 | 의미 | | --- | --- | | 빈 줄과 `#` 주석 | 무시 | | 첫 두 `|` | `id`, `description`, `regex` 구분자 | | regex | Python `re.compile` 가능해야 함 | | 출력 | 규칙 내용은 출력하지 않고 count만 출력 | 예시는 형식만 보여준다. 실제 조직명, 제품명, 개인 식별자는 로컬 파일에만 둔다. ```console $ export REDACTION_EXTRA_PATTERNS="$HOME/.config/redaction-extra.txt" $ bash scripts/onboarding-preflight.sh ``` publish-time scan은 `gitleaks`를 엔진으로 사용한다. ```console $ bash scripts/redaction-scan.sh $ bash scripts/redaction-scan.sh --staged $ bash scripts/redaction-scan.sh --range A..B $ bash scripts/redaction-scan.sh --commit-messages A..B $ REDACTION_REQUIRE_EXTRA=1 bash scripts/redaction-scan.sh ``` | exit code | 의미 | | --- | --- | | `0` | clean | | `1` | finding 있음 | | `2` | 판단 불가: `gitleaks` 없음, 필수 org rules 없음, range 오류, retired allowlist entry, engine error 등 | `redaction-scan.sh`는 repository tracked content와 선택된 commit message 범위를 읽는다. PR title, PR body, review comment, release note, issue text, forge 웹 UI에 직접 입력한 문장은 스캔하지 않는다. ## 선택 skill stack 선택 skill stack은 기본 실행 가능성과 별개로 master의 행동을 바꾸는 층이다. preflight는 `superpowers`와 `ponytail`을 `skill-stack`으로 측정한다. | pack | 역할 | 없을 때 | | --- | --- | --- | | `superpowers` | 방법론과 절차 discipline | charter가 절차보다 조언처럼 읽힐 수 있음 | | `ponytail` | restraint와 scope control | diff가 커지고 speculative structure가 늘 수 있음 | 탐지는 agent-neutral이다. skill directory가 알려진 root 아래에 있거나, agent plugin manifest에 pack이 있으면 통과한다. Claude Code가 선택된 host이면 `/plugin install ...` 계열 안내를 출력하고, 다른 agent이면 해당 agent의 skill pack 경로나 skill root 설치 안내를 출력한다. 이 stack은 특정 model provider에 묶인 필수 런타임이 아니다. 파일, 저장소, catalog 또는 agent별 plugin packaging으로 배포될 수 있는 portable skill layer로 취급한다. ## Waiver와 요약 판정 필수 체크를 정말 만족시킬 수 없을 때만 `PREFLIGHT_WAIVE`로 label을 지정한다. ```console $ PREFLIGHT_WAIVE=redaction-extra ORCA_AGENT_CLI=claude bash scripts/onboarding-preflight.sh ``` waive는 조용히 통과시키지 않는다. 해당 label은 `WAIVED`로 출력되고, summary는 `READY WITH WAIVERS`라고 말한다. 오타난 waiver는 적용되지 않고 “named checks that did not run”으로 출력되며 원래 check는 계속 enforced 상태다. 정상 종료 메시지는 세 가지 형태다. | summary | 의미 | | --- | --- | | `READY: all required checks passed` | 필수 체크 만족 | | `READY WITH WAIVERS` | 일부 필수 체크가 downgrade되었지만 만족된 것은 아님 | | `BLOCKED: fix every FAIL before onboarding` | founding 진행 금지 | ## Instance config에 남기는 값 preflight로 확인한 master CLI는 instance-owned config에 기록한다. template example은 커밋용 예시이고, 채워진 config는 설치 인스턴스 소유다. ```console $ test -f config/instance-runtime.json || cp config/instance-runtime.example.json config/instance-runtime.json ``` 주요 필드는 다음과 같다. | 필드 | 의미 | | --- | --- | | `master_host_runtime` | master session을 실행하는 agent CLI 이름 | | `transcript_globs` | runtime 이름별 session JSONL glob | | `product_repo` | 선택 primary product repository의 절대 경로 | model tier policy도 instance-owned 파일이다. ```console $ test -f config/model-tier-policy.json || cp config/model-tier-policy.example.json config/model-tier-policy.json ``` `version`은 `2`여야 한다. `agents`는 측정되었거나 사용자가 직접 명명한 runtime/model inventory이고, `tiers`는 model id 목록이다. 측정 불가 값은 추측하지 않고 `unknown`으로 둔다. `fanout_caps`에서 누락된 tier는 uncapped로 해석된다. ## 설치 실패 신호 | 증상 | 우선 확인 | 조치 | | --- | --- | --- | | `orca`는 있는데 orchestration이 `FAIL` | `run-current --json`의 Run 상태 | `orca orchestration run-create` 후 재실행 | | preflight가 `BLOCKED` | `FAIL` label | 각 label을 수리; waiver는 의도와 비용을 기록할 때만 사용 | | `gitleaks` 없음 | `WARN gitleaks` | publish 전 설치; master 실행만으로는 block 아님 | | redaction rules 없음 | `FAIL redaction-extra` | 로컬 org rules 파일 작성, 최소 1개 usable rule 유지 | | `bd where`가 ops repo 밖 | 반환된 `.beads` 경로 | ops repo에서 실행하거나 Beads 설정 수리 | | worker runtime 없음 | `FAIL worker-runtime` | `codex` 또는 `cursor-agent` 중 하나 이상 설치 | | `gh` auth warning | `gh auth status` | push/PR 작업 전 `gh auth login` 또는 `gh auth refresh -h github.com -s workflow` | ## Next clone, Orca 프로젝트 등록, agent 시작, wake-up 문장까지의 최소 실행 경로. `redaction-scan.sh`, `redaction-inventory`, pre-push hook, release gate 범위. preflight `BLOCKED`, Orca CLI 미등록, misplacement, redaction 판단 불가 증상별 대응. `instance-runtime.json`, `model-tier-policy.json`, 환경 변수 override와 fail-closed 동작.