portable-agent-layer 0.86.3 → 0.87.0

package/assets/schema/pal-settings.schema.json

@@ -94,6 +94,10 @@
           "type": "boolean",
           "description": "Opt-in, off by default. Send a reply with an unbacked result or status claim back to the agent once, asking it to show the output or say the result is unverified. Needs claimCheck. Not on Cursor, whose stop payload carries no reply text."
         },
+        "adaptationRules": {
+          "type": "boolean",
+          "description": "Let the rules you approved from your past corrections steer the agent: a rule triggered by your prompt is injected before the agent answers, and a reply that matches a rule's trigger is sent back to the agent once at stop. Each firing is logged to memory/adaptation/rule-events.jsonl. Set false to switch every rule off. Reply-side rules do not run on Cursor, whose stop payload carries no reply text, or on opencode, whose plugin does not run the stop check."
+        },
         "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
       }
     },

package/assets/skills/rule-review/SKILL.md

@@ -38,6 +38,8 @@ Each draft prints as:
 <id>  [draft]  <situation>
   trigger (<prompt|reply>): <pattern>
   steering: <steering>
+  check: <how to tell the steering was followed>
+  proof: fired on <n>/<n> corrections, <n>/<n> ordinary turns
   evidence: <line>
 ```
 
@@ -83,10 +85,14 @@ Present each draft as one compact block, nothing else in between:
 Draft <id>
   When:     <situation>
   Steer:    <steering>
+  Check:    <check>
+  Proof:    fired on <n>/<n> corrections, <n>/<n> ordinary turns
   Evidence: <evidence line>
             <evidence line>
 ```
 
+The proof is the trigger replayed over the last 30 days of turns: how many of the user's confirmed corrections it would have caught, and how many ordinary turns it would have fired on needlessly. Omit the Check or Proof line when the listing has none.
+
 Follow the list with one question, e.g. "Approve or deny each? Reply with the id and your decision." After a single draft, "Approve or deny <id>?" is enough.
 
 After each decision, output the CLI's result line (or error reason) verbatim and nothing more unless the user asked a question.

package/assets/templates/pal-settings.json

@@ -32,6 +32,7 @@
     "reactionSampling": true,
     "claimCheck": true,
     "claimCheckBlocks": false,
+    "adaptationRules": true,
     "steeringTestReport": false
   },
   "steering": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.86.3",
+  "version": "0.87.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/rule.ts

@@ -12,6 +12,7 @@ import {
   decideRule,
   type RuleStatus,
   readRules,
+  type TriggerProof,
 } from "../hooks/lib/adaptation-rules";
 
 const DECISIONS: Record<string, Exclude<RuleStatus, "draft">> = {
@@ -47,10 +48,16 @@ function formatRule(rule: AdaptationRule): string {
     `${rule.id}  [${rule.status}]  ${rule.when}`,
     `  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`,
     `  steering: ${rule.steering}`,
+    ...(rule.check ? [`  check: ${rule.check}`] : []),
+    ...(rule.proof ? [`  proof: ${formatProof(rule.proof)}`] : []),
     ...rule.evidence.map((e) => `  evidence: ${e}`),
   ].join("\n");
 }
 
