@workit-dev/core 0.0.1 → 1.0.0

package/src/core/config.ts

@@ -0,0 +1,351 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { configDir as workitConfigDir } from "./workit-paths.mjs";
+import type { Logger } from "./logger";
+import type { CommitFlavorPreset } from "./commit-flavors";
+
+// Optional diagnostic seam: adapters install their host logger so config
+// provenance events land in the same sanitized log stream.
+let diagnosticLogger: Logger | undefined;
+export const setDiagnosticLogger = (logger: Logger | undefined): void => {
+  diagnosticLogger = logger;
+};
+export const getDiagnosticLogger = (): Logger | undefined => diagnosticLogger;
+
+export type BranchPreset = "gitflow" | "github-flow" | "trunk-based" | "custom";
+
+export type ToolkitConfig = {
+  locale: string;
+  localeOptions: string[];
+  branchPolicy: {
+    preset: BranchPreset;
+    allowed: string[];
+    protected: string[];
+  };
+  commitPolicy: { preset: CommitFlavorPreset; pattern?: string };
+  /** How an interactive launch handles a newer release (default `prompt`). */
+  updates?: UpdatesMode;
+};
+
+/** `prompt` asks on an interactive launch, `auto` upgrades without asking, `off` never checks. */
+export type UpdatesMode = "prompt" | "auto" | "off";
+export const UPDATES_MODES: readonly UpdatesMode[] = ["prompt", "auto", "off"];
+export const isUpdatesMode = (value: unknown): value is UpdatesMode =>
+  UPDATES_MODES.includes(value as UpdatesMode);
+
+export const PRESETS: Record<BranchPreset, { allowed: string[]; protected: string[] }> = {
+  gitflow: {
+    allowed: ["feature/*", "bugfix/*", "hotfix/*", "release/*"],
+    protected: ["main", "develop", "master", "prod", "production"],
+  },
+  "github-flow": { allowed: ["*"], protected: ["main"] },
+  "trunk-based": { allowed: ["*"], protected: ["main"] },
+  custom: { allowed: [], protected: [] },
+};
+
+// RL-02: one shared preset merge helper. Changing the preset resets every
+// derived policy field from PRESETS; only `custom` carries explicit values
+// (falling back to the current policy when none are given).
+export const mergePreset = (
+  preset: BranchPreset,
+  input: { allowed?: string[]; protectedNames?: string[] } = {},
+  current: { branchPolicy: ToolkitConfig["branchPolicy"] } = {
+    branchPolicy: { preset, allowed: [], protected: [] },
+  },
+): ToolkitConfig["branchPolicy"] => {
+  const defs = PRESETS[preset];
+  return {
+    preset,
+    allowed:
+      preset === "custom" ? (input.allowed ?? current.branchPolicy.allowed) : [...defs.allowed],
+    protected:
+      preset === "custom"
+        ? (input.protectedNames ?? current.branchPolicy.protected)
+        : [...defs.protected],
+  };
+};
+
+/** Workit's config dir for this process (core/workit-paths.mjs). */
+export const resolveConfigDir = (): string => workitConfigDir(process.env);
+
+/** The path of a file in the config dir Workit reads, for every hint that names one. */
+export const configFilePath = (name: string): string => path.join(resolveConfigDir(), name);
+
+export const configDir = (): string => resolveConfigDir();
+
+// Region subtags: 2-letter ISO 3166 alpha-2 or 3-digit UN M.49 (es-419 =
+// Latinoamérica), per BCP-47 well-formedness for the tags this toolkit stores.
+export const LOCALE_RE = /^[a-z]{2,3}(-(?:[A-Z]{2}|[0-9]{3}))?$/;
+
+const DEFAULTS: ToolkitConfig = {
+  locale: "en",
+  localeOptions: ["en", "es-CL", "es-MX", "es-AR", "pt-BR"],
+  branchPolicy: {
+    preset: "gitflow",
+    allowed: [...PRESETS.gitflow.allowed],
+    protected: [...PRESETS.gitflow.protected],
+  },
+  commitPolicy: { preset: "conventional" },
+};
+
+// Configs whose branch policy nobody chose (no config.json, or one without a
+// valid branchPolicy.preset). For them the repository's own branches pick the
+// preset (resolveBranchPolicy's `repoPreset`), so a main-only repository is
+// not held to gitflow's `develop`.
+const unchosenBranchPolicy = new WeakSet<ToolkitConfig>([DEFAULTS]);
+
+const readSafe = (p: string): string | null => {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+// RL-01: typed reader contract. Every config reader distinguishes missing from
+// valid from malformed and reports the exact file path; risky consumers stop on
+// malformed instead of silently falling back to defaults.
+export type ReaderStatus = "missing" | "valid" | "malformed";
+
+export type ReaderResult<T> = {
+  status: ReaderStatus;
+  path: string;
+  config?: T;
+  error?: string;
+};
+
+// AR-07/CA-37: the one shared fail-closed shape rule for every object-config
+// reader (config, setup-state, workspaces, doctor). A parseable non-object
+// (null, scalar, array) is malformed, never defaults.
+export const isConfigObject = (value: unknown): boolean =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const parseConfigResult = (raw: string | null, file: string): ReaderResult<ToolkitConfig> => {
+  if (raw === null) return { status: "missing", path: file };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      status: "malformed",
+      path: file,
+      error: `${file} is not valid JSON`,
+    };
+  }
+  if (!isConfigObject(parsed)) {
+    return {
+      status: "malformed",
+      path: file,
+      error: `${file} is not a JSON object`,
+    };
+  }
+  // Only known keys are read: legacy fields such as the removed global
+  // `timezone` are tolerated and ignored, never an error.
+  const input = parsed as Partial<ToolkitConfig>;
+  const locale = LOCALE_RE.test(String(input.locale ?? ""))
+    ? (input.locale as string)
+    : DEFAULTS.locale;
+  const preset = (
+    Object.hasOwn(PRESETS, input.branchPolicy?.preset as string)
+      ? input.branchPolicy?.preset
+      : "gitflow"
+  ) as BranchPreset;
+  const commitPreset = (
+    COMMIT_PRESETS.includes(String(input.commitPolicy?.preset ?? ""))
+      ? input.commitPolicy?.preset
+      : "conventional"
+  ) as CommitFlavorPreset;
+  const config: ToolkitConfig = {
+    locale,
+    localeOptions: Array.isArray(input.localeOptions)
+      ? input.localeOptions
+      : DEFAULTS.localeOptions,
+    // RL-02/CA-23: the persisted preset is authoritative; derived allowed /
+    // protected fields always reset from PRESETS via the one shared merge.
+    branchPolicy: mergePreset(
+      preset,
+      {
+        allowed: Array.isArray(input.branchPolicy?.allowed)
+          ? input.branchPolicy.allowed
+          : undefined,
+        protectedNames: Array.isArray(input.branchPolicy?.protected)
+          ? input.branchPolicy.protected
+          : undefined,
+      },
+      DEFAULTS,
+    ),
+    commitPolicy: {
+      preset: commitPreset,
+      ...(typeof input.commitPolicy?.pattern === "string"
+        ? { pattern: input.commitPolicy.pattern }
+        : {}),
+    },
+    ...(isUpdatesMode(input.updates) ? { updates: input.updates } : {}),
+  };
+  if (!Object.hasOwn(PRESETS, input.branchPolicy?.preset as string))
+    unchosenBranchPolicy.add(config);
+  return { status: "valid", path: file, config };
+};
+
+export const readConfigTyped = (dir?: string): ReaderResult<ToolkitConfig> => {
+  const file = path.join(dir ?? configDir(), "config.json");
+  return parseConfigResult(readSafe(file), file);
+};
+
+// RL-01: no silent fallback on malformed config — every consumer gets an
+// exact-path diagnostic instead of defaults. Missing config still defaults.
+export const readConfig = (): ToolkitConfig => {
+  const result = readConfigTyped();
+  if (result.status === "malformed") throw new Error(result.error);
+  return result.config ?? DEFAULTS;
+};
+
+export const readConfigFromDir = (dir: string): ToolkitConfig => {
+  const result = readConfigTyped(dir);
+  if (result.status === "malformed") throw new Error(result.error);
+  return result.config ?? DEFAULTS;
+};
+
+export type ConfigInput = {
+  locale?: string;
+  localeOptions?: string[];
+  preset?: BranchPreset;
+  allowed?: string[];
+  protectedNames?: string[];
+  commitPolicy?: ToolkitConfig["commitPolicy"];
+};
+
+// RL-02: the single authoritative ToolkitConfig merge. CLI, OpenCode, and Cursor
+// adapters all route their `config` writes through this so a preset switch
+// resets every derived policy field identically everywhere.
+export const mergeConfigValues = (input: ConfigInput, current: ToolkitConfig): ToolkitConfig => ({
+  locale: input.locale ?? current.locale,
+  localeOptions: input.localeOptions ?? current.localeOptions,
+  branchPolicy: mergePreset(input.preset ?? current.branchPolicy.preset, input, current),
+  commitPolicy: input.commitPolicy ?? current.commitPolicy,
+  // Set only by `workit upgrade --set-updates`; every other write keeps it.
+  ...(current.updates ? { updates: current.updates } : {}),
+});
+
+/** A rewrite keeps the file's `"$schema"` first (setup writes it; core/config-schemas.ts). */
+export const writeConfig = (config: ToolkitConfig): void => {
+  const dir = configDir();
+  const file = path.join(dir, "config.json");
+  let schema: unknown;
+  try {
+    schema = (JSON.parse(readSafe(file) ?? "{}") as { $schema?: unknown }).$schema;
+  } catch {
+    schema = undefined;
+  }
+  mkdirSync(dir, { recursive: true });
+  const document = schema === undefined ? config : { $schema: schema, ...config };
+  writeFileSync(file, JSON.stringify(document, null, 2) + "\n", "utf8");
+};
+
+// Configuration provenance for startup diagnostics: where config.json came from
+// and whether it parsed. Only paths + a malformed flag — never the file body.
+export const describeConfigSource = (
+  dir: string = resolveConfigDir(),
+): { source: string; config_dir: string; malformed: boolean } => {
+  const file = path.join(dir, "config.json");
+  if (!existsSync(file)) return { source: "defaults", config_dir: dir, malformed: false };
+  const raw = readSafe(file);
+  if (raw === null) return { source: "unreadable", config_dir: dir, malformed: true };
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isConfigObject(parsed)) {
+      return { source: "defaults", config_dir: dir, malformed: true };
+    }
+    return { source: "file", config_dir: dir, malformed: false };
+  } catch {
+    return { source: "defaults", config_dir: dir, malformed: true };
+  }
+};
+
+/** The global vcs.json path (WORKIT_VCS_CONFIG overrides it). */
+export const vcsConfigPath = (): string =>
+  process.env.WORKIT_VCS_CONFIG ?? path.join(configDir(), "vcs.json");
+
+/** An allowed-branch glob (`feature/*`) as a case-insensitive whole-name RegExp. */
+export const branchGlobPattern = (glob: string): RegExp =>
+  new RegExp(`^${glob.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`, "i");
+
+export const resolveBranchPolicy = (
+  config: ToolkitConfig,
+  workspace?: { branchPolicy?: Record<string, any> } | null,
+  /** The preset the repository's branches imply (core/branch-policy.ts repoBranchPreset). */
+  repoPreset?: () => BranchPreset | null,
+): {
+  preset: BranchPreset;
+  allowed: RegExp[];
+  protected: Set<string>;
+  integration: "pr" | "merge";
+  defaultTargetBranch: string;
+  /** No policy was configured; the repository's branches chose the preset. */
+  detected: boolean;
+} => {
+  const wp = workspace?.branchPolicy ?? {};
+  // An invalid workspace preset (e.g. a typo) falls back to the global preset,
+  // preserving resolution order workspace > global > preset, instead of
+  // crashing on PRESETS[preset] (mirrors parseConfigResult's Object.hasOwn).
+  const workspacePreset = Object.hasOwn(PRESETS, wp.preset);
+  // With no policy chosen anywhere, the repository's branches pick the preset
+  // (M10); the gitflow protected names stay protected regardless.
+  const detected =
+    !workspacePreset && unchosenBranchPolicy.has(config) ? (repoPreset?.() ?? null) : null;
+  const preset = (
+    workspacePreset ? wp.preset : (detected ?? config.branchPolicy?.preset ?? "gitflow")
+  ) as BranchPreset;
+  // RL-02: the preset is authoritative — allowed/protected re-derive from the
+  // workspace's own values or the preset table, never the global config's, and
+  // the current config remains the `custom` fallback when no values are given.
+  const merged = mergePreset(
+    preset,
+    {
+      allowed: wp.allowed,
+      protectedNames: wp.protected,
+    },
+    config,
+  );
+  const allowed = merged.allowed.map(branchGlobPattern);
+  return {
+    preset,
+    allowed,
+    protected: new Set(
+      [...merged.protected, ...(detected ? PRESETS.gitflow.protected : [])].map((p) =>
+        p.toLowerCase(),
+      ),
+    ),
+    integration: wp.integration === "merge" ? "merge" : "pr",
+    // CA-05: preset-aware default target when vcs.defaultTargetBranch is unset.
+    defaultTargetBranch:
+      preset === "github-flow" ? "main" : preset === "trunk-based" ? "master" : "develop",
+    detected: detected !== null,
+  };
+};
+
+export const COMMIT_PRESETS: readonly string[] = [
+  "conventional",
+  "gitmoji",
+  "ticket-prefix",
+  "freeform",
+  "custom",
+  "auto",
+];
+
+/** Workspace commitPolicy override wins, else global — mirrors
+ * resolveBranchPolicy's workspace > global order, including the invalid-preset
+ * fallback instead of a crash. */
+export const resolveCommitPolicy = (
+  config: ToolkitConfig,
+  workspace?: { commitPolicy?: Record<string, any> } | null,
+): { preset: CommitFlavorPreset; pattern?: string } => {
+  const wp = workspace?.commitPolicy ?? {};
+  if (COMMIT_PRESETS.includes(String(wp.preset ?? ""))) {
+    return {
+      preset: wp.preset as CommitFlavorPreset,
+      ...(typeof wp.pattern === "string" ? { pattern: wp.pattern } : {}),
+    };
+  }
+  return config.commitPolicy ?? { preset: "conventional" };
+};

