@christang/keel 5.1.1

package/src/core/goal.js

@@ -0,0 +1,230 @@
+"use strict";
+
+// Keel 4.1.0 single-task native goal projection contract.
+//
+// Compiles one passing `keel-task-capsule/v1` into an ephemeral
+// `keel-native-goal/v1` projection for a supported native runtime. The
+// projection is never written as Keel-owned state; OpenSpec, Git, the capsule
+// fingerprint, and deterministic gates remain durable authority.
+
+const { resolveContext } = require("./context");
+const { loadTaskContract } = require("./task-contract");
+const { probeCapabilities } = require("./capabilities");
+
+const GOAL_VERSION = "keel-native-goal/v1";
+const CLAUDE_CONDITION_LIMIT = 4000;
+const SUPPORTED_GOAL_TARGETS = new Set(["codex", "claude"]);
+const TERMINAL_STATES = ["complete", "blocked", "paused"];
+const EVIDENCE_PRESENTATION = [
+  "Surface every Command result and gate outcome in the transcript before any success claim.",
+  "Native evaluator success alone never marks or reports the OpenSpec task complete.",
+  "Achievement requires matching change/task/fingerprint, Acceptance demonstrated by the named Commands, passing Review, passing task-complete, and the durably checked task checkbox.",
+];
+
+function blockedGoal(target, reason, warnings = [], extra = {}) {
+  return {
+    version: GOAL_VERSION,
+    status: "blocked",
+    target,
+    source: null,
+    capability: null,
+    goal: null,
+    reasons: [reason],
+    warnings,
+    ...extra,
+  };
+}
+
+function renderCondition(goal) {
+  const lines = [
+    `Goal: complete exactly one OpenSpec task — ${goal.owner} (fingerprint ${goal.fingerprint.value}).`,
+    `Objective: ${goal.objective}`,
+    "Acceptance (all must be demonstrated by the named Commands):",
+    ...goal.acceptance.map((item) => `- ${item}`),
+    "Commands:",
+    ...goal.commands.map((item) => `- ${item}`),
+    `Verification strategy: ${goal.verificationStrategy}.`,
+    `Write boundary (Touch): ${goal.touch.join(", ")}.`,
+    "Stop/Autonomy boundary:",
+    ...goal.stopBoundary.map((item) => `- ${item}`),
+    "Ownership: the current agent is the sole writer and owns Review, gate invocation, the task checkbox, and completion.",
+    "Done only when: task-complete passes and the current agent has durably checked the task; then stop and require a new explicit authorization before any next task.",
+  ];
+  return lines.join("\n");
+}
+
+function compileGoalProjection(repo, options) {
+  const target = options.target;
+  if (!SUPPORTED_GOAL_TARGETS.has(target)) {
+    return blockedGoal(
+      target,
+      `Native single-task goal execution supports codex and claude only; `
+        + `${target || "<missing>"} remains manual/compatibility-only.`
+    );
+  }
+  if (!options.change || !options.task) {
+    return blockedGoal(
+      target,
+      "Native goal activation requires one explicit --change and --task "
+        + "selection; ambiguous, multiple, or task-group activation is rejected."
+    );
+  }
+
+  const context = resolveContext(repo, {
+    change: options.change,
+    task: options.task,
+  });
+  if (context.status !== "ready" || !context.selection) {
+    return blockedGoal(
+      target,
+      context.reasons.join(" ") || "Current OpenSpec context is not ready.",
+      context.warnings
+    );
+  }
+  const change = context.selection.change;
+  const taskId = context.selection.task;
+  if (!taskId) {
+    return blockedGoal(
+      target,
+      "Native goal activation requires one selected executable task, not a "
+        + "change backlog or contiguous task group.",
+      context.warnings
+    );
+  }
+
+  const loaded = loadTaskContract(repo, change, taskId);
+  if (!loaded) {
+    return blockedGoal(
+      target,
+      `Selected durable task owner openspec/changes/${change}/tasks.md#${taskId} `
+        + "is missing.",
+      context.warnings
+    );
+  }
+  if (loaded.task.checked) {
+    return blockedGoal(
+      target,
+      "Selected task is already complete; a later task requires a new explicit "
+        + "user authorization and a new start fingerprint.",
+      context.warnings
+    );
+  }
+  if (loaded.contract.diagnostics.length > 0) {
+    return blockedGoal(
+      target,
+      loaded.contract.diagnostics.map((item) => item.message).join(" "),
+      context.warnings
+    );
+  }
+
+  const contract = loaded.contract;
+  const capsule = contract.capsule;
+  const owner = `openspec/changes/${change}/tasks.md#${taskId}`;
+
+  // Continuity is reconstructed from durable OpenSpec/Git authority, never a
+  // Keel cursor or cache: a resume passes the previously recorded owner and
+  // fingerprint, and any divergence hard-stops rather than silently rebinding.
+  if (options.expectedOwner && options.expectedOwner !== owner) {
+    return blockedGoal(
+      target,
+      `Recorded authorization owns ${options.expectedOwner}, but the current `
+        + `OpenSpec selection is ${owner}; checkout divergence requires new `
+        + "explicit authorization, not automatic rebinding.",
+      context.warnings
+    );
+  }
+  if (
+    options.expectedFingerprint
+    && options.expectedFingerprint !== contract.fingerprint.value
+  ) {
+    return blockedGoal(
+      target,
+      `Recompiled capsule fingerprint ${contract.fingerprint.value} does not `
+        + `match the recorded authorization ${options.expectedFingerprint}; `
+        + "fingerprint drift requires reauthorization before any product write.",
+      context.warnings
+    );
+  }
+
+  const capabilities = probeCapabilities(repo, target);
+  const capability = capabilities.capabilities["execution.goal"];
+
+  const goal = {
+    version: GOAL_VERSION,
+    target,
+    change,
+    task: taskId,
+    fingerprint: contract.fingerprint,
+    objective: capsule.task.title,
+    acceptance: capsule.acceptance,
+    commands: capsule.verification.commands.map(
+      (item) => `${item.label}: ${item.check}`
+    ),
+    verificationStrategy: capsule.verification.strategy,
+    touch: capsule.touch,
+    stopBoundary: [...capsule.boundaries.stop, ...capsule.boundaries.autonomy],
+    owner: capsule.owner,
+    ownership: "current-agent-sole-writer",
+    helperPolicy: capsule.helperAuthority,
+    terminalStates: TERMINAL_STATES,
+    evidencePresentation: EVIDENCE_PRESENTATION,
+    authorizationEvidence: {
+      field: "Automation authorization: single-task",
+      target,
+      change,
+      task: taskId,
+      fingerprint: contract.fingerprint.value,
+    },
+    prohibitions: capsule.prohibitions,
+  };
+  goal.owner = owner;
+  const conditionText = renderCondition(goal);
+  goal.condition = conditionText;
+  goal.conditionLength = conditionText.length;
+
+  if (target === "claude" && conditionText.length > CLAUDE_CONDITION_LIMIT) {
+    return blockedGoal(
+      target,
+      `Compiled goal condition is ${conditionText.length} characters, above the `
+        + `Claude ${CLAUDE_CONDITION_LIMIT}-character limit; refusing native `
+        + "activation rather than omitting Acceptance, fingerprint, or stop "
+        + "authority. Use the manual current-agent loop instead.",
+      context.warnings,
+      { conditionLength: conditionText.length }
+    );
+  }
+
+  return {
+    version: GOAL_VERSION,
+    status: "ready",
+    target,
+    source: { authority: "OpenSpec", owner, change, task: taskId },
+    capability,
+    goal,
+    reasons: [],
+    warnings: context.warnings,
+  };
+}
+
+function renderGoalProjection(result) {
+  const lines = [
+    `Keel native goal: ${result.status}`,
+    `Target: ${result.target}`,
+  ];
+  if (result.source) lines.push(`Owner: ${result.source.owner}`);
+  if (result.goal) {
+    lines.push(`Fingerprint: ${result.goal.fingerprint.value}`);
+    lines.push(`Condition length: ${result.goal.conditionLength}`);
+  }
+  for (const reason of result.reasons || []) lines.push(`Reason: ${reason}`);
+  for (const warning of result.warnings || []) lines.push(`Warning: ${warning}`);
+  return `${lines.join("\n")}\n`;
+}
+
+module.exports = {
+  GOAL_VERSION,
+  CLAUDE_CONDITION_LIMIT,
+  SUPPORTED_GOAL_TARGETS,
+  compileGoalProjection,
+  renderGoalProjection,
+};

