Engineering Handoff

엔지니어링 핸드오프 (Engineering Handoff)

FractalOps 시스템을 인계받거나, 한 번에 압축된 운영 관점을 잡고 싶을 때 이 문서부터 읽으세요.

이 문서는 제품 법(product law)을 다시 정의하지 않습니다. 먼저 헌법을 읽고, 그다음 이 페이지로 와서 “원칙(doctrine)“에서 “실행 제어(execution control)“로 넘어가세요.

읽는 순서 (Read Order)

FractalOps Constitution — 제품 법
FractalOps Canonical Architecture — 정규 아키텍처
Architecture Overview — 개요
FractalOps C4 Model — 현재 시스템·배포 경계

제품 앵커 (Product Anchor)

FractalOps는 조직의 메타 컨트롤 플레인(meta-control plane) 입니다.

안정적인 제품 경로는 다음과 같습니다.

조직 메타 컨트롤 플레인 -> 온보딩 -> 작업 -> 제안(proposal) -> 증명(proof) -> 반성적 개선

이 저장소의 모든 것은 경쟁하는 별도의 제어 표면을 발명하는 대신, 이 경로를 강화해야 합니다.

진실 평면과 실행 평면 (Truth and Execution Planes)

플레인이 많아서 헷갈리기 쉽습니다. 아래 다이어그램이 “누가 무엇의 진실을 소유하는가”를 한눈에 보여줍니다. 새 제어 로직을 추가하기 전에 항상 이 경계를 먼저 확인하세요.

flowchart TB
  Portal["Portal\n(사람 워크플로 표면)"]
  subgraph runtime["FractalOps 소유 런타임"]
    api["api / worker / execution-runtime"]
    studio["Studio\n(run/session/report/activity 진실)"]
  end
  subgraph engines["전용 엔진 (레인을 지킨다)"]
    temporal["Temporal\n(durable 잡 스케줄/재시도)"]
    daytona["Daytona\n(workspace/toolbox)"]
    gitops["CUE/Helm GitOps\n(인프라 desired-state 화해)"]
  end
  subgraph truth["진실/증명 평면"]
    proposal["Proposal Plane\n(유일한 non-read 변경 게이트)"]
    semantics["Semantics / DataHub\n(온톨로지·계보 그래프 진실)"]
    warehouse["ClickHouse warehouse\n(웨어하우스 사실/증명)"]
    chronicle["Chronicle evidence\n(장기 증명·출처)"]
    openbao["OpenBao\n(시크릿 진실 소스)"]
  end
  Portal --> api
  api --> proposal
  proposal --> temporal
  temporal --> studio
  studio --> daytona
  api --> semantics
  api --> warehouse
  api --> chronicle
  api -. 시크릿 조회 .-> openbao
  gitops -. desired state .-> runtime

핵심 소유권:

Portal — 주요 사람 워크플로 표면.
api / worker / execution-runtime — FractalOps 소유 런타임 컴포넌트.
Proposal Plane — 유일하게 허용된 non-read 변경 게이트.
Semantics — 온톨로지·계보·그래프 진실. DataHub는 프로젝트 RDF 스튜어드 에이전트가 채우는 카탈로그/계보 누적 평면이며, 신원·SCIM/JIT·변경·증명 권위가 아닙니다.
ClickHouse warehouse — 동일한 스튜어드 라이프사이클을 쿼리 가능한 이벤트/사실로 저장하는 웨어하우스 사실/증명 평면.
PostHog / OpenTelemetry — 분산 제품/런타임 이벤트 소스. ClickHouse 누적 전에 글로벌 온톨로지 id로 분류합니다.
GlitchTip — Sentry 호환 에러/성능 추적 평면. 프로젝트별 DSN을 project_factory가 자동 발급하고, 공개 ingest이며, 공식 MCP가 armory에 등록됩니다. 메트릭/온톨로지/증명 권위는 아닙니다.
Chronicle evidence — 장기 증명과 출처.
OpenBao — 시크릿 진실 소스.
CUE/Helm GitOps — 네임스페이스 정책, 리소스 제한, 배치, 스토리지, 런타임 메타데이터의 인프라 화해 권위. durable 잡 러너도, 에이전트 그래프 상태도, 워크스페이스 파일 동기화도 아닙니다.
Temporal — durable 잡 스케줄링·재시도·액티비티 실행·반복 스케줄. 에이전트 그래프 상태나 세션 진실이 아닙니다.
Studio — run/session/report/mailbox 상태와 next action의 공유 실행 경계.
Daytona — project workspace와 toolbox 제공자. lifecycle 권위가 아닙니다.
AgentSquad — Studio 위에서 도는 FractalOps 자기개선 워크플로. FractalOps에만 보고합니다.
Armory — 에이전트 초기화를 위한 MCP/tool-pack 구성 경계.

