@deltafleet/goalkeeper 0.2.0

package/examples/goalkeeper-session/context-pack.md

@@ -0,0 +1,39 @@
+# Goalkeeper Context Pack
+
+## Purpose
+
+This example context pack keeps reasoning that is too detailed for the checkpoint but useful after compaction.
+
+## Active Goal
+
+Ship a long-running agent feature without losing direction after repeated compaction.
+
+## Durable Constraints
+
+- Read the checkpoint before resuming after compaction or handoff.
+- Append important evidence to `events.jsonl` before updating the checkpoint.
+
+## Working Model
+
+- `checkpoint.md` is the small turn-start recovery note.
+- `context-pack.md` carries the larger reasoning chain.
+- `events.jsonl` is the append-only evidence trail.
+
+## Decision Chain
+
+- Keep state project-local so it travels with the workspace.
+- Keep checkpoint short so agents actually read it.
+- Use the context pack only when the checkpoint is too thin.
+
+## Rejected Alternatives
+
+- Full transcript storage in the checkpoint.
+- Treating host-agent goal metadata as enough for long-running work.
+
+## Open Threads
+
+- In a real project, replace this example with the actual codebase model and unresolved questions.
+
+## Evidence Index
+
+- `examples/goalkeeper-session/events.jsonl`

package/examples/goalkeeper-session/events.jsonl

