@deltafleet/codex-goalkeeper 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to Codex Goalkeeper are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-05-18
+
+Initial public release.
+
+- Added the `codex-goalkeeper` skill.
+- Added project-local `.goalkeeper/` session layout.
+- Added checkpoint, context pack, and JSONL event workflow.
+- Added helper scripts for init, turn start, event append, checkpoint update, and doctor checks.
+- Added examples, templates, multilingual READMEs, and open-source operating docs.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+Codex Goalkeeper uses a simple contributor standard:
+
+- Be direct, respectful, and specific.
+- Critique ideas and patches, not people.
+- Assume good intent, but prioritize technical clarity.
+- Do not harass, threaten, insult, or target people based on identity, background, or affiliation.
+- Keep issues and pull requests focused on the project.
+
+Maintainers may remove comments, close issues, block users, or restrict participation when behavior makes the project harder to use or maintain.
+
+Report conduct concerns privately through the security contact in [SECURITY.md](SECURITY.md).

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thanks for considering a contribution to Codex Goalkeeper.
+
+The project has one strong bias: keep the core small enough that agents will actually use it during long work.
+
+## Good Contributions
+
+- Make checkpoint-first recovery easier to follow.
+- Improve script reliability without adding hidden services.
+- Improve documentation, examples, or translations.
+- Add tests around existing helper behavior.
+- Tighten validation or error messages.
+
+## Contributions That Need Extra Justification
+
+- New persistent state beyond `.goalkeeper/`.
+- Background processes.
+- Runtime hooks into private Codex internals.
+- Global databases or cross-project indexing.
+- Large abstractions around the five core helper scripts.
+
+These may be useful later, but they should not enter the project without a clear real-world failure case.
+
+## Local Validation
+
+Run:
+
+```bash
+npm run validate
+```
+
+Manual equivalent:
+
+```bash
+find src/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node src/scripts/test-goalkeeper-update-checkpoint.mjs
+find examples -name '*.jsonl' -print0 | xargs -0 -n1 jq -c . >/dev/null
+npx skills add . --list
+```
+
+## Pull Request Checklist
+
+- Keep `SKILL.md` concise.
+- Keep `README.md` useful for first-time readers.
+- Update translated READMEs when changing the public workflow.
+- Update `CHANGELOG.md` for user-visible changes.
+- Update `docs/RELEASE.md` if the release process changes.
+- Do not add secrets, local `.goalkeeper/` state, or generated scratch output.
+
+## Versioning
+
+Use SemVer:
+
+- Patch for docs, examples, tests, and compatible bug fixes.
+- Minor for new compatible helpers or workflow fields.
+- Major for breaking checkpoint, event, or script contracts.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Deltafleet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.ja.md

