@deltafleet/goalkeeper 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Goalkeeper are documented here.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-05-18
+
+- Added `goalkeeper-close.mjs` so agents can shut down Goalkeeper sessions when a goal completes.
+- Added the `close` event type and `closed` event status.
+- Added shutdown instructions so Goalkeeper stops applying checkpoint-first recovery to unrelated questions after completion.
+
+## [0.2.1] - 2026-05-18
+
+- Simplified public invocation copy to `Use goalkeeper for this goal.`
+- Rewrote the README problem example around a clearer long-session payment bug scenario.
+- Shortened the UI default prompt so users are not asked to spell out Goalkeeper internals.
+
 ## [0.2.0] - 2026-05-18
 
 - Renamed the public project to `goalkeeper`.

package/CONTRIBUTING.md

@@ -18,7 +18,7 @@ The project has one strong bias: keep the core small enough that agents will act
 - Background processes.
 - Runtime hooks into private host-agent internals.
 - Global databases or cross-project indexing.
-- Large abstractions around the five core helper scripts.
+- Large abstractions around the six core helper scripts.
 
 These may be useful later, but they should not enter the project without a clear real-world failure case.
 

package/README.ja.md

@@ -39,15 +39,15 @@ Skill-compatible agent は、リクエストが metadata と強く一致する i
 
 そのため、次のような 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.
+> `/goal` Harden this release over a long-running session. Use goalkeeper.
 
 ただし 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.
+> Use goalkeeper for this goal.
 
-その後、ユーザーが Goalkeeper の helper script を手で実行する必要はありません。agent が skill workflow の一部として実行します。
+ユーザーが覚える必要がある文はここまでです。checkpoint、context pack、event log、失敗した試行、検証状態、helper script は、Goalkeeper workflow の中で agent が扱います。
 
 ## 問題
 
@@ -57,15 +57,15 @@ Skill-compatible agent は、リクエストが metadata と強く一致する i
 
 実際のセッションを想像してください。
 
-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 が通ります。このルートが安全なルートになります。
+1. agent に決済バグの修正を任せます。
+2. 早い段階で、`refunds` 周りのコードは legacy なので触るべきではないと分かります。
+3. 最速の patch は `refunds` を直接編集する方法なので、ユーザーはその方針を拒否します。
+4. agent は webhook handler 側に移そうとしますが、duplicate event のケースで失敗します。
+5. 最終的に service layer に idempotency guard を置き、regression test で検証するルートが通ります。
+6. テストが通ります。このルートが維持すべき安全なルートになります。
 7. コンテキストが compact されます。
-8. 後でエージェントは「release hardening はほぼ完了」というきれいな要約で戻ってきます。
-9. goal は残っています。しかし、なぜ schema shortcut を禁止し続ける必要があるのか、なぜ前の patch が失敗したのか、なぜその regression test が重要なのかは薄れているかもしれません。
+8. 後でエージェントは「決済バグはほぼ修正済み」というきれいな要約で戻ってきます。
+9. goal は残っています。しかし、`refunds` が触ってはいけない場所だったこと、webhook の試行が失敗したこと、service-layer test が安全なルートを証明したことは薄れているかもしれません。
 
 ここから drift が始まります。
 
@@ -119,10 +119,14 @@ Goalkeeper は長いエージェント作業を単純なループにします。
   -> resume、handoff、compaction が疑われる後、agent は checkpoint.md を最初に読む
   -> checkpoint が薄ければ context-pack.md を読む
   -> 正確な証拠が必要なら events.jsonl または source file を確認する