정규 실행 자산 모델 (Canonical Execution Asset Model)

runtime 명사를 또 추가하기 전에 Execution Naming Glossary를 먼저 보세요. 플랫폼/API 제어 명사는 operation asset이며, AgentSquad 산문에서는 execution surface, execution workspace, agent process adapter, deploy image를 선호합니다.

operation asset — asset_id 또는 role로 선택되는 타입화된 머신 표면.
operation asset control — 명령 실행과 HTTP 제어를 위해 유일하게 허용된 애플리케이션 계층 컨트랙트.
public URL — 사람이 보는 라우트. 브라우저-안전, 보통 엣지 보호.
executor URL — 머신이 보는 제어 경로. 보통 내부 또는 origin-only.

최근 SSOT 경계:

runtime_ssot — 공유 public/internal/local 런타임 URL 기본값.
principal_defaults — 공유 CLI/시스템/감사 principal 기본값.
internal/local URL SSOT — SSOT 계층을 확장하는 경우가 아니라면 새 코드에 raw 127.0.0.1, raw 클러스터 서비스 URL, 일회성 local override URL을 다시 박지 마세요.

현재 1급 operation asset 종류:

lxc
kubernetes

FractalOps 코드는 raw vmid, raw namespace, provider 키워드 휴리스틱, connector-local 노드 매핑을 정규 의미로 취급하면 안 됩니다.

실행 기반 vs 통합 엔드포인트 (Execution Substrate vs Integration Endpoints)

새 제어 로직을 추가하기 전에 이 구분을 먼저 적용하세요.

flowchart LR
  subgraph owned["강하게 소유한 실행 기반\n(runtime-asset control 사용)"]
    portal2["portal / api / worker / execution-runtime"]
    temporal2["Temporal"]
    db2["CNPG-backed Supabase Core / Storage / Realtime"]
    dy["Daytona"]
    pg["PlaywrightGrid"]
  end
  subgraph integ["평범한 통합 엔드포인트\n(URL/auth/readiness만 필요)"]
    nexus2["Nexus"]
    penpot["Penpot"]
    dokploy["Dokploy"]
    headlamp["Headlamp"]
    conn["많은 connector 타깃"]
  end

규칙:

FractalOps가 URL·auth·readiness만 필요하면 그 시스템은 통합 엔드포인트로 취급한다.
FractalOps가 머신 실행 경계를 진짜로 소유할 때만 runtime-asset control을 쓴다.

운영자 진입점 (Operator Entry Points)

먼저 이 진입점들을 사용하세요. 전부 실제 CLI/make 타깃입니다.

Operation Assets

fractalops operation-assets list
fractalops operation-assets show --role daytona_runtime
fractalops operation-assets check --asset-id <asset-id>
fractalops operation-assets run --role daytona_runtime -- python -V
fractalops operation-assets request --role langboard_executor --method GET --path /health

list는 토폴로지에 정의된 모든 operation asset을 보여줍니다.
check는 선택한 asset의 readiness를 검사합니다(HTTP/SSH).
run은 머신 위에서 명령을 실행하고, request는 executor URL에 HTTP 호출을 보냅니다.

Assembly SSOT

pnpm verify
pnpm docs:check

platform/k8s/environments/<env>/runtime.cue가 환경별 런타임 원본입니다. platform/k8s/cue-generate.sh가 Helm values와 runtime contract를 투영하며, pnpm verify가 생성 drift와 GitOps 경계를 함께 검사합니다.

LangBoard 프로젝션과 동기화

fractalops projects langboard-projection --project-slug <slug> --admin --subject-key <subject>
fractalops projects langboard-sync-plan --project-slug <slug> --admin --subject-key <subject>
fractalops projects langboard-sync --project-slug <slug> --admin --subject-key <subject> --mode scim
fractalops projects langboard-sync --project-slug <slug> --admin --subject-key <subject> --mode access
fractalops projects langboard-sync --project-slug <slug> --admin --subject-key <subject> --mode surface

langboard-sync-plan으로 먼저 무엇이 바뀔지 본 다음, --mode를 지정해 실제 동기화를 실행하세요.

LangBoard 포지션 (LangBoard Position)

