요구사항 — enode 기능 다섯

이 문서는 requirements/ 여섯 문서를 대체하지 않는다. 값은 거기 있고
어긋나면 enode-design/protocol/INVARIANTS.md 가 이긴다 (canon.md).

여기 있는 것은 넷이다.

   1절 ~ 2절    의도 분석과 입력.  무엇을 받았고 어떻게 읽었나
   3절          확인 질문 첫 묶음의 답.  decisions.md 에 행으로 올라갈 값이다
   4절 ~ 7절    기능 요구사항의 추적표 · 비기능 요구사항 · 수용 기준 · 안 하는 것
   8절          화면 대조.  design/ 을 실제로 열고 나온 것과 둘째 묶음의 답 (8.4)

1. 의도 분석

1.1 가치의 고정점

scene-gates.md §1 의 dhseo 장면이다. 완결성은 그 장면이 끝까지 도는가로
판단한다. 기능 넷을 각각 완성하는 것이 목표가 아니라 넷이 한 장면을
만드는 것이 목표다. 그래서 수용 기준이 유닛 완료가 아니라 조각 게이트다 (6절).

2. 입력

2.1 코드에서 확인한 것 — 요구사항을 줄인 자리

기준선을 다시 훑지 않고, 계약이 이미 참인지만 대조했다. 둘이 요구사항을
줄였다.

   store.Cancel 이 이미 verdict 를 쓴다
       reap.go:170.  verdict{state:FAILED, checks:[{what:"cancelled",
       ok:false, note:"cancelled by: <by>"}]} 를 쓰고 sealRecord 까지 부른다.
       at-boundary 가 놓은 Run 을 Cancel(ctx, run, "drain:<node_id>") 로 닫으면
       decisions.md 2절의 「verdict 가 drain 취소와 진짜 실패를 가른다」가
       새 열도 새 필드도 없이 참이 된다.  GET /v1/runs 가 verdict 를 내면 끝이다

   runctl 은 고칠 것이 없다
       internal/runctl/client.go 의 do 가 StatusCode/100 == 2 로 받으므로 202 가
       통과한다.  cmd/runctl/main.go 는 r.State 를 그대로 찍고, Terminal(state) 은
       SUCCEEDED 와 FAILED 뿐이라 --wait 도 QUEUED 에서 계속 폴링한다.
       ⇒ CP2 의 「runctl status 가 QUEUED 를 표시한다」가 코드 변경 0 으로 닫힌다.
       unit-boundaries.md §2 의 파일 행렬에 runctl 이 없는 것은 누락이 아니다

또 하나 — internal/store/store.go 가 이미 internal/match 를 임포트한다
(match.Reject). 그래서 store.WakeQueued 가 match.Match 를 부를 수 있고
임포트 순환이 없다. 매처는 여전히 한 벌이다 (ADR-014 결정 3).

3. 확인 질문 첫 묶음의 답 — decisions.md 에 올릴 값

사용자 답 A · A · A (2026-09-04). 이 셋은 decisions.md 2절에 행으로
올라간다. 아래가 그 행의 내용이다.

둘째 묶음은 8.4절에 있다. 그림을 열고 나온 셋이고 같은 날 같은 형식으로
닫혔다 — 두 묶음을 한 절에 합치지 않은 것은 나온 경로가 다르기 때문이다.
이 절은 decisions.md 를 읽고 나온 것이고 8.4절은 design/ 을 열고 나왔다.

3.1 QUEUED Run 의 steps 는 제출 시점에 만든다

GET /v1/runs/{id} 가 QUEUED Run 에 내는 것 — state: "QUEUED" ·
steps[] 전부 PENDING 이고 node 가 빈 값 · assigned 없음 · reject 없음.

3.2 WakeQueued 는 도착 순서로 전부 훑는다

3.3 SECURITY-04 는 네 헤더를 걸고 HSTS 는 N/A 다

4. 기능 요구사항 — 추적표

절 번호는 enode-features.md 의 것이다. 이 표가 요구사항과 유닛과 게이트를
잇는다. 유닛은 Units Generation 이 확정하고, 여기서는 unit-boundaries.md
의 권장을 그대로 딛는다.

