# master-ops 템플릿 참조 > 템플릿 manifest, template version, placeholder, workspace card, charter, runbook, hook, upgrade와 template-check surface를 정리합니다. - 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-master-ops:MANIFEST.json` - `local-master-ops:TEMPLATE-VERSION` - `local-master-ops:ONBOARDING.md` - `local-master-ops:workspace-card/README.md` - `local-master-ops:scripts/template-check` - `local-master-ops:scripts/template-apply` - `local-mogui-ade-orchestrator:scripts/generate-manifest` - `local-mogui-ade-orchestrator:tests/test_template_check_apply.py` --- --- title: "master-ops 템플릿 참조" description: "템플릿 manifest, template version, placeholder, workspace card, charter, runbook, hook, upgrade와 template-check surface를 정리합니다." --- `master-ops` 템플릿은 `local-mogui-ade-orchestrator:master-ops/`의 Stage 1 skeleton을 설치 가능한 ops 저장소로 복사하고, 설치된 복사본은 `local-master-ops:MANIFEST.json`의 `template_version`과 `files` 목록으로 자기 템플릿 계층을 판정한다. Founding은 manifest 목록을 복사하고 placeholder를 채우며, Reverify는 읽기 전용으로 상태를 보고하고, Upgrade는 `template-check`와 `template-apply`로 manifest가 주장하는 템플릿 파일만 앞으로 가져온다. ## 템플릿 계층 | 표면 | 위치 | 역할 | 설치 여부 | | --- | --- | --- | --- | | Manifest | `local-master-ops:MANIFEST.json` | 설치된 템플릿 버전과 필수 파일 목록 | 설치됨 | | Template version stamp | `local-master-ops:TEMPLATE-VERSION` | 템플릿 릴리스 문자열 | 템플릿 측 파일, 생성 ops 저장소에는 제외 | | Onboarding router | `local-master-ops:ONBOARDING.md` | Founding, Reverify, Upgrade, Template improve 모드 라우팅 | 템플릿 측 파일, 생성 ops 저장소에는 제외 | | Step files | `local-master-ops:onboarding/` | Founding 단계별 절차와 검증 | 템플릿 측 파일, 생성 ops 저장소에는 제외 | | Workspace card | `local-master-ops:workspace-card/` | 워크스페이스 루트에 배포할 canonical session card | 설치됨 | | Charter index | `local-master-ops:docs/MASTER-OPERATIONS.md` | 운영 SSOT와 charter section index | 설치됨 | | Charter sections | `local-master-ops:docs/charter/` | 역할, dispatch, succession, record, hook 규칙 | 설치됨 | | Runbooks | `local-master-ops:docs/runbooks/` | 현장 절차와 운영 card | 대부분 설치됨 | | Hooks | `local-master-ops:scripts/hooks/` | host hook에서 호출되는 guard/warn/inject 스크립트 | 설치됨 | | Check/apply scripts | `local-master-ops:scripts/template-check`, `local-master-ops:scripts/template-apply` | 템플릿 drift 보고와 적용 | 설치됨 | ```text local-mogui-ade-orchestrator:master-ops/ 템플릿 skeleton TEMPLATE-VERSION 릴리스 stamp MANIFEST.json 설치 대상 목록 onboarding/ 설치 절차, 템플릿 측 전용 generate-manifest / Founding / Upgrade local-master-ops/ 설치된 ops 저장소 MANIFEST.json 설치 버전과 required paths docs/MASTER-OPERATIONS.md 운영 SSOT index workspace-card/CLAUDE.md, AGENTS.md canonical session card scripts/template-check, template-apply drift 확인과 적용 onboarding step 05 deploy /CLAUDE.md, AGENTS.md host가 읽는 배포본 ``` ## Manifest 생성 규칙 `local-mogui-ade-orchestrator:scripts/generate-manifest`가 `master-ops/` skeleton을 walk해서 `MANIFEST.json`을 만든다. `files`는 POSIX 상대 경로 문자열로 정렬되며, `MANIFEST.json` 자체도 설치 목록에 포함된다. 설치 목록에서 제외되는 템플릿 측 파일과 디렉터리는 코드에 고정되어 있다. | 제외 범주 | 항목 | | --- | --- | | 파일 | `TEMPLATE-VERSION`, `CHANGELOG.md`, `ONBOARDING.md`, `.coverage` | | 디렉터리 | `onboarding`, `docs/lineage`, `.git`, `.beads`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `build`, `dist`, `htmlcov` | | 로컬 산출물 | `__pycache__`, `.pyc`, `.pyo`, `*.egg-info`, symlink | Generator는 설치될 파일에서 authoring frame 누수를 검사한다. `master-ops/` 경로 문자열과 `mogui-master-ops` authoring repository 이름은 설치 파일에 남으면 실패한다. 단, `docs/blame/` 아래 incident record는 측정 증거 보존을 위해 hygiene 검사에서 제외된다. `local-mogui-ade-orchestrator`에서 `python3 scripts/generate-manifest --check`가 0으로 종료하면 committed `MANIFEST.json`이 현재 skeleton, `TEMPLATE-VERSION`, 정렬 규칙과 일치한다. ## Template version 현재 설치 manifest와 stamp는 `v0.5.187`이다. `MANIFEST.json.template_version`은 `TEMPLATE-VERSION`의 한 줄 값을 복사한다. Changelog는 설치 파일이 아니라 템플릿 측 파일이며, 기존 설치본이 자동으로 업데이트되지 않는다는 전제를 둔다. Version skew는 숫자 크기 비교가 아니라 문자열 equality로 판정한다. 설치된 값과 템플릿 값이 다르면 `template-check --template`은 drift로 보고한다. `CHANGELOG.md`는 설치 버전보다 최신인 adoption note를 보고서에 붙여 Upgrade 판단을 돕는다. ## Placeholder 계약 허용 placeholder는 다음 8개뿐이다. | Placeholder | 값의 출처 | | --- | --- | | `{{WORKSPACE_NAME}}` | 기존 install 또는 Founding 중 확인한 워크스페이스 이름 | | `{{WORKSPACE_ROOT}}` | owner가 선택한 워크스페이스 루트 | | `{{OPS_REPO}}` | 승인된 ops 저장소 경로 | | `{{MONITOR_NS}}` | 확인된 monitor namespace | | `{{MODEL_ID}}` | 확인된 master model id | | `{{REPO_LIST}}` | 확인된 workspace repository inventory | | `{{RUNTIME_ROOT}}` | 템플릿 clone의 root, 측정값 | | `{{TEMPLATE_VERSION}}` | 템플릿 `TEMPLATE-VERSION`, 측정값 | Founding step 05는 ops 저장소 전체에서 `{{...}}` 토큰이 남지 않아야 통과한다. `workspace-card/`도 예외가 아니며, undecided 값은 deferral로 남기지 않는다. Upgrade에서 `template-apply --placeholder KEY=VALUE`는 같은 placeholder set만 받으며, 알 수 없는 key는 controlled error로 거절된다. `TEMPLATE_VERSION`을 넘기지 않으면 `template-apply`가 템플릿 측 `TEMPLATE-VERSION`에서 기본값을 읽는다. ## Workspace card `local-master-ops:workspace-card/CLAUDE.md`와 `local-master-ops:workspace-card/AGENTS.md`는 byte-identical canonical session card이다. 설치 후 워크스페이스 루트의 `CLAUDE.md`와 `AGENTS.md`는 이 canonical pair의 배포본이다. 이 pair는 ops 저장소 루트의 `CLAUDE.md` / `AGENTS.md`와 다른 문서다. Ops 루트 pair는 ops 저장소 안에서 agent가 어떻게 동작하는지 설명하고, workspace card는 host가 워크스페이스 루트에서 읽는 master session card다. Owner-facing operating card도 별도 산출물이다. 배포 명령은 placeholder가 채워진 뒤 실행한다. ```console $ cp "{{OPS_REPO}}/workspace-card/CLAUDE.md" "{{WORKSPACE_ROOT}}/CLAUDE.md" $ cp "{{OPS_REPO}}/workspace-card/AGENTS.md" "{{WORKSPACE_ROOT}}/AGENTS.md" ``` Workspace card 내부 링크는 저장 위치인 `workspace-card/`가 아니라 배포 위치인 `{{WORKSPACE_ROOT}}` 기준으로 해석한다. Reverify는 canonical pair와 root 배포본 drift를 보고만 하며, 자동으로 재배포하지 않는다. ## Charter와 runbook 표면 `local-master-ops:docs/MASTER-OPERATIONS.md`는 active operating rule의 index다. 문서 자체는 `{{WORKSPACE_NAME}}` workspace의 master operations SSOT이며, 변경 시 관련 issue-tracker memory pointer와 hook path를 함께 확인하라는 change rule을 가진다. Charter는 10개 section으로 분리되어 있다. | Section | 파일 | 담당 범위 | | --- | --- | --- | | §1 | `docs/charter/01-document-map.md` | 상태와 문서 ownership | | §2 | `docs/charter/02-role-constitution.md` | master role, role state format | | §3 | `docs/charter/03-execution-principles.md` | proposal, approval, execution, recovery | | §4 | `docs/charter/04-worker-routing-review.md` | worker dispatch와 review | | §5 | `docs/charter/05-dispatch-gate.md` | supervised dispatch gate | | §6 | `docs/charter/06-succession.md` | succession과 recovery | | §7 | `docs/charter/07-records.md` | record separation | | §8 | `docs/charter/08-boot-hooks-observability.md` | boot config, hook wiring, observability | | §9 | `docs/charter/09-incident-derived-rules.md` | incident-derived rule | | §10 | `docs/charter/10-closed-principles-pointer.md` | closed decision pointer | Runbook은 operational procedure를 담는다. 예를 들어 `docs/runbooks/hook-fire-observability.md`는 hook fire log를 `${MOGUI_HOOK_FIRE_LOG:-$HOME/.mogui/hook-fire-log.jsonl}`에 JSONL로 남기는 schema와 `scripts/hook-coverage-report` 확인 경로를 정의한다. ## Hook과 host 설정 Template은 hook script와 문서화된 wiring spec을 제공하지만, host별 settings 파일, credential, secret path, 조직별 보안 구현을 함께 배포하지 않는다. Step 08은 shipped hook과 skill layer를 default-on harness로 취급하되, host settings와 plugin configuration 변경에는 별도 host-edit approval을 요구한다. 주요 hook 표면은 다음과 같다. | Hook surface | 대표 파일 | 동작 | | --- | --- | --- | | Role-state injection | `scripts/hooks/role-state-inject.sh` | `UserPromptSubmit`에서 active role과 실행 원칙을 재주입 | | Product path guard | `scripts/hooks/product-path-guard.sh` | product repository write를 차단하거나, 측정된 Bash allowlist 기반으로 fail-closed | | Tracker reachability | `scripts/hooks/tracker-check.sh` | session start에서 tracker 접근성 경고 | | Inbox warning | `scripts/hooks/orch-inbox-warn.sh` | unread orchestration inbox item 표면화 | | Worker bypass warning | `scripts/hooks/worker-block-warn.sh` | supervised dispatch 우회 경고 | | Output/poll warning | `scripts/hooks/bash-output-trim-warn.sh`, `scripts/hooks/bash-poll-warn.sh` | Bash 출력과 poll 사용 경고 | Product path guard의 Bash fail-closed 측정 모드는 `MOGUI_PRODUCT_GUARD_FAIL_CLOSED=1`일 때 opt-in이다. 기본값은 off이며, 측정되지 않은 allowlist를 기본 policy로 쓰지 않는다. Multi-product workspace거나 primary product path가 확정되지 않았으면 guard wiring은 보류해야 한다. 이 템플릿의 hook/skill 구조는 파일과 저장소에 기반한 portable surface다. 특정 model provider, hosted connector, proprietary runtime을 전제로 하지 않는다. Host별 agent와 plugin ecosystem은 다를 수 있지만, manifest, placeholder, check/apply 계약은 파일 경로와 CLI exit code로 검증된다. ## `template-check` `local-master-ops:scripts/template-check`는 ops 설치본을 manifest 기준으로 검사한다. `--template`이 없으면 installed manifest만 보고, `--template`을 주면 현재 템플릿과 비교한다. ```console title="설치본 자체 검사" $ python3 scripts/template-check --ops "{{OPS_REPO}}" --json ``` ```console title="템플릿 clone과 비교" $ "{{RUNTIME_ROOT}}/master-ops/scripts/template-check" \ --ops "{{OPS_REPO}}" \ --template "{{RUNTIME_ROOT}}/master-ops" \ --json ``` Exit code 계약은 fail-closed다. | Exit code | 의미 | | --- | --- | | `0` | 검사했고 current 또는 drift 없음 | | `1` | 검사했고 drift, behind, absent required, unknown present, invalid path 중 하나가 있음 | | `2` | 입력을 검사할 수 없음. 예: malformed manifest, unreadable template version, unreadable changelog | Report set은 두 가지다. | `report_set` | 생성 조건 | 포함 정보 | | --- | --- | --- | | `install-manifest` | `--template` 없음 | `installed_version`, `manifest_status`, `absent_required`, `unknown_present`, `invalid_paths` | | `template-compare` | `--template` 있음 | install-manifest 필드 + `template_version`, `adoption_notes` | JSON report의 주요 field는 다음과 같다. | Field | 의미 | | --- | --- | | `ops_root` | 검사 대상 ops root | | `installed_version` | 설치 manifest의 `template_version`; manifest가 없으면 `null` | | `manifest_status` | `ok`, `absent`, `malformed` | | `absent_required` | manifest 또는 template manifest가 요구하지만 ops에 없는 경로 | | `unknown_present` | manifest가 주장하지 않고 instance-owned/template-side 예외도 아닌 경로 | | `invalid_paths` | symlink 등 regular file로 판정할 수 없는 경로 | | `template_version` | 비교 대상 템플릿 version | | `adoption_notes` | 설치 버전 이후 changelog section preview | | `questions_unanswered` | undecidable 또는 unreadable 원인 | `template-check`는 `.git/`과 `.beads/`를 unknown-path noise에서 제외한다. 그 외 local cache나 산출물이 ops tree 안에 있으면 manifest가 주장하지 않는 경로로 보고될 수 있다. ## `template-apply` `local-master-ops:scripts/template-apply`는 템플릿 manifest가 claim한 template-layer file만 ops 저장소에 적용한다. 항상 dry-run plan을 먼저 출력하며, write pass에는 confirmation phrase `apply`가 필요하다. 일반 사용자용 `--yes`는 없다. ```console $ "{{RUNTIME_ROOT}}/master-ops/scripts/template-apply" \ --ops "{{OPS_REPO}}" \ --template "{{RUNTIME_ROOT}}/master-ops" ``` 쓰기 pass는 같은 명령에 `--write`와 placeholder 값을 추가한다. ```console $ "{{RUNTIME_ROOT}}/master-ops/scripts/template-apply" \ --ops "{{OPS_REPO}}" \ --template "{{RUNTIME_ROOT}}/master-ops" \ --write \ --placeholder WORKSPACE_NAME="{{WORKSPACE_NAME}}" \ --placeholder WORKSPACE_ROOT="{{WORKSPACE_ROOT}}" \ --placeholder OPS_REPO="{{OPS_REPO}}" \ --placeholder MONITOR_NS="{{MONITOR_NS}}" \ --placeholder MODEL_ID="{{MODEL_ID}}" \ --placeholder REPO_LIST="{{REPO_LIST}}" \ --placeholder RUNTIME_ROOT="{{RUNTIME_ROOT}}" \ --placeholder TEMPLATE_VERSION="{{TEMPLATE_VERSION}}" ``` Per-file outcome은 다음 값 중 하나다. | Outcome | 의미 | | --- | --- | | `planned` | manifest가 claim한 template-layer path이며 dry-run에서 create 또는 overwrite 예정 | | `written` | write pass에서 atomic replace 완료 | | `skipped-as-instance-owned` | instance-owned path라서 이름으로 거절 | | `refused-not-in-manifest` | manifest가 claim하지 않는 path라서 거절 | | `error-invalid-path` | 절대 경로, path escape, symlink, directory target, root 밖 resolution 등 | | `error-missing-template-file` | manifest에는 있지만 템플릿 tree에 파일이 없음 | 쓰기 전 preflight는 모든 planned source와 destination을 다시 확인한다. Destination은 ops root 아래 regular file이어야 하며, symlink를 통과하거나 root 밖으로 resolve되면 쓰지 않는다. 실제 쓰기는 destination directory 안 temporary file을 만든 뒤 mode를 보존하고 atomic replace한다. Batch 중 OS error가 나면 앞선 파일은 이미 written일 수 있으므로 문제를 고친 뒤 재실행한다. ## Instance-owned refusals Template apply는 instance-owned record를 이름으로 거절한다. 이 경계는 `local-master-ops:scripts/template_common.py`에서 `template-check`와 `template-apply`가 공유한다. | Instance-owned path | 처리 | | --- | --- | | `docs/lineage/` | lineage record로 보존, apply 거절 | | `docs/runbooks/role-state.md` | role state SSOT로 보존, apply 거절 | | `.beads/` | tracker database/export로 보존, apply 거절 | | `config/` | local runtime config로 보존, apply 거절 | | `contracts/` | dispatch/worker contract로 보존, apply 거절 | | manifest가 claim하지 않는 모든 path | `refused-not-in-manifest` 또는 `unknown_present` | Upgrade는 local edits를 삭제하지 않는다. `unknown_present`는 남아 있는 local additions를 보여주는 보고 field이며, apply 대상 목록이 아니다. ## Founding, Reverify, Upgrade의 차이 | Mode | 진입 조건 | 쓰기 범위 | Spawn | | --- | --- | --- | --- | | Founding | 새 workspace, ops repository가 없거나 승인된 새 skeleton 생성 | manifest listed skeleton copy, placeholder fill, workspace card deploy, tracker/config/hook setup | Gen-1 master spawn | | Reverify | 이미 founded workspace와 master가 있음 | 기본 read-only. operating card lost reprint만 예외 | 금지 | | Upgrade | founded ops repository가 현재 템플릿보다 뒤처짐 | `template-apply`가 dry-run 후 확인받은 template-layer files만 write | 금지 | | Template improve | orchestrator repository 자체 문서/코드 변경 | 일반 개발 task로 처리 | 설치 flow 아님 | Existing ops repository나 lineage file이 보이면 Founding을 다시 실행하지 않는다. Template layer가 오래됐으면 Upgrade로 라우팅하고, master가 죽었거나 half-finished install이면 `docs/runbooks/succession-boot-card.md`가 소유한 succession/recovery 문제로 다룬다. ## 검증 표면 | 검증 | 명령 또는 판정 | | --- | --- | | Manifest 최신성 | `local-mogui-ade-orchestrator`에서 `python3 scripts/generate-manifest --check` | | 설치 shape | `python3 scripts/template-check --ops "{{OPS_REPO}}" --json` | | upstream currency | `template-check --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"` | | apply dry-run | `template-apply --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"` | | apply write | dry-run 확인 후 `--write`, confirmation phrase `apply` | | placeholder clean | `rg --hidden -g '!.git/**' -g '!.beads/**' '\{\{[^}]+\}\}' "{{OPS_REPO}}"`가 hit 없음 | | ops instruction pair | `cmp "{{OPS_REPO}}/CLAUDE.md" "{{OPS_REPO}}/AGENTS.md"` | | workspace card pair와 배포본 | canonical pair `cmp`, root 배포본과 canonical file `cmp` | | hook fire 관측 | `scripts/hook-coverage-report`, fire-log JSONL | ## 오류와 대응 | 증상 | 의미 | 대응 | | --- | --- | --- | | `manifest_status=absent` | pre-manifest install 또는 손상된 install | version을 추측하지 말고 content presence로 보고한 뒤 Upgrade 후보로 둔다 | | `manifest_status=malformed` | `MANIFEST.json` JSON 또는 shape가 깨짐 | exit 2로 실패. manifest를 복구한 뒤 재검사한다 | | `template VERSION unreadable` | `TEMPLATE-VERSION`을 읽을 수 없거나 UTF-8이 아님 | exit 2. 템플릿 clone 상태를 먼저 고친다 | | `unknown_present` 존재 | manifest가 claim하지 않는 local path | 삭제하지 않는다. local addition인지 cache인지 owner/master가 판정한다 | | `invalid_paths` 존재 | symlink 또는 regular file이 아닌 target | root escape와 symlink overwrite 위험을 제거한 뒤 재검사한다 | | `error-missing-template-file` | manifest와 template tree가 불일치 | 템플릿 manifest를 재생성하거나 missing file을 복구한다 | | confirmation declined | write pass 미승인 | 아무 파일도 쓰지 않고 중단한다 | | card drift | canonical pair 또는 root 배포본 불일치 | Reverify에서는 보고만 한다. 재배포는 별도 rescue task로 처리한다 | ## Related pages Founding, Reverify, Upgrade, Template improve의 진입 조건과 금지된 spawn 경로를 확인합니다. 새 workspace에서 skeleton copy, placeholder fill, card deploy, Gen-1 spawn까지의 설치 흐름을 봅니다. `scripts/` 명령, option, exit code와 테스트된 command surface를 확인합니다. `instance-runtime.json`, `workspace-descriptor.json`, model policy, 환경 변수 override를 확인합니다.