@deltafleet/codex-goalkeeper 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to Codex Goalkeeper are documented here.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.1.1] - 2026-05-18
+
+- Moved the installable skill payload into `src/codex-goalkeeper/` so Skills CLI installs only skill files.
+- Kept repository docs, tests, examples, and GitHub metadata outside the installable skill directory.
+- Added Node.js 18+ requirement notes to the README files.
+
 ## [0.1.0] - 2026-05-18
 
 Initial public release.

package/README.ja.md

@@ -1,37 +1,74 @@
 # Codex Goalkeeper
 
-長い Codex セッションを壊すのは、コンテキスト圧縮そのものではありません。方向感覚の喪失です。
+長い Codex 作業は、たいてい一気に壊れるわけではありません。
 
-Codex Goalkeeper は、長い `/goal` セッション、繰り返される compaction、handoff、数日にまたがる実装作業で、Codex が進むべき方向を失わないようにする小さな skill です。
+少しずつ方向を失います。
 
-隠れたメモリエンジンを目指していません。エージェントに単純な習慣を持たせます。
+エージェントはまだ自信ありげに話します。テストも実行します。計画も一見もっともらしいままです。しかし compaction、handoff、resume が重なると、いちばん重要な感覚が静かに薄れていきます。
 
-1. 現在のミッションを書き残す。
-2. compaction 後も残すべき判断理由を保存する。
-3. 決定、失敗、検証結果をイベントとして記録する。
-4. 続行する前に checkpoint を最初に読む。
+> なぜ、この方針で進んでいたのか？
 
-それだけです。退屈なファイル。より良い継続性。
+Codex Goalkeeper は、長い `/goal` 作業が compaction、resume、handoff をまたいでも方向を保てるようにする小さな skill です。
+
+隠れたメモリエンジンを追加するものではありません。エージェントに耐久性のある作業習慣を与えます。
+
+- 短い checkpoint を保つ
+- より詳しい context pack を保つ
+- 決定と検証を event log に残す
+- drift が起きやすい境界の後は、続行前に checkpoint を読む
+
+退屈なファイル。より良い継続性。
 
 [English](README.md) | [한국어](README.ko.md) | [中文](README.zh-CN.md)
 
+## インストール
+
+```bash
+npx skills add deltafleet/codex-goalkeeper
+```
+
+要件: Node.js 18+ と `npx`。長い goal workflow で、Codex は skill に同梱された Node helper script を使います。
+
+そして長い作業で Codex にこう依頼します。
+
+> Use codex-goalkeeper for this `/goal`. Keep the goal, constraints, decisions, verification state, failed attempts, and next action recoverable across compaction.
+
+通常の利用はここまでです。ユーザーが Goalkeeper の helper script を手で実行する必要はありません。Codex が skill workflow の一部として実行します。
+
 ## 問題
 
-長いエージェントセッションは、たいてい細かい情報を一つ忘れたせいで失敗するわけではありません。`なぜこの方向で進んでいたのか` が曖昧になることで失敗します。
+短い作業なら、compaction はたいてい大きな問題になりません。エージェントは大まかに復旧できます。
+
+しかし長い goal は違います。
 
-- なぜこの方針を選んだのか
-- ユーザーが明示的に禁止したことは何か
-- どの試行がすでに失敗したのか
-- 実際に検証済みなのは何か
-- 次に何をするはずだったのか
+実際のセッションを想像してください。
 
-何度も compaction が起きると、セッションは自信ありげに続いているように見えても、静かに筋を失うことがあります。
+1. Codex にリリース hardening を任せます。
+2. Codex は壊れやすい edge case を見つけ、保守的なルートを選びます。
+3. ユーザーは魅力的だが危険な shortcut を明示的に拒否します。
+4. 2 回の実装試行が微妙な理由で失敗します。
+5. あるテストがようやく正しいルートを証明します。
+6. コンテキストが compact されます。
+7. 後でエージェントはきれいな要約を持って戻りますが、そのルートが正しかった理由の圧力は薄れています。
 
-Goalkeeper は、その筋をファイルとして明示します。
+ここから drift が始まります。
 
-## 作成される状態
+失敗の原因は「モデルが全部忘れた」ことではありません。もっと厄介です。続けるだけの記憶はあるが、同じ方向で続けるだけの記憶がないのです。
 