@@ -0,0 +1,197 @@
+# Codex Goalkeeper
+
+長い Codex セッションを壊すのは、コンテキスト圧縮そのものではありません。方向感覚の喪失です。
+
+Codex Goalkeeper は、長い `/goal` セッション、繰り返される compaction、handoff、数日にまたがる実装作業で、Codex が進むべき方向を失わないようにする小さな skill です。
+
+隠れたメモリエンジンを目指していません。エージェントに単純な習慣を持たせます。
+
+1. 現在のミッションを書き残す。
+2. compaction 後も残すべき判断理由を保存する。
+3. 決定、失敗、検証結果をイベントとして記録する。
+4. 続行する前に checkpoint を最初に読む。
+
+それだけです。退屈なファイル。より良い継続性。
+
+[English](README.md) | [한국어](README.ko.md) | [中文](README.zh-CN.md)
+
+## 問題
+
+長いエージェントセッションは、たいてい細かい情報を一つ忘れたせいで失敗するわけではありません。`なぜこの方向で進んでいたのか` が曖昧になることで失敗します。
+
+- なぜこの方針を選んだのか
+- ユーザーが明示的に禁止したことは何か
+- どの試行がすでに失敗したのか
+- 実際に検証済みなのは何か
+- 次に何をするはずだったのか
+
+何度も compaction が起きると、セッションは自信ありげに続いているように見えても、静かに筋を失うことがあります。
+
+Goalkeeper は、その筋をファイルとして明示します。
+
+## 作成される状態
+
+Goalkeeper は作業中のプロジェクト内に状態を保存します。
+
+```text
+.goalkeeper/
+  active-session
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
+```
+
+それぞれの役割は異なります。
+
+- `checkpoint.md`: 毎回最初に読む短い復旧状態
+- `context-pack.md`: compaction 後も残すべき中密度の判断理由
+- `events.jsonl`: 決定、失敗、コマンド、検証、リスク、handoff の append-only 記録
+
+Codex の goal が目的地なら、Goalkeeper は道に迷わないための現在地の地図です。
+
+## インストール
+
+Skills CLI を使います。
+
+```bash
+npx skills add deltafleet/codex-goalkeeper
+```
+
+ローカル checkout からもインストールできます。
+
+```bash
+git clone https://github.com/deltafleet/codex-goalkeeper
+cd codex-goalkeeper
+npx skills add .
+```
+
+## 長い Goal を開始する
+
+作業プロジェクトに 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"
+```
+
+このコマンドは、プロジェクトローカルの `.goalkeeper/` ディレクトリと active session pointer を作成します。
+
+## 正しく再開する
+
+新しい turn、handoff 後、または compaction が疑われるときは、まずこれを実行します。
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
+  --workspace <workspace>
+```
+
+短い checkpoint だけでは不十分な場合は、context pack も読みます。
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
+  --workspace <workspace> \
+  --context
+```
+
+重要なのは、エージェントがプロジェクトに触れる前に現在のミッションを読むことです。
+
+## 重要なことだけを記録する
+
+意味のあるイベントを追加します。
+
+```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 を更新します。
+
+```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."
+```
+
+長い作業に使う前に 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 とイベント証拠を読む
+```
+
+Goalkeeper は compaction をなくしません。compaction 後の復旧を雰囲気ではなく状態に依存させます。
+
+## これは何ではないか
+
+- Codex plugin ではありません。
+- MCP server ではありません。
+- データベースではありません。
+- 会話 transcript の保存庫ではありません。
+- private runtime hook ではありません。
+- 完璧な記憶を保証しません。
+- compaction の頻度を減らしません。
+
+小さな習慣ほど、現実の作業で生き残ります。だから Goalkeeper は小さく保ちます。
+
+## 検証
+
+```bash
+npm run validate
+```
+
+手動では次を実行します。
+
+```bash
+find src/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node src/scripts/test-goalkeeper-update-checkpoint.mjs
+npx skills add . --list
+```
+
+## バージョン管理
+
+Goalkeeper は SemVer を使います。
+
+- Patch: 文書、例、テスト、互換性のあるバグ修正
+- Minor: 互換性のある helper または workflow field の追加
+- Major: checkpoint、event、script contract の破壊的変更
+
+リリース手順は [docs/RELEASE.md](docs/RELEASE.md) を参照してください。
+
+## コントリビューション
+
+Issue と PR を歓迎します。ただし、このプロジェクトの基準は厳格です。
+
+- core workflow を小さく保つ
+- 隠れた runtime dependency を追加しない
+- 完璧な復旧を約束しない
+- global state より project-local file を優先する
+- 変更は検証コマンドで証明する
+
+詳しくは [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md)、[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) を参照してください。
+
+## ライセンス
+
+MIT. [LICENSE](LICENSE) を参照してください。

package/README.ko.md

@@ -0,0 +1,197 @@
+# Codex Goalkeeper
+
+컨텍스트 컴팩션이 긴 Codex 작업을 망치는 게 아닙니다. 방향 상실이 망칩니다.
+
+Codex Goalkeeper는 긴 `/goal` 세션, 반복되는 compact, handoff, 며칠짜리 구현 작업에서 Codex가 방향을 잃지 않도록 도와주는 작은 skill입니다.
+
+숨겨진 메모리 엔진을 흉내 내지 않습니다. 대신 에이전트에게 단순한 습관을 강제합니다.
+
+1. 지금 목표를 짧게 기록한다.
+2. compact 이후에도 살아남아야 하는 판단 근거를 보존한다.
+3. 결정, 실패, 검증 결과를 이벤트로 남긴다.
+4. 다시 시작할 때 프로젝트 파일보다 checkpoint를 먼저 읽는다.
+
+그게 전부입니다. 지루한 파일들. 더 나은 연속성.
+
+[English](README.md) | [日本語](README.ja.md) | [中文](README.zh-CN.md)
+
+## 문제
+
+긴 에이전트 세션은 보통 사소한 디테일 하나를 잊어서 망하지 않습니다. `왜 이렇게 가고 있었는지`가 흐려지면서 망합니다.
+
+- 왜 이 방향을 선택했는지
+- 사용자가 명시적으로 금지한 접근이 무엇인지
+- 이미 실패한 시도가 무엇인지
+- 실제로 검증된 것이 무엇인지
+- 다음 액션이 무엇이었는지
+
+compact가 여러 번 지나면 세션은 여전히 그럴듯하게 말하지만, 실제로는 방향을 잃을 수 있습니다.
+
+Goalkeeper는 그 방향을 파일로 명시합니다.
+
+## 생성되는 상태
+
+Goalkeeper는 작업 중인 프로젝트 안에 상태를 저장합니다.
+
+```text
+.goalkeeper/
+  active-session
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
+```
+
+각 파일의 역할은 다릅니다.
+
+- `checkpoint.md`: 매번 먼저 읽는 짧은 복구 상태
+- `context-pack.md`: compact 이후에도 살아남아야 하는 중간 밀도의 판단 근거
+- `events.jsonl`: 결정, 실패, 명령, 검증, 리스크, handoff의 append-only 기록
+
+Codex의 goal이 목적지를 말한다면, Goalkeeper는 길을 잃지 않기 위한 현재 지도를 보존합니다.
+
+## 설치
+
+Skills CLI로 설치합니다.
+
+```bash
+npx skills add deltafleet/codex-goalkeeper
+```
+
+로컬 체크아웃에서 설치할 수도 있습니다.
+
+```bash
+git clone https://github.com/deltafleet/codex-goalkeeper
+cd codex-goalkeeper
+npx skills add .
+```
+
+## 긴 Goal 시작
+
+작업 프로젝트에 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"
+```
+
+이 명령은 프로젝트 로컬 `.goalkeeper/` 디렉터리와 active session pointer를 만듭니다.
+
+## 다시 시작할 때
+
+새 turn, handoff 이후, compact가 의심되는 상황에서는 먼저 이 명령을 실행합니다.
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
+  --workspace <workspace>
+```
+
+짧은 checkpoint만으로 충분하지 않으면 context pack까지 읽습니다.
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
+  --workspace <workspace> \
+  --context
+```
+
+핵심은 간단합니다. 에이전트가 프로젝트를 건드리기 전에 현재 미션을 먼저 읽게 만드는 것입니다.
+
+## 중요한 것만 기록
+
+중요한 이벤트를 남깁니다.
+
+```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를 갱신합니다.
+
+```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."
+```
+
+긴 작업을 믿고 맡기기 전에 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 또는 compact 이후 Codex는 checkpoint.md를 먼저 읽는다
+  -> 필요하면 context-pack.md와 이벤트 근거를 더 읽는다
+```
+
+Goalkeeper는 compact를 없애지 않습니다. compact 이후 복구를 감이 아니라 상태에 의존하게 만듭니다.
+
+## 이것이 아닌 것
+
+- Codex plugin이 아닙니다.
+- MCP server가 아닙니다.
+- 데이터베이스가 아닙니다.
+- 전체 대화 transcript 저장소가 아닙니다.
+- private runtime hook이 아닙니다.
+- 완벽한 기억을 보장하지 않습니다.
+- compact 빈도를 줄여주지 않습니다.
+
+작은 습관일수록 실제 작업에서 오래 살아남습니다. 그래서 Goalkeeper는 작게 유지합니다.
+
+## 검증
+
+```bash
+npm run validate
+```
+
+수동으로는 다음을 실행합니다.
+
+```bash
+find src/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node src/scripts/test-goalkeeper-update-checkpoint.mjs
+npx skills add . --list
+```
+
+## 버전 관리
+
+Goalkeeper는 SemVer를 사용합니다.
+
+- Patch: 문서, 예제, 테스트, 호환 가능한 버그 수정
+- Minor: 호환 가능한 helper 또는 workflow field 추가
+- Major: checkpoint, event, script contract의 breaking change
+
+릴리스 절차는 [docs/RELEASE.md](docs/RELEASE.md)를 참고하세요.
+
+## 기여
+
+Issue와 PR은 환영합니다. 단, 프로젝트의 기준은 엄격합니다.
+
+- core workflow는 작게 유지한다
+- 숨겨진 runtime dependency를 추가하지 않는다
+- 완벽한 복구를 약속하지 않는다
+- global state보다 project-local file을 우선한다
+- 변경사항은 검증 명령으로 증명한다
+
+자세한 내용은 [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)를 참고하세요.
+
+## 라이선스
+
+MIT. [LICENSE](LICENSE)를 참고하세요.