package/src/core/context-read.ts

@@ -0,0 +1,144 @@
+// Read-only repository and provider context (`workit_context` on OpenCode,
+// Pi and MCP). A read needs no grant: it changes nothing locally or remotely.
+import * as z from "zod";
+import {
+  changelogContext,
+  docsRefreshContext,
+  isSafeContextRange,
+  prReadyContext,
+  releaseNotesContext,
+} from "./repo-context";
+import { gitContext } from "./git";
+import { fetchGitHubIssueBody, fetchGitLabIssueBody } from "./tracker-issues";
+import { context as youTrackContext, fetchYouTrackIssueBody } from "./youtrack";
+import { failure, success, type Result } from "./task-contract";
+
+export const contextReadSchema = z
+  .object({
+    kind: z.enum([
+      "git",
+      "pr",
+      "youtrack",
+      "github_issue",
+      "gitlab_issue",
+      "changelog",
+      "release",
+      "affected",
+    ]),
+    range: z.string().optional(),
+    issueId: z.string().optional(),
+    issueUrl: z.string().optional(),
+    issueRef: z.string().optional(),
+    mode: z.string().optional(),
+    specPath: z.string().optional(),
+    planPath: z.string().optional(),
+    cwd: z.string().min(1).optional(),
+  })
+  .strict();
+export type ContextReadPayload = z.infer<typeof contextReadSchema>;
+
+/** The tool input schema hosts register for `workit_context`. */
+export const contextReadJsonSchema = (): Record<string, unknown> => {
+  const { $schema: _schema, ...schema } = z.toJSONSchema(contextReadSchema, {
+    target: "draft-2020-12",
+  }) as Record<string, unknown>;
+  return schema;
+};
+
+export const parseContextRead = (value: unknown): Result<ContextReadPayload> => {
+  const parsed = contextReadSchema.safeParse(value);
+  return parsed.success
+    ? success(null, null, parsed.data)
+    : failure("invalid_input", "context payload is invalid", {
+        fields: parsed.error.issues.map((issue) => ({
+          path: issue.path.join("."),
+          reason: issue.message,
+        })),
+      });
+};
+
+/** Read one fixed repository/provider context without approval or mutation. */
+export const readExternalContext = async (
+  root: string,
+  payload: ContextReadPayload,
+): Promise<Result<unknown>> => {
+  if (payload.range !== undefined && !isSafeContextRange(payload.range))
+    return failure("invalid_input", "revision range is invalid", {
+      fields: [{ path: "range", reason: "option-like or control characters are not allowed" }],
+    });
+  const render = (result: { stdout: string; stderr: string; exitCode: number; cwd: string }) =>
+    result.exitCode === 0
+      ? success(null, null, { kind: payload.kind, context: result.stdout })
+      : failure("capability_unavailable", "requested context is unavailable", {
+          capability: payload.kind,
+        });
+  switch (payload.kind) {
+    case "git": {
+      const context = gitContext(root);
+      return typeof context.exitCode === "number" && context.exitCode !== 0
+        ? failure("capability_unavailable", "Git context is unavailable", { capability: "git" })
+        : success(null, null, { kind: payload.kind, context });
+    }
+    case "pr":
+      return render(prReadyContext(root, payload.range));
+    case "changelog":
+      return render(changelogContext(root, payload.range));
+    case "release":
+      return render(releaseNotesContext(root, payload.range ?? "HEAD~1...HEAD"));
+    case "affected":
+      return render(docsRefreshContext(root, payload.range));
+    case "youtrack": {
+      const value = youTrackContext({
+        workspace_root: root,
+        ...(payload.specPath ? { spec_path: payload.specPath } : {}),
+        ...(payload.planPath ? { plan_path: payload.planPath } : {}),
+        ...(payload.issueId ? { issue_id: payload.issueId } : {}),
+        ...(payload.issueUrl ? { issue_url: payload.issueUrl } : {}),
+        ...(payload.issueRef ? { issue_ref: payload.issueRef } : {}),
+        ...(payload.mode ? { mode: payload.mode } : {}),
+      });
+      if (value && typeof value === "object" && "error" in value)
+        return failure("capability_unavailable", "YouTrack context is unavailable", {
+          capability: "youtrack",
+        });
+      if (value.requiresMeetingChoice || !value.issueId)
+        return success(null, null, { kind: payload.kind, context: value });
+      const body = await fetchYouTrackIssueBody(value.issueId);
+      if ("error" in body && body.kind === "request")
+        return failure("capability_unavailable", "YouTrack issue body is unavailable", {
+          capability: "youtrack",
+        });
+      return success(null, null, {
+        kind: payload.kind,
+        context: {
+          ...value,
+          ...("data" in body
+            ? { issueBody: body.data }
+            : { issueBody: null, issueBodyError: body.error }),
+        },
+      });
+    }
+    case "github_issue": {
+      const ref = payload.issueId ?? payload.issueUrl ?? payload.issueRef;
+      if (!ref)
+        return failure("invalid_input", "github_issue needs issueId, issueUrl, or issueRef");
+      const body = await fetchGitHubIssueBody(ref, root);
+      if ("error" in body)
+        return failure("capability_unavailable", `GitHub issue is unavailable: ${body.error}`, {
+          capability: "github_issue",
+        });
+      return success(null, null, { kind: payload.kind, context: { issueBody: body.data } });
+    }
+    case "gitlab_issue": {
+      const ref = payload.issueId ?? payload.issueUrl ?? payload.issueRef;
+      if (!ref)
+        return failure("invalid_input", "gitlab_issue needs issueId, issueUrl, or issueRef");
+      const body = await fetchGitLabIssueBody(ref, root);
+      if ("error" in body)
+        return failure("capability_unavailable", `GitLab issue is unavailable: ${body.error}`, {
+          capability: "gitlab_issue",
+        });
+      return success(null, null, { kind: payload.kind, context: { issueBody: body.data } });
+    }
+  }
+};

