@deltafleet/codex-goalkeeper 0.1.0

package/docs/ROADMAP.md

@@ -0,0 +1,77 @@
+# Roadmap
+
+## Product Thesis
+
+Long-running Codex 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 a root-level Codex skill 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:
+
+- `test-goalkeeper-update-checkpoint.mjs`
+
+## Non-Goals
+
+- no MCP server in the MVP
+- no Codex plugin packaging in the MVP
+- no SQLite or global database
+- no background daemon
+- no prompt-assembly hook
+- no Codex session rewriting
+- no claim of 100 percent compact recovery
+
+## Good Enough Release Bar
+
+- `npx skills add . --list` discovers exactly one skill named `codex-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 Codex 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 Codex 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: Codex'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 Codex 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

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 Codex 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 Codex 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 Codex 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,60 @@
+{
+  "name": "@deltafleet/codex-goalkeeper",
+  "version": "0.1.0",
+  "description": "A small Codex skill for keeping long-running goals oriented across compaction, resumes, and handoffs.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/deltafleet/codex-goalkeeper#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deltafleet/codex-goalkeeper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/deltafleet/codex-goalkeeper/issues"
+  },
+  "keywords": [
+    "codex",
+    "codex-skill",
+    "ai-agents",
+    "context",
+    "compaction",
+    "checkpoint",
+    "goal"
+  ],
+  "bin": {
+    "codex-goalkeeper-init": "src/scripts/goalkeeper-init.mjs",
+    "codex-goalkeeper-turn-start": "src/scripts/goalkeeper-turn-start.mjs",
+    "codex-goalkeeper-append-event": "src/scripts/goalkeeper-append-event.mjs",
+    "codex-goalkeeper-update-checkpoint": "src/scripts/goalkeeper-update-checkpoint.mjs",
+    "codex-goalkeeper-doctor": "src/scripts/goalkeeper-doctor.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "agents",
+    "src",
+    "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/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "test": "node src/scripts/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/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>/src/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 Codex 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/references/guardrail.md

@@ -0,0 +1,62 @@
+# Goalkeeper Guardrail
+
+The skill body is not enough to guarantee checkpoint-first behavior after compaction. Codex may resume from a compacted summary without the model noticing the exact session-log marker.
+
+For high-stakes long-running work, add the AGENTS guardrail template to the target workspace:
+
+```text
+src/templates/AGENTS.goalkeeper.md
+```
+
+Use it in one of these ways:
+
+- Copy the whole template into the target repository's `AGENTS.md`.
+- Merge the checkpoint-first section into an existing `AGENTS.md`.
+- Keep the template as project documentation and explicitly ask Codex 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 Codex runtime hook. It uses a surface Codex already honors: 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 `src/scripts/goalkeeper-turn-start.mjs` is present, it can be used as the first recovery action:
+
+```bash
+node src/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 src/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>/src/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>/src/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>/src/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/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 Codex 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>/src/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>/src/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>/src/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>/src/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>/src/scripts/goalkeeper-turn-start.mjs --workspace <workspace>
+```
+
+If checkpoint recovery is too thin, include the context pack:
+
+```bash
+node <skill-path>/src/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>/src/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 Codex 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-codex-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.