@deltafleet/codex-goalkeeper 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# Codex Goalkeeper
+
+Context compaction does not kill long Codex runs. Direction drift does.
+
+Codex Goalkeeper is a tiny skill that helps Codex keep its bearings during long `/goal` sessions, repeated compactions, handoffs, and multi-day implementation work.
+
+It does not try to be a hidden memory engine. It gives the agent a simple ritual:
+
+1. Write down the current mission.
+2. Preserve the reasoning that should survive compaction.
+3. Record decisions, failures, and verification as evidence.
+4. Read the checkpoint first before continuing.
+
+That is it. Boring files. Better continuity.
+
+[한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh-CN.md)
+
+## The Problem
+
+Long agent sessions do not usually fail because the model forgets a random detail. They fail because the "why" gets blurred:
+
+- why a direction was chosen
+- what the user explicitly ruled out
+- which attempt already failed
+- what was actually verified
+- what the next action was supposed to be
+
+After enough compaction, a session can still sound confident while quietly losing the thread.
+
+Goalkeeper makes the thread explicit.
+
+## What It Creates
+
+Goalkeeper stores state inside the project you are working on:
+
+```text
+.goalkeeper/
+  active-session
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
+```
+
+The three files have different jobs:
+
+- `checkpoint.md`: short, always-read recovery state
+- `context-pack.md`: medium-density reasoning that should survive compaction
+- `events.jsonl`: append-only evidence for decisions, failures, commands, risks, and handoffs
+
+The active Codex goal says where you are going. Goalkeeper preserves how not to get lost on the way.
+
+## Install
+
+With the Skills CLI:
+
+```bash
+npx skills add deltafleet/codex-goalkeeper
+```
+
+From a local checkout:
+
+```bash
+git clone https://github.com/deltafleet/codex-goalkeeper
+cd codex-goalkeeper
+npx skills add .
+```
+
+## Start A Long Goal
+
+Create a Goalkeeper session in your project:
+
+```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"
+```
+
+This creates the project-local `.goalkeeper/` directory and sets the active session pointer.
+
+## Resume Correctly
+
+At the start of a new turn, after handoff, or after suspected compaction:
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
+  --workspace <workspace>
+```
+
+If the short checkpoint is not enough:
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs \
+  --workspace <workspace> \
+  --context
+```
+
+This is the core behavior. The agent reads the current mission before touching the rest of the project.
+
+## Record What Matters
+
+Append meaningful events:
+
+```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."
+```
+
+Refresh the checkpoint after a real state change:
+
+```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."
+```
+
+Check the workspace before trusting it for a long run:
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-doctor.mjs \
+  --workspace <workspace> \
+  --session 2026-05-18-release-hardening \
+  --strict
+```
+
+## A Typical Loop
+
+```text
+User starts a long /goal
+  -> Goalkeeper initializes a project-local session
+  -> Codex works normally
+  -> important decisions and verification go into events.jsonl
+  -> checkpoint.md is refreshed at meaningful boundaries
+  -> context-pack.md preserves the reasoning chain
+  -> after resume or compaction, Codex reads checkpoint.md first
+  -> if needed, Codex reads context-pack.md and exact event evidence
+```
+
+Goalkeeper does not remove compaction. It makes recovery from compaction less dependent on vibes.
+
+## What This Is Not
+
+- Not a Codex plugin.
+- Not an MCP server.
+- Not a database.
+- Not a transcript archive.
+- Not a private runtime hook.
+- Not a promise of perfect memory.
+- Not a way to reduce compaction frequency.
+
+Goalkeeper is intentionally small because small rituals survive real work.
+
+## Why It Works
+
+Agent memory fails when the only durable state is the conversation itself.
+
+Goalkeeper moves the minimum useful continuity state into the repository:
+
+- constraints become visible
+- decisions become inspectable
+- failed paths stop repeating
+- verification survives handoff
+- the next action is explicit
+
+The model still has to do the work. Goalkeeper just gives it a better starting point after the context window gets rewritten.
+
+## Repository Layout
+
+```text
+SKILL.md                    # skill entrypoint
+agents/openai.yaml          # skill metadata
+src/scripts/                # deterministic helpers
+src/templates/              # starter Goalkeeper files
+src/references/             # workflow and schema references
+examples/goalkeeper-session # static example state
+docs/                       # roadmap and release policy
+```
+
+## Validation
+
+```bash
+npm run validate
+```
+
+Equivalent manual checks:
+
+```bash
+find src/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node src/scripts/test-goalkeeper-update-checkpoint.mjs
+npx skills add . --list
+```
+
+## Versioning
+
+Goalkeeper uses SemVer.
+
+- Patch: docs, examples, tests, and compatible bug fixes
+- Minor: new compatible helpers or workflow fields
+- Major: breaking changes to checkpoint, event, or script contracts
+
+See [docs/RELEASE.md](docs/RELEASE.md) for release steps.
+
+## Contributing
+
+Issues and PRs are welcome. The project bias is strict:
+
+- keep the core workflow small
+- do not add hidden runtime dependencies
+- do not promise perfect recovery
+- prefer project-local files over global state
+- prove changes with the validation commands above
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,197 @@
+# Codex Goalkeeper
+
+让长时间 Codex 任务失败的，通常不是上下文压缩本身，而是方向漂移。
+
+Codex Goalkeeper 是一个很小的 skill，用来帮助 Codex 在长时间 `/goal` 会话、反复 compaction、handoff、跨天实现任务中保持方向。
+
+它不伪装成隐藏的记忆引擎。它只让 agent 养成一个简单习惯：
+
+1. 写下当前任务。
+2. 保存 compaction 后仍然需要保留的推理链。
+3. 把决策、失败和验证结果记录为事件。
+4. 继续工作前先读取 checkpoint。
+
+就这些。无聊的文件。更好的连续性。
+
+[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
+
+## 问题
+
+长时间 agent 会话通常不是因为忘了某个小细节而失败，而是因为 `为什么要这样做` 变得模糊。
+
+- 为什么选择这个方向
+- 用户明确禁止了什么
+- 哪些尝试已经失败
+- 什么是真的验证过的
+- 下一步原本应该做什么
+
+经过多次 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
+```
+
+核心行为很简单：agent 在触碰项目其它文件之前，先读当前任务状态。
+
+## 只记录真正重要的东西
+
+追加重要事件：
+
+```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: 文档、示例、测试、兼容性 bug 修复
+- Minor: 新增兼容 helper 或 workflow field
+- Major: checkpoint、event 或 script contract 的破坏性变更
+
+发布步骤见 [docs/RELEASE.md](docs/RELEASE.md)。
+
+## 贡献
+
+欢迎 issue 和 PR。但项目的取舍很严格：
+
+- 保持 core workflow 足够小
+- 不添加隐藏 runtime dependency
+- 不承诺完美恢复
+- 优先使用 project-local files，而不是 global state
+- 用验证命令证明改动
+
+请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+The latest minor release receives security fixes.
+
+During the `0.x` series, APIs may still evolve, but security fixes will be released as patch versions whenever possible.
+
+## Reporting A Vulnerability
+
+Do not open a public issue for a vulnerability.
+
+Report security concerns through GitHub private vulnerability reporting when available, or contact the maintainers through the repository owner profile.
+
+Include:
+
+- affected version or commit
+- reproduction steps
+- expected impact
+- whether the issue exposes local files, credentials, or private project state
+
+## Project Boundaries
+
+Goalkeeper stores state in project-local `.goalkeeper/` directories. It should not require:
+
+- secret tokens
+- background daemons
+- network access for normal helper scripts
+- private Codex runtime hooks
+- global databases
+
+If a change introduces any of those, treat it as security-sensitive and document the reason clearly.

package/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: codex-goalkeeper
+description: Use automatically for Codex /goal work, long-running goals, multi-turn implementations, session resumes, handoffs, compacted conversations, or any task where Codex must preserve constraints, decisions, verification state, failed attempts, pre-compaction reasoning, and next actions. Maintains a project-local checkpoint, context pack, and append-only event log.
+---
+
+# Codex Goalkeeper
+
+Use this skill when a Codex task is expected to run long enough that compaction, handoff, or drift could cause the agent to lose direction.
+
+Goalkeeper does not replace Codex's goal system. It records the working continuity around the goal.
+
+Goalkeeper is a best-effort continuity habit, not a guarantee that every compacted turn will recover perfectly.
+
+When a user starts or continues a `/goal`, strongly prefer initializing or resuming Goalkeeper unless the task is clearly short-lived.
+
+## First Action Rule
+
+When a Goalkeeper-managed goal is already active, the first project-state action in a new assistant turn should be reading the active checkpoint, unless you have already read it in the same turn.
+
+This is stricter than waiting until you notice compaction. A compacted turn may not reliably expose the compaction marker to the model, so checkpoint-first is the practical recovery rule for long-running goals.
+
+Allowed before the checkpoint read:
+
+- `pwd`
+- listing `.goalkeeper/sessions/`
+- minimal filename inspection to choose the active Goalkeeper session id
+
+Do not send a user-visible progress or direction message before the checkpoint read.
+Do not read project docs, source files, examples, tests, or make edits before the checkpoint read.
+Do not combine the checkpoint read with other post-recovery work in the same shell command or parallel tool batch.
+
+## Required Files
+
+Use a project-local `.goalkeeper/` directory. Each long-running goal session gets its own subdirectory:
+
+```text
+.goalkeeper/
+  active-session  # optional: current goal session id
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
+```
+
+Use a stable, readable `<goal-session-id>` such as `2026-05-17-codex-goalkeeper-roadmap` or `ads-ops-release-hardening`.
+
+If any core file is missing during long goal work, create it from the templates in `src/templates/`.
+Use `.goalkeeper/active-session` when a workspace has one active Goalkeeper session and the agent should not have to reconstruct the session id after compaction.
+
+The directory is created inside the active project workspace, not in a global Codex directory. Example:
+
+```text
+/path/to/project/.goalkeeper/sessions/2026-05-17-release-hardening/checkpoint.md
+```
+
+Bundled scripts live in the skill package. When the script is not located inside the target workspace, pass the target workspace explicitly:
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs --workspace <workspace> --session <goal-session-id>
+```
+
+If `<workspace>/.goalkeeper/active-session` points to the session id, `--session` may be omitted:
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs --workspace <workspace>
+```
+
+To create a new session deterministically, run:
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-init.mjs --workspace <workspace> --session <goal-session-id> --goal "<active goal>"
+```
+
+## Recovery Rule
+
+Before continuing after a resume, suspected compaction, long interruption, or handoff:
+
+1. Resolve the current goal session directory under `.goalkeeper/sessions/`.
+2. Read its `checkpoint.md`.
+3. If the checkpoint is stale, too thin, or missing the reasoning chain, read `context-pack.md`.
+4. If exact evidence is needed, inspect recent entries in `events.jsonl`.
+5. Restate the active direction internally before taking action.
+6. Continue only when the next action matches the recovered goal, constraints, and open risks.
+
+After compaction, do not rely on the compacted conversation summary alone. Read the Goalkeeper checkpoint before continuing.
+
+## Recovery Guardrail
+
+After a visible compact boundary, the first project-state action must be a Goalkeeper recovery read:
+
+```text
+<workspace>/.goalkeeper/sessions/<goal-session-id>/checkpoint.md
+```
+
+If you notice that you already continued without the checkpoint, stop, read the checkpoint, append a `recovery_violation` event, then continue from the recovered state.
+
+## Update Rule
+
+Update Goalkeeper state when any of these change:
+
+- active goal or done criteria
+- user constraints or forbidden approaches
+- major design decision
+- failed attempt that should not be repeated
+- important file or artifact path
+- command result or verification status
+- open risk, blocker, or next action
+- handoff boundary
+
+Append the event first, then update the session's `checkpoint.md` when the event changes the current working state.
+Use `src/scripts/goalkeeper-update-checkpoint.mjs` when you want a bounded canonical checkpoint instead of manual Markdown edits.
+
+## Keep It Short
+
+The checkpoint is a recovery artifact, not a transcript.
+
+Keep it under about 8 KB when possible. If it grows beyond 16 KB, compact stale details into `events.jsonl` evidence references before relying on it for routine recovery.
+
+Prefer:
+
+- exact goal
+- current throughline
+- non-negotiable constraints
+- decisions that explain direction
+- verified facts
+- open risks
+- next action
+
+Avoid:
+
+- narrative summaries of every turn
+- long command output
+- speculative history
+- stale alternatives that no longer matter
+
+## Context Pack
+
+Use `context-pack.md` for medium-density pre-compaction context that is too detailed for the checkpoint:
+
+- decision chain and reasoning
+- rejected alternatives
+- open threads
+- domain model or implementation model
+- evidence index for where exact facts live
+
+Read it when checkpoint recovery is not enough. Keep raw transcripts and long command output out of it.
+
+## Reference Map
+
+- Read `src/references/workflow.md` for lifecycle rules and examples.
+- Read `src/references/event-schema.md` before adding or validating event records.
+- Read `src/references/guardrail.md` when you need stronger always-on behavior in a target repository.
+- Run `src/scripts/goalkeeper-init.mjs` when a long-running goal needs a new `.goalkeeper/sessions/<goal-session-id>/` directory.
+- Run `src/scripts/goalkeeper-turn-start.mjs --context` when checkpoint recovery needs the larger context pack too.
+- Run `src/scripts/goalkeeper-append-event.mjs` instead of hand-writing JSONL when recording decisions, verification, failures, risks, or handoffs; it can use `.goalkeeper/active-session` when `--session` is omitted.
+- Run `src/scripts/goalkeeper-update-checkpoint.mjs` after appending a meaningful event when checkpoint state should be refreshed in a short canonical shape.
+- Run `src/scripts/goalkeeper-doctor.mjs` after creating or changing Goalkeeper state to verify the target workspace is ready.
+
+## Safety Boundary
+
+- Do not depend on private Codex runtime internals.
+- Do not claim this reduces compaction frequency.
+- Do not treat the checkpoint as proof when exact evidence is needed; inspect `events.jsonl` or source files.