+  -> goal が完了したら、agent が Goalkeeper セッションを閉じる
+  -> その後の無関係な質問には Goalkeeper recovery を適用しない
 ```
 
 これは会話 transcript の保存ではありません。作業状態の保存です。
 
+Goalkeeper は永遠に張り付くべきではありません。管理していた goal が完了したら、agent は最終結果を記録し、checkpoint を closed 状態にし、active session pointer を削除してから完了報告をします。
+
 ## あえて小さくしています
 
 このプロジェクトを大きくするのは簡単です。

package/README.ko.md

@@ -39,15 +39,15 @@ Skill-compatible agent는 설치된 skill 중 요청과 관련성이 높은 skil
 
 그래서 아래처럼 goal 자체가 충분히 분명하면 자동으로 붙을 수 있습니다.
 
-> `/goal` 이번 릴리스를 장기 세션으로 안정화해줘. compact/resume 이후에도 목표, 제약, 거부한 경로, 실패한 시도, 검증 상태, 다음 액션이 복구 가능하게 관리해줘.
+> `/goal` 이번 릴리스를 장기 세션으로 안정화해줘. goalkeeper를 사용해줘.
 
 하지만 skill 활성화는 agent runtime hook이 아니라 routing 판단입니다. Goalkeeper가 모든 goal에 자신을 강제로 붙일 수는 없습니다.
 
 중요한 장기 작업이라면 goal을 만들 때, 또는 goal을 만든 직후 본격 작업 전에 명시적으로 호출하는 편이 가장 안전합니다.
 
-> 이 `/goal`에는 goalkeeper를 사용해줘. 목표, 제약, 결정, 검증 상태, 실패한 시도, 다음 액션이 compact 이후에도 복구 가능하게 관리해줘.
+> 이 goal에는 goalkeeper를 사용해줘.
 
-그 다음부터 사용자가 Goalkeeper의 helper script를 직접 실행할 필요는 없습니다. agent가 skill workflow의 일부로 실행합니다.
+사용자가 기억할 문장은 여기까지입니다. checkpoint, context pack, event log, 실패한 시도, 검증 상태, helper script 같은 것은 Goalkeeper workflow 안에서 agent가 관리합니다.
 
 ## 문제
 
@@ -57,15 +57,15 @@ Skill-compatible agent는 설치된 skill 중 요청과 관련성이 높은 skil
 
 실제 세션을 상상해보면 이렇습니다.
 
-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가 통과합니다. 이제 이 경로가 안전한 경로입니다.
+1. agent에게 결제 버그 수정을 맡깁니다.
+2. 초반 조사에서 `refunds` 쪽 코드는 레거시라 건드리면 안 된다는 사실이 드러납니다.
+3. 가장 빠른 patch는 `refunds`를 직접 고치는 방식이라, 사용자가 그 경로를 명시적으로 거부합니다.
+4. agent는 webhook handler 쪽으로 옮겨보지만, duplicate event 케이스에서 실패합니다.
+5. 결국 service layer에 idempotency guard를 두고 regression test로 막는 경로를 검증합니다.
+6. 테스트가 통과합니다. 이제 이 경로가 유지되어야 하는 안전한 경로입니다.
 7. 컨텍스트가 compact됩니다.
-8. 나중에 에이전트는 “release hardening은 거의 됨” 같은 깔끔한 요약으로 돌아옵니다.
-9. goal은 기억하지만, 왜 schema shortcut이 계속 금지되어야 하는지, 앞선 patch들이 왜 실패했는지, 그 regression test가 왜 중요한지는 희미해질 수 있습니다.
+8. 나중에 에이전트는 “결제 버그는 거의 해결됨” 같은 깔끔한 요약으로 돌아옵니다.
+9. goal은 기억하지만, `refunds`를 건드리면 안 된다는 점, webhook 시도가 실패했다는 점, service-layer test가 안전한 경로를 증명했다는 점은 희미해질 수 있습니다.
 
 여기서 drift가 시작됩니다.
 
@@ -119,10 +119,14 @@ Goalkeeper는 긴 에이전트 작업을 단순한 루프로 바꿉니다.
   -> resume, handoff, compact 의심 이후 agent는 checkpoint.md를 먼저 읽는다
   -> checkpoint가 얇으면 context-pack.md를 읽는다
   -> 정확한 증거가 필요하면 events.jsonl이나 source file을 확인한다
+  -> goal이 끝나면 agent가 Goalkeeper 세션을 닫는다
+  -> 이후 관련 없는 일반 질문에는 Goalkeeper recovery가 붙지 않는다
 ```
 
 이것은 대화 transcript 저장이 아닙니다. 작업 상태 보존입니다.
 
+Goalkeeper가 영원히 붙어 있으면 안 됩니다. 관리하던 goal이 끝나면 agent가 최종 결과를 기록하고, checkpoint를 closed 상태로 표시하고, active session pointer를 제거한 뒤 완료 보고를 합니다.
+
 ## 일부러 작게 만들었습니다
 
 이 프로젝트를 크게 만드는 방법은 쉽습니다.

package/README.md

