@deltafleet/goalkeeper 0.2.0

package/README.md

@@ -0,0 +1,220 @@
+# Goalkeeper
+
+Long agent runs do not usually fail all at once.
+
+They drift.
+
+The agent still sounds confident. The tests still run. The plan still looks plausible. But after enough compaction, handoffs, and resumed turns, the session can quietly forget the thing that mattered most:
+
+> Why were we doing it this way?
+
+Goalkeeper is a small Agent Skill that helps Claude Code, Codex, and other skill-compatible coding agents keep long-running `/goal` work oriented across compaction, resumes, and handoffs.
+
+It does not add a hidden memory engine. It gives the agent a durable working ritual:
+
+- keep a short checkpoint
+- keep a richer context pack
+- append decisions and verification to an event log
+- read the checkpoint before continuing after drift-prone boundaries
+
+Boring files. Better continuity.
+
+[한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh-CN.md)
+
+## Install
+
+```bash
+npx skills add deltafleet/goalkeeper
+```
+
+To target specific agents explicitly:
+
+```bash
+npx skills add deltafleet/goalkeeper --agent claude-code codex
+```
+
+Requirements: Node.js 18+ and `npx`. The agent uses the skill's bundled Node helper scripts during long-goal workflows.
+
+Skill-compatible agents can automatically load installed skills when a request strongly matches their metadata. Goalkeeper is written to match `/goal`, long-running work, compaction, resume, handoff, and continuity-preservation language.
+
+So this can be enough:
+
+> `/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.
+
+But skill activation is still a routing decision, not a private runtime hook. Goalkeeper cannot force itself onto every goal.
+
+For important long-running work, the safest path is to be explicit when you create the goal, or immediately after creating it:
+
+> Use goalkeeper for this `/goal`. Keep the goal, constraints, decisions, verification state, failed attempts, and next action recoverable across compaction.
+
+After that, you should not have to run Goalkeeper's helper scripts yourself. The agent runs them as part of the skill workflow.
+
+## The Problem
+
+If you use an agent for small tasks, compaction is just a detail. The agent can usually recover.
+
+But long goals are different.
+
+Imagine a real session:
+
+1. You ask an agent to harden a release.
+2. The obvious patch fixes the visible bug, but would break rollback compatibility.
+3. You set a hard constraint: no database schema change, keep backward compatibility.
+4. A second attempt passes unit tests, but fails an integration edge case.
+5. The agent settles on a compatibility shim plus a targeted regression test.
+6. The regression test passes. That path is now the safe one.
+7. The context compacts.
+8. Later, the agent resumes from a clean summary: "release hardening mostly done."
+9. It still knows the goal, but may no longer feel why the schema shortcut stayed forbidden, why the first patches failed, or why that regression test mattered.
+
+That is where drift starts.
+
+The failure mode is not "the model forgot everything." It is worse: it remembers enough to continue, but not enough to continue in the same direction.
+
+You see it when an agent:
+
+- reopens an approach the user already rejected
+- repeats a failed attempt because the failure was summarized away
+- treats an unverified assumption as settled fact
+- loses the exact next action after a long handoff
+- preserves the goal but loses the operating constraints
+- gives a polished explanation that no longer matches the workstream
+
+Goalkeeper exists for that gap between "the goal is still known" and "the session still has its bearings."
+
+## What The Agent Does
+
+When the skill is active, the agent maintains a project-local continuity folder:
+
+```text
+.goalkeeper/
+  active-session
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
+```
+
+Each file has a different job:
+
+- `checkpoint.md` is the short "read this first" recovery state.
+- `context-pack.md` preserves the reasoning chain that is too detailed for the checkpoint.
+- `events.jsonl` records decisions, failed attempts, command evidence, verification, risks, and handoffs.
+
+The active goal says where the work is going. Goalkeeper preserves why this is still the right route.
+
+## How It Works
+
+Goalkeeper turns long agent work into a simple loop:
+
+```text
+Long /goal begins
+  -> the agent creates or resumes a Goalkeeper session
+  -> important constraints and decisions are recorded
+  -> failed attempts are kept so they are not repeated
+  -> verification evidence is logged when confidence changes
+  -> checkpoint.md is refreshed at meaningful boundaries
+  -> context-pack.md keeps the deeper reasoning chain
+  -> after resume, handoff, or suspected compaction, the agent reads checkpoint.md first
+  -> if the checkpoint is too thin, the agent reads context-pack.md
+  -> if exact proof is needed, the agent checks events.jsonl or source files
+```
+
+This is not transcript storage. It is working-state preservation.
+
+## Why It Is Small On Purpose
+
+The obvious version of this project is too big:
+
+- a daemon
+- a database
+- a session rewriter
+- a private runtime hook
+- a vector memory layer
+- a full transcript engine
+
+Goalkeeper intentionally avoids that.
+
+It uses files because files are visible, reviewable, portable, and easy for agents to read after compaction. The point is not to make the agent omniscient. The point is to make the next turn start from the right state.
+
+## What This Is Not
+
+- Not a Codex or Claude Code plugin.
+- Not an MCP server.
+- Not a database.
+- Not a transcript archive.
+- Not a private agent runtime hook.
+- Not a guarantee of perfect memory.
+- Not a way to reduce compaction frequency.
+
+Goalkeeper improves continuity. It does not pretend to eliminate context limits.
+
+## What Gets Better
+
+With Goalkeeper, a resumed session has a better chance to recover:
+
+- the user's non-negotiable constraints
+- the current implementation direction
+- the reason rejected alternatives stayed rejected
+- the tests or commands that changed confidence
+- the real next action
+- unresolved risks that should not be hand-waved away
+
+That is enough to prevent many of the boring, expensive failures in long agent runs.
+
+## Repository Layout
+
+```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
+
+For repository maintainers:
+
+```bash
+npm run validate
+```
+
+Equivalent manual checks:
+
+```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
+```
+
+## 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,220 @@
+# Goalkeeper
+
+长时间 agent 任务通常不是突然失败的。
+
+它们会慢慢偏离方向。
+
+Agent 仍然会显得很自信。测试仍然会运行。计划看起来也仍然合理。但经过多次 compaction、handoff 和 resume 之后，最重要的东西可能会悄悄变模糊：
+
+> 我们为什么要按这个方向做？
+
+Goalkeeper 是一个很小的 skill，用来帮助 Claude Code、Codex 以及其他 skill-compatible coding agents 在长时间 `/goal` 工作中跨越 compaction、resume 和 handoff 仍然保持方向。
+
+它不添加隐藏的记忆引擎。它给 agent 一个可持续的工作习惯：
+
+- 保持一个简短 checkpoint
+- 保持一个更丰富的 context pack
+- 把决策和验证写入 event log
+- 在容易发生 drift 的边界之后，继续前先读 checkpoint
+
+无聊的文件。更好的连续性。
+
+[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.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 scripts。
+
+当请求和 metadata 高度匹配时，Skill-compatible agent 可以自动加载已安装的 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，不是私有的 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 scripts。agent 会把它们作为 skill workflow 的一部分来运行。
+
+## 问题
+
+对于短任务，compaction 通常只是细节。Agent 大多能恢复。
+
+但长 goal 不一样。
+
+想象一个真实会话：
+
+1. 你让 agent 做 release hardening。
+2. 最显眼的 patch 能修掉眼前的 bug，但会破坏 rollback compatibility。
+3. 你设下硬约束：不能改 database schema，必须保持 backward compatibility。
+4. 第二次尝试通过了 unit tests，但在 integration edge case 上失败。
+5. agent 选择 compatibility shim 加 targeted regression test。
+6. regression test 通过了。这条路线现在是安全路线。
+7. 上下文被 compact。
+8. 后来 agent 带着整洁摘要回来：“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 把长时间 agent 工作变成一个简单循环：
+
+```text
+长 /goal 开始
+  -> agent 创建或恢复 Goalkeeper session
+  -> 记录重要约束和决策
+  -> 保留失败尝试，避免重复犯错
+  -> 在信心变化时记录验证证据
+  -> 在有意义的边界刷新 checkpoint.md
+  -> context-pack.md 保存更深的推理链
+  -> resume、handoff 或怀疑 compaction 后，agent 先读 checkpoint.md
+  -> 如果 checkpoint 太薄，agent 再读 context-pack.md
+  -> 如果需要精确证据，agent 检查 events.jsonl 或 source files
+```
+
+这不是保存对话 transcript。它保存的是工作状态。
+
+## 为什么故意做得很小
+
+把这个项目做大很容易：
+
+- daemon
+- database
+- session rewriter
+- private runtime hook
+- vector memory layer
+- full transcript engine
+
+Goalkeeper 故意避开这些。
+
+它使用文件，因为文件可见、可审查、可移动，并且 compaction 后 agent 容易重新读取。目标不是让 agent 全知全能。目标是让下一轮从正确状态开始。
+
+## 它不是什么
+
+- 不是 Codex 或 Claude Code plugin。
+- 不是 MCP server。
+- 不是 database。
+- 不是完整对话 transcript 仓库。
+- 不是 private agent runtime hook。
+- 不保证完美记忆。
+- 不会降低 compaction 频率。
+
+Goalkeeper 改善连续性。它不假装消除上下文限制。
+
+## 改善什么
+
+使用 Goalkeeper 后，恢复的会话更有机会找回：
+
+- 用户的 non-negotiable constraints
+- 当前实现方向
+- 被拒绝的替代方案为什么仍然应被拒绝
+- 改变信心的测试或命令
+- 真实的 next action
+- 不应该被轻描淡写带过的 unresolved risks
+
+长时间 agent 工作里很多无聊但昂贵的失败，只靠这些就能减少。
+
+## Repository Layout
+
+```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
+
+For repository maintainers:
+
+```bash
+npm run validate
+```
+
+Equivalent manual checks:
+
+```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
+```
+
+## 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/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 host-agent runtime hooks
+- global databases
+
+If a change introduces any of those, treat it as security-sensitive and document the reason clearly.

package/docs/RELEASE.md

@@ -0,0 +1,79 @@
+# Release Policy
+
+Goalkeeper is released as a GitHub repository and optional npm package.
+
+The installable skill source of truth is:
+
+- `src/goalkeeper/SKILL.md`
+- `src/goalkeeper/agents/openai.yaml`
+- `src/goalkeeper/scripts/`
+- `src/goalkeeper/references/`
+- `src/goalkeeper/templates/`
+- `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.

package/docs/ROADMAP.md

@@ -0,0 +1,77 @@
+# Roadmap
+
+## Product Thesis
+
+Long-running agent goals need a small continuity layer outside the model context.
+
+Goalkeeper should stay boring: a short checkpoint, a medium-density context pack, an append-only event log, a turn-start helper, and a doctor check. It should not become a substitute context engine or a promise of perfect post-compact recovery.
+
+## MVP
+
+Ship an agent skill under `src/goalkeeper/` that manages project-local state:
+
+```text
+.goalkeeper/
+  active-session
+  sessions/
+    <goal-session-id>/
+      checkpoint.md
+      context-pack.md
+      events.jsonl
+```
+
+Core behavior:
+
+- initialize a Goalkeeper session for a long-running goal
+- read the active checkpoint first after resume or suspected compaction
+- read the context pack when the checkpoint is too thin to recover pre-compaction reasoning
+- append meaningful decisions, failures, verification, and handoff events
+- refresh the checkpoint when recoverable working state changes
+- run a read-only doctor before trusting a workspace for long work
+
+## User-Facing Scope
+
+Keep these scripts central:
+
+- `goalkeeper-init.mjs`
+- `goalkeeper-turn-start.mjs`
+- `goalkeeper-append-event.mjs`
+- `goalkeeper-update-checkpoint.mjs`
+- `goalkeeper-doctor.mjs`
+
+Keep this optional and maintainer-oriented:
+
+- `tests/test-goalkeeper-update-checkpoint.mjs`
+
+## Non-Goals
+
+- no MCP server in the MVP
+- no host-agent plugin packaging in the MVP
+- no SQLite or global database
+- no background daemon
+- no prompt-assembly hook
+- no host-agent session rewriting
+- no claim of 100 percent compact recovery
+
+## Good Enough Release Bar
+
+- `npx skills add . --list` discovers exactly one skill named `goalkeeper`
+- the skill body is concise enough to load routinely
+- README explains the simple workflow clearly
+- multilingual READMEs keep the same public workflow in Korean, Japanese, and Chinese
+- examples parse as valid JSONL
+- script syntax checks pass
+- checkpoint update helper test passes
+- doctor passes against this repo's live Goalkeeper state
+
+## Later, Only If Needed
+
+Possible future additions should be justified by real usage:
+
+- a tiny CLI wrapper around the existing scripts
+- event search helper
+- checkpoint compaction helper
+- optional MCP ergonomics
+- cross-workspace indexing
+
+These should not change the source of truth: project-local `.goalkeeper/` files.

package/examples/goalkeeper-session/checkpoint.md

@@ -0,0 +1,58 @@
+# Goalkeeper Checkpoint
+
+## Active Goal
+
+- Objective: Ship a long-running agent feature without losing direction after repeated compaction.
+- Done criteria: The implementation, tests, documentation, and handoff are complete; no known blocker remains untracked.
+- Current status: Example state for Goalkeeper.
+
+## Throughline
+
+- Current direction: Preserve the user's intent, constraints, major decisions, verification state, and next action in a short project-local checkpoint.
+- Why this direction: The host agent's active goal describes the destination, but repeated compaction can blur the decision chain that explains how to keep moving.
+
+## Constraints
+
+- Non-negotiable: Read this checkpoint before resuming after compaction or handoff.
+- Non-negotiable: Append important evidence to `events.jsonl` before updating this checkpoint.
+- Forbidden approaches: Treating memory as exact proof when the event log or source files are needed.
+
+## Decisions
+
+- Runtime state lives under `.goalkeeper/sessions/<goal-session-id>/`.
+- The checkpoint stays concise and current.
+- The event log keeps append-only evidence.
+
+## Attempts And Failures
+
+- Avoid writing full transcripts into the checkpoint; it becomes too long to read routinely.
+- Avoid relying only on the active goal; it does not preserve enough decision context.
+
+## Important Files
+
+- `SKILL.md`
+- `.goalkeeper/sessions/<goal-session-id>/checkpoint.md`
+- `.goalkeeper/sessions/<goal-session-id>/context-pack.md`
+- `.goalkeeper/sessions/<goal-session-id>/events.jsonl`
+
+## Context Pack
+
+- `examples/goalkeeper-session/context-pack.md`
+
+## Verification
+
+- Verified: This is a static example, not a live project verification result.
+- Not yet verified: Replace this section with real command/test evidence during actual work.
+
+## Open Risks
+
+- Agents may skip reading the checkpoint unless the skill makes the recovery ritual explicit.
+- Checkpoints can become stale if not updated at meaningful transitions.
+
+## Next Action
+
+- Read recent events when this checkpoint is insufficient, then continue from the stated next action.
+
+## Last Updated
+
+- 2026-05-17