-Goalkeeper は作業中のプロジェクト内に状態を保存します。
+それは次のような形で現れます。
+
+- ユーザーがすでに拒否した方針を再び開く
+- 失敗理由が要約から落ち、同じ試行を繰り返す
+- 未検証の仮説を確定事実のように扱う
+- 長い handoff の後で正確な next action を失う
+- goal は残るが運用上の制約を失う
+- 説明は滑らかだが実際の作業ストリームからずれる
+
+Goalkeeper は「goal は残っているが、セッションの方向感覚が弱くなった」その隙間を埋めるためのものです。
+
+## Codex がすること
+
+skill が有効になると、Codex はプロジェクト内に継続性フォルダを維持します。
 
 ```text
 .goalkeeper/
@@ -43,120 +80,90 @@ Goalkeeper は作業中のプロジェクト内に状態を保存します。
       events.jsonl
 ```
 
-それぞれの役割は異なります。
-
-- `checkpoint.md`: 毎回最初に読む短い復旧状態
-- `context-pack.md`: compaction 後も残すべき中密度の判断理由
-- `events.jsonl`: 決定、失敗、コマンド、検証、リスク、handoff の append-only 記録
-
-Codex の goal が目的地なら、Goalkeeper は道に迷わないための現在地の地図です。
-
-## インストール
+それぞれの役割は違います。
 
-Skills CLI を使います。
+- `checkpoint.md`: 再開時に最初に読む短い復旧状態
+- `context-pack.md`: checkpoint には長すぎるが compaction 後も残すべき判断理由
+- `events.jsonl`: 決定、失敗した試行、コマンド根拠、検証、リスク、handoff の記録
 
-```bash
-npx skills add deltafleet/codex-goalkeeper
-```
+Codex の active goal が目的地なら、Goalkeeper はなぜこのルートがまだ正しいのかを保ちます。
 
-ローカル checkout からもインストールできます。
-
-```bash
-git clone https://github.com/deltafleet/codex-goalkeeper
-cd codex-goalkeeper
-npx skills add .
-```
+## 仕組み
 
-## 長い Goal を開始する
+Goalkeeper は長いエージェント作業を単純なループにします。
 
-作業プロジェクトに Goalkeeper セッションを作成します。
-
-```bash
-node <skill-path>/src/scripts/goalkeeper-init.mjs \
-  --workspace <workspace> \
-  --session 2026-05-18-release-hardening \
-  --goal "Ship the release without losing constraints after compaction"
+```text
+長い /goal が始まる
+  -> Codex が Goalkeeper セッションを作成または再開する
+  -> 重要な制約と決定を記録する
+  -> 失敗した試行を残し、同じ失敗を繰り返さないようにする
+  -> 信頼度が変わる検証根拠を残す
+  -> 意味のある境界で checkpoint.md を更新する
+  -> context-pack.md が深い判断理由を保つ
+  -> resume、handoff、compaction が疑われる後、Codex は checkpoint.md を最初に読む
+  -> checkpoint が薄ければ context-pack.md を読む
+  -> 正確な証拠が必要なら events.jsonl または source file を確認する
 ```
 
-このコマンドは、プロジェクトローカルの `.goalkeeper/` ディレクトリと active session pointer を作成します。
+これは会話 transcript の保存ではありません。作業状態の保存です。
 
-## 正しく再開する
+## あえて小さくしています
 
-新しい turn、handoff 後、または compaction が疑われるときは、まずこれを実行します。
+このプロジェクトを大きくするのは簡単です。
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
-  --workspace <workspace>
-```
+- daemon
+- database
+- session rewriter
+- private runtime hook
+- vector memory layer
+- full transcript engine
 
-短い checkpoint だけでは不十分な場合は、context pack も読みます。
+Goalkeeper は意図的にその方向を避けます。
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
-  --workspace <workspace> \
-  --context
-```
+ファイルを使う理由は、見える、レビューできる、移動しやすい、そして compaction 後にエージェントが読み返しやすいからです。目的は Codex を全知にすることではありません。次の turn を正しい状態から始めることです。
 
-重要なのは、エージェントがプロジェクトに触れる前に現在のミッションを読むことです。
+## これは何ではないか
 
-## 重要なことだけを記録する
+- Codex plugin ではありません。
+- MCP server ではありません。
+- database ではありません。
+- 完全な会話 transcript の保存庫ではありません。
+- private Codex runtime hook ではありません。
+- 完璧な記憶を保証しません。
+- compaction の頻度を下げません。
 
-意味のあるイベントを追加します。
+Goalkeeper は継続性を改善します。コンテキスト制限が消えるふりはしません。
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-append-event.mjs \
-  --workspace <workspace> \
-  --type decision \
-  --text "Keep the MVP skill-only; no MCP server or background daemon."
-```
+## 何が良くなるか
 
