pyproc의 공개 지속 문서. "무엇을 지향하는가"(product)와 "어떻게 운영하는가"(operations/consuming)의 SSOT다. 그때그때의 개발 계획·결정 기록은 mainPlan/이 담당하고(완료 시 _done 이관), 강행규칙 요약은 저장소 루트의 CLAUDE.md(로컬 규칙 문서, git 미추적)에 있다.
- 카테고리 폴더는 실제 문서가 생길 때만 만든다. 빈 폴더나 "나중을 위한" 카테고리 금지.
- 문서 파일명은 저장소 규칙대로
camelCase.md. - 문서가 코드·규칙과 어긋나면 같은 변경에서 문서를 갱신한다.
| 카테고리 | 문서 | 무엇 |
|---|---|---|
| product/ | vision.md | 제품 방향: North Star, 무엇인가/아닌가, 성공·실패 기준, 지원 경계 |
| glossary.md | 용어집: pyproc(공개 커널)과 Web Machine 플랫폼(비공개) 사이 이름 소유권 경계 | |
| operations/ | operatingModel.md | 운영 모델: 3층 정보 구조, 아이디어 수명주기(attempts -> mainPlan -> src -> _done), 메모리 운영, 개발 원칙 |
| contractReality.md | 계약 실태: 계약 vs 실제 간극의 상시 추적(발견 즉시 기록, 해소 시 삭제). 열린 부채·상시 재검증·트레이드오프·프론티어 | |
| assetProvenance.md | 실행 자산의 provenance와 배포 정책: 증거 없음은 통과가 아니다, SSOT와 파생물, 공식 image 배포 게이트 7항목, 알려진 위험 | |
| testing.md | 테스트 게이트(npm test)와 브라우저 실측 절차(COOP/COEP 서버) |
|
| experimentalFreeze.md | 새 Experimental 공개 표면 동결과 해제 조건 | |
| moduleBoundaries.md | Runtime capability cluster, 정책 모듈, 계약 suite와 실행 자산의 소유권 경계 | |
| benchmarking.md | 내부 실측의 측정 계약, canonical scenario, raw evidence 규칙(공개 표면 게시는 금지: 숫자 자랑 금지 규칙) | |
| release.md | 버전·태그·릴리즈 절차(0.0.x 라인, SHA 핀 소비) |
|
| demoHosting.md | 라이브 데모 배포 절차(COOP/COEP 정적 호스팅, 루트 _headers) |
|
| consuming/ | contract.md | 소비 계약: 설치, 버전 핀, import 경계, 실행 자산 배포, 소비자별 배선 상태, Pyodide 버전 정합 |
| capabilityMatrix.md | 능력 매트릭스: 공개 표면별 제품 가치, 상태, 필수 조건, 실행 표면, 검증, 경계 | |
| resumeCatalog.md | 부활 후 resume.py가 제품별로 다시 열어야 하는 fd/socket/DB connection 정책 |
|
| trustPermissions.md | .pymachine 공개키 배포, signer fingerprint, 권한 UI 계약 |
|
| reference/ | api.md | 영문 API 레퍼런스: 루트 export 6개와 머신 핸들 어휘, 탈출구/subpath, 오류 코드 전 표(기계 게이트로 루트 전수 앵커 강제) |
| bundleFormat.md | 이동 bundle(PYBUNDLE1) 봉투 레이아웃 정본: 바이트 배치, 헤더 필드, 무결성/서명 분리 |
- pyproc이 무엇이고 어디로 가나 -> product/vision.md
- 새 아이디어를 어디서 시작하나 -> tests/attempts/README.md
- 설계·로드맵·결정 기록 -> mainPlan/ (완결 이니셔티브는 _done/, 활성 0이면 새 이니셔티브 개설부터)
- 커밋 전 무엇이 green이어야 하나 -> operations/testing.md
- 속도를 어떻게 실측하고 어디에 기록하나(공개 표면에는 안 건다) -> operations/benchmarking.md
- 버전을 언제 어떻게 올리나 -> operations/release.md
- 제품에서 pyproc을 가져다 쓰는 법 -> consuming/contract.md
- 제품에서 어떤 능력을 믿고 쓸 수 있나 -> consuming/capabilityMatrix.md
- 부활 후 제품 자원 재개설 정책 -> consuming/resumeCatalog.md
- 공개키 배포와 권한 UI 정책 -> consuming/trustPermissions.md
- 외부 기여 -> CONTRIBUTING.md