@christang/keel 5.1.1

package/src/core/helper.js

@@ -0,0 +1,319 @@
+"use strict";
+
+// Keel 4.1.0 bounded read-only helper contract.
+//
+// A helper is never a second writer. `keel project helper` compiles one
+// bounded read-only question or one exact repository-byte-stable verification
+// command into a `keel-helper-brief/v1` evidence contract, and verifies a
+// helper's return only after proving the repository bytes are unchanged. The
+// current agent stays the sole writer, owner of Acceptance, Review, gates, and
+// completion; helper absence never disables current-agent goal execution.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+
+const BRIEF_VERSION = "keel-helper-brief/v1";
+const BASELINE_VERSION = "keel-helper-baseline/v1";
+const VERIFY_VERSION = "keel-helper-verification/v1";
+const SUPPORTED_HELPER_TARGETS = new Set(["codex", "claude"]);
+
+// Any mutation, delegation, or ownership request disqualifies a read-only brief.
+const FORBIDDEN_INTENT = new RegExp(
+  "\\b(implement|write|edit|modify|create|refactor|delete|remove|fix|apply|"
+    + "generate|install|commit|push|sync|archive|mark|check off|rewrite|"
+    + "update the task|change the acceptance|use the fallback|use a fallback)\\b",
+  "i"
+);
+const DELEGATION_INTENT = new RegExp(
+  "\\b(subagent|sub-agent|delegate|delegation|spawn|agent team|another agent|"
+    + "helper)\\b",
+  "i"
+);
+// Shell tokens that would create or move repository artifacts.
+const ARTIFACT_TOKENS = [
+  ">", ">>", "|&", "tee ", "git commit", "git add", "git push", "git checkout",
+  "git reset", "git restore", "git rm", "git mv", "npm install", "npm i ",
+  "npm ci", "mkdir", "touch ", "rm ", "mv ", "cp ", "rmdir",
+];
+const REPORT_SCHEMA = [
+  "question-or-command",
+  "reads-performed",
+  "observed-evidence",
+  "byte-stability: verified|rejected|unverifiable",
+  "no-writes-no-delegation-no-completion-authority",
+];
+
+function blockedBrief(target, reason, extra = {}) {
+  return {
+    version: BRIEF_VERSION,
+    status: "blocked",
+    target,
+    brief: null,
+    reasons: [reason],
+    ...extra,
+  };
+}
+
+function isExternal(repo, candidate) {
+  const rel = path.relative(repo, path.resolve(candidate));
+  return (
+    rel === ".."
+    || rel.startsWith(`..${path.sep}`)
+    || path.isAbsolute(rel)
+  );
+}
+
+function compileHelperBrief(repo, options) {
+  const target = options.target;
+  if (!SUPPORTED_HELPER_TARGETS.has(target)) {
+    return blockedBrief(
+      target,
+      `Bounded read-only helpers support codex and claude only; `
+        + `${target || "missing"} remains manual/compatibility-only.`
+    );
+  }
+
+  const question = (options.helperQuestion || "").trim();
+  const command = (options.helperCommand || "").trim();
+  if ((question && command) || (!question && !command)) {
+    return blockedBrief(
+      target,
+      "A helper brief needs exactly one bounded read-only question or one exact "
+        + "repository-byte-stable verification command, not both and not neither."
+    );
+  }
+
+  const external = options.helperExternal || [];
+  for (const declared of external) {
+    if (!isExternal(repo, declared)) {
+      return blockedBrief(
+        target,
+        `Declared helper output path is inside the repository: ${declared}; `
+          + "helper temporaries must live outside the worktree."
+      );
+    }
+  }
+
+  if (question) {
+    if (/\?[\s\S]*\?/.test(question)) {
+      return blockedBrief(
+        target,
+        "A helper brief carries one bounded question; multiple unrelated "
+          + "questions must be split into separate read-only briefs."
+      );
+    }
+    if (DELEGATION_INTENT.test(question)) {
+      return blockedBrief(
+        target,
+        "A helper cannot delegate or spawn nested helpers; the brief must be a "
+          + "single read-only question the helper answers itself."
+      );
+    }
+    if (FORBIDDEN_INTENT.test(question)) {
+      return blockedBrief(
+        target,
+        "A helper is read-only and owns no completion authority; it cannot be "
+          + "asked to implement, write, mark, sync, archive, commit, push, or "
+          + "change Acceptance."
+      );
+    }
+  } else {
+    if (DELEGATION_INTENT.test(command)) {
+      return blockedBrief(
+        target,
+        "A helper verification command cannot delegate or nest further helpers."
+      );
+    }
+    const lowered = command.toLowerCase();
+    const artifact = ARTIFACT_TOKENS.find((token) => lowered.includes(token));
+    if (artifact) {
+      return blockedBrief(
+        target,
+        `Helper command would generate or move repository artifacts (${artifact.trim()}); `
+          + "only repository-byte-stable verification commands are allowed."
+      );
+    }
+    if (FORBIDDEN_INTENT.test(command)) {
+      return blockedBrief(
+        target,
+        "A helper verification command cannot mark, sync, archive, commit, push, "
+          + "or otherwise assume completion authority."
+      );
+    }
+  }
+
+  const brief = {
+    version: BRIEF_VERSION,
+    target,
+    mode: question ? "question" : "verification-command",
+    request: question || command,
+    reads: options.helperReads || [],
+    externalPaths: external,
+    authority: "read-only-evidence-only",
+    writesProducts: false,
+    delegates: false,
+    completionAuthority: false,
+    reportSchema: REPORT_SCHEMA,
+  };
+  return {
+    version: BRIEF_VERSION,
+    status: "ready",
+    target,
+    brief,
+    reasons: [],
+  };
+}
+
+function snapshotRepo(repo) {
+  const snapshot = {};
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === ".git") continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        const rel = path.relative(repo, full).replace(/\\/g, "/");
+        const bytes = fs.readFileSync(full);
+        const hash = crypto.createHash("sha256").update(bytes).digest("hex");
+        const mode = fs.statSync(full).mode & 0o777;
+        snapshot[rel] = `${hash}:${mode.toString(8)}`;
+      }
+    }
+  };
+  walk(repo);
+  return snapshot;
+}
+
+function captureHelperBaseline(repo, options) {
+  const outPath = options.helperBaseline;
+  if (!outPath) {
+    throw new Error("helper baseline capture requires --baseline");
+  }
+  if (!isExternal(repo, outPath)) {
+    throw new Error(
+      "helper baseline must be written outside the repository worktree"
+    );
+  }
+  const snapshot = snapshotRepo(repo);
+  fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+  fs.writeFileSync(
+    path.resolve(outPath),
+    `${JSON.stringify({ version: BASELINE_VERSION, snapshot }, null, 2)}\n`,
+    "utf8"
+  );
+  return {
+    version: BASELINE_VERSION,
+    status: "captured",
+    path: path.resolve(outPath),
+    count: Object.keys(snapshot).length,
+  };
+}
+
+function classifyChanges(before, after) {
+  const changes = [];
+  for (const [rel, value] of Object.entries(after)) {
+    if (!(rel in before)) {
+      changes.push({ path: rel, kind: "added" });
+    } else if (before[rel] !== after[rel]) {
+      const [beforeHash, beforeMode] = before[rel].split(":");
+      const [afterHash] = value.split(":");
+      changes.push({
+        path: rel,
+        kind: beforeHash === afterHash ? "permission-changed" : "modified",
+      });
+      void beforeMode;
+    }
+  }
+  for (const rel of Object.keys(before)) {
+    if (!(rel in after)) {
+      changes.push({ path: rel, kind: "removed" });
+    }
+  }
+  return changes.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function verifyHelperEvidence(repo, options) {
+  const baselinePath = options.helperBaseline;
+  if (!baselinePath || !fs.existsSync(path.resolve(baselinePath))) {
+    return {
+      version: VERIFY_VERSION,
+      status: "unverifiable",
+      target: options.target,
+      changes: [],
+      cleanup: "none",
+      reasons: [
+        "Byte stability cannot be established without a recorded baseline; the "
+          + "verification remains current-agent work.",
+      ],
+    };
+  }
+  let baseline;
+  try {
+    baseline = JSON.parse(fs.readFileSync(path.resolve(baselinePath), "utf8"));
+  } catch {
+    return {
+      version: VERIFY_VERSION,
+      status: "unverifiable",
+      target: options.target,
+      changes: [],
+      cleanup: "none",
+      reasons: [
+        "Recorded helper baseline is unreadable; byte stability cannot be "
+          + "established and the verification remains current-agent work.",
+      ],
+    };
+  }
+  const before = baseline.snapshot || {};
+  const after = snapshotRepo(repo);
+  const changes = classifyChanges(before, after);
+  if (changes.length === 0) {
+    return {
+      version: VERIFY_VERSION,
+      status: "verified",
+      target: options.target,
+      changes: [],
+      cleanup: "none",
+      reasons: [],
+    };
+  }
+  return {
+    version: VERIFY_VERSION,
+    status: "rejected",
+    target: options.target,
+    changes,
+    // The helper never restores, deletes, or attributes; it reports exact paths.
+    cleanup: "none",
+    reasons: [
+      "Helper evidence rejected: repository bytes changed at "
+        + changes.map((item) => `${item.path} (${item.kind})`).join(", ")
+        + "; the current agent owns these paths and no cleanup is performed.",
+    ],
+  };
+}
+
+function renderHelper(result) {
+  const lines = [
+    `Keel helper: ${result.status}`,
+    `Version: ${result.version}`,
+  ];
+  if (result.target) lines.push(`Target: ${result.target}`);
+  for (const change of result.changes || []) {
+    lines.push(`Changed: ${change.path} (${change.kind})`);
+  }
+  for (const reason of result.reasons || []) lines.push(`Reason: ${reason}`);
+  return `${lines.join("\n")}\n`;
+}
+
+module.exports = {
+  BRIEF_VERSION,
+  BASELINE_VERSION,
+  VERIFY_VERSION,
+  SUPPORTED_HELPER_TARGETS,
+  compileHelperBrief,
+  captureHelperBaseline,
+  verifyHelperEvidence,
+  renderHelper,
+};

package/src/core/projection.js

@@ -0,0 +1,195 @@
+"use strict";
+
+// Keel 4.1.0 one-way native projection contract.
+
+const { resolveContext } = require("./context");
+const { loadTaskContract } = require("./task-contract");
+const { probeCapabilities } = require("./capabilities");
+
+const EVENTS = new Set([
+  "startup",
+  "resume",
+  "compaction",
+  "goal",
+  "task-view",
+  "worktree",
+  "subagent-start",
+  "subagent-stop",
+]);
+
+function blocked(target, event, reason, warnings = []) {
+  return {
+    schemaVersion: 1,
+    status: "blocked",
+    target,
+    event,
+    source: null,
+    capability: {
+      level: "manual",
+      command: "keel context --json",
+    },
+    projection: null,
+    reasons: [reason],
+    warnings,
+  };
+}
+
+function capabilityKey(event) {
+  if (event === "startup") return "continuity.start";
+  if (["resume", "compaction"].includes(event)) return "continuity.reinject";
+  if (event === "goal") return "execution.goal";
+  if (event === "task-view") return "execution.task-view";
+  if (event === "worktree") return "execution.worktree";
+  if (event === "subagent-start") return "delegation.context";
+  return "delegation.return";
+}
+
+function projectRuntime(repo, options) {
+  const event = options.projectionEvent;
+  if (!EVENTS.has(event)) {
+    throw new Error(`unsupported projection event: ${event || "<missing>"}`);
+  }
+  if (!["claude", "codex", "opencode"].includes(options.target)) {
+    throw new Error(`unsupported target: ${options.target}`);
+  }
+
+  const context = resolveContext(repo, {
+    change: options.change,
+    task: options.task,
+  });
+  if (context.status !== "ready" || !context.selection) {
+    return blocked(
+      options.target,
+      event,
+      context.reasons.join(" ") || "Current OpenSpec context is not ready.",
+      context.warnings
+    );
+  }
+  const change = context.selection.change;
+  const taskId = context.selection.task;
+  if (!taskId) {
+    return blocked(
+      options.target,
+      event,
+      "Projection requires one selected executable task.",
+      context.warnings
+    );
+  }
+  const loaded = loadTaskContract(repo, change, taskId);
+  if (!loaded || loaded.task.checked) {
+    return blocked(
+      options.target,
+      event,
+      "Selected durable task owner is missing or already complete.",
+      context.warnings
+    );
+  }
+  if (loaded.contract.diagnostics.length > 0) {
+    return blocked(
+      options.target,
+      event,
+      loaded.contract.diagnostics.map((item) => item.message).join(" "),
+      context.warnings
+    );
+  }
+
+  const owner = `openspec/changes/${change}/tasks.md#${taskId}`;
+  if (
+    event === "worktree"
+    && (!options.expectedOwner || options.expectedOwner !== owner)
+  ) {
+    return blocked(
+      options.target,
+      event,
+      `Current checkout owner ${owner} does not match the explicit expected owner.`,
+      context.warnings
+    );
+  }
+
+  const authorization = new Set(options.authorizations || []);
+  const requiredAuthorization =
+    event === "goal"
+      ? "goal"
+      : event === "task-view"
+        ? "task-view"
+        : event.startsWith("subagent-")
+          ? "subagent"
+          : null;
+  if (requiredAuthorization && !authorization.has(requiredAuthorization)) {
+    return blocked(
+      options.target,
+      event,
+      `${event} projection requires explicit ${requiredAuthorization} authorization.`,
+      context.warnings
+    );
+  }
+
+  const contract = loaded.contract;
+  const capsule = contract.capsule;
+  const capabilities = probeCapabilities(repo, options.target);
+  const capability = capabilities.capabilities[capabilityKey(event)];
+  const warnings = [...context.warnings];
+  if (options.nativeComplete) {
+    warnings.push(
+      "Native completion was ignored; only task-complete plus current-agent "
+        + "durable updates can complete OpenSpec work."
+    );
+  }
+  const projection = {
+    objective: capsule.task.title,
+    acceptance: capsule.acceptance,
+    stopBoundary: [
+      ...capsule.boundaries.stop,
+      ...capsule.boundaries.autonomy,
+    ],
+    nextAction: context.nextAction,
+    read: capsule.read,
+    touch: capsule.touch,
+    verification: capsule.verification,
+    evidenceContract: capsule.verification.commands.map(
+      (item) => `${item.label}: ${item.check}`
+    ),
+    owner: capsule.owner,
+    helperAuthority: capsule.helperAuthority,
+    fingerprint: contract.fingerprint,
+    prohibitions: capsule.prohibitions,
+  };
+  if (event === "subagent-stop") {
+    projection.returnAuthority = "report-and-evidence-only";
+  }
+
+  return {
+    schemaVersion: 1,
+    status: "ready",
+    target: options.target,
+    event,
+    source: {
+      authority: "OpenSpec",
+      owner,
+      change,
+      task: taskId,
+    },
+    capability,
+    contract,
+    projection,
+    reasons: [],
+    warnings,
+  };
+}
+
+function renderProjection(result) {
+  const lines = [
+    `Keel projection: ${result.status}`,
+    `Target: ${result.target}`,
+    `Event: ${result.event}`,
+  ];
+  if (result.source) lines.push(`Owner: ${result.source.owner}`);
+  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 = {
+  projectRuntime,
+  renderProjection,
+};