아카이빙과 온톨로지

티켓이 완료되면 그 일의 맥락은 티켓 본문 한 장에 남습니다. 무엇을 어떻게 했는지, 어떤 명령으로 확인했는지가 ## 결과에 적혀 있습니다. 문제는 다음 달입니다. 같은 자리를 건드리는 세션이 그 본문을 찾아 읽으면 다행입니다. 못 찾으면 처음부터 다시 알아냅니다.

아카이빙은 그 사이에 한 단계를 끼웁니다. 티켓을 끝낸 세션이 티켓을 하나 더 냅니다. 그 티켓을 받은 세션은 방금 끝난 일에서 지금 참인 사실만 골라 카드 한 장으로 옮겨 적습니다. 무엇을 옮겼는지는 대상 티켓 본문 아래에 남깁니다. 카드가 쌓이는 자리가 온톨로지고, 앱에 전용 화면이 있습니다.

온톨로지 화면 - 파일트리와 지표

왼쪽 내비의 온톨로지. 제목 밑 회색 글씨가 이 프로젝트의 카드가 실제로 사는 경로입니다. 페르소나와 프로토콜이 사는 큐 폴더 안, ontology/입니다.

생김새는 프로토콜 화면과 같습니다. 왼쪽이 파일트리, 오른쪽이 편집기. 편집기도 그 장에 적힌 두 모드입니다. 들어가면 위지윅으로 열리고, 카드에 든 마크다운을 직접 볼 일이 있으면 칸 오른쪽 위 구석의 아이콘 버튼으로 넘깁니다. 파일을 고르면 주소에 남으니 그 자리를 그대로 링크할 수 있습니다. 한 글자라도 고치면 저장이 살아납니다. 오른쪽 위 새 파일도 같은 자리에 있습니다.

트리가 이렇게 섭니다.

• _ontology/SCHEMA.md - 지도 한 장. 이 프로젝트에 어떤 종류의 대상이 있고 서로 어떤 이름으로 이어지는지가 여기 있습니다. 처음 열 파일입니다.
• _ontology/object-types/ _ontology/link-types/ - 종류마다, 관계마다 정의 한 장. 지도의 표는 이름과 한 줄 뜻만 들고, 어떤 속성이 필수인지 같은 세부는 여기로 내려갑니다.
• objects/<종류>/ - 카드 본체. 파일 하나가 대상 하나고, 파일명이 곧 그 이름입니다.
• action-log/<연도>/<날짜>.md - 언제 무엇이 생기고 무엇이 바뀌었는지의 시간축 기록.
• templates/ - 새 카드를 시작할 때 베끼는 빈 껍데기.

디렉터리 이름도 내용입니다. 프루퍼주식회사/인물/임한솔.md처럼 무엇의 무엇인지가 경로에 드러납니다. 깊이 제한은 없습니다. 카드를 폴더째 옮겨도 서로 가리키는 링크는 안 깨집니다. 링크가 경로가 아니라 이름으로 걸려 있어서입니다.

위쪽 숫자 열두 칸 - 잘못 쌓이면 여기서 먼저 티가 납니다

트리 위에 지표 패널이 붙습니다. 칸이 열두 개입니다. 전부 파일을 그 자리에서 읽어 셉니다. 다 외울 필요는 없습니다. 자주 보게 되는 것만 추리면 이렇습니다.

나머지 여덟 칸은 껍데기, 고립, 서술 한 문장처럼 카드의 성김을 재거나, 계층 순환, 다의적 요소, 잉여 클래스처럼 종류 정의가 꼬인 자리를 잡습니다. 마지막 반영은 가장 최근 기록의 날짜입니다. 이 값이 오래 멈춰 있으면 아카이빙 자체가 안 돌고 있는 것입니다.

지도에 없는 종류나 관계가 카드에 쓰이면 패널 아래에 스키마 위반 상자가 뜹니다. 어긋난 파일과 줄이 열 개까지 그대로 나오고, 넘치면 외 N건으로 접힙니다.

문제해결 - 위반을 티켓 한 장으로 넘깁니다

상자 안에 버튼이 하나 있습니다. 문제해결입니다.

누르면 그 자리에서 파일이 고쳐지는 것이 아닙니다. 큐에 티켓이 한 장 생깁니다. 화면은 방금 만든 티켓 상세로 넘어가니 무엇을 시킨 것인지 바로 읽으실 수 있습니다. 본문에는 상자에 떠 있던 위반 줄이 측정 시각과 함께 들어갑니다. 50줄까지고 넘치면 외 N건으로 접힙니다. 남은 것은 다음 회차 몫입니다.

받는 쪽은 아카이빙을 도는 세션과 같습니다(archive-manager). 그 세션은 줄마다 무엇을 고쳤는지, 아니면 왜 위반이 아닌지를 ## 결과에 적고 반영을 action-log/에 한 줄 남깁니다. 쉬고 있는 워커가 있으면 다음 순회를 기다리지 않고 바로 집어 갑니다.