package/src/core/docs-gate.ts

@@ -0,0 +1,69 @@
+// The docs check `workit pr create` runs when a workspace sets
+// `docs: when-user-facing`. It never blocks: the docs pass is the ship skill's
+// step, and this check records whether the PR shows it (a doc file in the
+// diff, or a "Docs" line in the body the skill asks for when nothing changed).
+import { changedSince, nonUserFacingType, type ForkPoint } from "./changelog-gate";
+import { appendObserved, type LedgerActor } from "../ledger";
+import type { DocsMode } from "./workspaces";
+
+export type DocsGate =
+  | { status: "off" }
+  | { status: "not-user-facing"; type: string }
+  | { status: "updated"; files: string[] }
+  | { status: "reported" }
+  | { status: "unconfirmed" }
+  | { status: "base-unknown"; base: string; remote: string };
+
+const DOC_FILE = /\.(?:md|mdx|rst|adoc)$/iu;
+const CHANGELOG_FILE = /(?:^|\/)(?:changelog|changes|history)(?:\.[a-z]+)?$/iu;
+const DOCS_LINE = /^\s*(?:#{1,6}\s*)?docs\b/imu;
+
+/** Whether the PR titled `title` shows its docs pass under `mode`. */
+export function docsGate(input: {
+  cwd: string;
+  mode: DocsMode;
+  title: string;
+  body: string | null;
+  forkPoint: () => ForkPoint;
+}): DocsGate {
+  if (input.mode === "off") return { status: "off" };
+  const type = nonUserFacingType(input.title);
+  if (type) return { status: "not-user-facing", type };
+  const point = input.forkPoint();
+  if (!point.fork) return { status: "base-unknown", base: point.base, remote: point.remote };
+  const files = changedSince(input.cwd, point.fork).filter(
+    (file) => DOC_FILE.test(file) && !CHANGELOG_FILE.test(file),
+  );
+  if (files.length) return { status: "updated", files };
+  return DOCS_LINE.test(input.body ?? "") ? { status: "reported" } : { status: "unconfirmed" };
+}
+
+/** One `pr create` check outcome as it is printed and recorded. */
+export type PrCheckOutcome = { check: "changelog" | "docs"; status: string; line: string };
+
+const LINE_LIMIT = 1000;
+
+/**
+ * Record each outcome as an observed `pr.check` row on `branch` at `head`,
+ * so the ledger shows whether the step ran, passed, was skipped or blocked.
+ */
+export function recordPrChecks(
+  cwd: string,
+  context: { actor: LedgerActor; branch: string | null; head: string | null; base: string },
+  outcomes: readonly PrCheckOutcome[],
+): string | null {
+  for (const outcome of outcomes) {
+    const row = appendObserved(cwd, {
+      type: "pr.check",
+      actor: context.actor,
+      branch: context.branch,
+      head: context.head,
+      base: context.base,
+      check: outcome.check,
+      status: outcome.status,
+      line: outcome.line.slice(0, LINE_LIMIT),
+    });
+    if (!row.ok) return row.error;
+  }
+  return null;
+}

package/src/core/finding-evidence.ts

@@ -0,0 +1,89 @@
+// Which evidence resolves a finding (#317), so a refused `finding resolve`
+// names what would work instead of only "unrelated" or "requires evidence".
+// It mirrors the engine's rules (task-engine.ts findingOnce) as a read-only
+// explanation; the engine stays the judge.
+//
+// fixed:     check or review evidence, result passed, recorded after the
+//            finding, still current on the tree (bound to a candidate when
+//            the finding names one).
+// dismissed: evidence of any kind with result passed or failed, on the
+//            finding's candidate (both none, or the same one), that shares a
+//            ref with the finding or makes the same claim.
+// deferred:  an approved limitation decision covering the finding's scope.
+import {
+  canonicalJson,
+  type Entry,
+  type Evidence,
+  type Finding,
+  type TaskRecord,
+} from "./task-contract";
+
+export type ResolveDisposition = "fixed" | "dismissed" | "deferred";
+
+const RULES: Record<ResolveDisposition, string> = {
+  fixed:
+    "check or review evidence with result passed, recorded after the finding and still current on this tree",
+  dismissed:
+    "evidence (check, review, investigation or artifact) with result passed or failed, on the finding's candidate, that shares a ref with the finding or repeats its claim",
+  deferred:
+    "an approved limitation decision (decisionIds) that references an acceptanceAllowed requirement and covers the finding's scope",
+};
+
+const sameRef = (left: unknown, right: unknown): boolean => {
+  try {
+    return canonicalJson(left) === canonicalJson(right);
+  } catch {
+    return false;
+  }
+};
+
+const sameCandidate = (finding: Finding, evidence: Evidence): boolean =>
+  finding.candidateId === null
+    ? (evidence.candidateId ?? null) === null
+    : evidence.candidateId === finding.candidateId ||
+      evidence.beforeCandidateId === finding.candidateId;
+
+/** Evidence ids in the task that meet the disposition's recorded-shape rule. */
+export function matchingEvidence(
+  task: Pick<TaskRecord, "evidence">,
+  finding: Entry<Finding>,
+  disposition: ResolveDisposition,
+): string[] {
+  if (disposition === "deferred") return [];
+  return task.evidence
+    .filter((entry) => {
+      const data = entry.data;
+      if (disposition === "fixed")
+        return (
+          entry.recordedAt >= finding.recordedAt &&
+          data.result === "passed" &&
+          (data.kind === "check" || data.kind === "review") &&
+          (finding.data.candidateId === null || data.candidateId != null)
+        );
+      return (
+        (data.result === "passed" || data.result === "failed") &&
+        sameCandidate(finding.data, data) &&
+        (finding.data.refs.some((left) => data.refs.some((right) => sameRef(left, right))) ||
+          data.claim === finding.data.claim)
+      );
+    })
+    .map((entry) => entry.id);
+}
+
+/**
+ * The sentence a refused resolve gains: the evidence the disposition
+ * accepts, the ids in this task that fit it, or how to record one.
+ */
+export function acceptedEvidenceText(
+  task: Pick<TaskRecord, "evidence">,
+  finding: Entry<Finding>,
+  disposition: ResolveDisposition,
+): string {
+  const accepted = `accepted for ${disposition}: ${RULES[disposition]}`;
+  if (disposition === "deferred") return accepted;
+  const ids = matchingEvidence(task, finding, disposition);
+  if (ids.length) return `${accepted}; evidence in this task that fits: ${ids.join(", ")}`;
+  const ref = finding.data.refs[0];
+  const refs = ref ? JSON.stringify([ref]) : "[]";
+  return `${accepted}; none recorded in this task yet: workit evidence record --payload '{"kind":"${disposition === "fixed" ? "check" : "review"}","claim":${JSON.stringify(finding.data.claim)},"result":"passed","refs":${refs},…}' (or workit check <name> for a check)`;
+}

package/src/core/finding-queue.ts

@@ -0,0 +1,36 @@
+// `workit finding record --queue [<issue>]` (#439): a finding reaches the
+// tracker as a new issue, or as a comment on an open one, so it is not left
+// in a ledger only the recording session reads.
+import type { Ref } from "./task-contract";
+
+const TITLE_MAX = 120;
+
+const refLine = (ref: Ref): string =>
+  ref.kind === "file"
+    ? `\`${ref.path}\``
+    : ref.kind === "external"
+      ? ref.url
+      : ref.kind === "record"
+        ? `${ref.collection}/${ref.id}`
+        : `${ref.host}:${ref.handle}`;
+
+/** The issue title and body (or comment body) for a finding. */
+export function findingIssueText(finding: {
+  claim: string;
+  consequence: string;
+  refs: readonly Ref[];
+}): { title: string; body: string } {
+  const claim = finding.claim.trim().replace(/\s+/gu, " ");
+  const title = claim.length > TITLE_MAX ? `${claim.slice(0, TITLE_MAX - 1)}…` : claim;
+  const body = [
+    finding.claim.trim(),
+    "",
+    `Consequence: ${finding.consequence.trim()}`,
+    ...(finding.refs.length
+      ? ["", "Refs:", ...finding.refs.map((ref) => `- ${refLine(ref)}`)]
+      : []),
+    "",
+    "Queued by `workit finding record --queue`.",
+  ].join("\n");
+  return { title, body };
+}