argus-decision-mcp 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Argus
+Copyright (c) 2026 commet
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,9 @@
 # argus-decision-mcp
 
+[![npm version](https://img.shields.io/npm/v/argus-decision-mcp.svg)](https://www.npmjs.com/package/argus-decision-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/argus-decision-mcp.svg)](https://www.npmjs.com/package/argus-decision-mcp)
+[![license](https://img.shields.io/npm/l/argus-decision-mcp.svg)](./LICENSE)
+
 > **Your AI gives you an answer. Argus gives you a receipt — and checks it against reality on the date you set.**
 
 Argus is an MCP server for **decision accountability**. Instead of grading your
@@ -9,7 +13,9 @@ what actually happened. The artifact it produces — a **Judgment Receipt** —
 carries one line no other AI tool will: `AI VERDICT … NONE`. The model never
 graded you. Reality did.
 
-Works with any MCP host — Claude, ChatGPT, Gemini, or any MCP-compatible client.
+Runs on any MCP host that supports local **stdio** servers — Claude Desktop,
+Claude Code, and other clients that launch a local process. (Remote-only
+connectors that require an HTTP transport aren't supported yet — see the roadmap.)
 
 ```
 ┌─ ARGUS · JUDGMENT RECEIPT ────────────────────────────────┐
@@ -32,6 +38,14 @@ Works with any MCP host — Claude, ChatGPT, Gemini, or any MCP-compatible clien
 
 ## Why it's different
 
+**It is not a receipt of what your *agent* did.** A growing set of tools now
+log an AI coding run — prompt captured, files touched, checkpoint saved, replay
+path written down. That receipt is about the *machine's* actions over one run.
+Argus receipts something no run-logger can: *your* judgment call, in your own
+words, opened again on a date you set and settled against **reality** — not
+against a model's opinion, and not against a diff. Machine-action receipts and
+judgment receipts are different primitives; you can keep both.
+
 Most decision tools compete on a *better answer*, a *score*, a *confidence*.
 Argus does the opposite, and the opposite is enforced **structurally**, not
 promised in prose:
@@ -39,7 +53,7 @@ promised in prose:
 - **There is no verdict tool.** The model cannot grade your decision because no
   `argus_verdict` / `argus_score` tool exists to call. `grep dist/` and see.
 - **You can't settle what you never sealed.** `argus_settle` hard-errors without
-  a prior `argus_seal` — "no judgment without a falsifiable bet" is a
+  a prior `argus_seal` — "no judgment without a falsifiable prediction" is a
   precondition, not a suggestion.
 - **State is the ledger, not a flag.** A decision's status is the fold of an
   append-only event log, so it can't be faked by calling tools out of order.
@@ -52,7 +66,10 @@ Claude Code:
 claude mcp add argus -- npx -y argus-decision-mcp
 ```
 
-Or add to your host's MCP config:
+Or add to your host's MCP config. **Zero config works**: with no `env` at all,
+your ledger lives in `~/.argus`.
+
+**Claude Code** (expands `${CLAUDE_PROJECT_DIR}`, so a per-project ledger works):
 
 ```jsonc
 {
@@ -61,19 +78,21 @@ Or add to your host's MCP config:
       "command": "npx",
       "args": ["-y", "argus-decision-mcp"],
       "env": {
-        // Set this ONCE and you never pass argus_dir again — every tool falls
-        // back to it. Claude Code expands ${CLAUDE_PROJECT_DIR}; on other hosts
-        // put an absolute path here (or pass argus_dir per call).
+        // OPTIONAL — per-project ledger. Omit entirely to use ~/.argus.
         "ARGUS_DIR": "${CLAUDE_PROJECT_DIR}/.argus",
         // OPTIONAL — connect to your Argus account so sealed predictions get an
         // email at their check-by date (the Companion Brief) and show up in the
-        // web dashboard. Issue the token in the web app. Leave it unset to stay
-        // fully local (the privacy-preserving default).
+        // web dashboard. Issue the token in the web app (Settings → sync token).
+        // Leave it unset to stay fully local (the privacy-preserving default).
         "ARGUS_TOKEN": "argus_pat_…",
         // OPTIONAL — the timezone that decides when a check-by date becomes
-        // "today". Unset = UTC, which for Korean users means the day flips at
-        // 9am KST (a due decision won't show until then). Set your zone:
-        "ARGUS_TZ": "Asia/Seoul"
+        // "today". Unset = your machine's local timezone (usually right).
+        // Set it only if your machine's clock zone isn't where you live:
+        "ARGUS_TZ": "Asia/Seoul",
+        // OPTIONAL — opt in to anonymous usage telemetry (OFF by default). Sends
+        // a random install id + which tool ran + version/platform; never your
+        // decisions or token. Honors DO_NOT_TRACK. See SECURITY.md → Telemetry.
+        "ARGUS_TELEMETRY": "1"
         // "ARGUS_API_URL": "https://argus.voyage"  // override only for self-host
       }
     }
@@ -81,14 +100,98 @@ Or add to your host's MCP config:
 }
 ```
 
+**Claude Desktop** does **not** expand `${...}` variables — a literal
+`${CLAUDE_PROJECT_DIR}` would fail on every call (Argus names this error when
+it happens). Either omit `ARGUS_DIR` (→ `~/.argus`) or use an absolute path:
+
+```jsonc
+// macOS
+"env": { "ARGUS_DIR": "/Users/you/.argus" }
+// Windows — also note the command form below
+"env": { "ARGUS_DIR": "C:\\Users\\you\\.argus" }
+```
+
+**Windows** hosts often can't launch bare `npx` (it's `npx.cmd`). If the server
+fails to start, use:
+
+```jsonc
+{
+  "command": "cmd",
+  "args": ["/c", "npx", "-y", "argus-decision-mcp"]
+}
+```
+
 > `argus_dir` is **optional** on every tool: omit it and it resolves from
-> `ARGUS_DIR`. A per-call `argus_dir` still wins — so Argus works on any host
-> even when env-variable interpolation doesn't.
+> `ARGUS_DIR`, then falls back to `~/.argus`. A per-call `argus_dir` still
+> wins — so Argus works on any host even when env-variable interpolation
+> doesn't.
+
+## Your first receipt (2 minutes)
+
+You never call these tools by name. Once the server is connected, you just
+talk to your AI in plain language and it calls the right tool for you. One
+full loop — from sealing a prediction to letting reality grade it — looks like
+this:
+
+**1 · Seal a prediction** — before you commit to a decision, tell your AI:
+
+> **You:** "I'm shipping the new onboarding flow next week. Seal a prediction:
+> signups go up at least 10% by the end of the month."
+
+Argus records your predicate and a check-by date. Nothing is scored — it's a
+prediction against reality, not a grade from the model.
+
+**2 · Re-check a premise** *(optional, any time before the date)* — if a fact
+your decision leaned on might have moved:
+
+> **You:** "Re-check my onboarding decision — did the weekly signup number
+> change since I sealed it?"
+
+Argus compares the new number to the baseline and tells you if it drifted. It
+returns the handle — whether to revisit the decision stays your call.
+
+**3 · Settle on the check-by date** — when the date arrives:
+
+> **You:** "Settle my onboarding prediction. Signups went up 14%."
+
+Argus prints the **Judgment Receipt** at the top of this page — with
+`AI VERDICT … NONE`. You made the call; reality graded it, not the model.
+
+That's the whole spine. Everything below is detail on top of these three steps.
+
+## Two loops
+
+Argus runs two loops side by side — the same three habits its author
+uses daily: **봉인하기** (seal it before you ask the AI) · **드러내기**
+(surface claims you accepted without checking) · **돌아보기** (return when
+reality has answered):
+
+- **The daily watch** (`argus_watch`) — turns over once a *day*. In the morning
+  (or whenever a session starts) you anchor one line: today's aim, your working
+  hypothesis, where you lean. While you work, you capture the things that
+  usually evaporate: a claim you accepted without checking, a premise you
+  haven't verified, a question you're deferring. Tomorrow's `check_in` mirrors
+  yesterday's line back — *"so, how did it go?"* — as a question, never a grade.
+  An anchor is a **note, not a prediction**: nothing about it is scored, counted, or
+  streaked, ever.
+- **The decision loop** (everything below) — plays out over days to months.
+  When a capture turns out to be load-bearing, *you* promote it: open the
+  decision, seal a falsifiable prediction, track its premises, and let reality
+  settle it into a Judgment Receipt.
+
+The watch builds the habit; the decision loop builds the record.
 
 ## The loop
 
+**The spine is three tools:** **`argus_seal`** (write the falsifiable prediction) →
+optional **`argus_recheck`** (has a load-bearing premise moved?) →
+**`argus_settle`** (reality answers, on the date). If you only ever learn
+these three, Argus works. Everything else in the table supports that spine —
+reach for it when you need it, not before.
+
 | Tool | What it does |
 |------|--------------|
+| `argus_watch` | The daily watch. `anchor` keeps today's one-line aim (your words, verbatim); `capture` notes an unchecked claim / unverified premise / deferred question mid-work without opening a decision; `list` reads the recent log. Anchors are mirrored back by the next `check_in` as a question — never evaluated, never counted in any record. |
 | `argus_open_decision` | Opens a consequential decision. Runs a restraint gate first — on a flat / low-stakes / reversible / already-closed call it tells you to leave it as is. If it fires, it surfaces **one** neutral question, never a fork or a lean. |
 | `argus_review` | Reviews an existing document (strategy memo / PRD / deck text / AI answer) for judgment risk: reviewability score, routed lenses, source units with anchors, and the extraction prompt — then hands the analysis to you. Degrades honestly on unextractable input; never a verdict. End by sealing one follow-up. |
 | `argus_seal` | Seals a falsifiable prediction (`predicate` + `check_by`) and captures the receipt's real-question / unverified-assumption / human-only / your-call fields. Refuses an empty predicate or a non-future date. If you seal without naming the assumption, it's recorded as an explicit **skip** — never a forced gate (which would just eject the tiredest user), never a silent blank. With `ARGUS_TOKEN` set, the prediction also syncs to your account so the Companion Brief can email you at its check-by date. |
@@ -97,7 +200,7 @@ Or add to your host's MCP config:
 | `argus_settle` | On the check-by date, records what reality did and issues the Judgment Receipt. Hard-errors without a prior seal. Optionally records **which premise broke** (your attribution, never inferred) — over time your track record can say "3 of your 4 missed bets traced to a broken external premise": a frequency, never a diagnosis. |
 | `argus_amend` | Changes the predicate or check-by date **before** reality answers — a course change, not an erasure (the original stays on the append-only ledger). Hard-errors once the decision is settled. |
 | `argus_dismiss` | Closes a decision **without settling** — it became irrelevant, was decided elsewhere, or you changed your mind. No verdict is recorded; terminal, not reopened. |
-| `argus_check_in` | Returns contracts past their check-by date **and premise facts due for a re-check** (the same fact under several decisions is one re-check). If nothing is due, it says so and stops — it doesn't manufacture engagement. |
+| `argus_check_in` | Returns contracts past their check-by date **and premise facts due for a re-check** (the same fact under several decisions is one re-check), and mirrors yesterday's watch anchor back as a question. If nothing is due, it says so and stops — it doesn't manufacture engagement. |
 | `argus_sync` | Pulls your account receipts into the terminal (live judgments + what's due) so you can settle here. Seals push automatically; this is the read side. Requires `ARGUS_TOKEN`. |
 | `argus_recall` | Reads your own history: a receipt, the open contracts, or a sample-size-caveated track record (never a tier or score). |
 | `argus_init` / `argus_config` | Initialize the `.argus` directory; read/write non-spine settings. |
@@ -124,12 +227,19 @@ Argus does not pretend liveness.
 
 Everything is local, under `.argus/` in your project (gitignored by default) —
 an append-only `ledger.jsonl` **you own**: plain JSON lines, no lock-in,
-receipts render to shareable text. No telemetry. The **only** network call
-Argus ever makes is the opt-in account sync: if — and only if — you set
-`ARGUS_TOKEN`, a sealed/settled prediction is POSTed to your own Argus account
-so it can email you at its check-by date. **Premise data never leaves your
-machine** — it is not part of the sync payload. Unset the token and Argus never
-touches the network. See [SECURITY.md](SECURITY.md).
+receipts render to shareable text. **No telemetry by default.** The only network
+call Argus makes out of the box is the opt-in account sync: if — and only if —
+you set `ARGUS_TOKEN`, a sealed/settled prediction is POSTed to your own Argus
+account so it can email you at its check-by date. Separately, you can opt in to
+**anonymous** usage telemetry with `ARGUS_TELEMETRY=1` (a random install id +
+which tool ran + version/platform, never your decisions or token; honors
+`DO_NOT_TRACK`) — see SECURITY.md. **Premise data stays on your machine
+by default** — it is not part of the sync payload. There is exactly one switch
+that changes this: `argus_config premise_sync:true` (off unless you set it)
+sends a sealed decision's *monitored* premises along, so your account's
+autonomous premise-watch can re-check them against reality and email you when
+one materially moves. Unset the token and Argus never touches the network.
+See [SECURITY.md](SECURITY.md).
 
 ## Measured
 

package/SECURITY.md

@@ -2,14 +2,28 @@
 
 ## Data & privacy
 
-- **All data is local.** Argus writes only under the `.argus/` directory you
-  point it at: an append-only `ledger/ledger.jsonl`, per-decision
-  `sessions/{id}/` files, and a `config.yaml`. Nothing leaves the machine.
-- **No telemetry, no network.** The runtime dependency surface is two packages
-  (`@modelcontextprotocol/sdk`, `js-yaml`). `npm ls --prod` should show no
-  analytics or network client. CI fails if the production dependency tree grows.
-- **Private by default.** `argus_init` adds `sessions/`, `ledger/`, and `.bound`
-  to `.argus/.gitignore` so your decisions are never committed.
+- **All data is local by default.** Argus writes only under the `.argus/`
+  directory you point it at: an append-only `ledger/ledger.jsonl`,
+  per-decision `sessions/{id}/` files, and a `config.yaml`. Nothing leaves the
+  machine unless you explicitly set `ARGUS_TOKEN` for account sync (or opt in to
+  anonymous telemetry with `ARGUS_TELEMETRY=1`; see below).
+- **No telemetry by default.** With no `ARGUS_TOKEN` and no `ARGUS_TELEMETRY=1`,
+  the server makes no network calls. Telemetry is strictly **opt-in**: set
+  `ARGUS_TELEMETRY=1` and it sends an anonymous, content-free ping — a random,
+  machine-local install id (`~/.argus/.telemetry-id`, not tied to your account
+  or token, regenerable by deleting the file), which of the built-in tools ran
+  and whether it succeeded, plus the package version, coarse OS platform, and
+  Node major. It **never** sends decision content, titles, predicates, file
+  paths, `argus_dir`, or the account token. `DO_NOT_TRACK=1` disables it even if
+  the flag is set, and the sink stores no `user_id` (nothing to identify).
+  Telemetry rows are **deleted automatically after 90 days** (a daily database
+  job — retention is enforced by the database itself, not by policy prose). The
+  runtime dependency surface is intentionally small and visible in
+  `package.json`: MCP SDK, schema/config helpers, and document parsers for
+  `argus_review`. `npm audit --omit=dev` should stay clean before publishing.
+- **Private by default.** `argus_init` adds `sessions/`, `ledger/`,
+  `config.yaml`, and `.bound` to `.argus/.gitignore` so your decisions and
+  local settings are never committed accidentally.
 
 ## Threat model
 

package/dist/lib/ambient-due.js

@@ -0,0 +1,63 @@
+import { replayLedger } from './ledger-replay.js';
+import { duePremises, groupDuePremises, dueOpenQuestions } from './premises.js';
+import { surfacesFor, SURFACES, resolveResponseLocale } from './surfaces.js';
+/** Count from an already-replayed ledger (when the caller has one in hand). */
+export function ambientDueFromState(state) {
+    return {
+        contractsDue: state.overdue.length,
+        premiseFactsDue: groupDuePremises(duePremises(state)).length,
+        openQuestionsDue: dueOpenQuestions(state).length,
+    };
+}
+/** Count by replaying the ledger for `dir` as of `today`. */
+export function ambientDue(dir, today) {
+    return ambientDueFromState(replayLedger(dir, today));
+}
+/** True when nothing at all is due — the silence gate (restraint: zero renders
+ *  nothing, never an empty nag). */
+export function isSilent(due) {
+    return due.contractsDue === 0 && due.premiseFactsDue === 0 && due.openQuestionsDue === 0;
+}
+/**
+ * The user's own language, read from the LEDGER's user-authored text — the
+ * one deterministic voice source for surfaces that have no fresh input (the
+ * ambient tail, recall's textless views). Chain: the latest watch anchor, an
+ * overdue predicate, a due premise's decision, a due question, else ANY
+ * contract predicate (replay order = deterministic). Never env/Intl — an
+ * English user on a Korean machine must not get a Korean frame (experience
+ * loop caught exactly that).
+ */
+export function ledgerVoiceText(state) {
+    const anchors = [...state.watch.anchors.values()].sort((a, b) => (a.date < b.date ? 1 : -1));
+    return anchors[0]?.text
+        || state.overdue[0]?.text
+        || duePremises(state)[0]?.decision_text
+        || dueOpenQuestions(state)[0]?.text
+        || [...state.contracts.values()].find((c) => typeof c.predicate === 'string' && c.predicate)?.predicate;
+}
+/**
+ * The localized one-line ambient fact for a due count, or '' when silent.
+ * Leads with a space so it appends cleanly to the END of a tool's surface
+ * (M1 §1.3, §6: never obscure the result — the line is last, and it is a fact
+ * + the argus_check_in handle, never a directive).
+ * `state` (when the caller has one) lends the ledger's own voice — without it
+ * the tail fell back to config-or-EN and read "By the way — 2 to settle" to a
+ * user whose every decision is Korean (experience-loop worst-moment).
+ */
+export function ambientLine(dir, due, state) {
+    if (isSilent(due))
+        return '';
+    const voice = state ? ledgerVoiceText(state) : undefined;
+    const A = (voice ? SURFACES[resolveResponseLocale(dir, voice)] : surfacesFor(dir)).ambient;
+    const { contractsDue: c, premiseFactsDue: p, openQuestionsDue: q } = due;
+    // Fragment-composed so any subset of the three due kinds reads naturally in
+    // both locales (M3 adds a third kind — a fixed combo table would be 7 cases).
+    const frags = [];
+    if (c > 0)
+        frags.push(A.frag_contracts(c));
+    if (p > 0)
+        frags.push(A.frag_premises(p));
+    if (q > 0)
+        frags.push(A.frag_open_questions(q));
+    return A.wrap(frags);
+}

package/dist/lib/argus-dir.js

@@ -1,4 +1,5 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { boundMarkerPath } from './layout.js';
 /**
@@ -26,6 +27,14 @@ export function requireArgusDir(callArg) {
     if (typeof callArg !== 'string' || callArg.length === 0) {
         throw new ArgusDirError('argus_dir is required (absolute path to the .argus directory).');
     }
+    // An unexpanded config variable is the #1 Claude Desktop first-run failure:
+    // only Claude Code expands ${CLAUDE_PROJECT_DIR}, so Desktop passes the
+    // literal string through. Name the actual problem instead of "not absolute".
+    if (/\$\{[^}]*\}|%[A-Za-z_]+%/.test(callArg)) {
+        throw new ArgusDirError(`Your MCP host did not expand the variable in "${callArg}" (only some hosts interpolate env vars). ` +
+            'Replace it with an absolute path in your MCP config (e.g. "C:\\Users\\you\\.argus" or "/Users/you/.argus"), ' +
+            'or remove ARGUS_DIR entirely to use the default ~/.argus.');
+    }
     const resolved = path.resolve(callArg);
     if (!path.isAbsolute(callArg)) {
         throw new ArgusDirError('argus_dir must be an absolute path.');
@@ -48,7 +57,10 @@ export function resolveToolArgusDir(callArg) {
     const env = process.env['ARGUS_DIR'];
     if (typeof env === 'string' && env.length > 0)
         return requireArgusDir(env);
-    throw new ArgusDirError('No argus_dir given and ARGUS_DIR is not set. Pass an absolute argus_dir, or set "ARGUS_DIR" in your MCP config env (then you can omit it every call).');
+    // Zero-config default (blueprint §9.4 "첫 설치의 문"): a brand-new user on a
+    // host without env interpolation still gets a working home for their ledger.
+    // Per-call argus_dir and ARGUS_DIR both keep winning over this.
+    return path.join(os.homedir(), '.argus');
 }
 /** Record the bound dir so Resources (which get no args) can find it later. */
 export function writeBoundMarker(argusDir) {
@@ -61,6 +73,43 @@ export function writeBoundMarker(argusDir) {
     catch {
         /* non-critical */
     }
+    // Global registry (M2 fleet, §9.4): every init'd project dir also lands in
+    // ~/.argus/.bound so ONE check_in can report due items across all of a
+    // user's projects. Local paths only, stays on this machine, best-effort.
+    try {
+        const home = path.join(os.homedir(), '.argus');
+        fs.mkdirSync(home, { recursive: true });
+        const reg = path.join(home, '.bound');
+        let dirs = [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(reg, 'utf8'));
+            dirs = Array.isArray(parsed.bound) ? parsed.bound.filter((x) => typeof x === 'string') : [];
+        }
+        catch { /* fresh registry */ }
+        if (!dirs.includes(argusDir))
+            dirs.unshift(argusDir);
+        fs.writeFileSync(reg, JSON.stringify({ bound: dirs.slice(0, 16) }), 'utf8');
+    }
+    catch {
+        /* non-critical */
+    }
+}
+/** The cross-project registry (~/.argus/.bound) — existing dirs only. */
+export function readGlobalBoundList() {
+    try {
+        const reg = path.join(os.homedir(), '.argus', '.bound');
+        const parsed = JSON.parse(fs.readFileSync(reg, 'utf8'));
+        const dirs = Array.isArray(parsed.bound) ? parsed.bound.filter((x) => typeof x === 'string') : [];
+        return dirs.filter((d) => { try {
+            return fs.existsSync(d);
+        }
+        catch {
+            return false;
+        } });
+    }
+    catch {
+        return [];
+    }
 }
 function readBoundList(argusDir) {
     try {

package/dist/lib/calendar.js

@@ -0,0 +1,75 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { calendarPath } from './layout.js';
+function ymdCompact(ymd) {
+    return ymd.replace(/-/g, '');
+}
+function addOneDay(ymd) {
+    const t = Date.parse(`${ymd}T00:00:00Z`);
+    if (Number.isNaN(t))
+        return ymd;
+    return new Date(t + 86_400_000).toISOString().slice(0, 10);
+}
+function escapeIcs(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/\r?\n/g, '\\n')
+        .replace(/,/g, '\\,')
+        .replace(/;/g, '\\;');
+}
+function foldLine(line) {
+    if (line.length <= 74)
+        return line;
+    const chunks = [];
+    let rest = line;
+    while (rest.length > 74) {
+        chunks.push(rest.slice(0, 74));
+        rest = rest.slice(74);
+    }
+    chunks.push(rest);
+    return chunks.map((chunk, i) => (i === 0 ? chunk : ` ${chunk}`)).join('\r\n');
+}
+export function renderReturnCalendarEvent(args) {
+    const start = ymdCompact(args.check_by);
+    const end = ymdCompact(addOneDay(args.check_by));
+    const stamp = args.created_at.replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+    const summary = `Argus return: ${args.predicate.slice(0, 80)}`;
+    const description = [
+        'Your sealed Argus decision is due today.',
+        `Predicate: ${args.predicate}`,
+        'Open your terminal and run argus_check_in, then argus_settle if reality is clear.',
+    ].join('\n');
+    const lines = [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//Argus//Return Calendar//EN',
+        'CALSCALE:GREGORIAN',
+        'METHOD:PUBLISH',
+        'BEGIN:VEVENT',
+        `UID:${escapeIcs(args.id)}@argus.local`,
+        `DTSTAMP:${stamp}`,
+        `DTSTART;VALUE=DATE:${start}`,
+        `DTEND;VALUE=DATE:${end}`,
+        `SUMMARY:${escapeIcs(summary)}`,
+        `DESCRIPTION:${escapeIcs(description)}`,
+        'BEGIN:VALARM',
+        // DTSTART is local midnight of the check-by (an all-day event), so a POSITIVE
+        // offset lands on the morning OF the due date. `-PT9H` fired nine hours
+        // BEFORE midnight — 15:00 the previous afternoon — while the alarm text said
+        // "due today". This .ics is the only thing that brings a sealed bet back
+        // without an account, so it has to ring on the right day.
+        'TRIGGER;RELATED=START:PT9H',
+        'ACTION:DISPLAY',
+        `DESCRIPTION:${escapeIcs(summary)}`,
+        'END:VALARM',
+        'END:VEVENT',
+        'END:VCALENDAR',
+    ];
+    return `${lines.map(foldLine).join('\r\n')}\r\n`;
+}
+export async function writeReturnCalendarEvent(argusDir, args) {
+    const file = calendarPath(argusDir, args.id);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, renderReturnCalendarEvent(args), 'utf8');
+    return file;
+}

package/dist/lib/canonical-scales.js

@@ -0,0 +1,105 @@
+/**
+ * Canonical scales & units — the pre-rule normalization layer for M2 drift
+ * materiality (internal design notes §3, §10.4).
+ *
+ * Rules compare CANONICAL values, never raw labels. This module turns an ordinal
+ * label ("BBB", "Baa2", "Enterprise", "Maintenance") into a comparable number via
+ * a built-in ordinal map, and converts a few units into a common axis before the
+ * rule ever runs. When a label can't be placed on a known scale, this returns
+ * `null` — the caller routes that to `uncertain` (host-judgment lane), never a
+ * silent guess (§3.1, "규칙이 아니라 매번 모델 판정 = 스파인 위반").
+ *
+ * Alias normalization is the load-bearing win: Baa2 ≡ BBB, so a Moody's→S&P
+ * relabel is `unchanged`, not a manufactured downgrade (CAT-06).
+ */
+/** Normalize a label for lookup: trim, collapse spaces, lowercase. Ordinal maps
+ *  are keyed by this normalized form so "BBB ", "bbb", "BBB" all hit. */
+function normLabel(label) {
+    return label.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+// ── S&P / Moody's credit ratings (AAA=1 … D=22), with cross-agency aliases ──
+// The canonical axis is S&P notation; Moody's labels are aliases onto the same
+// rank so Baa2 ≡ BBB (CAT-06), A2 ≡ A, Ba1 ≡ BB+, etc.
+const SP_ORDER = [
+    'AAA', 'AA+', 'AA', 'AA-', 'A+', 'A', 'A-', 'BBB+', 'BBB', 'BBB-',
+    'BB+', 'BB', 'BB-', 'B+', 'B', 'B-', 'CCC+', 'CCC', 'CCC-', 'CC', 'C', 'D',
+];
+// Moody's, index-aligned to SP_ORDER above.
+const MOODYS_ORDER = [
+    'Aaa', 'Aa1', 'Aa2', 'Aa3', 'A1', 'A2', 'A3', 'Baa1', 'Baa2', 'Baa3',
+    'Ba1', 'Ba2', 'Ba3', 'B1', 'B2', 'B3', 'Caa1', 'Caa2', 'Caa3', 'Ca', 'C', 'DDD',
+];
+function buildCreditRanks() {
+    const r = {};
+    SP_ORDER.forEach((lbl, i) => {
+        r[normLabel(lbl)] = i + 1;
+        const m = MOODYS_ORDER[i];
+        if (m)
+            r[normLabel(m)] = i + 1; // alias onto the same rank
+    });
+    return r;
+}
+// ── LTS / lifecycle stages (Active=1 … EOL highest) ──
+const LTS_ORDER = ['Active', 'Maintenance', 'Security', 'Deprecated', 'EOL'];
+// ── Product tiers (Free=1 … Enterprise highest) ──
+const TIER_ORDER = ['Free', 'Trial', 'Starter', 'Pro', 'Business', 'Team', 'Enterprise'];
+// ── Generic quality letter grades (A=1 … F) ──
+const QUALITY_ORDER = ['A', 'B', 'C', 'D', 'E', 'F'];
+function buildOrdinal(order) {
+    const r = {};
+    order.forEach((lbl, i) => { r[normLabel(lbl)] = i + 1; });
+    return r;
+}
+/** Built-in scales, addressable by name from a premise's `scale` modifier. */
+export const BUILTIN_SCALES = {
+    sp_credit: { name: 'S&P/Moody\'s credit rating', kind: 'credit', ranks: buildCreditRanks() },
+    lts: { name: 'lifecycle stage', kind: 'lts', ranks: buildOrdinal(LTS_ORDER) },
+    tier: { name: 'product tier', kind: 'tier', ranks: buildOrdinal(TIER_ORDER) },
+    quality: { name: 'quality grade', kind: 'quality', ranks: buildOrdinal(QUALITY_ORDER) },
+};
+/**
+ * Map a label onto a named scale's ordinal rank. Returns null when the scale is
+ * unknown OR the label isn't on it — the caller routes null to `uncertain`
+ * (host-judgment lane), never a silent numeric guess (§3.1).
+ *
+ * A custom scale (user-provided ordered labels) can be passed inline via
+ * `customScales` so a premise isn't limited to the built-ins.
+ */
+export function normalizeLabel(scale, label, customScales) {
+    if (!scale)
+        return null;
+    const custom = customScales?.[scale];
+    if (custom) {
+        const ranks = Array.isArray(custom) ? buildOrdinal(custom) : custom.ranks;
+        const hit = ranks[normLabel(label)];
+        return typeof hit === 'number' ? hit : null;
+    }
+    const builtin = BUILTIN_SCALES[scale];
+    if (!builtin)
+        return null;
+    const hit = builtin.ranks[normLabel(label)];
+    return typeof hit === 'number' ? hit : null;
+}
+const UNIT_TABLE = {
+    // temperature: Kelvin ↔ Celsius (offset). Canonical = Celsius for delta axes.
+    k: { to: 'c', convert: (v) => v - 273.15 },
+    kelvin: { to: 'c', convert: (v) => v - 273.15 },
+    // fuel economy: mpg (US) → L/100km (reciprocal). Canonical = L/100km.
+    mpg: { to: 'l/100km', convert: (v) => (v === 0 ? Infinity : 235.215 / v) },
+    // percentage points and percent share a numeric magnitude; the AXIS (not the
+    // unit) disambiguates — handled by unit_axis, not here.
+};
+/**
+ * Convert a value from a source unit to its canonical unit. Returns null when the
+ * unit is unknown (caller keeps host_reported + low_confidence). When from===to
+ * or from is already canonical, returns the value unchanged.
+ */
+export function normalizeUnit(value, from) {
+    if (!from)
+        return null;
+    const key = from.trim().toLowerCase();
+    const conv = UNIT_TABLE[key];
+    if (!conv)
+        return { value, unit: key }; // unknown but not an error — pass through as-is unit-tagged
+    return { value: conv.convert(value), unit: conv.to };
+}