두 번 눌러도 티켓은 한 장입니다. 정리 티켓이 아직 안 끝났으면 버튼 자리에 정리 티켓 a1b2c3d4 진행중처럼 링크가 대신 서고, 누르면 그 티켓으로 갑니다. 탭을 둘 열어 두고 양쪽에서 눌러도 마찬가지입니다. 발행 직전에 큐를 한 번 더 훑어서, 이미 있으면 새로 만들지 않고 그것을 열어 주기 때문입니다.

정리 티켓이 완료됐는데 상자가 그대로 남아 있으면 버튼이 다시 섭니다. 그 회차가 다 못 고쳤다는 뜻이니 한 번 더 보내시면 됩니다. 위반이 0건이 되면 상자째 사라집니다.

비어 있으면 질문 넷부터

온톨로지가 없는 프로젝트도 그냥 돕니다. 폴더가 비어 있으면 엔진은 아무 말 없이 넘어갑니다. 그래서 이 화면의 첫 상태는 빈 트리가 아니라 설문입니다. 몇 가지만 답하면 시작할 자료를 만들어 드립니다.

묻는 것은 넷입니다. 이 프로젝트가 주로 무엇을 다루는지, 일하다 보면 자주 이름을 부르게 될 대상이 무엇인지, 나중에 무엇을 물어보게 될 것 같은지, 정리 대상이 아닌 것은 무엇인지. 마지막 질문의 첫 항목은 이 관리 도구 자신이고 처음부터 체크돼 있습니다.

만들기를 누르면 답을 그대로 지도로 옮깁니다. 종류가 셋에서 다섯, 관계가 둘에서 넷입니다. 그 하나하나에 정의 파일이 한 장씩 따라 서고, 종류에는 빈 템플릿도 붙습니다. 그게 전부입니다. 작게 시작하는 것이 설계입니다. 나머지는 일하면서 붙습니다.

그다음이 첫 채움입니다. 지도만 서고 카드가 0장이면 읽을 것이 없으니 세션 하나가 프로젝트 폴더를 훑어 첫 카드를 세웁니다. 홈 대화에서 도는 일이라, 화면이 띄우는 링크를 따라가면 무엇을 세웠는지 그 자리에서 읽으실 수 있습니다.

답할 것이 마땅치 않으면 건너뛰어도 됩니다. 새 파일로 빈 파일부터 시작해도 됩니다. 아예 안 만들어도 프로젝트는 그대로 돕니다.

완료 뒤에 티켓이 하나 더 돕니다

여기부터가 평소에 도는 고리입니다.

세션이 티켓을 끝내는 순서는 정해져 있습니다. 작업을 마치고 push가 성공한 것을 확인한 다음 파일을 .done으로 바꿉니다. 아카이브 티켓을 내는 자리는 그 둘 사이입니다. push보다 앞서면 통합되지도 않은 일의 아카이브가 남고, .done 뒤로 미루면 그때는 세션이 이미 끝나 있을 수 있습니다.

새로 나는 티켓에는 persona: archive-manager가 붙습니다. 프로젝트를 만들 때 같이 서는 기본 페르소나 중 하나입니다(페르소나). 대상은 언제나 티켓 하나입니다. 여러 건을 묶지 않습니다.

deps도 한 줄 붙습니다. 대상이 .done이 되기 전에는 이 티켓이 큐에 안 뜬다는 뜻입니다. 이 줄이 없으면 앞 세션이 아직 ## 결과를 쓰고 있는 파일에 아카이브 세션이 절을 덧붙이는 일이 생깁니다. 실제로 한 번 열렸던 창입니다. 그래서 닫아 뒀습니다.

아카이브 티켓은 아카이브 티켓을 내지 않습니다. 이 한 줄이 고리를 끊습니다.

값은 치릅니다. 완료 한 건이 티켓 한 건이니 워커 하나가 그만큼 다른 일을 못 합니다. 안 쓰기로 했으면 프로토콜 문서에서 그 절을 지우면 됩니다. 엔진 기능이 아니라 규약이라 끄는 자리가 파일 한 군데입니다.

어디서 보이나 - 완료 카드 아래 한 줄

아카이브 티켓은 보드에 자기 카드로 서지 않습니다. 대신 대상 카드 맨 아래에 한 줄이 붙습니다. .wip 카드가 방금 한 일을 이는 그 자리, 같은 슬롯입니다.

문구는 셋입니다. 아카이빙 대기, 아카이빙중, 아카이빙 답변 대기. 눌러 들어가면 그 아카이브 티켓의 상세입니다. 보드에서 거기로 가는 길이 이 줄 하나뿐입니다. 아카이빙이 끝나면 줄이 사라집니다. 끝난 것이 기본 상태라 말할 값이 없습니다.