4.1 확정된 계약 — 접점에서 갈리면 안 되는 것

unit-boundaries.md §4 의 접점 표에 3절의 답을 얹은 것이다. Functional
Design 이 내부를 다듬을 수 있으나 아래 모양은 못 바꾼다 — 유닛 둘 이상이
읽기 때문이다.

   contract.Policy{Drain string}          "" | "graceful" | "at-boundary".  문자열 그대로
   store.DrainingNodes(ctx)               map[string]bool.  match.Match 의 busy 와 같은 모양
   store.WakeQueued(ctx) error            도착 순서로 전부.  재진입 · 동시 호출 안전
   store.UpsertAdvert(...) 의 반환         이전 정책을 돌려준다.  해제 감지가 이 값을 읽는다
   store.ListNodes · store.ListRuns       decisions.md 2절의 응답 모양을 그대로 낸다
   GET /v1/runs 의 행                      decisions.md 2절 + current[] + reject (8.4절 ①)
   current[]                              [{node, step, attempt, started_at}].  CLAIMED 마다 하나
   reject                                 {code, as, reason}.  match.Reject 에 태그를 단다
   GET /v1/nodes 노드 항목                 ADR-065 모양 + draining
   GET /api/status 의 observed · stale     8.4절 ③.  캐시가 비면 observed 를 안 내고 stale 이 true
   광고 응답의 정책 왕복                    advertResponse 에 policy 를 더한다 (4.2절)
   policy.Read(path) · policy.Write(path, Policy)   U-drain 이 정본.  제어판은 파서를 안 만든다
   enodectl serve 의 라우트                4.3절.  전부 ?node=<name> 을 받는다
   MCP 도구 이름 일곱                      decisions.md 5.3.  Claude 설정에 박히면 못 바꾼다
   runctl.Client.Nodes · .Runs            GET /v1/nodes · GET /v1/runs 를 그대로 낸다

MCP 도구 이름이 계약인 이유 — 사용자의 Claude 설정과 대화에 그 글자가
박힌다. 라우트 이름을 바꾸는 것과 같은 무게이고, 그래서 Functional Design 이
내부는 다듬어도 일곱 이름은 못 바꾼다.

4.2 광고 응답의 정책 왕복 — 권장값을 벗어난 자리

unit-boundaries.md §4 는 이 접점의 모양을 안 정했다. advertResponse 에
policy 를 더한다 — GET /v1/nodes 의 납작한 draining 과 이름을 달리 한다.

근거 — 광고 요청이 올려보낸 것과 같은 객체를 그대로 되돌리는 왕복이다.
같은 것에 이름을 둘로 두면 어느 쪽이 정본인지가 갈린다. GET /v1/nodes 쪽은
관측이고 ADR-065 가 납작한 필드로 응답을 짜 뒀으므로 거기서는 draining 이
맞다. 데몬은 policy.drain 만 읽는다.

왜 왕복이 필요한가 — 데몬이 파일을 직접 읽었는데도 응답의 값을 쓰는 이유는
Worker 가 Mediator 가 확인한 값으로 움직여야 하기 때문이다. 그렇지 않으면
노드는 at-boundary 로 임대를 놓았는데 중앙은 아직 후보로 알고 있는 창이
생긴다. 그 창을 없애는 것이 이 왕복이다 (enode-features.md 3.2.2 「데몬은
응답의 값을 Worker 에 넘긴다」).

4.3 제어판 라우트 — 권장값을 넘긴 자리

unit-boundaries.md §4 는 /api/status · /api/policy · 정적 / 셋을
시작값으로 뒀다. 그 셋으로는 FR-18(프로세스 제어)이 안 닫힌다. Units
Generation 이 확정한다고 같은 절이 적었으므로 여기서 늘린다. 8.4절 ② 의 답
A 가 여기에 ?node= 와 /api/nodes 를 더했다.

   GET  /                     정적 파일.  S3 · S5
   GET  /api/nodes            이 기계의 노드 목록.  사이드바가 읽는다 (8.4절 ②)
   GET  /api/status?node=     신원 · 프로세스 살았나 · 탐지 능력 · 현재 작업
                              · Mediator 마지막 응답 시각 · observed · stale
   GET  /api/policy?node=     현재 정책
   PUT  /api/policy?node=     정책 쓰기.  drain 걸기와 풀기.  모드 바꾸기는 못 한다 (아래)
   POST /api/start?node=      데몬 띄우기
   POST /api/stop?node=       데몬 멈추기
   GET  /api/logs?node=       로그 꼬리