LangBoard는 회사 소유 1급 솔루션이지만, 진실 소유자가 아니라 확장 표면(extension surface) 입니다.

정규 역할:

LangBoard 라이프사이클 표면
지식 위키 표면
봇 자동화 표면

비정규 역할:

신원 진실 소유자
제안 권위
증명 권위

실무 규칙:

FractalOps는 프로젝션·계보·증명 링크를 소유한다.
LangBoard는 프로젝트-네이티브 보드·위키·접근·봇 실행 동작을 소유한다.
머신 제어는 공개 Cloudflare 경로가 아니라 executor URL을 쓴다.

작업 규칙 (Working Rules)

소유한 머신 실행은 RuntimeAssetControlService를 거쳐야 한다.
평범한 엔드포인트 통합은 타입화된 URL/auth 컨트랙트와 foundation HTTP 클라이언트를 선호한다.
비즈니스 작업은 host shell, raw Kubernetes CLI, urllib를 직접 호출하면 안 된다.
동기 아웃바운드 HTTP는 runtime-asset control이 머신 경계를 소유하지 않는 한 foundation HttpClient를 쓴다.
로컬 프로세스 캡처/스폰은 ad-hoc subprocess.run/Popen이 아니라 fractalops.foundation.process_exec를 거친다.
토폴로지는 타입화된 operation asset으로 표현될 때만 권위를 가진다.
오케스트레이션 엔진은 레인을 지킨다:
- CUE/Helm GitOps: 인프라 desired-state 화해만
- Temporal: durable 잡만
- Studio: run/session/mailbox/control 진실만
- Agent Execution: provider policy와 process adapter 경계만
- 운영자 CLI: 라이브 관찰/복구 드라이버만
- 플랫폼 CI 이미지 빌드: GitOps-pinned 런타임 이미지 릴리스만 (프로젝트별 또는 in-sandbox 빌드 평면 없음)
셸 스크립트는 래퍼/어댑터이지 원칙(doctrine)이 아니다.
public URL, executor URL, local/internal URL은 엣지 보호나 브라우저 라우팅이 머신 제어를 오염시킬 수 있을 때 분리되어야 한다.
라이브 운영자/미니맵 진실은 portal_live_events -> harness-projection이다.
AgentSquad 공개 연속성은 fresh | resume이다.
프로젝트 에이전트 스쿼드와 AgentSquad는 Studio 프리미티브를 공유하지만 보고 대상이 다르다: 프로젝트 스쿼드는 바인딩된 프로젝트 이슈 표면에, AgentSquad는 FractalOps에 보고한다.
Armory 구성은 prompt-only 관례가 아니라 런타임/도구 초기화여야 한다.
관리되는 README 블록은 손으로 복사하지 말고 .agent-os/config/managed-blocks.tsv에서 todo 스킬 스크립트를 통해 동기화한다.

아직 못생겨도 되는 곳 (What Is Still Allowed To Be Ugly)

다음 영역은 아직 구현 세부이며, 애플리케이션 컨트랙트가 깨끗하다면 어댑터-특화 transport 코드를 유지해도 됩니다.

platform/k8s/* 래퍼 스크립트
ops/lxc/* 유틸리티 스크립트
runtime-asset control 어댑터 내부의 컨트롤러 내부

다음 영역은 후퇴(regress)가 허용되지 않습니다.

backend/src/fractalops/application/*/features
backend/src/fractalops/interfaces/cli
portal API/read-model 네이밍
토폴로지 env 생성 컨트랙트

남은 어댑터 심(seam) — 다음 리팩터 큐

저장소는 이제 더 깨끗하지만, 일부 파일은 여전히 transport-heavy 구현 세부를 담고 있어 정규 설계 예시가 아니라 다음 리팩터 큐로 다뤄야 합니다.

backend/src/fractalops/application/access/features/runtime_asset_control/ — typed operation asset locator를 소유한다. retired guest-exec 우회 경로는 복원하지 않는다.
backend/src/fractalops/application/access/features/native_operations/native_operations.py — 얇은 operation registry다. provider transport를 다시 넣지 않는다.
backend/src/fractalops/platform/composition/connector_executors.py — Keycloak 등 provider 조립 경계다.
Backend domain/agent_execution/features/, application/agent_execution/features/, adapters/agent_execution/features/, interfaces/http/agent_execution/features/ — provider-neutral Agent Execution의 유일한 재사용 경계다.
backend/src/fractalops/application/access/features/studio_runner/ — 브라우저 executor probe는 공식 MCP Python SDK 경계를 사용한다. JSON-RPC initialize/tools/list를 손으로 쓰지 않는다.
backend/src/fractalops/application/access/features/studio/scenario_policy.py — 작은 직접 subprocess 심이 남아 있다.