-実際の状態が変わったら checkpoint を更新します。
+Goalkeeper を使うと、再開されたセッションが次を復旧できる可能性が上がります。
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-update-checkpoint.mjs \
-  --workspace <workspace> \
-  --goal "Ship the release without losing constraints after compaction" \
-  --status "Docs complete; validation pending." \
-  --next "Run validation and cut v0.1.0."
-```
+- ユーザーの non-negotiable constraints
+- 現在の実装方向
+- 拒否した代替案がなぜ今も拒否されるべきか
+- 信頼度を変えたテストやコマンド
+- 実際の next action
+- 雑に流してはいけない unresolved risks
 
-長い作業に使う前に doctor で状態を確認します。
+長いエージェント作業で起きる退屈で高くつく失敗の多くは、これだけでも減らせます。
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-doctor.mjs \
-  --workspace <workspace> \
-  --session 2026-05-18-release-hardening \
-  --strict
-```
-
-## 典型的な流れ
+## リポジトリ構成
 
 ```text
-ユーザーが長い /goal を開始する
-  -> Goalkeeper がプロジェクトローカルのセッションを作る
-  -> Codex は通常どおり作業する
-  -> 重要な決定と検証は events.jsonl に残す
-  -> 意味のある境界で checkpoint.md を更新する
-  -> context-pack.md が判断理由を保持する
-  -> resume または compaction 後、Codex は checkpoint.md を最初に読む
-  -> 必要なら context-pack.md とイベント証拠を読む
+src/codex-goalkeeper/       # installable skill payload
+  SKILL.md
+  agents/openai.yaml
+  scripts/
+  templates/
+  references/
+tests/                      # maintainer tests
+examples/goalkeeper-session # static example state
+docs/                       # roadmap and release policy
 ```
 
-Goalkeeper は compaction をなくしません。compaction 後の復旧を雰囲気ではなく状態に依存させます。
-
-## これは何ではないか
-
-- Codex plugin ではありません。
-- MCP server ではありません。
-- データベースではありません。
-- 会話 transcript の保存庫ではありません。
-- private runtime hook ではありません。
-- 完璧な記憶を保証しません。
-- compaction の頻度を減らしません。
-
-小さな習慣ほど、現実の作業で生き残ります。だから Goalkeeper は小さく保ちます。
+## Maintainer Validation
 
-## 検証
+リポジトリ maintainer 向けの検証です。
 
 ```bash
 npm run validate
@@ -165,8 +172,8 @@ npm run validate
 手動では次を実行します。
 
 ```bash
