@deltafleet/goalkeeper 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to Goalkeeper are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-05-18
+
+- Renamed the public project to `goalkeeper`.
+- Renamed the npm package to `@deltafleet/goalkeeper`.
+- Generalized the skill for Claude Code, Codex, and other skill-compatible coding agents.
+- Added a Claude Code guardrail template and doctor support for `CLAUDE.md`.
+- Kept backward-compatible `codex-goalkeeper-*` CLI aliases for existing users.
+
+## [0.1.1] - 2026-05-18
+
+- Moved the installable skill payload into `src/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.
+
+- Added the `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
+
+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 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 host-agent 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/goalkeeper/scripts tests -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node tests/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,220 @@
+# Goalkeeper
+
+長い agent 作業は、たいてい一気に壊れるわけではありません。
+
+少しずつ方向を失います。
+
+エージェントはまだ自信ありげに話します。テストも実行します。計画も一見もっともらしいままです。しかし compaction、handoff、resume が重なると、いちばん重要な感覚が静かに薄れていきます。
+
+> なぜ、この方針で進んでいたのか？
+
+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/goalkeeper
+```
+
+特定の agent を明示する場合:
+
+```bash
+npx skills add deltafleet/goalkeeper --agent claude-code codex
+```
+
+要件: Node.js 18+ と `npx`。長い goal workflow で、agent は skill に同梱された Node helper script を使います。
+
+Skill-compatible agent は、リクエストが metadata と強く一致する installed skill を自動で読み込むことがあります。Goalkeeper の metadata は `/goal`、長い作業、compaction、resume、handoff、continuity preservation に反応するように書かれています。
+
+そのため、次のような goal だけで有効になることがあります。
+
+> `/goal` Harden this release over a long-running session. Keep the goal, constraints, rejected paths, failed attempts, verification state, and next action recoverable after compact/resume.
+
+ただし skill activation は routing decision であり、private agent runtime hook ではありません。Goalkeeper がすべての goal に強制的に自分を適用することはできません。
+
+重要な長期作業では、goal を作る時点、または goal 作成直後で本格作業に入る前に、明示的に呼び出すのがもっとも安全です。
+
+> Use goalkeeper for this `/goal`. Keep the goal, constraints, decisions, verification state, failed attempts, and next action recoverable across compaction.
+
+その後、ユーザーが Goalkeeper の helper script を手で実行する必要はありません。agent が skill workflow の一部として実行します。
+
+## 問題
+
+短い作業なら、compaction はたいてい大きな問題になりません。エージェントは大まかに復旧できます。
+
+しかし長い goal は違います。
+
+実際のセッションを想像してください。
+
+1. agent にリリース hardening を任せます。
+2. いちばん分かりやすい patch は目の前の bug を直しますが、rollback compatibility を壊す可能性があります。
+3. ユーザーは強い制約を置きます。database schema は変更せず、backward compatibility を維持する。
+4. 2 回目の試行は unit test を通りますが、integration edge case で失敗します。
+5. agent は compatibility shim と targeted regression test の組み合わせに決めます。
+6. regression test が通ります。このルートが安全なルートになります。
+7. コンテキストが compact されます。
+8. 後でエージェントは「release hardening はほぼ完了」というきれいな要約で戻ってきます。
+9. goal は残っています。しかし、なぜ schema shortcut を禁止し続ける必要があるのか、なぜ前の patch が失敗したのか、なぜその regression test が重要なのかは薄れているかもしれません。
+
+ここから drift が始まります。
+
+失敗の原因は「モデルが全部忘れた」ことではありません。もっと厄介です。続けるだけの記憶はあるが、同じ方向で続けるだけの記憶がないのです。
+
+それは次のような形で現れます。
+
+- ユーザーがすでに拒否した方針を再び開く
+- 失敗理由が要約から落ち、同じ試行を繰り返す
+- 未検証の仮説を確定事実のように扱う
+- 長い handoff の後で正確な next action を失う
+- goal は残るが運用上の制約を失う
+- 説明は滑らかだが実際の作業ストリームからずれる
+
+Goalkeeper は「goal は残っているが、セッションの方向感覚が弱くなった」その隙間を埋めるためのものです。
+
+## Agent がすること
+
+skill が有効になると、agent はプロジェクト内に継続性フォルダを維持します。
+
+```text
+.goalkeeper/
+  active-session
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
+```
+
+それぞれの役割は違います。
+
+- `checkpoint.md`: 再開時に最初に読む短い復旧状態
+- `context-pack.md`: checkpoint には長すぎるが compaction 後も残すべき判断理由
+- `events.jsonl`: 決定、失敗した試行、コマンド根拠、検証、リスク、handoff の記録
+
+active goal が目的地なら、Goalkeeper はなぜこのルートがまだ正しいのかを保ちます。
+
+## 仕組み
+
+Goalkeeper は長いエージェント作業を単純なループにします。
+
+```text
+長い /goal が始まる
+  -> agent が Goalkeeper セッションを作成または再開する
+  -> 重要な制約と決定を記録する
+  -> 失敗した試行を残し、同じ失敗を繰り返さないようにする
+  -> 信頼度が変わる検証根拠を残す
+  -> 意味のある境界で checkpoint.md を更新する
+  -> context-pack.md が深い判断理由を保つ
+  -> resume、handoff、compaction が疑われる後、agent は checkpoint.md を最初に読む
+  -> checkpoint が薄ければ context-pack.md を読む
+  -> 正確な証拠が必要なら events.jsonl または source file を確認する
+```
+
+これは会話 transcript の保存ではありません。作業状態の保存です。
+
+## あえて小さくしています
+
+このプロジェクトを大きくするのは簡単です。
+
+- daemon
+- database
+- session rewriter
+- private runtime hook
+- vector memory layer
+- full transcript engine
+
+Goalkeeper は意図的にその方向を避けます。
+
+ファイルを使う理由は、見える、レビューできる、移動しやすい、そして compaction 後にエージェントが読み返しやすいからです。目的は agent を全知にすることではありません。次の turn を正しい状態から始めることです。
+
+## これは何ではないか
+
+- Codex または Claude Code plugin ではありません。
+- MCP server ではありません。
+- database ではありません。
+- 完全な会話 transcript の保存庫ではありません。
+- private agent runtime hook ではありません。
+- 完璧な記憶を保証しません。
+- compaction の頻度を下げません。
+
+Goalkeeper は継続性を改善します。コンテキスト制限が消えるふりはしません。
+
+## 何が良くなるか
+
+Goalkeeper を使うと、再開されたセッションが次を復旧できる可能性が上がります。
+
+- ユーザーの non-negotiable constraints
+- 現在の実装方向
+- 拒否した代替案がなぜ今も拒否されるべきか
+- 信頼度を変えたテストやコマンド
+- 実際の next action
+- 雑に流してはいけない unresolved risks
+
+長いエージェント作業で起きる退屈で高くつく失敗の多くは、これだけでも減らせます。
+
+## リポジトリ構成
+
+```text
+src/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
+```
+
+## Maintainer Validation
+
+リポジトリ maintainer 向けの検証です。
+
+```bash
+npm run validate
+```
+
+手動では次を実行します。
+
+```bash
+find src/goalkeeper/scripts tests -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node tests/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,220 @@
+# Goalkeeper
+
+긴 agent 작업은 보통 한 번에 망가지지 않습니다.
+
+조금씩 방향을 잃습니다.
+
+에이전트는 여전히 자신 있게 말합니다. 테스트도 돌립니다. 계획도 그럴듯해 보입니다. 그런데 compact, handoff, resume이 반복된 뒤에는 가장 중요한 감각이 조용히 흐려질 수 있습니다.
+
+> 우리가 왜 이 방향으로 가고 있었지?
+
+Goalkeeper는 긴 `/goal` 작업이 compact, resume, handoff를 지나도 방향을 잃지 않도록 돕는 작은 skill입니다.
+
+숨겨진 메모리 엔진을 추가하지 않습니다. 대신 에이전트에게 지속 가능한 작업 습관을 줍니다.
+
+- 짧은 checkpoint를 유지한다
+- 더 풍부한 context pack을 유지한다
+- 결정과 검증을 event log에 남긴다
+- drift가 생기기 쉬운 경계 이후에는 계속하기 전에 checkpoint를 먼저 읽는다
+
+지루한 파일들. 더 나은 연속성.
+
+[English](README.md) | [日本語](README.ja.md) | [中文](README.zh-CN.md)
+
+## 설치
+
+```bash
+npx skills add deltafleet/goalkeeper
+```
+
+특정 agent를 명시하려면 다음처럼 설치할 수 있습니다.
+
+```bash
+npx skills add deltafleet/goalkeeper --agent claude-code codex
+```
+
+요구사항: Node.js 18+와 `npx`. 긴 goal workflow에서 agent가 skill에 포함된 Node helper script를 사용합니다.
+
+Skill-compatible agent는 설치된 skill 중 요청과 관련성이 높은 skill을 자동으로 불러올 수 있습니다. Goalkeeper의 metadata는 `/goal`, 긴 작업, compact, resume, handoff, continuity 보존 신호에 반응하도록 작성되어 있습니다.
+
+그래서 아래처럼 goal 자체가 충분히 분명하면 자동으로 붙을 수 있습니다.
+
+> `/goal` 이번 릴리스를 장기 세션으로 안정화해줘. compact/resume 이후에도 목표, 제약, 거부한 경로, 실패한 시도, 검증 상태, 다음 액션이 복구 가능하게 관리해줘.
+
+하지만 skill 활성화는 agent runtime hook이 아니라 routing 판단입니다. Goalkeeper가 모든 goal에 자신을 강제로 붙일 수는 없습니다.
+
+중요한 장기 작업이라면 goal을 만들 때, 또는 goal을 만든 직후 본격 작업 전에 명시적으로 호출하는 편이 가장 안전합니다.
+
+> 이 `/goal`에는 goalkeeper를 사용해줘. 목표, 제약, 결정, 검증 상태, 실패한 시도, 다음 액션이 compact 이후에도 복구 가능하게 관리해줘.
+
+그 다음부터 사용자가 Goalkeeper의 helper script를 직접 실행할 필요는 없습니다. agent가 skill workflow의 일부로 실행합니다.
+
+## 문제
+
+짧은 작업에서 compact는 대개 큰 문제가 아닙니다. 에이전트가 대충 복구할 수 있습니다.
+
+하지만 긴 goal은 다릅니다.
+
+실제 세션을 상상해보면 이렇습니다.
+
+1. agent에게 릴리스 hardening을 맡깁니다.
+2. 가장 쉬운 patch는 눈앞의 bug는 고치지만 rollback compatibility를 깨뜨릴 수 있습니다.
+3. 사용자는 강한 제약을 둡니다. database schema는 바꾸지 말고, backward compatibility를 유지해야 합니다.
+4. 두 번째 시도는 unit test를 통과하지만 integration edge case에서 실패합니다.
+5. agent는 compatibility shim과 targeted regression test 조합으로 방향을 정합니다.
+6. regression test가 통과합니다. 이제 이 경로가 안전한 경로입니다.
+7. 컨텍스트가 compact됩니다.
+8. 나중에 에이전트는 “release hardening은 거의 됨” 같은 깔끔한 요약으로 돌아옵니다.
+9. goal은 기억하지만, 왜 schema shortcut이 계속 금지되어야 하는지, 앞선 patch들이 왜 실패했는지, 그 regression test가 왜 중요한지는 희미해질 수 있습니다.
+
+여기서 drift가 시작됩니다.
+
+실패 원인은 “모델이 전부 잊었다”가 아닙니다. 더 까다롭습니다. 계속할 만큼은 기억하지만, 같은 방향으로 계속할 만큼은 기억하지 못합니다.
+
+이런 순간에 드러납니다.
+
+- 사용자가 이미 거부한 접근을 다시 연다
+- 실패 이유가 요약에서 사라져 같은 시도를 반복한다
+- 검증되지 않은 가정을 확정 사실처럼 다룬다
+- 긴 handoff 뒤에 정확한 next action을 잃는다
+- goal은 유지하지만 운영 제약을 잃는다
+- 설명은 매끄럽지만 실제 작업 흐름과 어긋난다
+
+Goalkeeper는 “goal은 남아 있지만 세션의 방향 감각은 약해진” 그 틈을 메우기 위한 도구입니다.
+
+## Agent가 하는 일
+
+skill이 활성화되면 agent는 프로젝트 안에 연속성 폴더를 유지합니다.
+
+```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 기록
+
+active goal이 목적지를 말한다면, Goalkeeper는 왜 이 경로가 아직 맞는지를 보존합니다.
+
+## 동작 원리
+
+Goalkeeper는 긴 에이전트 작업을 단순한 루프로 바꿉니다.
+
+```text
+긴 /goal이 시작된다
+  -> agent가 Goalkeeper 세션을 만들거나 재개한다
+  -> 중요한 제약과 결정을 기록한다
+  -> 실패한 시도를 남겨 같은 삽질을 반복하지 않게 한다
+  -> 신뢰도가 바뀌는 검증 근거를 남긴다
+  -> 의미 있는 경계마다 checkpoint.md를 갱신한다
+  -> context-pack.md가 더 깊은 판단 근거를 보존한다
+  -> resume, handoff, compact 의심 이후 agent는 checkpoint.md를 먼저 읽는다
+  -> checkpoint가 얇으면 context-pack.md를 읽는다
+  -> 정확한 증거가 필요하면 events.jsonl이나 source file을 확인한다
+```
+
+이것은 대화 transcript 저장이 아닙니다. 작업 상태 보존입니다.
+
+## 일부러 작게 만들었습니다
+
+이 프로젝트를 크게 만드는 방법은 쉽습니다.
+
+- daemon
+- database
+- session rewriter
+- private runtime hook
+- vector memory layer
+- full transcript engine
+
+Goalkeeper는 의도적으로 그 방향을 피합니다.
+
+파일을 쓰는 이유는 파일이 보이고, 검토 가능하고, 옮기기 쉽고, compact 이후에도 에이전트가 다시 읽기 쉽기 때문입니다. 목표는 agent를 전지전능하게 만드는 것이 아닙니다. 다음 turn이 올바른 상태에서 시작하게 만드는 것입니다.
+
+## 이것이 아닌 것
+
+- Codex 또는 Claude Code plugin이 아닙니다.
+- MCP server가 아닙니다.
+- 데이터베이스가 아닙니다.
+- 전체 대화 transcript 저장소가 아닙니다.
+- private agent runtime hook이 아닙니다.
+- 완벽한 기억을 보장하지 않습니다.
+- compact 빈도를 줄이지 않습니다.
+
+Goalkeeper는 연속성을 개선합니다. 컨텍스트 한계를 없애는 척하지 않습니다.
+
+## 좋아지는 것
+
+Goalkeeper를 쓰면 resume된 세션이 다음을 복구할 가능성이 높아집니다.
+
+- 사용자의 non-negotiable constraints
+- 현재 구현 방향
+- 거부된 대안이 왜 여전히 거부되어야 하는지
+- 신뢰도를 바꾼 테스트나 명령
+- 실제 next action
+- 대충 넘기면 안 되는 unresolved risks
+
+긴 에이전트 작업에서 발생하는 지루하고 비싼 실패 상당수는 이 정도만으로도 줄어듭니다.
+
+## 저장소 구조
+
+```text
+src/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
+```
+
+## Maintainer Validation
+
+저장소 maintainer용 검증입니다.
+
+```bash
+npm run validate
+```
+
+수동으로는 다음을 실행합니다.
+
+```bash
+find src/goalkeeper/scripts tests -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node tests/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)를 참고하세요.