?node= 는 이 기계의 노드 이름이다. 생략하면 names() 의 첫째이고,
names() 에 없는 이름이면 404 다. 노드가 하나뿐인 기계에서는 붙일 일이 없다.
/api/nodes 가 하나 는 것은 사이드바가 목록을 어디선가 받아야 하기 때문이다 —
/api/status 에 목록을 얹으면 노드마다 부르는 라우트가 전체 목록을 매번 나른다.

PUT /api/policy 하나로 걸기와 풀기를 받는다 — 정책은 상태이지 명령이 아니고,
명령으로 쪼개면 「지금 무엇이 걸려 있나」가 라우트 셋에 흩어진다.
GET /api/status 가 종합이라 화면이 폴링 하나로 돈다.

모드 바꾸기는 받지 않는다. 이 절의 1판은 「걸기 · 모드 바꾸기 · 풀기가
전부 이것 하나」였고 그것이 틀렸다. C3 컴포넌트의 각주가 「걸 때 고른
모드(graceful · at-boundary)는 풀기 전까지 바뀌지 않는다」이고 C3 에
모드 라디오가 없다 (§8.5). 그래서 전이는 둘뿐이다.

   ""            -> graceful | at-boundary      받는다
   graceful | at-boundary -> ""                 받는다.  언제나
   graceful <-> at-boundary                     409.  먼저 풀어라

정본은 여전히 노드의 파일이므로 소유자가 파일을 직접 고쳐 모드를 갈아치울 수
있다 — 라우트가 막는 것은 화면에서 오는 길뿐이다. 그것으로 충분하다:
막는 이유가 안전이 아니라 「되찾았다」의 뜻을 지키는 것이기 때문이다.
at-boundary 를 graceful 로 바꾸면 이미 놓인 임대가 안 돌아오고, 반대로
바꾸면 도는 Run 이 예고 없이 경계에서 죽는다.

5. 비기능 요구사항

5.1 보안 — 새 표면에만 건다

security-baseline 이 켜져 있다. decisions.md 3절이 규칙마다 취급을 미리
적었고, 여기에 3.3 절이 SECURITY-04 를 더했다. 기존 코드의 사실은 기록만
하고 고치지 않는다.

limit 상한 — 새로 정하는 값

decisions.md 2절이 기본 100 만 정했고 상한은 안 정했다. SECURITY-05 가
명시적 상한을 요구하므로 여기서 정한다 — 상한 1000, 넘으면 1000 으로
자른다. 기본의 열 배이고, 이틀 안에 그만큼 쌓이지 않으며, 페이지네이션이
없는 것과 모순되지 않는다 (limit 이 유일한 손잡이다).

하지 말 것

   TLS 를 넣는 것                          constraints.md §6
   cmd/mediator · internal/config 를 보안 이유로 고치는 것   constraints.md §6.  유닛 경계 밖
   bootstrapToken 의 stderr 토큰 출력을 고치는 것             decisions.md 3절 SECURITY-03
   Mediator Listen :8080 을 좁히는 것                        decisions.md 3절 SECURITY-07
   sslmode=disable 을 고치는 것                              decisions.md 3절 SECURITY-01

5.2 불변식 — 건드리면 안 되는 것

5.3 패키지 경계

5.4 관측과 갱신

5.5 품질 게이트

5.6 성능

상한을 두지 않는 것이 결정이다. 근거는 decisions.md 1절.

   대기 상한            없다.  QUEUED 는 무기한.  빠져나가는 길은 cancel 뿐
   at-boundary 지연 상한  없다.  도는 단계의 남은 시간 + 광고 주기가 곧 값
   페이지네이션          없다.  limit 뿐
   노드 수              여섯 규모.  LISTEN/NOTIFY 는 ADR-015 가 적어둔 나중의 최적화다

6. 수용 기준