-find src/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
-node src/scripts/test-goalkeeper-update-checkpoint.mjs
+find src/codex-goalkeeper/scripts tests -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node tests/test-goalkeeper-update-checkpoint.mjs
 npx skills add . --list
 ```
 

package/README.ko.md

@@ -1,148 +1,126 @@
 # Codex Goalkeeper
 
-컨텍스트 컴팩션이 긴 Codex 작업을 망치는 게 아닙니다. 방향 상실이 망칩니다.
+긴 Codex 작업은 보통 한 번에 망가지지 않습니다.
 
-Codex Goalkeeper는 긴 `/goal` 세션, 반복되는 compact, handoff, 며칠짜리 구현 작업에서 Codex가 방향을 잃지 않도록 도와주는 작은 skill입니다.
+조금씩 방향을 잃습니다.
 
-숨겨진 메모리 엔진을 흉내 내지 않습니다. 대신 에이전트에게 단순한 습관을 강제합니다.
+에이전트는 여전히 자신 있게 말합니다. 테스트도 돌립니다. 계획도 그럴듯해 보입니다. 그런데 compact, handoff, resume이 반복된 뒤에는 가장 중요한 감각이 조용히 흐려질 수 있습니다.
 
-1. 지금 목표를 짧게 기록한다.
-2. compact 이후에도 살아남아야 하는 판단 근거를 보존한다.
-3. 결정, 실패, 검증 결과를 이벤트로 남긴다.
-4. 다시 시작할 때 프로젝트 파일보다 checkpoint를 먼저 읽는다.
+> 우리가 왜 이 방향으로 가고 있었지?
 
-그게 전부입니다. 지루한 파일들. 더 나은 연속성.
+Codex Goalkeeper는 긴 `/goal` 작업이 compact, resume, handoff를 지나도 방향을 잃지 않도록 돕는 작은 skill입니다.
 
-[English](README.md) | [日本語](README.ja.md) | [中文](README.zh-CN.md)
-
-## 문제
-
-긴 에이전트 세션은 보통 사소한 디테일 하나를 잊어서 망하지 않습니다. `왜 이렇게 가고 있었는지`가 흐려지면서 망합니다.
+숨겨진 메모리 엔진을 추가하지 않습니다. 대신 에이전트에게 지속 가능한 작업 습관을 줍니다.
 
-- 왜 이 방향을 선택했는지
-- 사용자가 명시적으로 금지한 접근이 무엇인지
-- 이미 실패한 시도가 무엇인지
-- 실제로 검증된 것이 무엇인지
-- 다음 액션이 무엇이었는지
+- 짧은 checkpoint를 유지한다
+- 더 풍부한 context pack을 유지한다
+- 결정과 검증을 event log에 남긴다
+- drift가 생기기 쉬운 경계 이후에는 계속하기 전에 checkpoint를 먼저 읽는다
 
-compact가 여러 번 지나면 세션은 여전히 그럴듯하게 말하지만, 실제로는 방향을 잃을 수 있습니다.
+지루한 파일들. 더 나은 연속성.
 
-Goalkeeper는 그 방향을 파일로 명시합니다.
-
-## 생성되는 상태
+[English](README.md) | [日本語](README.ja.md) | [中文](README.zh-CN.md)
 
-Goalkeeper는 작업 중인 프로젝트 안에 상태를 저장합니다.
+## 설치
 
-```text
-.goalkeeper/
-  active-session
-  sessions/
-    <goal-session-id>/
-      checkpoint.md
-      context-pack.md
-      events.jsonl
+```bash
+npx skills add deltafleet/codex-goalkeeper
 ```
 
-각 파일의 역할은 다릅니다.
+요구사항: Node.js 18+와 `npx`. 긴 goal workflow에서 Codex가 skill에 포함된 Node helper script를 사용합니다.
 
-- `checkpoint.md`: 매번 먼저 읽는 짧은 복구 상태
-- `context-pack.md`: compact 이후에도 살아남아야 하는 중간 밀도의 판단 근거
-- `events.jsonl`: 결정, 실패, 명령, 검증, 리스크, handoff의 append-only 기록
+그리고 긴 작업에서 Codex에게 이렇게 요청합니다.
 
-Codex의 goal이 목적지를 말한다면, Goalkeeper는 길을 잃지 않기 위한 현재 지도를 보존합니다.
+> 이 `/goal`에는 codex-goalkeeper를 사용해줘. 목표, 제약, 결정, 검증 상태, 실패한 시도, 다음 액션이 compact 이후에도 복구 가능하게 관리해줘.
 
-## 설치
+정상적인 사용 흐름은 여기까지입니다. 사용자가 Goalkeeper의 helper script를 직접 실행할 필요는 없습니다. Codex가 skill workflow의 일부로 실행합니다.
 
-Skills CLI로 설치합니다.
+## 문제
 
-```bash
-npx skills add deltafleet/codex-goalkeeper
-```
+짧은 작업에서 compact는 대개 큰 문제가 아닙니다. 에이전트가 대충 복구할 수 있습니다.
 
-로컬 체크아웃에서 설치할 수도 있습니다.
+하지만 긴 goal은 다릅니다.
 
-```bash
-git clone https://github.com/deltafleet/codex-goalkeeper
-cd codex-goalkeeper
-npx skills add .
-```
+실제 세션을 상상해보면 이렇습니다.
 