@@ -39,15 +39,15 @@ Skill-compatible agents can automatically load installed skills when a request s
 
 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.
+> `/goal` Harden this release over a long-running session. Use goalkeeper.
 
 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.
+> Use goalkeeper for this goal.
 
-After that, you should not have to run Goalkeeper's helper scripts yourself. The agent runs them as part of the skill workflow.
+That is the whole user-facing instruction. After that, you should not have to name the checkpoint, context pack, event log, failed attempts, verification state, or helper scripts yourself. The agent runs Goalkeeper as part of the skill workflow.
 
 ## The Problem
 
@@ -57,15 +57,15 @@ 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.
+1. You ask an agent to fix a payment bug.
+2. Early in the work, it discovers `refunds` is legacy code and should not be touched.
+3. The quickest patch would edit `refunds`, so you reject that path.
+4. The agent tries moving the fix into a webhook handler, but duplicate events break it.
+5. It finally proves the safe route: put an idempotency guard in the service layer and cover it with a regression test.
+6. The test passes. That route is now the one you want preserved.
 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.
+8. Later, the agent resumes from a clean summary: "payment bug mostly fixed."
+9. It still knows the goal, but may no longer remember that `refunds` was off-limits, that the webhook attempt failed, or that the service-layer test is what made the route safe.
 
 That is where drift starts.
 
@@ -119,10 +119,14 @@ Long /goal begins
   -> 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
+  -> when the goal is done, the agent closes the Goalkeeper session
+  -> later unrelated questions do not trigger Goalkeeper recovery
 ```
 
 This is not transcript storage. It is working-state preservation.
 
+Goalkeeper should not stay attached forever. A managed goal has a shutdown step: the agent records the final outcome, marks the checkpoint closed, and removes the active session pointer before giving the completion response.
+
 ## Why It Is Small On Purpose
 
 The obvious version of this project is too big:

package/README.zh-CN.md

@@ -39,15 +39,15 @@ npx skills add deltafleet/goalkeeper --agent claude-code codex
 
 所以像下面这样的 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.
+> `/goal` Harden this release over a long-running session. Use goalkeeper.
 
 但 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.
+> Use goalkeeper for this goal.
 
-之后用户不需要手动执行 Goalkeeper 的 helper scripts。agent 会把它们作为 skill workflow 的一部分来运行。
+用户需要记住的句子到这里就够了。checkpoint、context pack、event log、失败尝试、验证状态和 helper scripts，都由 agent 在 Goalkeeper workflow 中处理。
 
 ## 问题
 
@@ -57,15 +57,15 @@ npx skills add deltafleet/goalkeeper --agent claude-code codex
 
 想象一个真实会话：
 
-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 通过了。这条路线现在是安全路线。
+1. 你让 agent 修一个支付 bug。
+2. 早期调查发现，`refunds` 相关代码是 legacy，不能轻易动。
+3. 最快的 patch 是直接改 `refunds`，所以你明确拒绝这条路。
+4. agent 尝试把修复放到 webhook handler，但 duplicate event 场景会失败。
+5. 最后它验证了安全路线：在 service layer 加 idempotency guard，并用 regression test 覆盖。
+6. 测试通过了。这条路线现在是需要保留下来的安全路线。
 7. 上下文被 compact。
-8. 后来 agent 带着整洁摘要回来：“release hardening 基本完成。”
-9. 它还记得 goal，但可能不再清楚为什么 schema shortcut 必须继续禁止，为什么前几个 patch 失败，以及为什么那个 regression test 很关键。
+8. 后来 agent 带着整洁摘要回来：“支付 bug 基本修好了。”
+9. 它还记得 goal，但可能不再清楚 `refunds` 为什么不能动，webhook 尝试为什么失败，以及 service-layer test 为什么证明了正确路线。
 
 drift 就从这里开始。
 
@@ -119,10 +119,14 @@ Goalkeeper 把长时间 agent 工作变成一个简单循环：
   -> resume、handoff 或怀疑 compaction 后，agent 先读 checkpoint.md
   -> 如果 checkpoint 太薄，agent 再读 context-pack.md
   -> 如果需要精确证据，agent 检查 events.jsonl 或 source files
+  -> goal 完成后，agent 关闭 Goalkeeper session
+  -> 之后无关的一般问题不会触发 Goalkeeper recovery
 ```
 
 这不是保存对话 transcript。它保存的是工作状态。
 