scene-gates.md 가 정본이다. 조각마다 실행 명령이 있고, 조각이 초록이
아니면 다음 유닛에 들어가지 않는다. 집행자는 그 유닛을 구현하지 않은 사람이다.

6.1 화면 검증은 API 검증과 따로 적는다

API 어휘(「임대가 풀린다」)는 화면 없이도 초록이 된다. 그래서 화면이 있는
유닛의 완료 조건은 그 화면의 버튼을 전부 나열한다. 「누르면 걸린다」만으로는
「풀기」가 빠진 채 통과된다 (scene-gates.md §2.1 · design/README.md §7).

Units Generation 이 유닛마다 그 목록을 낸다.

6.2 게이트가 그 유닛 밖의 이유로 빨간 경우

진행자가 사실을 aidlc-docs/audit.md 에 적고 조각을 보류로 표시한 뒤
넘어간다. 보류는 통과가 아니다 — CP4 전에 전부 초록이어야 한다
(scene-gates.md §4).

7. 범위 밖

constraints.md 여덟 범주와 decisions.md 4절 이월이 정본이다. 요약만 둔다.

   실행 중 선점 · FIFO 외의 공정성 정책 · 격리 강화 · 중앙에서의 소유권 판정
   SSE · WebSocket · 트랜스크립트 (S4 는 자리만)
   대시보드 인증 · TLS · 리버스 프록시 · 다중 Mediator · 페이지네이션
   기존 계약 변경 (success_when 문법 · 봉인 규칙 · 임대 키 · READY · 중앙 drain 라우트)
   역할 주입 · 우선순위 · 별칭 · 메모
   트랜스크립트 구독 (MCP 는 범위 안이지만 구독 표현은 여전히 이월이다)

Mediator MCP 가 이 목록에서 빠졌다 (2026-09-05). CP2 가 닫힌 뒤 진행자가
이월을 되돌렸고 근거는 decisions.md 5절이다 — 이월의 이유가 결합이 아니라
값 둘(전송 · 토큰 전달)이었고 5.2 가 그 둘을 닫았다. 유닛 U-MCP · 게이트 CP5
로 들어왔고 FR-26 ~ FR-29 가 그것이다.

7.1 정본 쪽 선행 조건 — 이 저장소의 일이 아니다

canon.md §3 이 셋을 적었다. enode-design 의 PR 이고 이 저장소가 하지
않는다. 다만 이 팩은 개정된 문장을 따른다.

   ADR-065 개정      GET /v1/nodes 에 draining 필드를 더한다
   ADR-063 개정      §2.1 을 graceful 한정으로 하고 at-boundary 를 갈라 적는다
   ADR-063 · 064     초안을 결정으로 올린다.  decisions.md 가 미결에 값을 줬다

ADR-065 는 「구현됨」이라고 적혀 있으나 1c290a6 에 GET /v1/nodes 가 없다
(canon.md §2). v1 은 1c290a6 만 본다 — U-관측API 는 ADR-065 §2 의
응답 모양에서 새로 만든다.

8. 화면 대조 — design/ 을 실제로 열고 나온 것