-## 긴 Goal 시작
+1. Codex에게 릴리스 hardening을 맡깁니다.
+2. Codex가 취약한 edge case를 발견하고 보수적인 경로를 선택합니다.
+3. 사용자는 그럴듯하지만 위험한 shortcut을 명시적으로 금지합니다.
+4. 두 번의 구현 시도가 미묘한 이유로 실패합니다.
+5. 어떤 테스트가 드디어 올바른 경로를 증명합니다.
+6. 컨텍스트가 compact됩니다.
+7. 나중에 에이전트가 깔끔한 요약을 들고 돌아오지만, 왜 그 경로가 맞았는지에 대한 압력은 희미해져 있습니다.
 
-작업 프로젝트에 Goalkeeper 세션을 만듭니다.
+여기서 drift가 시작됩니다.
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-init.mjs \
-  --workspace <workspace> \
-  --session 2026-05-18-release-hardening \
-  --goal "Ship the release without losing constraints after compaction"
-```
+실패 원인은 “모델이 전부 잊었다”가 아닙니다. 더 까다롭습니다. 계속할 만큼은 기억하지만, 같은 방향으로 계속할 만큼은 기억하지 못합니다.
 
-이 명령은 프로젝트 로컬 `.goalkeeper/` 디렉터리와 active session pointer를 만듭니다.
+이런 순간에 드러납니다.
 
-## 다시 시작할 때
+- 사용자가 이미 거부한 접근을 다시 연다
+- 실패 이유가 요약에서 사라져 같은 시도를 반복한다
+- 검증되지 않은 가정을 확정 사실처럼 다룬다
+- 긴 handoff 뒤에 정확한 next action을 잃는다
+- goal은 유지하지만 운영 제약을 잃는다
+- 설명은 매끄럽지만 실제 작업 흐름과 어긋난다
 
-새 turn, handoff 이후, compact가 의심되는 상황에서는 먼저 이 명령을 실행합니다.
+Goalkeeper는 “goal은 남아 있지만 세션의 방향 감각은 약해진” 그 틈을 메우기 위한 도구입니다.
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
-  --workspace <workspace>
-```
+## Codex가 하는 일
 
-짧은 checkpoint만으로 충분하지 않으면 context pack까지 읽습니다.
+skill이 활성화되면 Codex는 프로젝트 안에 연속성 폴더를 유지합니다.
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
-  --workspace <workspace> \
-  --context
+```text
+.goalkeeper/
+  active-session
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
 ```
 
-핵심은 간단합니다. 에이전트가 프로젝트를 건드리기 전에 현재 미션을 먼저 읽게 만드는 것입니다.
+각 파일의 역할은 다릅니다.
 
-## 중요한 것만 기록
+- `checkpoint.md`: 다시 시작할 때 먼저 읽는 짧은 복구 상태
+- `context-pack.md`: checkpoint에는 너무 길지만 compact 이후에도 살아남아야 하는 판단 근거
+- `events.jsonl`: 결정, 실패한 시도, 명령 근거, 검증, 리스크, handoff 기록
 