package/src/core/guard.js

@@ -0,0 +1,295 @@
+"use strict";
+
+// Keel 4.x write-guard contract: an explicit, fingerprinted, disposable
+// enforcement manifest for exactly one task. The manifest is never selection,
+// continuity, or completion authority; only its presence authorizes the
+// plugin PreToolUse hook to deny out-of-Touch file edits, and every broken
+// state fails closed through guard status while absence changes nothing.
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { loadTaskContract } = require("./task-contract");
+
+const MANIFEST_SCHEMA = "keel-write-guard/v1";
+
+class GuardInputError extends Error {}
+
+function manifestFile(repo) {
+  return path.join(repo, "keel", "guard.json");
+}
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function guardResult(subcommand, status, extra = {}) {
+  return {
+    schemaVersion: 1,
+    command: "guard",
+    subcommand,
+    status,
+    manifestPath: "keel/guard.json",
+    problems: [],
+    warnings: [
+      "The guard manifest is a disposable enforcement pointer; OpenSpec and "
+        + "Git remain the only durable authority and selection never derives "
+        + "from it.",
+    ],
+    ...extra,
+  };
+}
+
+function authorityPaths(repo, change, contract) {
+  const paths = new Set([`openspec/changes/${change}/tasks.md`]);
+  for (const item of contract.capsule.authority) {
+    const source = String(item.source || "").split("#")[0].trim();
+    if (source && fs.existsSync(path.join(repo, source))) {
+      paths.add(source.replace(/\\/g, "/"));
+    }
+  }
+  return [...paths].sort();
+}
+
+function hashAuthority(repo, paths) {
+  return paths.map((relative) => ({
+    path: relative,
+    sha256: sha256(fs.readFileSync(path.join(repo, relative))),
+  }));
+}
+
+function readManifest(repo) {
+  const file = manifestFile(repo);
+  if (!fs.existsSync(file)) return { state: "absent" };
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {
+      state: "invalid",
+      problems: [
+        {
+          code: "invalid-manifest",
+          message:
+            "keel/guard.json is unreadable or not JSON; run `keel guard "
+            + "clear` and reauthorize with `keel guard start`.",
+        },
+      ],
+    };
+  }
+  const shapeErrors = [];
+  if (manifest.schema !== MANIFEST_SCHEMA) {
+    shapeErrors.push(`schema must be ${MANIFEST_SCHEMA}`);
+  }
+  if (typeof manifest.change !== "string" || !manifest.change) {
+    shapeErrors.push("change must be a non-empty string");
+  }
+  if (typeof manifest.task !== "string" || !manifest.task) {
+    shapeErrors.push("task must be a non-empty string");
+  }
+  if (
+    !manifest.fingerprint
+    || manifest.fingerprint.algorithm !== "sha256"
+    || !/^[0-9a-f]{64}$/.test(String(manifest.fingerprint.value || ""))
+  ) {
+    shapeErrors.push("fingerprint must record a sha256 value");
+  }
+  if (
+    !Array.isArray(manifest.touch)
+    || manifest.touch.length === 0
+    || manifest.touch.some((item) => typeof item !== "string" || !item)
+  ) {
+    shapeErrors.push("touch must be a non-empty string list");
+  }
+  if (
+    !Array.isArray(manifest.authority)
+    || manifest.authority.length === 0
+    || manifest.authority.some(
+      (item) =>
+        !item
+        || typeof item.path !== "string"
+        || !/^[0-9a-f]{64}$/.test(String(item.sha256 || ""))
+    )
+  ) {
+    shapeErrors.push("authority must list hashed source files");
+  }
+  if (shapeErrors.length > 0) {
+    return {
+      state: "invalid",
+      problems: shapeErrors.map((message) => ({
+        code: "invalid-manifest",
+        message:
+          `keel/guard.json is invalid (${message}); run \`keel guard clear\` `
+          + "and reauthorize with `keel guard start`.",
+      })),
+    };
+  }
+  return { state: "ok", manifest };
+}
+
+function startGuard(repo, options) {
+  if (!options.change || !options.task) {
+    throw new GuardInputError("guard start requires --change and --task");
+  }
+  const loaded = loadTaskContract(repo, options.change, options.task);
+  if (!loaded) {
+    throw new GuardInputError(
+      `task ${options.change}#${options.task} does not exist`
+    );
+  }
+  const problems = [];
+  if (loaded.task.checked) {
+    problems.push({
+      code: "task-completed",
+      message:
+        `Task ${options.change}#${options.task} is already checked complete; `
+        + "a completed task cannot be guarded. Run `keel guard clear` and "
+        + "authorize a new task explicitly.",
+    });
+  }
+  problems.push(...loaded.contract.diagnostics);
+
+  const existing = readManifest(repo);
+  if (
+    problems.length === 0
+    && existing.state === "ok"
+    && (
+      existing.manifest.change !== options.change
+      || existing.manifest.task !== options.task
+    )
+    && !options.force
+  ) {
+    problems.push({
+      code: "guard-active",
+      message:
+        `An active guard already covers ${existing.manifest.change}#`
+        + `${existing.manifest.task}; run \`keel guard clear\` first or pass `
+        + "--force to replace it.",
+    });
+  }
+  if (problems.length > 0) {
+    const refused = guardResult("start", "refused");
+    refused.problems = problems;
+    return refused;
+  }
+
+  const paths = authorityPaths(repo, options.change, loaded.contract);
+  const manifest = {
+    schema: MANIFEST_SCHEMA,
+    change: options.change,
+    task: options.task,
+    fingerprint: loaded.contract.fingerprint,
+    touch: loaded.contract.capsule.touch,
+    authority: hashAuthority(repo, paths),
+  };
+  fs.mkdirSync(path.join(repo, "keel"), { recursive: true });
+  fs.writeFileSync(
+    manifestFile(repo),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8"
+  );
+  return guardResult("start", "started", { manifest });
+}
+
+function guardStatus(repo) {
+  const existing = readManifest(repo);
+  if (existing.state === "absent") {
+    return guardResult("status", "absent");
+  }
+  if (existing.state === "invalid") {
+    const invalid = guardResult("status", "invalid");
+    invalid.problems = existing.problems;
+    return invalid;
+  }
+  const manifest = existing.manifest;
+  const problems = [];
+  const loaded = loadTaskContract(repo, manifest.change, manifest.task);
+  if (!loaded) {
+    problems.push({
+      code: "authority-drift",
+      message:
+        `Guarded task ${manifest.change}#${manifest.task} no longer resolves; `
+        + "reauthorize through `keel gate task-start` and `keel guard start`.",
+    });
+    const drifted = guardResult("status", "drifted", { manifest });
+    drifted.problems = problems;
+    return drifted;
+  }
+  if (loaded.task.checked) {
+    const completed = guardResult("status", "completed", { manifest });
+    completed.problems = [
+      {
+        code: "task-completed",
+        message:
+          `Guarded task ${manifest.change}#${manifest.task} is checked `
+          + "complete; run `keel guard clear` before authorizing new work.",
+      },
+    ];
+    return completed;
+  }
+  if (loaded.contract.diagnostics.length > 0) {
+    problems.push(...loaded.contract.diagnostics);
+  } else if (
+    loaded.contract.fingerprint.value !== manifest.fingerprint.value
+  ) {
+    problems.push({
+      code: "fingerprint-drift",
+      message:
+        "The recompiled capsule fingerprint no longer matches the guard; "
+        + "reauthorize through `keel gate task-start` and `keel guard start`.",
+    });
+  }
+  for (const entry of manifest.authority) {
+    const file = path.join(repo, entry.path);
+    if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== entry.sha256) {
+      problems.push({
+        code: "authority-drift",
+        message:
+          `Recorded authority hash for ${entry.path} no longer matches; `
+          + "reauthorize through `keel gate task-start` and `keel guard start`.",
+      });
+    }
+  }
+  if (problems.length > 0) {
+    const drifted = guardResult("status", "drifted", { manifest });
+    drifted.problems = problems;
+    return drifted;
+  }
+  return guardResult("status", "active", { manifest });
+}
+
+function clearGuard(repo) {
+  const file = manifestFile(repo);
+  if (!fs.existsSync(file)) {
+    return guardResult("clear", "absent");
+  }
+  fs.rmSync(file, { force: true });
+  return guardResult("clear", "cleared");
+}
+
+function renderGuard(result) {
+  const lines = [
+    `Keel guard: ${result.subcommand}`,
+    `Status: ${result.status}`,
+  ];
+  if (result.manifest) {
+    lines.push(
+      `Selection: ${result.manifest.change}#${result.manifest.task}`,
+      `Fingerprint: ${result.manifest.fingerprint.algorithm}:`
+        + result.manifest.fingerprint.value
+    );
+  }
+  for (const item of result.problems) lines.push(`Problem: ${item.message}`);
+  for (const warning of result.warnings) lines.push(`Warning: ${warning}`);
+  return `${lines.join("\n")}\n`;
+}
+
+module.exports = {
+  GuardInputError,
+  MANIFEST_SCHEMA,
+  clearGuard,
+  guardStatus,
+  readManifest,
+  renderGuard,
+  startGuard,
+};