Workflow Planning 까지 이 절이 비어 있었다. 읽은 것은 design/README.md
(그리는 규칙)뿐이었고 그림 자체를 안 봤다. 사용자 지적으로 열었다.

   pencil MCP       안 붙는다.  failed to connect to running Pencil app: code-server
                    MCP 는 실행 중인 앱에 붙는 통로다.  이 작업에는 필요 없었다
   @pen.dev/cli     0.3.6.  pen login 뒤 헤드리스로 .pen 을 직접 연다 —
                    pen interactive --in design/enode-ux.pen --out <스크래치패드>
                    save() 를 안 부르고 --out 을 저장소 밖에 뒀다.  원본 무변경
   PNG 로 읽은 것     design/exports/*.png 일곱 — S0 · S0b · S1 · S1b · S2 · S3 · S5
                    C1 · C2 는 S1 안에 인스턴스로 들어 있어 같이 봤다
   .pen 으로 읽은 것  C3 · C4 · C5.  export 가 없어 원본을 열어야 보였다 (8.5절)
                    S1 · S1b · S2 의 배지와 필터 글자를 원본에서 대조했다 (8.6절)
   안 읽어도 되는 것   S4.  범위 밖이고 자리만이다 (constraints.md §5)

그림은 장식이 아니었다. decisions.md 와 ADR-065 가 정한 응답 모양으로는
못 그리는 자리가 셋 있다 — 8.3 절.

8.1 확인된 것 — 문서가 맞았다

design/README.md §4.1 은 「중앙 카드는 label 만. principal 을 내지 않는다」
인데 S1 카드 제목이 taeels@thinkpad:ws-a 라 언뜻 principal@host:label 로
보인다. 아니다. internal/enode/identity.go 의 deriveLabel 이
local@host:configbase 를 만든다 — 그 문자열 전체가 label 이다. S3 의 신원
블록이 principal: taeels@corp 과 label: taeels@thinkpad:ws-a 를 따로
보이며 「principal 은 이 화면에만 있다」고 못 박아 뒀다. ADR-065 를
안 어긴다.

node_id 도 맞다 — 화면의 a3f19c2b8e04 는 12 자이고 deriveFrom 이
hex[:12] 를 쓴다. 자르는 것이 아니라 그것이 전부다.

8.2 근거를 적고 닫은 것 — 묻지 않는다

8.3 화면의 버튼 전부 — 유닛 완료 조건의 재료

scene-gates.md §2.1 과 design/README.md §7 이 「화면이 있는 유닛의 완료
조건은 그 화면의 버튼을 전부 나열한다」고 요구한다. Units Generation 이 이
목록을 쓴다.

   S0    토큰 표시 · 숨김 토글 (눈 아이콘)
         현황판 열기
   S0b   같은 둘.  입력 테두리가 붉고 그 아래 「401 — Mediator 가 이 토큰을
         받지 않았다」 가 인라인으로 붙는다.  버튼은 그대로 산다

   S1    필터 칩 다섯 — 전체 · RUNNING · QUEUED · SUCCEEDED · FAILED
         Run 행의 열기 (>)  -> S2
         (카드에는 조작이 없다.  중앙은 읽기 전용이다)

   S2    닫기 (X)  -> S1
         단계 노드 고르기 -> 오른쪽 상세
         「함대 격자의 이 노드로」 (->)  -> S1 의 그 카드

   S3    사이드바의 노드 고르기
         「로그」 · 「재시작」 · 「정지」                 (헤더 셋.  프레임 이름 Btn 로그 · Btn 재시작 · Btn 정지)
         graceful (라디오) · at-boundary (라디오)
         「drain 걸기」
         [건 뒤 = C3]  「drain 풀기 · 함대로 돌려주기」   <- 이것이 빠지면 통과가 아니다
                       모드 배지 (graceful | at-boundary).  라디오는 사라진다
         트랜스크립트 (->)                          자리만 · 비활성

   S5    사이드바의 노드 고르기
         「마지막 로그」                              (헤더 하나.  로그·재시작·정지가 아니다)
         「시작」
         (drain 블록 없음)

8.4 그림이 연 계약 구멍 셋 — 답으로 닫았다

사용자 답 A · A · A (2026-09-04). 질문 전문은
design-verification-questions.md 에 그대로 남아 있다. 셋 다 decisions.md 도
ADR-065 도 답을 갖고 있지 않던 자리이고, 셋 다 결정표 2절의 권장값을 넘긴
자리라 근거를 적는다 — 그것이 결정표의 게이트 규칙이다.

① Run 행과 S1 카드의 「지금 무슨 단계」 — GET /v1/runs 를 넓힌다

② enodectl serve 의 범위 — 이 기계의 노드를 전부 서브한다

③ 멈춘 노드의 「마지막 관측」 — 제어판이 메모리에 든다

답 A 가 덜 정한 자리 셋 — 셋도 닫혔다

값으로 굳히면서 코드와 대조했더니 답 자체는 맞는데 모양이 하나로 안 정해지는
자리가 셋 남았다. 유닛 둘 이상이 읽는 접점이라 unit-of-work-plan.md §1 이
물었고 사용자 답 A · A · A (2026-09-04) 로 닫혔다.

①-b 는 constraints.md §7 을 넘지 않는다. 그 절의 목록은 success_when
문법 · 봉인 규칙 · 임대 키 · READY · drain 중앙 라우트 · I1·I2·I4·I5
다. 태그를 다는 것은 그중 어느 것도 아니고 match.Match 의 시그니처와 로직을
안 건드리므로 NFR-I4 도 그대로다. 다만 internal/match/match.go 를 만지는
유닛이 하나 생긴다 — unit-boundaries.md §2 의 「아무 유닛도 안 만진다」가
이 한 줄만큼 바뀐다. 처리는 unit-of-work-dependency.md 에 있다.

8.5 C3 · C4 · C5 — .pen 을 열어 읽었다

@pen.dev/cli 로 로그인한 뒤 pen interactive --in design/enode-ux.pen --out <스크래치패드> 로 헤드리스로 열었다. MCP 는 필요 없다 — MCP 는 실행 중인
앱에 붙는 통로이고 CLI 헤드리스는 파일을 직접 연다. save() 를 안 불렀고
--out 을 저장소 밖으로 두어 원본을 안 건드렸다 (START.md §5 — design/
은 진행자만 고친다).

C3 자원 회수 · 활성 (pxDrainActive)

   제목        자원 회수 (drain) · 활성
   모드 배지    graceful                          걸 때 고른 모드를 그대로 보인다
   상태 1      지금 도는 작업 없음 — 되찾은 상태
   상태 2      이 기계는 온전히 당신 것이다. 풀기 전까지 새 임대가 안 온다
   버튼        drain 풀기 · 함대로 돌려주기        단 하나다.  모드 라디오가 없다
   각주        푸는 순간 매칭 후보로 돌아온다 — 대기 중인 Run이 있으면 곧바로
              배정될 수 있다.  걸 때 고른 모드(graceful · at-boundary)는
              풀기 전까지 바뀌지 않는다

각주의 마지막 문장이 §4.3 의 라우트 설계를 정정했다. 모드 전이를 라우트가
받지 않는다.

C3 은 「자유」 국면(C5)만 그렸다. 「진행 중」 국면(C4)의 상태 문구는 그림에
없으므로 구현이 유도한다 — 임대가 남아 있으면 도는 Run 과 그 단계를 적고
「경계를 기다린다」로 쓴다. 근거는 C4 배지의 문구와 decisions.md 1절의
at-boundary 정의다.

C4 · C5 배지 — 문구가 design/README.md 와 다르다

   C4  draining · 진행 중            채운 배지.  $state-drain 바탕에 어두운 글자
   C5  draining · 대기 중(owner)     테두리 배지.  $state-drain 글자

design/README.md §2.2 는 C5 를 「draining · 대기 중」으로 적었으나 원본의
글자는 draining · 대기 중(owner) 다. (owner) 가 붙는 것이 더 정확하다 —
무엇을 기다리는지가 「소유자가 풀기」임을 그 자리에서 말한다. 원본을 따른다.

S1 카드의 배지는 지금 그냥 draining 이고 범례도 draining 이다. 구현이
C4 · C5 를 조건부로 끼운다 (design/README.md §3). 범례는 그대로 둔다 —
범례는 색의 뜻이고 배지가 국면을 말한다.

8.6 원본이 코드와 어긋난 자리 둘 — 규칙이 이긴다

.pen 을 열어 보이는 글자를 직접 확인했다. 둘 다 design/README.md §6 의
「API 값을 보이는 자리는 원문 enum 그대로」가 판정한다.

S2 범례가 넷(DONE · RUNNING · PENDING · SKIPPED)뿐이다. 여섯 중
CLAIMED(범례의 RUNNING 자리) 말고 FAILED 와 ASKED 가 빠져 있다.
구현이 둘을 더한다 — 안 더하면 실패한 단계와 되묻는 단계가 색 없이 뜬다.

.pen 자체의 스키마 흠 하나

여는 동안 검증 경고가 하나 났다.

   /children/10/children/3/textGrowth
   expected one of: "auto", "fixed-width", "fixed-width-height", got "auto-height"

children[10] 이 C3 이고 그 children[3] 이 각주 텍스트다. 고치지 않았다 —
design/ 은 진행자만 고친다 (START.md §5). 파일은 그래도 열리고 읽힌다.