+Goalkeeper 不应该一直附着在会话上。被管理的 goal 完成后，agent 会记录最终结果，把 checkpoint 标记为 closed，移除 active session pointer，然后再汇报完成。
+
 ## 为什么故意做得很小
 
 把这个项目做大很容易：

package/docs/ROADMAP.md

@@ -4,7 +4,7 @@
 
 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.
+Goalkeeper should stay boring: a short checkpoint, a medium-density context pack, an append-only event log, a turn-start helper, a close helper, and a doctor check. It should not become a substitute context engine or a promise of perfect post-compact recovery.
 
 ## MVP
 
@@ -27,6 +27,7 @@ Core behavior:
 - 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
+- close the active session when the managed goal completes so unrelated questions do not trigger recovery
 - run a read-only doctor before trusting a workspace for long work
 
 ## User-Facing Scope
@@ -37,6 +38,7 @@ Keep these scripts central:
 - `goalkeeper-turn-start.mjs`
 - `goalkeeper-append-event.mjs`
 - `goalkeeper-update-checkpoint.mjs`
+- `goalkeeper-close.mjs`
 - `goalkeeper-doctor.mjs`
 
 Keep this optional and maintainer-oriented:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deltafleet/goalkeeper",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A small Agent Skill for keeping long-running goals oriented across compaction, resumes, and handoffs.",
   "license": "MIT",
   "type": "module",
@@ -29,11 +29,13 @@
     "goalkeeper-append-event": "src/goalkeeper/scripts/goalkeeper-append-event.mjs",
     "goalkeeper-update-checkpoint": "src/goalkeeper/scripts/goalkeeper-update-checkpoint.mjs",
     "goalkeeper-doctor": "src/goalkeeper/scripts/goalkeeper-doctor.mjs",
+    "goalkeeper-close": "src/goalkeeper/scripts/goalkeeper-close.mjs",
     "codex-goalkeeper-init": "src/goalkeeper/scripts/goalkeeper-init.mjs",
     "codex-goalkeeper-turn-start": "src/goalkeeper/scripts/goalkeeper-turn-start.mjs",
     "codex-goalkeeper-append-event": "src/goalkeeper/scripts/goalkeeper-append-event.mjs",
     "codex-goalkeeper-update-checkpoint": "src/goalkeeper/scripts/goalkeeper-update-checkpoint.mjs",
