portable-agent-layer 0.108.0 → 0.110.0

package/README.md

@@ -90,14 +90,15 @@ pal cli status        # check your setup
 | `pal cli patterns` | How you work across projects, read from the event log |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
-| `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium`, `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |
+| `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium\|large\|flagship` (on Claude: Haiku, Sonnet, Opus, Fable; on Codex: Luna, Sol, Sol at high effort, Astra; on Antigravity: Flash at low, medium and high effort, and no flagship; an agent without the tier asked refuses it), `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |
 | `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
 | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
 | `pal cli telos` | Which TELOS topics are answered, in interview order, and which one comes next |
 | `pal cli timezone [<zone>]` | Show or set your timezone. IANA names only, validated before it is stored |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
-| `pal cli rule` | Review the rules drafted from your corrections — `list [--all] [--json]`, `approve <id>`, `deny <id>`. A draft steers nothing until approved; a denied one is never drafted again |
+| `pal cli rule` | Review the rules drafted from your corrections — `list [--all] [--json]`, `approve <id>`, `opinion <id>`, `deny <id>`, `retire <id>`, `add-opinion --kind --when --steering`. A draft steers nothing until approved; a denied one is never drafted again. An opinion has no trigger and steers every session, at most 8 of them and one per correction kind; `list --all` shows each one's correction-kind rate before and after approval |
+| `pal cli correction` | The kinds of mistakes you corrected — `kinds [--days N] [--split DATE] [--json]` shows each kind per 100 turns, before and after a date with `--split`; `backfill` labels confirmed corrections without a kind or with one from an older prompt, and `--relabel` labels every one again |
 | `pal cli server` | The morning screen: a local page to open before a terminal — three moves for today, an urgent/important grid over every project *and* every stated goal, where you left off, and a drawer holding the signal and the action ledger — `start [--port <n>]`, `stop`, `status`. Loopback only, default port 7250. No model runs on page load |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |

package/assets/skills/scientific-research/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: scientific-research
 license: MIT
-description: "Answers scientific questions from trustworthy primary sources only (PubMed-indexed peer-reviewed literature, clinical guidelines from ERC, ESC, AHA, CDC and specialty societies, NEJM, The Lancet, JAMA, BMJ, UpToDate when accessible), with every claim cited to a source that was actually read, graded by evidence level and year, and cross-checked by a verifier agent. Use for EVERY health, medical, nutrition, drug, supplement, symptom, disease, treatment, diagnosis, exercise-physiology or other empirical scientific question, including 'is it safe to', 'does X work', 'what does the evidence say', 'side effects of', 'how much should I take' and 'what do the guidelines recommend'. Never answer such questions from memory; route them here."
+description: "Answers scientific questions from trustworthy primary sources only (PubMed-indexed peer-reviewed literature, clinical guidelines from ERC, ESC, AHA, CDC and specialty societies, NEJM, The Lancet, JAMA, BMJ, UpToDate when accessible), with every claim cited to a source that was actually read, graded by evidence level and year, its funding and any vendor ties named, and cross-checked by a verifier agent. Excludes preprints and MDPI journals and prefers SJR Q1 journals. Use for EVERY health, medical, nutrition, drug, supplement, symptom, disease, treatment, diagnosis, exercise-physiology or other empirical scientific question, including 'is it safe to', 'does X work', 'what does the evidence say', 'side effects of', 'how much should I take' and 'what do the guidelines recommend'. Never answer such questions from memory; route them here."
 argument-hint: <scientific or health question>
 metadata:
   source: portable-agent-layer
@@ -57,9 +57,26 @@ specialty society (WHO, NICE, EMA, FDA and their peers). Label each such
 source in the answer as "outside the core list".
 
 Not sources, under any circumstances: blogs, news sites, forums, supplement or
-vendor sites, encyclopedias, press releases, lecture slides, model memory. Preprints
-may be mentioned only when the answer labels them "preprint, not peer-reviewed" and
-no peer-reviewed source covers the claim.
+vendor sites, encyclopedias, press releases, lecture slides, model memory.
+
+Excluded even when they look peer-reviewed:
+
+- **Preprints and repositories**: bioRxiv, medRxiv, PsyArXiv, arXiv, SSRN, Research
+  Square, OSF Preprints, Preprints.org and any other server of unreviewed
+  manuscripts. Do not search them. PubMed and Europe PMC also index preprints, so
+  add `NOT preprint[pt]` to PubMed queries and drop any record whose publication type
+  is Preprint.
+- **MDPI journals** (Nutrients, Medicina, IJMS, Healthcare and the rest), identified
+  by publisher, not by title: a DOI starting with `10.3390` or a page on `mdpi.com`.
+  Add `-site:mdpi.com` to web searches.
+
+### Journal rank
+
+Prefer journals ranked Q1 by SCImago (SJR, `scimagojr.com`) in the subject category
+that fits the question. Rank breaks ties within one evidence level and never
+outranks study design: a Q2 RCT beats a Q1 observational study. Cite a journal below
+Q1 only when no Q1 source covers the claim, and label it with its quartile, for
+example "SJR Q2". Guidelines and official bodies are not ranked.
 
 ## Citation and evidence rules
 
@@ -74,12 +91,23 @@ For every claim record and later print:
   review.
 - **Year** of publication or of the guideline edition, so stale evidence is visible.
   When a newer edition of a guideline exists, cite the newer one.
+- **Journal quartile**: the SJR quartile of the journal, for every journal article.
+- **Funding and conflicts of interest**, read from the source's Funding, Acknowledgements
+  and Competing Interests sections, never inferred. Name the funders, then add one label:
+  - **vendor-funded**: a funder sells the product or intervention studied, or is a
+    trade group of its sellers (manufacturer, supplement brand, food or drug industry
+    association).
+  - **vendor-linked authors**: the funding is independent, but an author is employed,
+    paid or holds shares in such a company.
+  - **funding not stated**: the opened source has no funding statement.
+  - **funding not accessible**: the statement sits behind a paywall that did not open.
 
 Apply these tests before keeping a claim:
 
 1. Does the opened source state this claim, in this population, at this dose or in
    this setting? Paraphrase the source, do not extrapolate from it.
-2. Does the source belong to the allowed set? If not, discard the claim.
+2. Does the source belong to the allowed set, and is it neither a preprint nor an MDPI
+   journal? If not, discard the claim.
 3. Is the number or direction of effect quoted exactly as the source gives it
    (effect size, confidence interval, absolute versus relative risk)?
 
@@ -144,12 +172,20 @@ Rules:
 - Search only your lane's domains (use site: restricted queries). Open each
   candidate and read the relevant section before using it.
 - Prefer the newest guideline edition, then systematic reviews and meta-analyses,
-  then RCTs, then observational work.
+  then RCTs, then observational work. Within one level, prefer journals ranked SJR
+  Q1 in the question's subject category.
+- Never search or cite preprint servers (bioRxiv, medRxiv, PsyArXiv, arXiv, SSRN,
+  Research Square, OSF Preprints, Preprints.org). Add NOT preprint[pt] to PubMed
+  queries and drop any record typed Preprint.
+- Never cite an MDPI journal: a DOI starting with 10.3390 or a page on mdpi.com. Add
+  -site:mdpi.com to web searches.
 - For each claim return: the claim in one sentence, quoted as the source states it;
   population and setting; effect size with confidence interval when given; evidence
   level (guideline recommendation with class/level or GRADE, meta-analysis, RCT,
   observational, expert opinion); year; full citation (authors or body, title,
-  journal or body, year, PMID or DOI or URL).
+  journal or body, year, PMID or DOI or URL); the journal's SJR quartile; funding:
+  the funders named in the source and one label, vendor-funded, vendor-linked
+  authors, funding not stated or funding not accessible.
 - Lane D only: if UpToDate does not open or shows a paywall, return the single line
   "UpToDate inaccessible" and nothing else.
 - Do not fill gaps from memory. If your lane has nothing on a sub-question, say
@@ -180,8 +216,15 @@ For every claim:
    numbers. Mark "confirmed" or "could not verify: <what differs>".
 3. Confirm the source is in the allowed set: PubMed-indexed peer-reviewed journal,
    ERC/ESC/AHA/CDC or another official health body or specialty society, NEJM, The
-   Lancet, JAMA, BMJ, or UpToDate. Otherwise mark "could not verify: source not
-   allowed".
+   Lancet, JAMA, BMJ, or UpToDate. A preprint, a record typed Preprint in PubMed, or
+   an MDPI journal (DOI starting with 10.3390) is never allowed. Otherwise mark
+   "could not verify: source not allowed".
+4. Check the journal's SJR quartile on scimagojr.com and correct it when the lane
+   got it wrong.
+5. Open the source's Funding and Competing Interests sections and confirm the
+   funders and the label (vendor-funded, vendor-linked authors, funding not stated,
+   funding not accessible). Correct the label when it differs, and flag every
+   vendor-funded or vendor-linked study.
 
 Then return three sections:
 - Confirmed matches: claims supported by two or more independent sources, with
@@ -203,8 +246,10 @@ Then:
 1. **Bottom line** — two to four sentences answering the question directly, with
    citation numbers.
 2. **Key findings** — one bullet per claim: the claim, inline citation number(s)
-   `[n]`, evidence level, year. Group by sub-question when there are several. Mark
-   any source outside the core list.
+   `[n]`, evidence level, year, funding label. Write **vendor-funded** or
+   **vendor-linked authors** in bold and name the company. Group by sub-question
+   when there are several. Mark any source outside the core list and any journal
+   below SJR Q1 with its quartile.
 3. **Agreement and contradictions** — the verifier's confirmed matches and
    contradictions, each contradiction with who says what and the likely reason.
 4. **What is uncertain / not found** — sub-questions with no trustworthy evidence
@@ -214,7 +259,8 @@ Then:
 5. **Method** — one line: parallel subagents or sequential lanes; UpToDate read or
    inaccessible; number of sources opened.
 6. **References** — numbered list matching the inline numbers: authors or body,
-   title, journal or body, year, PMID or DOI or URL.
+   title, journal or body, year, PMID or DOI or URL, SJR quartile, and funding (the
+   funders and the label).
 
 For a question about the user's own health, add exactly one plain sentence after the
 Bottom line: this is a summary of published evidence, not individual medical advice,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.108.0",
+  "version": "0.110.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -70,7 +70,11 @@
     "eval:waiting-on": "bun eval/run.ts waiting-on",
     "eval:reaction": "bun eval/run.ts reaction",
     "eval:correction-check": "bun eval/run.ts correction-check",
-    "eval:entity-extraction": "bun eval/entity-extraction/build-prompt.ts && bun eval/run.ts entity-extraction"
+    "eval:entity-extraction": "bun eval/entity-extraction/build-prompt.ts && bun eval/run.ts entity-extraction",
+    "eval:correction-kind": "bun eval/correction-kind/build-prompt.ts && bun eval/run.ts correction-kind",
+    "eval:correction-kind:test": "bun eval/correction-kind/test-set.ts",
+    "eval:rule-drafter": "bun eval/rule-drafter/build-prompt.ts && bun eval/run.ts rule-drafter",
+    "eval:rule-drafter:test": "bun eval/rule-drafter/test-set.ts"
   },
   "lint-staged": {
     "*.ts": [

package/src/cli/correction.ts

@@ -0,0 +1,115 @@
+/**
+ * pal cli correction — the kinds of mistakes the user corrected, and how often.
+ *
+ * Subcommands:
+ *   kinds [--days N] [--split DATE] [--json]   Corrections per 100 turns, by kind
+ *   backfill [--relabel]                        Label the confirmed corrections without a current kind
+ */
+
+import { readTurns } from "../hooks/lib/adaptation-turns";
+import {
+  backfillCorrectionKinds,
+  type KindLabeller,
+  labelWithInference,
+} from "../hooks/lib/correction-backfill";
+import { type KindRates, kindRates, splitRates } from "../hooks/lib/correction-rates";
+import { group, leaf, runCommand, UsageError } from "../tools/lib/command";
+
+function correctionCommandFor(label: KindLabeller) {
+  return group({
+    summary: "The kinds of mistakes you corrected, and how often",
+    commands: {
+      kinds: leaf({
+        summary: "Corrections per 100 turns, by kind",
+        options: {
+          days: { type: "string", description: "Window in days (default 30)" },
+          split: { type: "string", description: "Compare before and after this date" },
+          json: { type: "boolean", description: "Machine-readable output" },
+        },
+        run: ({ values }) => cmdKinds(values.days, values.split, values.json === true),
+      }),
+      backfill: leaf({
+        summary: "Label the confirmed corrections without a kind of the current version",
+        options: {
+          relabel: {
+            type: "boolean",
+            description: "Label every confirmed correction again, after a prompt change",
+          },
+        },
+        run: ({ values }) => cmdBackfill(label, values.relabel === true),
+      }),
+    },
+  });
+}
+
+export const correctionCommand = correctionCommandFor(labelWithInference);
+
+export function runCorrection(
+  args: string[],
+  label: KindLabeller = labelWithInference
+): Promise<number> {
+  return runCommand(correctionCommandFor(label), args, ["pal", "cli", "correction"]);
+}
+
+function windowDays(days: string | undefined): number {
+  if (days === undefined) return 30;
+  const parsed = Number(days);
+  if (!Number.isInteger(parsed) || parsed < 1)
+    throw new UsageError(`--days must be a whole number of days, got "${days}"`);
+  return parsed;
+}
+
+function splitDate(split: string): Date {
+  const at = new Date(split);
+  if (Number.isNaN(at.getTime()))
+    throw new UsageError(`--split must be a date such as 2026-10-20, got "${split}"`);
+  return at;
+}
+
+function kindLine(name: string, count: string, rate: string, extra = ""): string {
+  return `  ${name.padEnd(22)}${count.padStart(4)}  ${rate.padStart(5)}${extra}`;
+}
+
+function formatRates(rates: KindRates, title: string): string {
+  const stale = rates.stale ? `, ${rates.stale} labelled by an older prompt` : "";
+  const header = `${title}: ${rates.turns} turns, ${rates.corrections} confirmed corrections, ${rates.unlabelled} without a kind${stale}`;
+  const rows = rates.kinds.map((rate) => {
+    const names = rate.suggestions.length
+      ? `  (${[...new Set(rate.suggestions)].join(", ")})`
+      : "";
+    return kindLine(rate.kind, String(rate.count), rate.per100.toFixed(1), names);
+  });
+  return [header, kindLine("kind", "n", "/100"), ...rows].join("\n");
+}
+
+function cmdKinds(days: string | undefined, split: string | undefined, json: boolean) {
+  const turns = readTurns(windowDays(days));
+  const result = split ? splitRates(turns, splitDate(split)) : kindRates(turns);
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  const sections =
+    "before" in result
+      ? [
+          formatRates(result.before, "Before ".concat(split ?? "")),
+          formatRates(result.after, "From ".concat(split ?? "")),
+        ]
+      : [formatRates(result, "Last ".concat(String(windowDays(days)), " days"))];
+  console.log(sections.join("\n\n"));
+  return 0;
+}
+
+function labelledLine(turn: { ts: string; issue: string }, kind: string): string {
+  return `${turn.ts.slice(0, 16)}  ${kind}  ${turn.issue}`;
+}
+
+async function cmdBackfill(label: KindLabeller, relabel: boolean) {
+  const result = await backfillCorrectionKinds({
+    label,
+    relabel,
+    onLabelled: (turn, kind) => console.log(labelledLine(turn, kind?.kind ?? "failed")),
+  });
+  console.log(`Labelled ${result.labelled}, failed ${result.failed}.`);
+  return result.failed > 0 ? 1 : 0;
+}

package/src/cli/infer.ts

@@ -136,7 +136,7 @@ export const inferCommand = leaf({
     tier: {
       type: "string",
       value: "<tier>",
-      description: `Model size: ${INFERENCE_TIERS.join(" or ")} (default small)`,
+      description: `Model size: ${INFERENCE_TIERS.join(", ")} (default small)`,
     },
     system: { type: "string", value: "<file>", description: "System prompt file" },
     schema: {

package/src/cli/rule.ts

@@ -4,17 +4,32 @@
  * Subcommands:
  *   list [--all] [--json]   Drafts waiting for a decision (--all: every rule)
  *   approve <id>            Turn a draft into a rule that steers
+ *   opinion <id>            Keep a draft as an opinion, steering every session
  *   deny <id>               Reject a draft; it stays on record so it is not redrafted
+ *   retire <id>             End an approved rule or opinion
+ *   add-opinion --kind K --when W --steering S [--evidence E]
  */
 
 import {
   type AdaptationRule,
+  addOpinion,
   decideRule,
-  type RuleStatus,
+  isOpinion,
   readRules,
+  retireRule,
   type TriggerProof,
 } from "../hooks/lib/adaptation-rules";
-import { group, leaf, runCommand } from "../tools/lib/command";
+import { readTurns, type Turn } from "../hooks/lib/adaptation-turns";
+import { CORRECTION_KINDS, type CorrectionKindName } from "../hooks/lib/correction-kind";
+import {
+  EFFECT_WINDOW_DAYS,
+  type OpinionEffect,
+  opinionEffectOf,
+} from "../hooks/lib/correction-rates";
+import { gateAdvice } from "../hooks/lib/opinion-gate";
+import { group, leaf, runCommand, UsageError } from "../tools/lib/command";
+
+type DecideResult = ReturnType<typeof decideRule>;
 
 export const ruleCommand = group({
   summary: "Review the rules PAL drafted from your corrections",
@@ -30,12 +45,36 @@ export const ruleCommand = group({
     approve: leaf({
       summary: "Approve a draft so it steers",
       args: "<id>",
-      run: ({ positionals }) => cmdDecide(positionals[0], "approved"),
+      run: ({ positionals }) =>
+        report(positionals[0], decideRule(positionals[0], "approved")),
+    }),
+    opinion: leaf({
+      summary: "Keep a draft as an opinion, steering every session without a trigger",
+      args: "<id>",
+      run: ({ positionals }) =>
+        report(positionals[0], decideRule(positionals[0], "opinion")),
     }),
     deny: leaf({
       summary: "Deny a draft; it stays on record so it is not drafted again",
       args: "<id>",
-      run: ({ positionals }) => cmdDecide(positionals[0], "denied"),
+      run: ({ positionals }) =>
+        report(positionals[0], decideRule(positionals[0], "denied")),
+    }),
+    retire: leaf({
+      summary: "End an approved rule or opinion",
+      args: "<id>",
+      run: ({ positionals }) => report(positionals[0], retireRule(positionals[0])),
+    }),
+    "add-opinion": leaf({
+      summary: "Write an opinion by hand; it is approved at once",
+      options: {
+        kind: { type: "string", description: "The correction kind it prevents" },
+        when: { type: "string", description: "The situation, in one sentence" },
+        steering: { type: "string", description: "The instruction, imperative" },
+        evidence: { type: "string", description: "Why it is needed" },
+      },
+      run: ({ values }) =>
+        cmdAddOpinion(values.kind, values.when, values.steering, values.evidence),
     }),
   },
 });
@@ -54,37 +93,105 @@ function cmdList(all: boolean, json: boolean): number {
     console.log(all ? "No rules yet." : "No drafts waiting.");
     return 0;
   }
-  console.log(rules.map(formatRule).join("\n\n"));
+  const measure: Measure = { turns: readTurns(EFFECT_WINDOW_DAYS), rules: readRules() };
+  console.log(rules.map((rule) => formatRule(rule, measure)).join("\n\n"));
   return 0;
 }
 
-function formatRule(rule: AdaptationRule): string {
+interface Measure {
+  turns: Turn[];
+  rules: AdaptationRule[];
+}
+
+function formatRule(rule: AdaptationRule, measure: Measure): string {
+  const label = isOpinion(rule) ? "opinion" : rule.status;
   return [
-    `${rule.id}  [${rule.status}]  ${rule.when}`,
+    `${rule.id}  [${label}]  ${rule.when}`,
     ...(rule.widens ? [`  widens: ${rule.widens}`] : []),
-    `  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`,
+    ...(rule.trigger
+      ? [`  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`]
+      : []),
     `  steering: ${rule.steering}`,
+    ...(rule.kind ? [`  kind: ${rule.kind}`] : []),
     ...(rule.check ? [`  check: ${rule.check}`] : []),
     ...(rule.proof ? [`  proof: ${formatProof(rule.proof)}`] : []),
+    ...offerLines(rule),
+    ...gateLines(rule, measure),
+    ...effectLines(rule, measure),
     ...rule.evidence.map((e) => `  evidence: ${e}`),
   ].join("\n");
 }
 
+function offerLines(rule: AdaptationRule): string[] {
+  if (rule.offer !== "opinion-only" || rule.status !== "draft" || rule.opinionGate)
+    return [];
+  const why = rule.trigger ? "the trigger did not prove" : "no trigger";
+  return [`  offer: ${why}; keep it as an opinion or deny it`];
+}
+
+function gateLines(rule: AdaptationRule, { turns, rules }: Measure): string[] {
+  const advice = gateAdvice(rule, rules, turns);
+  return advice ? [`  no opinion: ${advice}`] : [];
+}
+
+function effectLines(rule: AdaptationRule, { turns, rules }: Measure): string[] {
+  const effect = opinionEffectOf(rule, rules, turns);
+  if (!effect) return [];
+  return [
+    `  effect: ${formatWindows(effect)} (${effect.verdict})`,
+    `  other kinds: ${formatWindows(effect.control)}`,
+  ];
+}
+
+function formatWindows({
+  before,
+  after,
+}: Pick<OpinionEffect, "before" | "after">): string {
+  return `${before.count} in ${before.turns} turns before (${before.per100.toFixed(1)}/100), ${after.count} in ${after.turns} after (${after.per100.toFixed(1)}/100)`;
+}
+
 function formatProof(proof: TriggerProof): string {
   return `fired on ${proof.firedCorrections}/${proof.corrections} corrections, ${proof.firedOrdinary}/${proof.ordinary} ordinary turns`;
 }
 
-function decisionLine(id: string, decision: string, rule: AdaptationRule): string {
-  if (rule.id === id) return `Rule ${id} ${decision}: ${rule.when}`;
-  return `Rule ${rule.id} now triggers on: ${rule.trigger.pattern} (widened by ${id})`;
+function resultLine(id: string, rule: AdaptationRule): string {
+  if (rule.id !== id)
+    return `Rule ${rule.id} now triggers on: ${rule.trigger?.pattern} (widened by ${id})`;
+  const label = isOpinion(rule) ? "kept as an opinion" : rule.status;
+  return `Rule ${id} ${label}: ${rule.when}`;
 }
 
-function cmdDecide(id: string, decision: Exclude<RuleStatus, "draft">): number {
-  const result = decideRule(id, decision);
+function report(id: string, result: DecideResult): number {
   if (!result.ok) {
     console.error(result.reason);
     return 1;
   }
-  console.log(decisionLine(id, decision, result.rule));
+  console.log(resultLine(id, result.rule));
   return 0;
 }
+
+function correctionKind(kind: string | undefined): CorrectionKindName {
+  if (CORRECTION_KINDS.includes(kind as CorrectionKindName))
+    return kind as CorrectionKindName;
+  throw new UsageError(`--kind must be one of ${CORRECTION_KINDS.join(", ")}`);
+}
+
+function required(name: string, value: string | undefined): string {
+  if (!value?.trim()) throw new UsageError(`--${name} is required`);
+  return value.trim();
+}
+
+function cmdAddOpinion(
+  kind: string | undefined,
+  when: string | undefined,
+  steering: string | undefined,
+  evidence: string | undefined
+): number {
+  const result = addOpinion({
+    kind: correctionKind(kind),
+    when: required("when", when),
+    steering: required("steering", steering),
+    evidence: evidence?.trim() ? [evidence.trim()] : [],
+  });
+  return report(result.ok ? result.rule.id : "", result);
+}

package/src/cli/tree.ts

@@ -15,6 +15,7 @@ import {
 } from "../tools/lib/command";
 import { builtinTools, builtinToolVerbs } from "./builtin-tools";
 import { contentCommand } from "./content";
+import { correctionCommand } from "./correction";
 import { costCommand } from "./cost";
 import { eventsCommand } from "./events";
 import { identityCommand } from "./identity";
@@ -169,6 +170,7 @@ export function cliTree(admin: AdminHandlers): Group {
       knowledge: knowledgeCommand,
       ledger: ledgerCommand,
       rule: ruleCommand,
+      correction: correctionCommand,
       server: serverCommand,
       skill: skillCommand,
       subagent: subagentCommand,

package/src/hooks/handlers/rating.ts

@@ -17,6 +17,12 @@ import {
 } from "../lib/adaptation-candidates";
 import { readRules } from "../lib/adaptation-rules";
 import { appendTurn, readTurns, withRequests } from "../lib/adaptation-turns";
+import {
+  correctionKindRequest,
+  needsCorrectionKind,
+  parseCorrectionKind,
+  withCorrectionKind,
+} from "../lib/correction-kind";
 import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { replyEnd } from "../lib/interaction-samples";
@@ -231,6 +237,16 @@ async function checkCorrection(reply: string, message: string, sessionId?: strin
   return result.success ? parseCorrectionCheck(result.output) : null;
 }
 
+async function labelCorrectionKind(
+  reply: string,
+  message: string,
+  issue: string,
+  sessionId?: string
+) {
+  const result = await inference(correctionKindRequest(reply, message, issue, sessionId));
+  return result.success ? parseCorrectionKind(result.output) : null;
+}
+
 function knownRules() {
   const waiting = readCandidates().filter((candidate) => candidate.verdict === "waiting");
   return [
@@ -251,7 +267,7 @@ async function draftRuleCandidate(sessionId?: string): Promise<void> {
   else logDebug("rule-drafter", `no candidate: ${result.output ?? result.error ?? ""}`);
 }
 
-/** Background mode: label the reaction, check a possible correction, store the rating. */
+/** Background mode: label the reaction, check a possible correction, name a confirmed one's kind, store the rating. */
 async function runReactionRatingAndStore(
   message: string,
   reply: string,
@@ -273,7 +289,10 @@ async function runReactionRatingAndStore(
       label,
       check
     );
-    if (turn) appendTurn(turn, sentAt);
+    const kind = needsCorrectionKind(turn)
+      ? await labelCorrectionKind(reply, message, turn.issue, sessionId)
+      : null;
+    if (turn) appendTurn(withCorrectionKind(turn, kind), sentAt);
     if (turn?.confirmed) await draftRuleCandidate(sessionId);
   } catch (err) {
     const { logError } = await import("../lib/log");

package/src/hooks/handlers/update-check.ts

@@ -134,6 +134,11 @@ async function checkRepo(): Promise<UpdateCache> {
   }
 }
 
+/** npm's latest tag lags a fresh release by seconds; an older latest is never an update. */
+export function isNewerRelease(latest: string, current: string): boolean {
+  return Bun.semver.order(latest, current) === 1;
+}
+
 async function checkNpm(): Promise<UpdateCache> {
   const current = getInstalledVersion();
 
@@ -149,7 +154,7 @@ async function checkNpm(): Promise<UpdateCache> {
 
     return {
       checkedAt: new Date().toISOString(),
-      available: latest !== current,
+      available: isNewerRelease(latest, current),
       current,
       latest,
       mode: "package",