@@ -0,0 +1,5 @@
+{"ts":"2026-05-17T00:00:00Z","type":"goal","text":"Ship a long-running agent feature without losing direction after repeated compaction.","status":"open"}
+{"ts":"2026-05-17T00:01:00Z","type":"user_constraint","text":"The agent must read checkpoint.md before resuming after compaction."}
+{"ts":"2026-05-17T00:02:00Z","type":"decision","text":"Use .goalkeeper/sessions/<goal-session-id>/ for runtime state.","reason":"Separates multiple long-running goals within one project while keeping state local to the workspace."}
+{"ts":"2026-05-17T00:03:00Z","type":"failure","text":"Do not store full conversation summaries in checkpoint.md.","reason":"Long checkpoints defeat routine recovery because agents stop reading them carefully."}
+{"ts":"2026-05-17T00:04:00Z","type":"next_action","text":"Use the checkpoint to recover direction, then inspect event evidence only when exact details are needed.","status":"open"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@deltafleet/goalkeeper",
+  "version": "0.2.0",
+  "description": "A small Agent Skill for keeping long-running goals oriented across compaction, resumes, and handoffs.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/deltafleet/goalkeeper#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deltafleet/goalkeeper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/deltafleet/goalkeeper/issues"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "claude-skill",
+    "codex",
+    "ai-agents",
+    "context",
+    "compaction",
+    "checkpoint",
+    "goal"
+  ],
+  "bin": {
+    "goalkeeper-init": "src/goalkeeper/scripts/goalkeeper-init.mjs",
+    "goalkeeper-turn-start": "src/goalkeeper/scripts/goalkeeper-turn-start.mjs",
+    "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",
+    "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"
+  },
+  "files": [
+    "src/goalkeeper",
+    "examples",
+    "docs",
+    "README.md",
+    "README.ko.md",
+    "README.ja.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "scripts": {
+    "check:scripts": "find src/goalkeeper/scripts tests -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "test": "node tests/test-goalkeeper-update-checkpoint.mjs",
+    "validate:skill": "npx skills add . --list",
+    "validate:examples": "find examples -name '*.jsonl' -print0 | xargs -0 -n1 jq -c . >/dev/null",
+    "validate": "npm run check:scripts && npm test && npm run validate:examples && npm run validate:skill"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/goalkeeper/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: goalkeeper
+description: Use automatically for Claude Code /goal, Codex /goal, long-running agent goals, multi-turn implementations, session resumes, handoffs, compacted conversations, or any task where an AI coding agent 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.
+---
+
+# Goalkeeper
+
+Use this skill when an AI coding agent task is expected to run long enough that compaction, handoff, or drift could cause the agent to lose direction.
+
+Goalkeeper does not replace the host agent'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` in Claude Code, Codex, or another skill-compatible agent, 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-goalkeeper-roadmap` or `ads-ops-release-hardening`.
+
+If any core file is missing during long goal work, create it from the templates in `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 agent 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.
+
+In Claude Code, `${CLAUDE_SKILL_DIR}` can resolve the installed skill directory. In other agents, use the concrete installed skill path:
+
+```bash
+node <skill-path>/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>/scripts/goalkeeper-turn-start.mjs --workspace <workspace>
+```
+
+To create a new session deterministically, run:
+
+```bash
+node <skill-path>/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 `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 `references/workflow.md` for lifecycle rules and examples.
+- Read `references/event-schema.md` before adding or validating event records.
+- Read `references/guardrail.md` when you need stronger always-on behavior in a target repository.
+- Run `scripts/goalkeeper-init.mjs` when a long-running goal needs a new `.goalkeeper/sessions/<goal-session-id>/` directory.
+- 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-doctor.mjs` after creating or changing Goalkeeper state to verify the target workspace is ready.
+
+## Safety Boundary
+
+- Do not depend on private Codex, Claude Code, or other host-agent 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/src/goalkeeper/agents/openai.yaml

@@ -0,0 +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."
+  brand_color: "#2563EB"

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

@@ -0,0 +1,63 @@
+# Event Schema
+
+Events are newline-delimited JSON records in the current goal session's `events.jsonl`.
+
+Default path:
+
+```text
+<workspace>/.goalkeeper/sessions/<goal-session-id>/events.jsonl
+```
+
+Prefer the append helper when available:
+
+```bash
+node <skill-path>/scripts/goalkeeper-append-event.mjs --workspace <workspace> --session <goal-session-id> --type decision --text "<summary>"
+```
+
+When `<workspace>/.goalkeeper/active-session` points to the current session, `--session` may be omitted. The helper validates existing JSONL schema before writing and reports the appended line number.
+
+## Required Fields
+
+```json
+{"ts":"2026-05-17T00:00:00Z","type":"decision","text":"Use skill-only continuity files before adding optional MCP automation."}
+```
+
+- `ts`: ISO timestamp.
+- `type`: event type.
+- `text`: concise event summary.
+
+## Optional Fields
+
+- `goal`: active goal identifier or short title.
+- `reason`: why the event matters.
+- `evidence`: short supporting detail.
+- `files`: array of file paths.
+- `commands`: array of commands.
+- `status`: `open`, `done`, `failed`, `blocked`, or `superseded`.
+- `supersedes`: event id or short reference.
+
+## Initial Types
+
+- `goal`: objective or done criteria changed.
+- `user_constraint`: user gave a durable constraint or forbidden path.
+- `decision`: direction-setting choice.
+- `attempt`: meaningful path tried.
+- `failure`: path failed or should not be repeated.
+- `edit`: important file or artifact changed.
+- `command`: command result worth preserving.
+- `verification`: verification evidence.
+- `risk`: unresolved risk or blocker.
+- `handoff`: current state prepared for resume.
+- `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.
+
+## Writing Rules
+
+- Keep records one line each.
+- Prefer `goalkeeper-append-event.mjs` over manual edits for routine event writes.
+- Expect `goalkeeper-doctor.mjs` to fail if event type, timestamp, text, status, files, or commands violate this schema.
+- Prefer exact paths and commands when they matter.
+- Do not paste large output. Summarize and link to artifact paths.
+- Use `failure` only when the result should influence future behavior.
+- Use `verification` only when the result changes confidence.

package/src/goalkeeper/references/guardrail.md

@@ -0,0 +1,64 @@
+# Goalkeeper Guardrail
+
+The skill body is not enough to guarantee checkpoint-first behavior after compaction. A host agent may resume from a compacted summary without the model noticing the exact session-log marker.
+
+For high-stakes long-running work, add a guardrail template to the target workspace:
+
+```text
+templates/AGENTS.goalkeeper.md
+templates/CLAUDE.goalkeeper.md
+```
+
+Use it in one of these ways:
+
+- Copy `templates/AGENTS.goalkeeper.md` into the target repository's `AGENTS.md` for Codex-style agents.
+- Copy `templates/CLAUDE.goalkeeper.md` into the target repository's `CLAUDE.md` for Claude Code.
+- Merge the checkpoint-first section into an existing `AGENTS.md` or `CLAUDE.md`.
+- Keep the template as project documentation and explicitly ask the agent to follow it before starting a long goal.
+
+The guardrail is still skill-first. It does not require a plugin, MCP server, database, or private runtime hook. It uses surfaces coding agents already honor: repository instructions.
+
+## Why This Matters
+
+Compacted or resumed sessions can restart from a thin summary. The practical fix is to move the checkpoint-first rule into an always-on project instruction for workspaces that opt in.
+
+## Minimum Rule
+
+For an active Goalkeeper-managed goal:
+
+1. Read `.goalkeeper/sessions/<goal-session-id>/checkpoint.md` before normal project files.
+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.
+
+If `scripts/goalkeeper-turn-start.mjs` is present, it can be used as the first recovery action:
+
+```bash
+node scripts/goalkeeper-turn-start.mjs --session <goal-session-id>
+```
+
+If `.goalkeeper/active-session` contains the current session id, this shorter form is valid:
+
+```bash
+node scripts/goalkeeper-turn-start.mjs
+```
+
+If the helper is being run from an installed skill package rather than from the target repository, pass the target workspace explicitly:
+
+```bash
+node <skill-path>/scripts/goalkeeper-turn-start.mjs --workspace <workspace> --session <goal-session-id>
+```
+
+Add `--context` when the medium-density context pack is needed:
+
+```bash
+node <skill-path>/scripts/goalkeeper-turn-start.mjs --workspace <workspace> --session <goal-session-id> --context
+```
+
+Before starting a high-stakes long run, use the read-only doctor to verify the target workspace has the required state and guardrail:
+
+```bash
+node <skill-path>/scripts/goalkeeper-doctor.mjs --workspace <workspace> --session <goal-session-id> --strict
+```
+
+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

@@ -0,0 +1,187 @@
+# Workflow
+
+## Start
+
+When a user starts a long-running goal:
+
+1. Confirm the active objective from the user request or host agent goal state.
+2. Choose a stable goal session id.
+3. Create `.goalkeeper/sessions/<goal-session-id>/checkpoint.md` if missing.
+4. Create `.goalkeeper/sessions/<goal-session-id>/context-pack.md` if missing.
+5. Create `.goalkeeper/sessions/<goal-session-id>/events.jsonl` if missing.
+6. Write `.goalkeeper/active-session` when this is the current Goalkeeper session for the workspace.
+7. Append a `goal` event.
+8. Record any explicit user constraints as `user_constraint` events.
+9. Write the initial checkpoint and seed context pack.
+
+Use the init helper when available:
+
+```bash
+node <skill-path>/scripts/goalkeeper-init.mjs --workspace <workspace> --session <goal-session-id> --goal "<active goal>"
+```
+
+Pass repeated `--constraint "<text>"` flags for known durable constraints. The helper refuses to overwrite an existing session unless `--force` is explicitly provided.
+By default, it updates `.goalkeeper/active-session`; pass `--no-activate` when creating a non-current session.
+
+## Continue
+
+During normal work:
+
+- Append `decision` events for direction-setting choices.
+- Append `attempt` events for meaningful implementation or investigation paths.
+- Append `failure` events when a path should not be repeated without new evidence.
+- Append `command` or `verification` events for commands whose output changes confidence.
+- Append `risk` events for unresolved issues.
+- Keep `checkpoint.md` aligned with the current state.
+
+Use the append helper for routine event writes:
+
+```bash
+node <skill-path>/scripts/goalkeeper-append-event.mjs --workspace <workspace> --session <goal-session-id> --type verification --text "<summary>"
+```
+
+If `.goalkeeper/active-session` points to the target session, `--session` may be omitted. The helper reports the appended JSONL line number so later checkpoint evidence can cite the event precisely.
+
+When the event changes the recoverable working state, refresh the checkpoint in the same working segment:
+
+```bash
+node <skill-path>/scripts/goalkeeper-update-checkpoint.mjs \
+  --workspace <workspace> \
+  --session <goal-session-id> \
+  --goal "<active goal>" \
+  --done "<done criteria>" \
+  --status "<current status>" \
+  --throughline "<current direction>" \
+  --constraint "<durable constraint>" \
+  --decision "<current decision>" \
+  --verified "<trusted verification>" \
+  --risk "<open risk>" \
+  --next "<exact next action>"
+```
+
+If `.goalkeeper/active-session` points to the target session, `--session` may be omitted. The helper rewrites only `checkpoint.md` and refuses to write over the configured size budget, so long-running sessions do not silently turn the checkpoint into a transcript.
+
+Use `context-pack.md` for medium-density reasoning that should survive compaction but should not be read on every turn. Update it at major design or implementation boundaries:
+
+- decision chain
+- rejected alternatives
+- open threads
+- domain or codebase model
+- evidence index
+
+## Start of Each Turn
+
+For an already active Goalkeeper-managed task, begin each new assistant turn with a checkpoint-first recovery read before touching normal project files.
+
+Recommended sequence:
+
+```bash
+pwd
+find .goalkeeper/sessions -maxdepth 2 -name checkpoint.md
+sed -n '1,220p' .goalkeeper/sessions/<goal-session-id>/checkpoint.md
+```
+
+If the turn-start helper is available, use it instead of manually reading the checkpoint:
+
+```bash
+node <skill-path>/scripts/goalkeeper-turn-start.mjs --workspace <workspace> --session <goal-session-id>
+```
+
+If `.goalkeeper/active-session` points to the correct session id, omit `--session`:
+
+```bash
+node <skill-path>/scripts/goalkeeper-turn-start.mjs --workspace <workspace>
+```
+
+If checkpoint recovery is too thin, include the context pack:
+
+```bash
+node <skill-path>/scripts/goalkeeper-turn-start.mjs --workspace <workspace> --context
+```
+
+## Resume After Compaction
+
+When the conversation appears compacted or the agent is resuming after a long gap:
+
+1. Read `checkpoint.md`.
+2. Read `context-pack.md` if the checkpoint does not explain why the current direction exists.
+3. Read recent `events.jsonl` entries if exact prior evidence is needed.
+4. Search `events.jsonl` for a topic if exact prior evidence is needed.
+5. Do not proceed from memory alone when the checkpoint says a risk or constraint is open.
+
+### Recovery Guardrail
+
+After resume or suspected compaction, the first project-state action should be reading the active Goalkeeper checkpoint.
+
+Allowed before the checkpoint read:
+
+- determine `pwd`
+- list `.goalkeeper/sessions/`
+- inspect filenames only when needed to choose the active session id
+- run `goalkeeper-turn-start.mjs --session <goal-session-id>` or `goalkeeper-turn-start.mjs --workspace <workspace> --session <goal-session-id>`
+
+Not allowed before the checkpoint read:
+
+- sending a user-visible progress, status, or direction message based on memory
+- reading `README.md`, `docs/`, `src/`, examples, tests, or other project files
+- editing files
+- running verification commands that depend on recovered state
+- relying on the compacted summary as the source of current direction
+
+If an agent violates this order, append a `recovery_violation` event, read the checkpoint immediately, and continue only after reconciling the current action with the checkpoint.
+
+Before relying on a workspace for a long run, run the read-only doctor:
+
+```bash
+node <skill-path>/scripts/goalkeeper-doctor.mjs --workspace <workspace> --session <goal-session-id> --strict
+```
+
+## Goal Session Directory
+
+The goal session directory is project-local, not global:
+
+```text
+<workspace>/.goalkeeper/sessions/<goal-session-id>/
+```
+
+Use one directory per long-running agent goal session. A compacted conversation, resumed thread, or handoff should keep using the same directory when the underlying goal is the same.
+
+Suggested id format:
+
+```text
+YYYY-MM-DD-short-goal-slug
+```
+
+Example:
+
+```text
+.goalkeeper/sessions/2026-05-17-goalkeeper-roadmap/
+```
+
+## Handoff
+
+Before ending a long working segment:
+
+1. Append a `handoff` event.
+2. Update `checkpoint.md` with the current state and exact next action.
+3. Include unresolved risks and verification gaps.
+
+## Checkpoint Update Guidance
+
+Update the checkpoint after a meaningful state transition, not after every minor tool call.
+
+Good checkpoint updates:
+
+- A user changes scope.
+- A design route is chosen.
+- A blocker is discovered.
+- A test result proves or disproves the current direction.
+- Implementation reaches a stable boundary.
+- The next action changes.
+
+Bad checkpoint updates:
+
+- Repeating the same status after every file read.
+- Copying long command output into the checkpoint.
+- Adding uncertain claims without evidence.
+- Refreshing the checkpoint without first appending the event that explains why the state changed.