@deltafleet/codex-goalkeeper 0.1.0

package/src/scripts/goalkeeper-update-checkpoint.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_MAX_BYTES = 8_000;
+const HARD_MAX_BYTES = 16_000;
+
+const USAGE = `Usage:
+  node src/scripts/goalkeeper-update-checkpoint.mjs --goal <text> --next <text> [--session <goal-session-id>] [--workspace <path>] [--done <text>] [--status <text>] [--throughline <text>] [--why <text>] [--constraint <text> ...] [--forbidden <text> ...] [--decision <text> ...] [--attempt <text> ...] [--file <path> ...] [--verified <text> ...] [--unverified <text> ...] [--risk <text> ...] [--evidence <text> ...] [--max-bytes <n>] [--dry-run] [--json]
+
+Replaces checkpoint.md with a bounded, canonical recovery checkpoint.
+Append the corresponding event first with goalkeeper-append-event.mjs; this script writes only checkpoint.md.
+If --session is omitted, <workspace>/.goalkeeper/active-session is used.
+`;
+
+function parseArgs(argv) {
+  const options = {
+    sessionId: null,
+    workspace: ".",
+    title: null,
+    goal: null,
+    doneCriteria: null,
+    status: null,
+    throughline: null,
+    why: null,
+    constraints: [],
+    forbidden: [],
+    decisions: [],
+    attempts: [],
+    files: [],
+    verified: [],
+    unverified: [],
+    risks: [],
+    evidence: [],
+    next: null,
+    maxBytes: DEFAULT_MAX_BYTES,
+    dryRun: false,
+    json: false,
+  };
+
+  const repeated = new Map([
+    ["--constraint", "constraints"],
+    ["--forbidden", "forbidden"],
+    ["--decision", "decisions"],
+    ["--attempt", "attempts"],
+    ["--file", "files"],
+    ["--verified", "verified"],
+    ["--unverified", "unverified"],
+    ["--risk", "risks"],
+    ["--evidence", "evidence"],
+  ]);
+
+  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 === "--title") {
+      options.title = argv[i + 1];
+      i += 1;
+    } else if (arg === "--goal") {
+      options.goal = argv[i + 1];
+      i += 1;
+    } else if (arg === "--done") {
+      options.doneCriteria = argv[i + 1];
+      i += 1;
+    } else if (arg === "--status") {
+      options.status = argv[i + 1];
+      i += 1;
+    } else if (arg === "--throughline") {
+      options.throughline = argv[i + 1];
+      i += 1;
+    } else if (arg === "--why") {
+      options.why = argv[i + 1];
+      i += 1;
+    } else if (arg === "--next") {
+      options.next = argv[i + 1];
+      i += 1;
+    } else if (arg === "--max-bytes") {
+      options.maxBytes = Number(argv[i + 1]);
+      i += 1;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (repeated.has(arg)) {
+      options[repeated.get(arg)].push(argv[i + 1]);
+      i += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!options.workspace || !options.goal || !options.next) {
+    throw new Error("Missing required argument.");
+  }
+
+  if (!Number.isInteger(options.maxBytes) || options.maxBytes < 1 || options.maxBytes > HARD_MAX_BYTES) {
+    throw new Error(`--max-bytes must be an integer between 1 and ${HARD_MAX_BYTES}.`);
+  }
+
+  const stringFields = [
+    "sessionId",
+    "title",
+    "goal",
+    "doneCriteria",
+    "status",
+    "throughline",
+    "why",
+    "next",
+  ];
+
+  for (const field of stringFields) {
+    if (options[field] !== null && options[field] !== undefined) {
+      options[field] = normalizeText(options[field], field);
+    }
+  }
+
+  for (const key of repeated.values()) {
+    const normalize = key === "files" ? normalizePathText : normalizeText;
+    options[key] = options[key].map((value) => normalize(value, key));
+    if (options[key].some((value) => !value)) {
+      throw new Error(`Values for ${key} must not be empty.`);
+    }
+  }
+
+  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 normalizePathText(value, field) {
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string.`);
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${field} must not be empty.`);
+  }
+  if (/[\r\n]/.test(normalized)) {
+    throw new Error(`${field} must not contain newlines.`);
+  }
+  return normalized;
+}
+
+function isSingleSegmentSessionId(value) {
+  return typeof value === "string" && value.trim() && !value.includes("/") && !value.includes("..");
+}
+
+function readActiveSession(workspace) {
+  const activeSessionPath = path.join(workspace, ".goalkeeper", "active-session");
+  if (!fs.existsSync(activeSessionPath)) {
+    throw new Error(`--session was omitted and active-session is missing: ${activeSessionPath}`);
+  }
+  const sessionId = fs.readFileSync(activeSessionPath, "utf8").trim();
+  if (!isSingleSegmentSessionId(sessionId)) {
+    throw new Error(`active-session must contain a single session id path segment: ${activeSessionPath}`);
+  }
+  return { sessionId, activeSessionPath };
+}
+
+function bulletList(items, fallback = "None recorded.") {
+  if (items.length === 0) return `- ${fallback}`;
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+function renderCheckpoint(options, context) {
+  const title = options.title || context.sessionId;
+  const contextPack = fs.existsSync(context.contextPackPath)
+    ? `.goalkeeper/sessions/${context.sessionId}/context-pack.md`
+    : "None recorded.";
+
+  return `# Checkpoint: ${title}
+
+## Active Goal
+
+- Objective: ${options.goal}
+- Done criteria: ${options.doneCriteria || "Not explicitly recorded."}
+- Current status: ${options.status || "Open."}
+
+## Throughline
+
+- Current direction: ${options.throughline || "Continue from the active goal and latest verified state."}
+- Why this direction: ${options.why || "Preserve direction across compaction with project-local state."}
+
+## Constraints
+
+- Non-negotiable:
+${indentBullets(options.constraints, "None recorded.")}
+- Forbidden approaches:
+${indentBullets(options.forbidden, "None recorded.")}
+
+## Decisions
+
+${bulletList(options.decisions)}
+
+## Attempts And Failures
+
+${bulletList(options.attempts)}
+
+## Important Files
+
+${bulletList(options.files)}
+
+## Evidence
+
+${bulletList(options.evidence)}
+
+## Context Pack
+
+- ${contextPack}
+
+## Verification
+
+- Verified:
+${indentBullets(options.verified, "None recorded.")}
+- Not yet verified:
+${indentBullets(options.unverified, "None recorded.")}
+
+## Open Risks
+
+${bulletList(options.risks)}
+
+## Next Action
+
+- ${options.next}
+
+## Last Updated
+
+- ${context.updatedAt}
+`;
+}
+
+function indentBullets(items, fallback) {
+  return bulletList(items, fallback)
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+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 activeSessionPath = null;
+  if (!options.sessionId) {
+    try {
+      const active = readActiveSession(workspace);
+      options.sessionId = active.sessionId;
+      activeSessionPath = active.activeSessionPath;
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+  }
+
+  if (!isSingleSegmentSessionId(options.sessionId)) {
+    console.error("Session id must be a single path segment.");
+    process.exit(2);
+  }
+
+  const sessionDir = path.join(workspace, ".goalkeeper", "sessions", options.sessionId);
+  const checkpointPath = path.join(sessionDir, "checkpoint.md");
+  const contextPackPath = path.join(sessionDir, "context-pack.md");
+
+  if (!fs.existsSync(sessionDir) || !fs.statSync(sessionDir).isDirectory()) {
+    console.error(`Goalkeeper session directory is missing: ${sessionDir}`);
+    process.exit(1);
+  }
+
+  const updatedAt = new Date().toISOString();
+  const checkpoint = renderCheckpoint(options, {
+    sessionId: options.sessionId,
+    contextPackPath,
+    updatedAt,
+  });
+  const bytes = Buffer.byteLength(checkpoint);
+
+  if (bytes > options.maxBytes) {
+    console.error(`Rendered checkpoint is ${bytes} bytes, over --max-bytes ${options.maxBytes}.`);
+    console.error("Shorten fields or raise --max-bytes up to the 16000 hard limit only when recovery cost is acceptable.");
+    process.exit(1);
+  }
+
+  if (!options.dryRun) {
+    fs.writeFileSync(checkpointPath, checkpoint);
+  }
+
+  const result = {
+    ok: true,
+    dryRun: options.dryRun,
+    workspace,
+    sessionId: options.sessionId,
+    sessionDir,
+    checkpointPath,
+    activeSessionPath,
+    bytes,
+    maxBytes: options.maxBytes,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log("Goalkeeper update-checkpoint: PASS");
+  console.log(`Workspace: ${workspace}`);
+  console.log(`Session: ${options.sessionId}`);
+  console.log(`Checkpoint: ${checkpointPath}`);
+  console.log(`Bytes: ${bytes}/${options.maxBytes}`);
+  if (options.dryRun) console.log("Dry run: yes");
+}
+
+main();

package/src/scripts/test-goalkeeper-update-checkpoint.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(SCRIPT_DIR, "..", "..");
+const TMP_ROOT = path.join(REPO_ROOT, ".goalkeeper", "tmp", "checkpoint-update");
+const WORKSPACE = path.join(TMP_ROOT, "workspace");
+const SESSION_ID = "checkpoint-update-poc";
+
+function run(args, options = {}) {
+  const result = spawnSync(process.execPath, args, {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    ...options,
+  });
+  return {
+    ...result,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+  };
+}
+
+function script(name) {
+  return path.join(SCRIPT_DIR, name);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function setupWorkspace() {
+  fs.rmSync(TMP_ROOT, { recursive: true, force: true });
+  fs.mkdirSync(WORKSPACE, { recursive: true });
+  fs.writeFileSync(
+    path.join(WORKSPACE, "AGENTS.md"),
+    [
+      "# Goalkeeper Guardrail",
+      "",
+      "At the start of each new assistant turn, before source work, read .goalkeeper/sessions/<goal-session-id>/checkpoint.md.",
+      "This checkpoint-first rule applies after compaction, compact, start, resume, and before normal project work.",
+      "",
+    ].join("\n"),
+  );
+}
+
+function main() {
+  setupWorkspace();
+
+  const init = run([
+    script("goalkeeper-init.mjs"),
+    "--workspace",
+    WORKSPACE,
+    "--session",
+    SESSION_ID,
+    "--goal",
+    "Validate canonical checkpoint updates.",
+    "--constraint",
+    "Keep checkpoints short.",
+    "--json",
+  ]);
+  assert(init.status === 0, `init failed:\n${init.stderr}\n${init.stdout}`);
+
+  const append = run([
+    script("goalkeeper-append-event.mjs"),
+    "--workspace",
+    WORKSPACE,
+    "--type",
+    "decision",
+    "--text",
+    "Use the update helper to rewrite checkpoint.md canonically.",
+    "--json",
+  ]);
+  assert(append.status === 0, `append failed:\n${append.stderr}\n${append.stdout}`);
+  const parsedAppend = JSON.parse(append.stdout);
+  assert(parsedAppend.sessionId === SESSION_ID, "append helper should recover the session id from active-session");
+  assert(parsedAppend.lineNumber === 4, "append helper should report the appended JSONL line number");
+
+  const contextPackPath = path.join(WORKSPACE, ".goalkeeper", "sessions", SESSION_ID, "context-pack.md");
+  assert(fs.existsSync(contextPackPath), "init should create context-pack.md");
+
+  const turnStartWithContext = run([
+    script("goalkeeper-turn-start.mjs"),
+    "--workspace",
+    WORKSPACE,
+    "--context",
+    "--json",
+  ]);
+  assert(turnStartWithContext.status === 0, `turn-start --context failed:\n${turnStartWithContext.stderr}\n${turnStartWithContext.stdout}`);
+  const parsedTurnStart = JSON.parse(turnStartWithContext.stdout);
+  assert(parsedTurnStart.contextPackPath === contextPackPath, "turn-start should report context-pack.md path");
+  assert(parsedTurnStart.contextPack.includes("Context Pack"), "turn-start --context should include context pack content");
+
+  const noActiveWorkspace = path.join(TMP_ROOT, "no-active-workspace");
+  fs.mkdirSync(path.join(noActiveWorkspace, ".goalkeeper", "sessions", SESSION_ID), { recursive: true });
+  fs.writeFileSync(path.join(noActiveWorkspace, ".goalkeeper", "sessions", SESSION_ID, "events.jsonl"), "");
+  const appendWithoutActive = run([
+    script("goalkeeper-append-event.mjs"),
+    "--workspace",
+    noActiveWorkspace,
+    "--type",
+    "decision",
+    "--text",
+    "This should fail because no active-session pointer exists.",
+    "--json",
+  ]);
+  assert(appendWithoutActive.status === 1, "append without --session should fail when active-session is missing");
+
+  const schemaInvalidWorkspace = path.join(TMP_ROOT, "schema-invalid-workspace");
+  const schemaInvalidSessionDir = path.join(schemaInvalidWorkspace, ".goalkeeper", "sessions", SESSION_ID);
+  fs.mkdirSync(schemaInvalidSessionDir, { recursive: true });
+  fs.writeFileSync(path.join(schemaInvalidWorkspace, ".goalkeeper", "active-session"), `${SESSION_ID}\n`);
+  fs.writeFileSync(
+    path.join(schemaInvalidSessionDir, "events.jsonl"),
+    `${JSON.stringify({ ts: "2026-05-18T00:00:00Z", type: "unknown", text: "bad existing event" })}\n`,
+  );
+  const appendToSchemaInvalid = run([
+    script("goalkeeper-append-event.mjs"),
+    "--workspace",
+    schemaInvalidWorkspace,
+    "--type",
+    "decision",
+    "--text",
+    "This should fail because the existing event log is schema-invalid.",
+    "--json",
+  ]);
+  assert(appendToSchemaInvalid.status === 1, "append should refuse an existing schema-invalid event log");
+
+  const update = run([
+    script("goalkeeper-update-checkpoint.mjs"),
+    "--workspace",
+    WORKSPACE,
+    "--goal",
+    "Validate canonical checkpoint updates.",
+    "--done",
+    "Doctor passes after a helper-rendered checkpoint.",
+    "--status",
+    "Helper under test.",
+    "--throughline",
+    "Use deterministic CLI rendering instead of manual checkpoint Markdown.",
+    "--why",
+    "Long sessions need bounded state that can be safely refreshed after compacted turns.",
+    "--constraint",
+    "Keep checkpoint under the routine-read budget.",
+    "--forbidden",
+    "Do not paste long command output into checkpoint.md.",
+    "--decision",
+    "Render a canonical checkpoint from CLI fields.",
+    "--attempt",
+    "Manual checkpoint edits remain possible but are not the default path.",
+    "--file",
+    "src/scripts/goalkeeper-update-checkpoint.mjs",
+    "--file",
+    "docs/path with spaces.md",
+    "--evidence",
+    "This test rewrites checkpoint.md in a guarded temporary workspace.",
+    "--verified",
+    "Update helper exits 0.",
+    "--unverified",
+    "No real compact boundary is generated by this unit test.",
+    "--risk",
+    "Overlong input should fail before writing.",
+    "--next",
+    "Run strict doctor against the updated temporary workspace.",
+    "--json",
+  ]);
+  assert(update.status === 0, `update failed:\n${update.stderr}\n${update.stdout}`);
+
+  const parsedUpdate = JSON.parse(update.stdout);
+  assert(parsedUpdate.bytes > 0 && parsedUpdate.bytes <= 8_000, "updated checkpoint should fit the default budget");
+
+  const checkpointPath = path.join(WORKSPACE, ".goalkeeper", "sessions", SESSION_ID, "checkpoint.md");
+  const checkpoint = fs.readFileSync(checkpointPath, "utf8");
+  assert(checkpoint.includes("## Active Goal"), "checkpoint should include Active Goal section");
+  assert(checkpoint.includes("## Context Pack"), "checkpoint should include Context Pack section");
+  assert(checkpoint.includes("## Next Action"), "checkpoint should include Next Action section");
+  assert(checkpoint.includes("src/scripts/goalkeeper-update-checkpoint.mjs"), "checkpoint should include important files");
+  assert(checkpoint.includes("docs/path with spaces.md"), "checkpoint should preserve spaces in file paths");
+
+  const beforeOversize = checkpoint;
+  const oversize = run([
+    script("goalkeeper-update-checkpoint.mjs"),
+    "--workspace",
+    WORKSPACE,
+    "--goal",
+    "Validate oversize refusal.",
+    "--decision",
+    "x".repeat(2_000),
+    "--next",
+    "This should not be written.",
+    "--max-bytes",
+    "1000",
+    "--json",
+  ]);
+  assert(oversize.status === 1, "oversize checkpoint update should exit 1");
+  assert(fs.readFileSync(checkpointPath, "utf8") === beforeOversize, "oversize failure should not rewrite checkpoint.md");
+
+  const doctor = run([
+    script("goalkeeper-doctor.mjs"),
+    "--workspace",
+    WORKSPACE,
+    "--session",
+    SESSION_ID,
+    "--strict",
+    "--json",
+  ]);
+  assert(doctor.status === 0, `doctor failed:\n${doctor.stderr}\n${doctor.stdout}`);
+  const parsedDoctor = JSON.parse(doctor.stdout);
+  assert(parsedDoctor.ok === true, "doctor JSON should be ok");
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        workspace: WORKSPACE,
+        sessionId: SESSION_ID,
+        checkpointBytes: parsedUpdate.bytes,
+        doctor: parsedDoctor.summary,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/src/templates/AGENTS.goalkeeper.md

@@ -0,0 +1,48 @@
+# Goalkeeper Guardrail
+
+When this repository has an active `.goalkeeper/sessions/<goal-session-id>/` directory, treat it as the continuity source for long-running Codex work.
+
+At the start of each new assistant turn, before reading normal project files or making edits:
+
+1. Run `pwd` if the workspace is unclear.
+2. Locate the active checkpoint under `.goalkeeper/sessions/`.
+3. Read `.goalkeeper/sessions/<goal-session-id>/checkpoint.md`.
+4. If the checkpoint is unclear or too thin, read `.goalkeeper/sessions/<goal-session-id>/context-pack.md`.
+5. If exact evidence is needed, inspect recent `.goalkeeper/sessions/<goal-session-id>/events.jsonl` entries.
+
+If this repository includes `src/scripts/goalkeeper-turn-start.mjs`, you may use:
+
+```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 also valid:
+
+```bash
+node src/scripts/goalkeeper-turn-start.mjs
+```
+
+If the helper comes from an installed skill path instead of this repository, pass the target workspace:
+
+```bash
+node <skill-path>/src/scripts/goalkeeper-turn-start.mjs --workspace <workspace> --session <goal-session-id>
+```
+
+If checkpoint recovery needs the larger context pack too, add `--context`.
+
+Allowed before reading the checkpoint:
+
+- `pwd`
+- listing `.goalkeeper/sessions/`
+- reading `.goalkeeper/active-session`
+- minimal filename inspection needed to choose the active session
+- running `node src/scripts/goalkeeper-turn-start.mjs --session <goal-session-id>`
+- running `node src/scripts/goalkeeper-turn-start.mjs`
+- running `node <skill-path>/src/scripts/goalkeeper-turn-start.mjs --workspace <workspace> --session <goal-session-id>`
+- adding `--context` to the turn-start command when the checkpoint is too thin
+
+Do not read project docs, source files, examples, tests, or make edits before the checkpoint read.
+
+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.
+
+Do not claim Goalkeeper reduces compaction frequency. Its purpose is direction recovery after compaction, resume, or handoff.

package/src/templates/active-session

@@ -0,0 +1 @@
+<goal-session-id>

package/src/templates/checkpoint.md

@@ -0,0 +1,54 @@
+# Goalkeeper Checkpoint
+
+## Active Goal
+
+- Objective:
+- Done criteria:
+- Current status:
+
+## Throughline
+
+- Current direction:
+- Why this direction:
+
+## Constraints
+
+- Non-negotiable:
+- Forbidden approaches:
+
+## Decisions
+
+- 
+
+## Attempts And Failures
+
+- 
+
+## Important Files
+
+- 
+
+## Evidence
+
+- 
+
+## Context Pack
+
+- 
+
+## Verification
+
+- Verified:
+- Not yet verified:
+
+## Open Risks
+
+- 
+
+## Next Action
+
+- 
+
+## Last Updated
+
+-