핸드오프 체크리스트 (Handoff Checklist)

다음 엔지니어에게 넘기기 전에 확인하세요.

요청된 흐름이 stack-local 은어가 아니라 정규 용어로 명명되었는가.
실행 표면이 operation asset asset_id 또는 role로 선택되었는가.
시크릿이 lab-local override 파일이 아니라 OpenBao 또는 명시적 env overlay에서 오는가.
public URL과 executor URL이 섞이지 않았는가.
LangBoard 변경이 (a) 일반 upstream-safe 제품 동작과 (b) FractalOps-특화 프로젝션/동기화 로직으로 분리되었는가.
새 문서가 평행 원칙을 만들지 않고 헌법/정규 아키텍처로 다시 라우팅되는가.

빠른 검증 (Fast Validation)

make test-unit         # 조용한 fail-only unittest_runner
make test-contract     # 큐레이트된 Schemathesis 컨트랙트 스위트
make test-integration  # 공유 런타임 스모크만
make codegen-check     # 생성된 아티팩트 drift 검사
git diff --check       # 공백/충돌 마커 검사

Portal 검사는 yamonco/fractalops-frontend에 있습니다.

pnpm run lint:frontend:ci
pnpm run portal:check
pnpm run portal:build

검증 정책:

test-unit은 조용한 fail-only unittest_runner를 쓴다.
test-contract는 큐레이트된 Schemathesis 컨트랙트 스위트를 쓴다.
test-integration은 공유 런타임 스모크만 쓴다.
공유 서비스 5xx는 로컬 Docker 우회 경로로 처리하지 말고 skip + report로 기록한다.

Backend 집중 검증:

cd backend
uv run --frozen --group test pytest -q \
  backend/src/fractalops/<layer>/<context>/features/<outcome>/*_test.py

문서 사이트 운영 — docs.monstore.io (Docs Site Runbook)

Starlight 문서는 Kubernetes에서 서빙합니다. 이미지는 호스트에서 만들지 않습니다. Documentation Release workflow가 Assembly 소스를 Kubernetes BuildKit으로 한 번 빌드하고, GHCR digest와 source commit을 image-pin.json에 기록하는 automation PR을 엽니다. Assembly CI 통과 후 자동 병합되며 Argo CD가 exact digest를 배포합니다.

flowchart LR
  edit["apps/docs 변경"] --> ci["Assembly CI\nStarlight build"]
  ci --> build["Kubernetes BuildKit\nOCI build + push"]
  build --> pin["automation PR\ndigest + source revision"]
  pin --> argo["Argo CD sync"]
  argo --> serve["docs.monstore.io"]

구성 요소

네임스페이스: fractalops-docs
Deployment: deploy/docs; platform/k8s/apps/fractalops-docs/image-pin.json의 exact digest 사용.
Service/Ingress: docs Service(80), docs-edge Ingress가 docs.monstore.io를 Traefik websecure 엔트리포인트 + cloudflare DNS-01 인증서로 노출.
GHCR pull 자격증명: ExternalSecret ghcr-pull; ESO가 OpenBao reference를 동기화.
Argo Application: fractalops-docs (project edge-delivery)가 platform/k8s/apps/fractalops-docs를 main에서 동기화(automated prune + selfHeal).

재발행 (republish)

apps/docs/** 변경을 main에 병합하면 release가 자동 시작됩니다. 수동 재실행은 GitHub Actions의 Documentation Release workflow dispatch를 사용합니다. 로컬 docker build, mutable tag 덮어쓰기, 수동 rollout restart는 배포 경로가 아닙니다.

로컬 검증:

pnpm docs:build
pnpm test:docs-release

배포 검증:

curl -sS -o /dev/null -w '%{http_code}\n' https://docs.monstore.io/   # 200 기대
pnpm assembly:kubectl -- -n fractalops-docs get deploy/docs
pnpm assembly:kubectl -- -n fractalops-docs get pod -l app=docs \
  -o jsonpath='{.items[0].status.containerStatuses[0].imageID}{"\n"}'

롤백은 image-pin.json을 이전 검증 digest와 source revision으로 되돌리는 PR입니다. 새 이미지를 다시 빌드하지 않습니다.