package/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Codex Goalkeeper"
+  short_description: "Keep Codex goals oriented"
+  default_prompt: "Use $codex-goalkeeper for this /goal or long-running Codex task so checkpoint, context pack, and event log preserve direction across compaction."
+  brand_color: "#2563EB"

package/docs/RELEASE.md

@@ -0,0 +1,77 @@
+# Release Policy
+
+Codex Goalkeeper is released as a GitHub repository and optional npm package.
+
+The skill source of truth is the repository root:
+
+- `SKILL.md`
+- `agents/openai.yaml`
+- `src/`
+- `examples/`
+- `docs/`
+
+## Versioning
+
+Use SemVer.
+
+- `PATCH`: documentation, examples, tests, and compatible bug fixes
+- `MINOR`: compatible helper scripts, metadata, templates, or workflow fields
+- `MAJOR`: breaking changes to checkpoint, context-pack, event, or script contracts
+
+During `0.x`, minor releases may still adjust public contracts. Document those changes clearly in `CHANGELOG.md`.
+
+## Release Checklist
+
+1. Update `package.json` version.
+2. Update `CHANGELOG.md`.
+3. Run validation:
+
+   ```bash
+   npm run validate
+   ```
+
+4. Confirm the public package does not include local Goalkeeper state:
+
+   ```bash
+   git status --short --ignored
+   npm pack --dry-run
+   ```
+
+5. Commit:
+
+   ```bash
+   git commit -m "Release vX.Y.Z"
+   ```
+
+6. Tag:
+
+   ```bash
+   git tag vX.Y.Z
+   ```
+
+7. Push:
+
+   ```bash
+   git push origin main --tags
+   ```
+
+8. Create a GitHub release:
+
+   ```bash
+   GH_CONFIG_DIR=$HOME/.config/gh-deltafleet gh release create vX.Y.Z --generate-notes
+   ```
+
+9. Optional npm publish:
+
+   ```bash
+   npm --userconfig ~/.config/npm-deltafleet/npmrc publish --access public
+   ```
+
+## Deltafleet Credentials
+
+This repository can be published with the local deltafleet profiles:
+
+- GitHub CLI: `GH_CONFIG_DIR=$HOME/.config/gh-deltafleet`
+- npm: `npm --userconfig ~/.config/npm-deltafleet/npmrc`
+
+Never commit these config files or token values.