-중요한 이벤트를 남깁니다.
+Codex의 active goal이 목적지를 말한다면, Goalkeeper는 왜 이 경로가 아직 맞는지를 보존합니다.
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-append-event.mjs \
-  --workspace <workspace> \
-  --type decision \
-  --text "Keep the MVP skill-only; no MCP server or background daemon."
-```
+## 동작 원리
 
-실제 상태가 바뀌면 checkpoint를 갱신합니다.
+Goalkeeper는 긴 에이전트 작업을 단순한 루프로 바꿉니다.
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-update-checkpoint.mjs \
-  --workspace <workspace> \
-  --goal "Ship the release without losing constraints after compaction" \
-  --status "Docs complete; validation pending." \
-  --next "Run validation and cut v0.1.0."
+```text
+긴 /goal이 시작된다
+  -> Codex가 Goalkeeper 세션을 만들거나 재개한다
+  -> 중요한 제약과 결정을 기록한다
+  -> 실패한 시도를 남겨 같은 삽질을 반복하지 않게 한다
+  -> 신뢰도가 바뀌는 검증 근거를 남긴다
+  -> 의미 있는 경계마다 checkpoint.md를 갱신한다
+  -> context-pack.md가 더 깊은 판단 근거를 보존한다
+  -> resume, handoff, compact 의심 이후 Codex는 checkpoint.md를 먼저 읽는다
+  -> checkpoint가 얇으면 context-pack.md를 읽는다
+  -> 정확한 증거가 필요하면 events.jsonl이나 source file을 확인한다
 ```
 
-긴 작업을 믿고 맡기기 전에 doctor로 상태를 점검합니다.
+이것은 대화 transcript 저장이 아닙니다. 작업 상태 보존입니다.
 
-```bash
-node <skill-path>/src/scripts/goalkeeper-doctor.mjs \
-  --workspace <workspace> \
-  --session 2026-05-18-release-hardening \
-  --strict
-```
+## 일부러 작게 만들었습니다
 
-## 전형적인 흐름
+이 프로젝트를 크게 만드는 방법은 쉽습니다.
 
-```text
-사용자가 긴 /goal을 시작한다
-  -> Goalkeeper가 프로젝트 로컬 세션을 만든다
-  -> Codex는 평소처럼 작업한다
-  -> 중요한 결정과 검증은 events.jsonl에 남긴다
-  -> 의미 있는 경계마다 checkpoint.md를 갱신한다
-  -> context-pack.md는 판단 근거를 보존한다
-  -> resume 또는 compact 이후 Codex는 checkpoint.md를 먼저 읽는다
-  -> 필요하면 context-pack.md와 이벤트 근거를 더 읽는다
-```
+- daemon
+- database
+- session rewriter
+- private runtime hook
+- vector memory layer
+- full transcript engine
 
-Goalkeeper는 compact를 없애지 않습니다. compact 이후 복구를 감이 아니라 상태에 의존하게 만듭니다.
+Goalkeeper는 의도적으로 그 방향을 피합니다.
+
+파일을 쓰는 이유는 파일이 보이고, 검토 가능하고, 옮기기 쉽고, compact 이후에도 에이전트가 다시 읽기 쉽기 때문입니다. 목표는 Codex를 전지전능하게 만드는 것이 아닙니다. 다음 turn이 올바른 상태에서 시작하게 만드는 것입니다.
 
 ## 이것이 아닌 것
 
@@ -150,13 +128,42 @@ Goalkeeper는 compact를 없애지 않습니다. compact 이후 복구를 감이
 - MCP server가 아닙니다.
 - 데이터베이스가 아닙니다.
 - 전체 대화 transcript 저장소가 아닙니다.
-- private runtime hook이 아닙니다.
+- private Codex runtime hook이 아닙니다.
 - 완벽한 기억을 보장하지 않습니다.
-- compact 빈도를 줄여주지 않습니다.
+- compact 빈도를 줄이지 않습니다.
+
+Goalkeeper는 연속성을 개선합니다. 컨텍스트 한계를 없애는 척하지 않습니다.
+
+## 좋아지는 것
+
+Goalkeeper를 쓰면 resume된 세션이 다음을 복구할 가능성이 높아집니다.
+
+- 사용자의 non-negotiable constraints
+- 현재 구현 방향
+- 거부된 대안이 왜 여전히 거부되어야 하는지
+- 신뢰도를 바꾼 테스트나 명령
+- 실제 next action
+- 대충 넘기면 안 되는 unresolved risks
+
+긴 에이전트 작업에서 발생하는 지루하고 비싼 실패 상당수는 이 정도만으로도 줄어듭니다.
+
+## 저장소 구조
+
+```text
+src/codex-goalkeeper/       # installable skill payload
+  SKILL.md
+  agents/openai.yaml
+  scripts/
+  templates/
+  references/
+tests/                      # maintainer tests
+examples/goalkeeper-session # static example state
+docs/                       # roadmap and release policy
+```
 
-작은 습관일수록 실제 작업에서 오래 살아남습니다. 그래서 Goalkeeper는 작게 유지합니다.
+## Maintainer Validation
 
-## 검증
+저장소 maintainer용 검증입니다.
 
 ```bash
 npm run validate
@@ -165,8 +172,8 @@ npm run validate
 수동으로는 다음을 실행합니다.
 
 ```bash
-find src/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
-node src/scripts/test-goalkeeper-update-checkpoint.mjs
+find src/codex-goalkeeper/scripts tests -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node tests/test-goalkeeper-update-checkpoint.mjs
 npx skills add . --list
 ```