티켓 상세에서는 관계 절에 한 줄이 섭니다. 대상 티켓 쪽에는 아카이브, 아카이브 티켓 쪽에는 아카이브 대상. 양쪽에서 서로를 가리킵니다.

대상 티켓 본문 맨 아래에는 ## 아카이브 절이 붙습니다. 이번 회차에 무엇을 온톨로지에 옮겼는지가 여기 적힙니다. ## 결과를 고쳐 쓰지는 않습니다. 위는 그 일을 한 세션의 글이고 아래는 아카이브 세션의 글이라 둘이 나란히 남습니다.

카드에 적히는 것 - 사실만, 없으면 빈손

카드 한 장은 세 층입니다. 파일 위쪽 frontmatter에 종류, 이름, 속성과 다른 카드로 가는 관계가 들어갑니다. 그 아래 본문이 그 대상은 무엇이며 왜 지금 이런 상태인지를 산문으로 적습니다.

기준은 하나입니다. 지금 참인 상태를 적고, 앞으로 이렇게 하자는 판단은 안 적습니다.

• 적습니다 - "이 워커는 옛 문구가 남아 있어 실측 경로와 어긋난다"
• 안 적습니다 - "재디스패치 전에 로그를 먼저 보는 게 낫다"

뒤엣것도 버리지는 않습니다. 자리가 다를 뿐이라 페르소나 메모리로 갑니다. 안 가르면 온톨로지가 메모리와 같아집니다. 파일만 두 벌이 되는 것입니다.

남길 사실이 없으면 아무것도 안 적는 것이 정상 종료입니다. 세션은 ## 아카이브 절에 "이번엔 줄 것이 없음"이라고 쓰고 기록에 한 줄 남기고 끝냅니다. 티켓 대부분이 그렇습니다. 빈손 비율이 낮게 나오면 반대로 의심하는 이유가 이것입니다.

다음 세션이 받는 것은 위치와 찾는 법입니다

쌓인 카드가 되돌아오는 자리는 세션 프롬프트입니다. 티켓이 디스패치될 때마다 짧은 블록이 하나 붙습니다. 온톨로지가 어디 있는지, 지도가 어느 파일인지(_ontology/SCHEMA.md), 필요한 개념은 티켓의 어휘로 grep해서 열라는 것. 이게 전부입니다.

본문은 안 실립니다. 그래서 카드가 몇 장이 되든 이 블록은 안 자랍니다. 프로필과 갈리는 자리가 여기입니다. 프로필은 길어진 만큼 매 세션이 값을 치르지만(페르소나) 온톨로지는 몇천 장이 돼도 프롬프트가 그대로입니다. 대신 세션이 필요할 때 직접 찾아 읽습니다.

폴더가 없거나 .md가 한 장도 없으면 블록 자체가 안 붙습니다. 경고도 없습니다.

이미 굴리던 프로젝트라면 - 마이그레이션

설문은 새 프로젝트의 자리입니다. 이미 티켓이 쌓인 프로젝트에는 다른 문이 있습니다. 프로젝트 목록에서 그 행의 톱니를 누르면 나오는 온톨로지 마이그레이션입니다. 설명이 그 자리에 이렇게 적혀 있습니다. 없으면 새로 세우고, 있으면 최신 규약으로 다시 올립니다. 다시 돌려도 안전합니다.

다시 돌리는 것이 정상 사용입니다. 손으로 고친 카드는 덮어쓰지 않습니다. 이미 규약에 맞는 것도 건드리지 않습니다. 옛 기록을 버리지도 않습니다. 사실에 해당하는 것만 카드로 건져 올리고 판단은 메모리 쪽으로 보냅니다.

마이그레이션 시작을 누르면 돌아가는 동안 그 자리에 진행이 흐릅니다. 끝나면 무엇을 했는지가 같은 자리에 뜹니다. 다이얼로그를 닫아도 세션은 계속 돌고, 그 대화는 홈에 남습니다.

폴더 하나가 그대로 남습니다

온톨로지는 데이터베이스가 아니라 마크다운 파일 더미입니다. 큐 폴더 안에 있으니 프로젝트를 옮기면 같이 가고, 앱을 지워도 파일은 남습니다.

카드끼리 거는 링크는 [[이름]] 표기라, 그 폴더를 obsidian vault로 열면 그래프가 그대로 보입니다. 편집기든 grep이든 여는 방법은 마음대로입니다.

한 가지는 미리 아셔야 합니다. 큐는 git에 안 들어갑니다. 이 폴더도 마찬가지입니다. 레포를 clone한 사람에게는 0장이라, 팀과 나누려면 폴더를 따로 옮기셔야 합니다.

다음은 인증입니다.