-    "codex-goalkeeper-doctor": "src/goalkeeper/scripts/goalkeeper-doctor.mjs"
+    "codex-goalkeeper-doctor": "src/goalkeeper/scripts/goalkeeper-doctor.mjs",
+    "codex-goalkeeper-close": "src/goalkeeper/scripts/goalkeeper-close.mjs"
   },
   "files": [
     "src/goalkeeper",

package/src/goalkeeper/SKILL.md

@@ -17,6 +17,8 @@ When a user starts or continues a `/goal` in Claude Code, Codex, or another skil
 
 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.
 
+Only treat Goalkeeper as active when `<workspace>/.goalkeeper/active-session` points to a live session or the user explicitly asks to resume a specific Goalkeeper session. If no active session pointer exists and the user asks an unrelated question, do not apply checkpoint-first recovery.
+
 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:
@@ -113,6 +115,31 @@ Update Goalkeeper state when any of these change:
 Append the event first, then update the session's `checkpoint.md` when the event changes the current working state.
 Use `scripts/goalkeeper-update-checkpoint.mjs` when you want a bounded canonical checkpoint instead of manual Markdown edits.
 
+## Shutdown Rule
+
+When a Goalkeeper-managed goal is complete, shut down the active Goalkeeper session before sending the final completion response.
+
+Do this when:
+
+- the done criteria are satisfied
+- the user explicitly ends the goal
+- the work is abandoned, superseded, or intentionally paused without needing checkpoint-first recovery on unrelated questions
+
+Shutdown steps:
+
+1. Append a final `close` event.
+2. Mark `checkpoint.md` as closed with the final outcome and residual risks.
+3. Remove `.goalkeeper/active-session` when it points to the closed session.
+4. Do not apply checkpoint-first recovery to later unrelated user questions.
+
+Use the close helper:
+
+```bash
+node <skill-path>/scripts/goalkeeper-close.mjs --workspace <workspace> --outcome "<final outcome>"
+```
+
+After shutdown, read the closed session again only if the user explicitly resumes that goal or asks about its history.
+
 ## Keep It Short
 
 The checkpoint is a recovery artifact, not a transcript.
@@ -157,6 +184,7 @@ Read it when checkpoint recovery is not enough. Keep raw transcripts and long co
 - Run `scripts/goalkeeper-turn-start.mjs --context` when checkpoint recovery needs the larger context pack too.
 - Run `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 `scripts/goalkeeper-update-checkpoint.mjs` after appending a meaningful event when checkpoint state should be refreshed in a short canonical shape.
+- Run `scripts/goalkeeper-close.mjs` before the final completion response when the managed goal is done, abandoned, or superseded.
 - Run `scripts/goalkeeper-doctor.mjs` after creating or changing Goalkeeper state to verify the target workspace is ready.
 
 ## Safety Boundary

package/src/goalkeeper/agents/openai.yaml

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

package/src/goalkeeper/references/event-schema.md

@@ -33,7 +33,7 @@ When `<workspace>/.goalkeeper/active-session` points to the current session, `--
 - `evidence`: short supporting detail.
 - `files`: array of file paths.
 - `commands`: array of commands.
-- `status`: `open`, `done`, `failed`, `blocked`, or `superseded`.
+- `status`: `open`, `done`, `failed`, `blocked`, `superseded`, or `closed`.
 - `supersedes`: event id or short reference.
 
 ## Initial Types
@@ -51,6 +51,7 @@ When `<workspace>/.goalkeeper/active-session` points to the current session, `--
 - `next_action`: explicit next step.
 - `compact_observed`: a real agent compaction boundary was observed.
 - `recovery_violation`: the agent continued after compaction or resume before reading the Goalkeeper checkpoint.
+- `close`: the managed goal was completed, abandoned, or superseded and the active session should stop applying to unrelated questions.
 
 ## Writing Rules
 

package/src/goalkeeper/references/guardrail.md

@@ -30,6 +30,9 @@ For an active Goalkeeper-managed goal:
 2. Use `context-pack.md` when the checkpoint is too thin to recover the reasoning chain.
 3. Use `events.jsonl` only when exact evidence is needed.
 4. Append `recovery_violation` if the agent continued after compaction or resume before reading the checkpoint.
+5. When the goal is complete, run `goalkeeper-close.mjs` before the final completion response.
+
+If `.goalkeeper/active-session` is absent and the user asks an unrelated question, do not read closed Goalkeeper sessions first.
 
 If `scripts/goalkeeper-turn-start.mjs` is present, it can be used as the first recovery action:
 
@@ -61,4 +64,10 @@ Before starting a high-stakes long run, use the read-only doctor to verify the t
 node <skill-path>/scripts/goalkeeper-doctor.mjs --workspace <workspace> --session <goal-session-id> --strict
 ```
 
+When the managed goal is done, close the session:
+
+```bash
+node <skill-path>/scripts/goalkeeper-close.mjs --workspace <workspace> --outcome "<final outcome>"
+```
+
 Parallel calls are still subject to checkpoint-first ordering. It is acceptable to batch `pwd`, `.goalkeeper/sessions` discovery, and `goalkeeper-turn-start.mjs`; it is not acceptable to include normal project files or verification in that same first post-compact parallel call.

package/src/goalkeeper/references/workflow.md

@@ -73,6 +73,8 @@ Use `context-pack.md` for medium-density reasoning that should survive compactio
 
 For an already active Goalkeeper-managed task, begin each new assistant turn with a checkpoint-first recovery read before touching normal project files.
 
+Only apply this rule when `.goalkeeper/active-session` exists or the user explicitly resumes a known Goalkeeper session. If the active pointer is absent and the user asks an unrelated question, do not read closed sessions first.
+
 Recommended sequence:
 
 ```bash
@@ -166,6 +168,23 @@ Before ending a long working segment:
 2. Update `checkpoint.md` with the current state and exact next action.
 3. Include unresolved risks and verification gaps.
 
+## Shutdown
+
+Before sending the final completion response for a Goalkeeper-managed goal:
+
+1. Confirm the done criteria are satisfied, or that the goal was explicitly abandoned or superseded.
+2. Run the close helper:
+
+   ```bash
+   node <skill-path>/scripts/goalkeeper-close.mjs --workspace <workspace> --outcome "<final outcome>"
+   ```
+
+3. Include repeated `--risk "<text>"` and `--evidence "<text>"` fields when residual risks or final proof should remain recoverable.
+4. Verify `.goalkeeper/active-session` was removed when it pointed to the closed session.
+5. Send the final completion response.
+
+After shutdown, do not apply checkpoint-first recovery to unrelated user questions. Read the closed session only if the user explicitly resumes that goal or asks about its history.
+
 ## Checkpoint Update Guidance
 
 Update the checkpoint after a meaningful state transition, not after every minor tool call.

package/src/goalkeeper/scripts/goalkeeper-append-event.mjs

@@ -17,9 +17,10 @@ const EVENT_TYPES = new Set([
   "next_action",
   "compact_observed",
   "recovery_violation",
+  "close",
 ]);
 
-const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded"]);
+const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded", "closed"]);
 
 const USAGE = `Usage:
   node scripts/goalkeeper-append-event.mjs --type <event-type> --text <summary> [--session <goal-session-id>] [--workspace <path>] [--goal <text>] [--reason <text>] [--evidence <text>] [--status <status>] [--file <path> ...] [--command <cmd> ...] [--ts <iso>] [--json]

package/src/goalkeeper/scripts/goalkeeper-close.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const EVENT_TYPES = new Set([
+  "goal",
+  "user_constraint",
+  "decision",
+  "attempt",
+  "failure",
+  "edit",
+  "command",
+  "verification",
+  "risk",
+  "handoff",
+  "next_action",
+  "compact_observed",
+  "recovery_violation",
+  "close",
+]);
+
+const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded", "closed"]);
+
+const USAGE = `Usage:
+  node scripts/goalkeeper-close.mjs --outcome <text> [--session <goal-session-id>] [--workspace <path>] [--risk <text> ...] [--evidence <text> ...] [--json]
+
+Closes the active Goalkeeper session after a goal is complete, abandoned, or superseded.
+This appends a close event, marks checkpoint.md closed, and removes <workspace>/.goalkeeper/active-session when it points to the closed session.
+`;
+
+function parseArgs(argv) {
+  const options = {
+    sessionId: null,
+    workspace: ".",
+    outcome: null,
+    risks: [],
+    evidence: [],
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--session") {
+      options.sessionId = argv[i + 1];
+      i += 1;
+    } else if (arg === "--workspace") {
+      options.workspace = argv[i + 1];
+      i += 1;
+    } else if (arg === "--outcome") {
+      options.outcome = argv[i + 1];
+      i += 1;
+    } else if (arg === "--risk") {
+      options.risks.push(argv[i + 1]);
+      i += 1;
+    } else if (arg === "--evidence") {
+      options.evidence.push(argv[i + 1]);
+      i += 1;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!options.workspace || !options.outcome) {
+    throw new Error("Missing required argument.");
+  }
+
+  options.outcome = normalizeText(options.outcome, "outcome");
+  options.risks = options.risks.map((item) => normalizeText(item, "risk"));
+  options.evidence = options.evidence.map((item) => normalizeText(item, "evidence"));
+
+  if (options.sessionId && !isValidSessionId(options.sessionId)) {
+    throw new Error("Session id must be a single path segment.");
+  }
+
+  return options;
+}
+
+function normalizeText(value, field) {
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string.`);
+  }
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    throw new Error(`${field} must not be empty.`);
+  }
+  return normalized;
+}
+
+function isValidSessionId(sessionId) {
+  return typeof sessionId === "string" && sessionId.trim().length > 0 && !sessionId.includes("/") && !sessionId.includes("..");
+}
+
+function resolveSessionId(workspace, explicitSessionId) {
+  const activeSessionPath = path.join(workspace, ".goalkeeper", "active-session");
+  if (explicitSessionId) {
+    return { sessionId: explicitSessionId, activeSessionPath, resolvedFromActive: false };
+  }
+
+  if (!fs.existsSync(activeSessionPath)) {
+    throw new Error(`Missing --session and active session pointer: ${activeSessionPath}`);
+  }
+
+  const sessionId = fs.readFileSync(activeSessionPath, "utf8").trim();
+  if (!isValidSessionId(sessionId)) {
+    throw new Error(`Invalid active session id in ${activeSessionPath}`);
+  }
+
+  return { sessionId, activeSessionPath, resolvedFromActive: true };
+}
+
+function validateExistingJsonl(eventsPath) {
+  if (!fs.existsSync(eventsPath)) return 0;
+  const lines = fs.readFileSync(eventsPath, "utf8").split(/\r?\n/);
+  let records = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    records += 1;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`Refusing to append to invalid JSONL at ${eventsPath}:${i + 1}: ${error.message}`);
+    }
+    validateEventRecord(parsed, eventsPath, i + 1);
+  }
+  return records;
+}
+
+function validateEventRecord(parsed, eventsPath, lineNumber) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event must be a JSON object`);
+  }
+  if (typeof parsed.ts !== "string" || Number.isNaN(Date.parse(parsed.ts))) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event ts must be a valid ISO timestamp string`);
+  }
+  if (typeof parsed.type !== "string" || !EVENT_TYPES.has(parsed.type)) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event type is missing or unknown: ${parsed.type}`);
+  }
+  if (typeof parsed.text !== "string" || parsed.text.trim().length === 0) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event text must be a non-empty string`);
+  }
+  if (parsed.status !== undefined && (typeof parsed.status !== "string" || !STATUSES.has(parsed.status))) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event status is unknown: ${parsed.status}`);
+  }
+}
+
+function bulletList(items, fallback = "None recorded.") {
+  const values = items.length > 0 ? items : [fallback];
+  return values.map((item) => `- ${item}`).join("\n");
+}
+
+function renderClosedCheckpoint(existingCheckpoint, options, closedAt) {
+  const withoutOldClosedSection = existingCheckpoint.replace(/\n## Closed\n[\s\S]*?(?=\n## |\s*$)/g, "").trimEnd();
+  const withClosedStatus = withoutOldClosedSection.includes("- Current status:")
+    ? withoutOldClosedSection.replace(/^- Current status: .*$/m, "- Current status: Closed.")
+    : `${withoutOldClosedSection}\n\n## Status\n\n- Current status: Closed.`;
+
+  return `${withClosedStatus}
+
+## Closed
+
+- Outcome: ${options.outcome}
+- Closed at: ${closedAt}
+
+## Residual Risks
+
+${bulletList(options.risks)}
+
+## Final Evidence
+
+${bulletList(options.evidence)}
+`;
+}
+
+function maybeRemoveActiveSession(activeSessionPath, sessionId) {
+  if (!fs.existsSync(activeSessionPath)) {
+    return { removed: false, reason: "active-session was already missing." };
+  }
+
+  const activeSessionId = fs.readFileSync(activeSessionPath, "utf8").trim();
+  if (activeSessionId !== sessionId) {
+    return {
+      removed: false,
+      reason: `active-session points to ${activeSessionId || "(empty)"}, not ${sessionId}.`,
+    };
+  }
+
+  fs.rmSync(activeSessionPath);
+  return { removed: true, reason: "active-session pointed to the closed session." };
+}
+
+function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    console.error(USAGE);
+    process.exit(2);
+  }
+
+  const workspace = path.resolve(options.workspace);
+  if (!fs.existsSync(workspace) || !fs.statSync(workspace).isDirectory()) {
+    console.error(`Workspace does not exist or is not a directory: ${workspace}`);
+    process.exit(1);
+  }
+
+  let resolvedSession;
+  try {
+    resolvedSession = resolveSessionId(workspace, options.sessionId);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const sessionDir = path.join(workspace, ".goalkeeper", "sessions", resolvedSession.sessionId);
+  const checkpointPath = path.join(sessionDir, "checkpoint.md");
+  const eventsPath = path.join(sessionDir, "events.jsonl");
+
+  if (!fs.existsSync(sessionDir) || !fs.statSync(sessionDir).isDirectory()) {
+    console.error(`Goalkeeper session directory is missing: ${sessionDir}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(checkpointPath)) {
+    console.error(`Checkpoint is missing: ${checkpointPath}`);
+    process.exit(1);
+  }
+
+  let existingRecords;
+  try {
+    existingRecords = validateExistingJsonl(eventsPath);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const closedAt = new Date().toISOString();
+  const event = {
+    ts: closedAt,
+    type: "close",
+    text: options.outcome,
+    status: "closed",
+  };
+  if (options.risks.length > 0) event.reason = `Residual risks: ${options.risks.join("; ")}`;
+  if (options.evidence.length > 0) event.evidence = options.evidence.join("; ");
+
+  fs.appendFileSync(eventsPath, `${JSON.stringify(event)}\n`);
+
+  const existingCheckpoint = fs.readFileSync(checkpointPath, "utf8");
+  const checkpoint = renderClosedCheckpoint(existingCheckpoint, options, closedAt);
+  fs.writeFileSync(checkpointPath, checkpoint);
+
+  const activeSession = maybeRemoveActiveSession(resolvedSession.activeSessionPath, resolvedSession.sessionId);
+
+  const result = {
+    ok: true,
+    workspace,
+    sessionId: resolvedSession.sessionId,
+    sessionDir,
+    checkpointPath,
+    eventsPath,
+    lineNumber: existingRecords + 1,
+    activeSessionPath: resolvedSession.activeSessionPath,
+    activeSession,
+    event,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log("Goalkeeper close: PASS");
+  console.log(`Session: ${resolvedSession.sessionId}`);
+  console.log(`Checkpoint: ${checkpointPath}`);
+  console.log(`Events: ${eventsPath}`);
+  console.log(`Active session removed: ${activeSession.removed ? "yes" : "no"}`);
+}
+
+main();

package/src/goalkeeper/scripts/goalkeeper-doctor.mjs

@@ -19,9 +19,10 @@ const EVENT_TYPES = new Set([
   "next_action",
   "compact_observed",
   "recovery_violation",
+  "close",
 ]);
 
-const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded"]);
+const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded", "closed"]);
 const CHECKPOINT_TARGET_BYTES = 8_000;
 const CHECKPOINT_MAX_BYTES = 16_000;
 const CONTEXT_PACK_TARGET_BYTES = 30_000;

package/src/goalkeeper/templates/AGENTS.goalkeeper.md

@@ -1,6 +1,8 @@
 # Goalkeeper Guardrail
 
-When this repository has an active `.goalkeeper/sessions/<goal-session-id>/` directory, treat it as the continuity source for long-running agent work.
+When this repository has an active `.goalkeeper/active-session` pointer, treat the referenced `.goalkeeper/sessions/<goal-session-id>/` directory as the continuity source for long-running agent work.
+
+If `.goalkeeper/active-session` is absent and the user asks an unrelated question, do not read closed Goalkeeper sessions first.
 
 At the start of each new assistant turn, before reading normal project files or making edits:
 
@@ -45,4 +47,6 @@ Do not read project docs, source files, examples, tests, or make edits before th
 
 If you notice that you continued after compaction or resume without reading the checkpoint, stop, read it immediately, append a `recovery_violation` event, then continue from the recovered state.
 
+When the managed goal is complete, run `goalkeeper-close.mjs` before sending the final completion response. This records the final outcome and removes `.goalkeeper/active-session` so later unrelated questions are not treated as goal recovery.
+
 Do not claim Goalkeeper reduces compaction frequency. Its purpose is direction recovery after compaction, resume, or handoff.

package/src/goalkeeper/templates/CLAUDE.goalkeeper.md

@@ -1,6 +1,8 @@
 # Goalkeeper Guardrail
 
-When this repository has an active `.goalkeeper/sessions/<goal-session-id>/` directory, treat it as the continuity source for long-running Claude Code or agent work.
+When this repository has an active `.goalkeeper/active-session` pointer, treat the referenced `.goalkeeper/sessions/<goal-session-id>/` directory as the continuity source for long-running Claude Code or agent work.
+
+If `.goalkeeper/active-session` is absent and the user asks an unrelated question, do not read closed Goalkeeper sessions first.
 
 At the start of each new assistant turn, before reading normal project files or making edits:
 
@@ -45,4 +47,6 @@ Do not read project docs, source files, examples, tests, or make edits before th
 
 If you notice that you continued after compaction or resume without reading the checkpoint, stop, read it immediately, append a `recovery_violation` event, then continue from the recovered state.
 
+When the managed goal is complete, run `goalkeeper-close.mjs` before sending the final completion response. This records the final outcome and removes `.goalkeeper/active-session` so later unrelated questions are not treated as goal recovery.
+
 Do not claim Goalkeeper reduces compaction frequency. Its purpose is direction recovery after compaction, resume, or handoff.