+function formatProof(proof: TriggerProof): string {
+  return `fired on ${proof.firedCorrections}/${proof.corrections} corrections, ${proof.firedOrdinary}/${proof.ordinary} ordinary turns`;
+}
+
 function cmdDecide(
   id: string | undefined,
   decision: Exclude<RuleStatus, "draft">

package/src/hooks/StopOrchestrator.ts

@@ -6,6 +6,7 @@
  */
 
 import { checkReadmeSync } from "./handlers/readme-sync";
+import { watchReplyRules } from "./lib/adaptation-steering";
 import { stopBlockResponse } from "./lib/agent";
 import { watchClaims } from "./lib/claim-log";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
@@ -42,4 +43,13 @@ try {
 } catch (err) {
   logError("StopOrchestrator:claim-check", err);
 }
+try {
+  const sendBack = watchReplyRules(payload);
+  if (sendBack) {
+    process.stdout.write(stopBlockResponse(sendBack));
+    process.exit(0);
+  }
+} catch (err) {
+  logError("StopOrchestrator:adaptation-rules", err);
+}
 await stopTurn(payload);

package/src/hooks/UserPromptOrchestrator.ts

@@ -29,12 +29,13 @@ const input = await readStdinJSON<PromptSubmitInput>();
 logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)}`);
 if (!input?.prompt) process.exit(0);
 
+const sentAt = new Date();
 const sessionId = hookSessionId(input);
 const injected = await injectPromptContext(input.prompt, sessionId);
 logPromptSnapshot(input.prompt, injected);
 
 const results = await Promise.allSettled([
-  captureRating(input.prompt, sessionId),
+  captureRating(input.prompt, sessionId, sentAt),
   captureSessionName(input.prompt, sessionId ?? ""),
 ]);
 

package/src/hooks/handlers/inject-retrieval.ts

@@ -7,6 +7,7 @@
  * produces empty output, never blocks the prompt.
  */
 
+import { promptRulesReminder } from "../lib/adaptation-steering";
 import { promptContextResponse } from "../lib/agent";
 import { dueNudgeReminder } from "../lib/daily-nudge";
 import { observeTurn } from "../lib/interaction";
@@ -82,6 +83,7 @@ export async function getPromptContext(
 ): Promise<string | null> {
   const parts = [
     getWallClockReminder(),
+    withinBudget(() => promptRulesReminder(prompt, sessionId), BUDGET_MS),
     withinBudget(() => getRepoStateReminder(), BUDGET_MS),
     withinBudget(() => observeTurn(prompt, sessionId), BUDGET_MS),
     withinBudget(() => dueNudgeReminder(), BUDGET_MS),

package/src/hooks/handlers/rating.ts

@@ -10,10 +10,17 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { appendTurn } from "../lib/adaptation-turns";
+import {
+  readCandidates,
+  recordCandidate,
+  reproveWaiting,
+} from "../lib/adaptation-candidates";
+import { readRules } from "../lib/adaptation-rules";
+import { appendTurn, readTurns, withRequests } from "../lib/adaptation-turns";
 import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { replyEnd } from "../lib/interaction-samples";
+import { logDebug } from "../lib/log";
 import { paths } from "../lib/paths";
 import { isSystemText, stripInjectedTags } from "../lib/prompt-text";
 import {
@@ -24,6 +31,12 @@ import {
   reactionRequest,
   turnFromLabels,
 } from "../lib/reaction-rating";
+import {
+  canRepeat,
+  correctionsToDraftFrom,
+  drafterRequest,
+  parseDraft,
+} from "../lib/rule-drafter";
 import { emitRating } from "../lib/signals";
 import { now } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
@@ -173,7 +186,7 @@ function handleRating(
 
 // ── Implicit Rating ──
 
-function handleImplicitReaction(message: string, sessionId?: string): void {
+function handleImplicitReaction(message: string, sentAt: Date, sessionId?: string): void {
   const trimmed = message.trim();
   const reply = replyEnd(getLastResponse(sessionId));
 
@@ -199,6 +212,7 @@ function handleImplicitReaction(message: string, sessionId?: string): void {
       sessionId ?? "",
       Buffer.from(trimmed).toString("base64"),
       Buffer.from(reply).toString("base64"),
+      sentAt.toISOString(),
     ],
     "rating"
   );
@@ -210,11 +224,32 @@ async function labelReaction(reply: string, message: string, sessionId?: string)
   return result.success ? parseReactionLabel(result.output) : null;
 }
 
+function knownRules() {
+  const waiting = readCandidates().filter((candidate) => candidate.verdict === "waiting");
+  return [
+    ...readRules(),
+    ...waiting.map((candidate) => ({ ...candidate, status: "candidate" })),
+  ];
+}
+
+async function draftRuleCandidate(sessionId?: string): Promise<void> {
+  const turns = withRequests(readTurns());
+  reproveWaiting(turns);
+  const corrections = correctionsToDraftFrom(turns);
+  if (!canRepeat(corrections)) return;
+  const result = await inference(drafterRequest(corrections, knownRules(), sessionId));
+  if (result.usage) logTokenUsage("rule-drafter", result.usage);
+  const candidate = result.success ? parseDraft(result.output, corrections) : null;
+  if (candidate) recordCandidate(candidate, turns);
+  else logDebug("rule-drafter", `no candidate: ${result.output ?? result.error ?? ""}`);
+}
+
 /** Background mode: label the reaction, confirm a correction, store the rating. */
 async function runReactionRatingAndStore(
   message: string,
   reply: string,
-  sessionId?: string
+  sessionId: string | undefined,
+  sentAt: Date
 ): Promise<void> {
   try {
     const first = await labelReaction(reply, message, sessionId);
@@ -230,7 +265,8 @@ async function runReactionRatingAndStore(
       first,
       confirmation
     );
-    if (turn) appendTurn(turn);
+    if (turn) appendTurn(turn, sentAt);
+    if (turn?.confirmed) await draftRuleCandidate(sessionId);
   } catch (err) {
     const { logError } = await import("../lib/log");
     logError("rating:reaction-child", err);
@@ -239,7 +275,11 @@ async function runReactionRatingAndStore(
 
 // ── Main Export ──
 
-export function captureRating(message: string, sessionId?: string): void {
+export function captureRating(
+  message: string,
+  sessionId?: string,
+  sentAt: Date = new Date()
+): void {
   // Strip IDE/system-injected tags to recover raw user text
   const cleaned = stripInjectedTags(message);
 
@@ -258,7 +298,7 @@ export function captureRating(message: string, sessionId?: string): void {
 
   // Path 2: Implicit reaction — the praise fast-path runs synchronously, the
   // model path detaches to a background bun subprocess (mirrors session-name).
-  handleImplicitReaction(cleaned, sessionId);
+  handleImplicitReaction(cleaned, sentAt, sessionId);
 }
 
 // Background reaction entry point
@@ -268,10 +308,12 @@ if (process.argv[2] === "--sentiment") {
   const replyB64 = process.argv[5];
   if (msgB64 && replyB64) {
     const decode = (b64: string) => Buffer.from(b64, "base64").toString("utf-8");
+    const sentAt = new Date(process.argv[6] ?? "");
     await runReactionRatingAndStore(
       decode(msgB64),
       decode(replyB64),
-      sid === "" ? undefined : sid
+      sid === "" ? undefined : sid,
+      Number.isNaN(sentAt.getTime()) ? new Date() : sentAt
     );
   }
   process.exit(0);

package/src/hooks/lib/adaptation-candidates.ts

@@ -0,0 +1,89 @@
+/**
+ * Rule candidates: drafts the small model wrote from repeated corrections, each
+ * with the proof of its trigger. Only a proven candidate becomes a draft in the
+ * rule store for the user to review; one the log is still too short to judge
+ * waits and is proven again as the log grows.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { addDraft, type DraftInput, type TriggerProof } from "./adaptation-rules";
+import type { RequestedTurn } from "./adaptation-turns";
+import { paths } from "./paths";
+import { type ProofVerdict, proofVerdict, proveTrigger } from "./rule-proof";
+
+export interface CandidateInput extends DraftInput {
+  check: string;
+}
+
+export interface Candidate extends CandidateInput {
+  id: string;
+  createdAt: string;
+  verdict: ProofVerdict;
+  proof: TriggerProof;
+}
+
+function candidatesPath(): string {
+  return resolve(paths.adaptation(), "candidates.jsonl");
+}
+
+function parseLine(line: string): Candidate | null {
+  try {
+    const parsed = JSON.parse(line) as Candidate;
+    return typeof parsed.createdAt === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readCandidates(): Candidate[] {
+  const path = candidatesPath();
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf-8")
+    .split("\n")
+    .map(parseLine)
+    .filter((candidate): candidate is Candidate => candidate !== null);
+}
+
+function writeCandidates(candidates: Candidate[]): void {
+  const path = candidatesPath();
+  const pending = `${path}.${process.pid}.tmp`;
+  writeFileSync(pending, candidates.map((c) => `${JSON.stringify(c)}\n`).join(""));
+  renameSync(pending, path);
+}
+
+function prove(candidate: Candidate, turns: RequestedTurn[]): Candidate {
+  const proof = proveTrigger(candidate.trigger, turns);
+  return { ...candidate, proof, verdict: proofVerdict(proof) };
+}
+
+function promoteIfPassed(candidate: Candidate): void {
+  if (candidate.verdict !== "passed") return;
+  const { id: _id, createdAt: _createdAt, verdict: _verdict, ...draft } = candidate;
+  addDraft(draft);
+}
+
+export function recordCandidate(
+  input: CandidateInput,
+  turns: RequestedTurn[],
+  now: Date = new Date()
+): Candidate {
+  const fresh = {
+    ...input,
+    id: randomUUID().slice(0, 8),
+    createdAt: now.toISOString(),
+  } as Candidate;
+  const candidate = prove(fresh, turns);
+  writeCandidates([...readCandidates(), candidate]);
+  promoteIfPassed(candidate);
+  return candidate;
+}
+
+export function reproveWaiting(turns: RequestedTurn[]): void {
+  const candidates = readCandidates();
+  if (!candidates.some((c) => c.verdict === "waiting")) return;
+  const updated = candidates.map((c) => (c.verdict === "waiting" ? prove(c, turns) : c));
+  writeCandidates(updated);
+  updated.filter((c, i) => candidates[i].verdict === "waiting").forEach(promoteIfPassed);
+}

package/src/hooks/lib/adaptation-rules.ts

@@ -12,17 +12,28 @@ import { paths } from "./paths";
 export type RuleStatus = "draft" | "approved" | "denied";
 type Decision = Exclude<RuleStatus, "draft">;
 
-interface RuleTrigger {
+export interface RuleTrigger {
   /** Whether the pattern is matched against the user's prompt or the assistant's reply. */
   side: "prompt" | "reply";
   pattern: string;
 }
 
+/** Where the trigger fired when replayed over the turn log. */
+export interface TriggerProof {
+  firedCorrections: number;
+  corrections: number;
+  firedOrdinary: number;
+  ordinary: number;
+}
+
 export interface DraftInput {
   when: string;
   trigger: RuleTrigger;
   steering: string;
   evidence: string[];
+  /** How to tell from a reply whether the steering was followed. */
+  check?: string;
+  proof?: TriggerProof;
 }
 
 export interface AdaptationRule extends DraftInput {

package/src/hooks/lib/adaptation-steering.ts

@@ -0,0 +1,87 @@
+/**
+ * Approved adaptation rules at work: a prompt-side rule is injected when its
+ * trigger matches the user's prompt; a reply-side rule sends a matching reply
+ * back once at stop. Every fire is logged so a rule's effect can be measured.
+ */
+
+import { appendFileSync } from "node:fs";
+import { type AdaptationRule, type RuleTrigger, readRules } from "./adaptation-rules";
+import { alreadySentBack } from "./claim-log";
+import { hookFinalReply, hookSessionId } from "./hook-turn";
+import { replyEnd } from "./interaction-samples";
+import { ruleEventsPath } from "./rule-effect";
+import { isEnabled } from "./settings";
+import type { StopTurnPayload } from "./stop";
+
+const REMINDER_MAX = 1500;
+const REMINDER_HEADER =
+  "Rules the user approved from past corrections — follow them on this turn:";
+
+type Side = RuleTrigger["side"];
+
+function triggers(rule: AdaptationRule, side: Side, text: string): boolean {
+  if (rule.status !== "approved" || rule.trigger.side !== side) return false;
+  try {
+    return new RegExp(rule.trigger.pattern, "i").test(text);
+  } catch {
+    return false;
+  }
+}
+
+function firingRules(side: Side, text: string): AdaptationRule[] {
+  if (!isEnabled("adaptationRules") || !text) return [];
+  return readRules().filter((rule) => triggers(rule, side, text));
+}
+
+function logFire(
+  rules: AdaptationRule[],
+  side: Side,
+  session: string,
+  now: Date,
+  sentBack?: boolean
+): void {
+  const lines = rules.map((rule) =>
+    JSON.stringify({ ts: now.toISOString(), rule: rule.id, side, session, sentBack })
+  );
+  appendFileSync(ruleEventsPath(), `${lines.join("\n")}\n`);
+}
+
+function withinBudget(rules: AdaptationRule[]): AdaptationRule[] {
+  let size = REMINDER_HEADER.length + "<system-reminder>\n\n</system-reminder>".length;
+  return rules.filter((rule) => {
+    size += rule.steering.length + 3;
+    return size <= REMINDER_MAX;
+  });
+}
+
+export function promptRulesReminder(
+  prompt: string,
+  sessionId?: string,
+  now: Date = new Date()
+): string | null {
+  const fired = withinBudget(firingRules("prompt", prompt));
+  if (fired.length === 0) return null;
+  logFire(fired, "prompt", sessionId ?? "unknown", now);
+  return [
+    "<system-reminder>",
+    REMINDER_HEADER,
+    ...fired.map((rule) => `- ${rule.steering}`),
+    "</system-reminder>",
+  ].join("\n");
+}
+
+function sendBackReason(rules: AdaptationRule[]): string {
+  const steering = rules.map((rule) => rule.steering).join(" ");
+  return `Your reply matches a rule the user approved from past corrections. ${steering}`;
+}
+
+export function watchReplyRules(
+  payload: StopTurnPayload | null,
+  now: Date = new Date()
+): string | null {
+  const fired = firingRules("reply", replyEnd(hookFinalReply(payload) ?? ""));
+  if (!payload || fired.length === 0) return null;
+  const sentBack = !alreadySentBack(payload);
+  logFire(fired, "reply", hookSessionId(payload) ?? "unknown", now, sentBack);
+  return sentBack ? sendBackReason(fired) : null;
+}

package/src/hooks/lib/adaptation-turns.ts

@@ -30,6 +30,26 @@ export interface Turn extends TurnInput {
   ts: string;
 }
 
+export interface RequestedTurn extends Turn {
+  /** The user's request the reply answered, when that message was logged too. */
+  prompt: string;
+}
+
+function precedingRequest(turns: Turn[], index: number): string {
+  const session = turns[index].session;
+  for (let i = index - 1; i >= 0; i--) {
+    if (turns[i].session === session) return turns[i].message;
+  }
+  return "";
+}
+
+export function withRequests(turns: Turn[]): RequestedTurn[] {
+  return turns.map((turn, index) => ({
+    ...turn,
+    prompt: precedingRequest(turns, index),
+  }));
+}
+
 function monthFile(date: Date): string {
   return `turns-${date.toISOString().slice(0, 7)}.jsonl`;
 }

package/src/hooks/lib/claim-log.ts

@@ -72,7 +72,7 @@ function record({ check, commands, session, blocked }: Watched, now: Date) {
   appendFileSync(monthFile(now), `${JSON.stringify(line)}\n`);
 }
 
-function alreadySentBack(payload: StopTurnPayload): boolean {
+export function alreadySentBack(payload: StopTurnPayload): boolean {
   return payload.stop_hook_active === true || (payload.loop_count ?? 0) > 0;
 }
 

package/src/hooks/lib/rule-drafter.ts

@@ -0,0 +1,168 @@
+/**
+ * The rule drafter: after a confirmed correction, the small model decides
+ * whether it repeats an earlier one and, if so, drafts a rule that would have
+ * prevented them all.
+ */
+
+import type { CandidateInput } from "./adaptation-candidates";
+import { type RequestedTurn, type Turn, withRequests } from "./adaptation-turns";
+
+const MIN_CITED = 2;
+const EVIDENCE_MESSAGE_MAX = 200;
+
+type Correction = RequestedTurn;
+
+export interface KnownRule {
+  when: string;
+  steering: string;
+  status: string;
+}
+
+const DRAFTER_SYSTEM_PROMPT = `You turn an AI assistant's repeated mistakes into one rule that prevents them.
+
+You get the corrections the user made recently, numbered and oldest first. Each has the end of the assistant's reply the user corrected, the user's correcting message, what the reply got wrong, and, when known, the user's request the reply answered. The newest one just happened.
+
+Decide whether the newest correction is the same kind of mistake as at least one earlier correction. Same kind means one instruction would have prevented both, not that they share a topic.
+
+If it is not, or a known rule already covers it, set recurring to false, say why in reason in one sentence, leave the text fields empty and set cites to [].
+
+If it is, draft one rule:
+- when: the situation, in one sentence.
+- side and pattern: a case-insensitive JavaScript regular expression for that situation. Side "reply" matches the end of the assistant's reply; side "prompt" matches the user's request. It must match the cited corrections, stay general enough to catch the next one, and not match ordinary turns.
+- steering: the instruction to the assistant, imperative, at most two sentences.
+- check: how to tell from a reply whether the instruction was followed, in one sentence.
+- cites: the numbers of the corrections this rule would have prevented, including the newest.
+- reason: why these corrections are the same mistake, in one sentence.`;
+
+const DRAFTER_SCHEMA = {
+  type: "object",
+  properties: {
+    recurring: { type: "boolean" },
+    reason: { type: "string" },
+    when: { type: "string" },
+    side: { enum: ["prompt", "reply"] },
+    pattern: { type: "string" },
+    steering: { type: "string" },
+    check: { type: "string" },
+    cites: { type: "array", items: { type: "integer" } },
+  },
+  required: [
+    "recurring",
+    "reason",
+    "when",
+    "side",
+    "pattern",
+    "steering",
+    "check",
+    "cites",
+  ],
+  additionalProperties: false,
+} as const;
+
+export function correctionsToDraftFrom(turns: Turn[]): Correction[] {
+  return withRequests(turns).filter((turn) => turn.confirmed === true);
+}
+
+export function canRepeat(corrections: Correction[]): boolean {
+  return corrections.length >= MIN_CITED;
+}
+
+function correctionBlock(correction: Correction, n: number, newest: boolean): string {
+  const request = correction.prompt ? `<request>${correction.prompt}</request>\n` : "";
+  return `<correction n="${n}"${newest ? ' newest="true"' : ""}>\n${request}<reply_end>${correction.replyEnd}</reply_end>\n<user_message>${correction.message}</user_message>\n<what_was_wrong>${correction.issue}</what_was_wrong>\n</correction>`;
+}
+
+function knownRulesBlock(known: KnownRule[]): string {
+  const lines = known.map((rule) => `- ${rule.status}: ${rule.when}. ${rule.steering}`);
+  return `Known rules:\n${lines.length ? lines.join("\n") : "none"}`;
+}
+
+export function drafterRequest(
+  corrections: Correction[],
+  known: KnownRule[],
+  sessionId?: string
+) {
+  const last = corrections.length - 1;
+  const blocks = corrections.map((c, n) => correctionBlock(c, n, n === last));
+  return {
+    system: DRAFTER_SYSTEM_PROMPT,
+    user: `${blocks.join("\n\n")}\n\n${knownRulesBlock(known)}`,
+    tier: "small" as const,
+    maxTokens: 600,
+    timeout: 90_000,
+    jsonSchema: DRAFTER_SCHEMA,
+    caller: "rule-drafter",
+    sessionId,
+  };
+}
+
+interface DraftOutput {
+  recurring: boolean;
+  when: string;
+  side: "prompt" | "reply";
+  pattern: string;
+  steering: string;
+  check: string;
+  cites: number[];
+}
+
+const REGEX_LITERAL = /^\/(.+)\/[a-z]*$/s;
+
+function bareExpression(pattern: string): string {
+  return REGEX_LITERAL.exec(pattern)?.[1] ?? pattern;
+}
+
+function isValidPattern(pattern: string): boolean {
+  try {
+    new RegExp(pattern, "i");
+    return pattern.trim() !== "";
+  } catch {
+    return false;
+  }
+}
+
+function validCites(cites: unknown, count: number): number[] | null {
+  if (!Array.isArray(cites)) return null;
+  const distinct = [...new Set(cites)];
+  const inRange = distinct.every((n) => Number.isInteger(n) && n >= 0 && n < count);
+  const citesNewest = distinct.includes(count - 1);
+  return inRange && citesNewest && distinct.length >= MIN_CITED
+    ? (distinct as number[]).sort((a, b) => a - b)
+    : null;
+}
+
+function parseOutput(output: string): DraftOutput | null {
+  try {
+    return JSON.parse(output) as DraftOutput;
+  } catch {
+    return null;
+  }
+}
+
+function hasText(...fields: unknown[]): boolean {
+  return fields.every((field) => typeof field === "string" && field.trim() !== "");
+}
+
+export function parseDraft(
+  output: string | null | undefined,
+  corrections: Correction[]
+): CandidateInput | null {
+  const draft = output ? parseOutput(output) : null;
+  if (draft?.recurring !== true) return null;
+  const cites = validCites(draft.cites, corrections.length);
+  const sideOk = draft.side === "prompt" || draft.side === "reply";
+  if (!cites || !sideOk || !hasText(draft.pattern)) return null;
+  const pattern = bareExpression(draft.pattern);
+  if (!isValidPattern(pattern)) return null;
+  if (!hasText(draft.when, draft.steering, draft.check)) return null;
+  return {
+    when: draft.when.trim(),
+    trigger: { side: draft.side, pattern },
+    steering: draft.steering.trim(),
+    check: draft.check.trim(),
+    evidence: cites.map((n) => {
+      const cited = corrections[n];
+      return `${cited.issue}: ${cited.message.slice(0, EVIDENCE_MESSAGE_MAX)}`;
+    }),
+  };
+}