euthyna 0.8.0 → 0.9.1

package/.agents/skills/euthyna/SKILL.md

@@ -92,6 +92,23 @@ license: Apache-2.0
 **可以做多个阶段，但阶段之间不许互相替代。**
 特别是：**阶段 B 报出的疑似发现，必须逐个走阶段 C 验证**，不许直接写进报告当结论。
 
+### 模式词（斜杠命令）
+
+用户用斜杠命令进来时，按下表把模式映射到阶段与第一条命令。**词表只在这里维护**，
+各宿主命令文件（Cursor / OpenCode / Copilot / Hermes）指向本节，不各自重抄一份。
+
+| 你打 | 走哪条支路 | 第一条命令 |
+|---|---|---|
+| `/euthyna pr` | 阶段 B 变更面 | `euthyna audit`（省略 `--base` 即按分叉点推断并声明） |
+| `/euthyna graph` | 阶段 B 的来源谱系视图 | `euthyna audit --graph`（同样可省略 `--base`） |
+| `/euthyna repo` | 阶段 A 依赖面 | `euthyna deps --all` |
+| `/euthyna claim <结论>` | 阶段 C 结论面 | `euthyna coverage --symbol <名>` |
+| `/euthyna gate <报告>` | 校验一份已写的报告 | `euthyna gate <报告>` |
+| `/euthyna help` | 只打印这张表 | 不跑命令，不改变状态 |
+
+`/euthyna graph` 不是新测量：`--graph` 只是把 `history` 已经给出的归属画成 Mermaid。
+**图上没有第二条边不等于内容没被移过**，边界见 references/fact-producers.md。
+
 ---
 
 ## 本技能自带的两个确定性测量
@@ -106,7 +123,7 @@ license: Apache-2.0
 | `coverage` | 某个符号在测试运行中**到底有没有被调用过**？ | 报告里要说「测过 / 没测过」时（阶段 B / C） |
 
 ```powershell
-# 唯一必需的参数是 --base（改前版本 / PR 分叉点）：
+# --base 可以省略：省略时按 merge-base(HEAD, origin/main) 推断，并在报告里声明为 range-inferred
 node <euthyna 仓库>/bin/euthyna.js audit --base <改前版本> --repo <被审计的仓库>
 
 # history / coverage 按需单独跑：

package/.agents/skills/euthyna/references/fact-producers.md

@@ -72,6 +72,10 @@ node <euthyna 仓库>/bin/euthyna.js history --base <改前版本> --no-origins
 ```
 
 `--base` 是**改前版本**（PR 的分叉点），`--head` 默认 `HEAD`。
+省略 `--base` 时按 `merge-base(<被审的 head>, origin/main)` 推断，并在「范围」那一行标出「推断」、在
+「未评估的判据」里加一条 `range-inferred`。推断出的范围**只到分叉点**，看不到更早的历史；
+两个引用都解析不出来时报用法错误，不猜 `HEAD~1`。斜杠命令免参数进来靠的就是这条，所以
+**看到 `range-inferred` 第一步是确认分叉点对不对**，而不是接受它。
 分叉点不确定时用 `git merge-base <目标分支> HEAD` 的结果。
 
 ### 归属语义（两个固有近似，已确证≠精确）
@@ -95,7 +99,7 @@ node <euthyna 仓库>/bin/euthyna.js history --base <改前版本> --no-origins
 ### 输出长什么样（真实捕获）
 
 ```
-euthyna euthyna-history — 被删除代码的来源归属与安全分类
+euthyna-history — 被删除代码的来源归属与安全分类
 目标: D:/axe-core/axe-core
 范围: 8390a5a9…..397f5fce…
 
@@ -239,7 +243,7 @@ node <euthyna 仓库>/bin/euthyna.js coverage `
 ### 输出长什么样（真实捕获，一次查询命中两种结果）
 
 ```
-euthyna euthyna-coverage — 符号调用计数（只能证伪）
+euthyna-coverage — 符号调用计数（只能证伪）
 
 已确证 (1)
   • 符号 cleanup 在本次测试运行中一次都没有被调用（调用计数为 0）
@@ -338,6 +342,11 @@ node <euthyna 仓库>/bin/euthyna.js gate <报告文件> --verify --cwd <被审
 - `history` 的归属**默认追「最初引入」**（`git log -S`，有探针上限，只对 ≥ 12 字符的行做追溯）；
   要退回 blame 的「最后修改」语义用 `--no-origins`（更快，输出会写明）。两个近似都写在本文件「归属语义」一节。
 - `history` 只覆盖**被删除的行**。新增的代码它不管（`--pickaxe` 除外）。
+- `--graph` 只把上面这些归属**画出来**（Mermaid 源码，不是图片）：范围 → 最后修改者 → 最初引入者。
+  它不新增任何测量，也不画严重性——图上只有已测到的状态与行数。这也是契约，不是漏写。
+- 图上**没有第二条边不等于内容没被移过**。追溯结果被丢下有两条路：短行（`}`、`return x;`）与
+  `--no-origins` 会写成虚线的 `history-origins`；而「来源提交本身没被判为安全相关」是**静默**丢弃，
+  图上没有那条边，也没有任何说明。看图谱时把「没有边」当成中性事实，不是清白。
 - `coverage` **只能证伪**。见上文。
 - `coverage` 依赖调用计数，**不处理动态派发、反射、字符串调用**。
   计数为 0 的结论在存在这些机制时要打折扣。

package/.agents/skills/euthyna-en/SKILL.md

@@ -102,6 +102,26 @@ facts from the producers decide where the manual reading must be directed.
 In particular: every suspected finding reported by Stage B must go through Stage C one by
 one — never write it straight into the report as a conclusion.
 
+### Modes (slash commands)
+
+When a user arrives through a slash command, map the mode to the stage and the first
+command using this table. **The table is maintained only here**; the host command files
+(Cursor / OpenCode / Copilot / Hermes) point at this section instead of each keeping their
+own copy.
+
+| You type | Which branch | First command |
+|---|---|---|
+| `/euthyna pr` | Stage B, the change surface | `euthyna audit` (omit `--base` and the fork point is inferred and declared) |
+| `/euthyna graph` | Stage B, the provenance view | `euthyna audit --graph` (`--base` may be omitted here too) |
+| `/euthyna repo` | Stage A, the dependency surface | `euthyna deps --all` |
+| `/euthyna claim <assertion>` | Stage C, the claim surface | `euthyna coverage --symbol <name>` |
+| `/euthyna gate <report>` | Validating a written report | `euthyna gate <report>` |
+| `/euthyna help` | Print this table only | run nothing, change no state |
+
+`/euthyna graph` is not a new measurement: `--graph` only draws the attribution `history`
+already emits, as Mermaid. **A missing second edge does not mean the content never moved** —
+the boundaries are in references/fact-producers.md.
+
 ---
 
 ## The two deterministic measurements this skill ships
@@ -117,7 +137,8 @@ reliably — are shipped by this skill as a zero-dependency CLI:
 | `coverage` | Was this symbol **ever actually invoked** by a test run? | when the report claims "tested / not tested" (Stage B / C) |
 
 ```powershell
-# the only required argument is --base (pre-change revision / PR fork point):
+# --base may be omitted: then the fork point is inferred as merge-base(HEAD, origin/main) and
+# declared as range-inferred in the report. When given, it is used exactly as given:
 node <euthyna repo>/bin/euthyna.js audit --base <pre-change revision> --repo <audited repo>
 
 # history / coverage run alone when needed:

package/.agents/skills/euthyna-en/references/fact-producers.md

@@ -72,6 +72,11 @@ node <euthyna repo>/bin/euthyna.js history --base <pre-change revision> --no-ori
 ```
 
 `--base` is the **pre-change revision** (the PR's fork point); `--head` defaults to `HEAD`.
+Omitting `--base` infers it as `merge-base(<the audited head>, origin/main)`, marks the range line as inferred
+and adds a `range-inferred` entry to the criteria not evaluated. An inferred range reaches **the
+fork point only** — nothing earlier; when neither ref resolves the run stops with a usage error
+instead of guessing `HEAD~1`. This is what lets a slash command arrive with no arguments, so
+**the first thing to do with `range-inferred` is check the fork point**, not accept it.
 When the fork point is uncertain, use the result of `git merge-base <target branch> HEAD`.
 
 ### Attribution semantics (two inherent approximations; established ≠ exact)
@@ -84,7 +89,7 @@ When the fork point is uncertain, use the result of `git merge-base <target bran
 ### What the output looks like (real capture)
 
 ```
-euthyna euthyna-history — attribution and security classification of deleted code
+euthyna-history — attribution and security classification of deleted code
 Target: D:/axe-core/axe-core
 Range: 8390a5a9…..397f5fce…
 
@@ -212,7 +217,7 @@ node <euthyna repo>/bin/euthyna.js coverage `
 ### What the output looks like (real capture; one query hitting both result kinds)
 
 ```
-euthyna euthyna-coverage — symbol invocation counts (can only falsify)
+euthyna-coverage — symbol invocation counts (can only falsify)
 
 Established (1)
   • Symbol cleanup was never invoked in this test run (invocation count 0) — any behavior depending on it was never exercised
@@ -307,6 +312,8 @@ that a conclusion without evidence is not handed over wearing the face of "estab
 - `history`'s classifier is **biased wide**: missing a security commit is more dangerous than over-reporting, so it would rather report `fix` too. The classification is a **lead** — read the commit message yourself.
 - `history`'s attribution **traces the "original introducer" by default** (`git log -S`, probe-capped, only lines ≥ 12 characters); to fall back to blame's "last modified" semantics use `--no-origins` (faster; the output states this). Both approximations are documented in this file's "Attribution semantics" section.
 - `history` only covers **deleted lines**. It does not handle newly added code (except with `--pickaxe`).
+- `--graph` only **draws** the attributions above (Mermaid source, not an image): the range → the last modifier → the commit that first introduced the content. It measures nothing new and draws no severity — a graph carries measured states and line counts, and that is the contract too, not an omission.
+- **The absence of the second edge does not mean the content never moved.** A traced origin is dropped two ways: a generic short line (`}`, `return x;`) or `--no-origins` is written as the dotted `history-origins` edge, while an origin commit the classifier does not read as security-relevant is dropped **silently** — no edge and no note. Read a missing edge as a neutral fact, not as a clearance.
 - `coverage` **can only falsify**. See above.
 - `coverage` relies on invocation counts and **does not handle dynamic dispatch, reflection, or string-based calls**. Conclusions of count 0 must be discounted when such mechanisms exist.
 - The two halves of `audit` **do not read the same thing**: `history` takes the commits named by `--base`/`--head`, while `deps` takes the manifest **currently checked out at the root of the repository** `--repo` points into (manifests are located from the root only). So the criterion is **content**: when the manifest measured differs from the one at `--head`, or does not exist in that commit at all (a gitignored lockfile is exactly that), *Criteria not evaluated* gains an entry naming the file and `--head`. The `code` (`manifest-not-head` / `manifest-unverified`) appears only on the `--json` channel. **Seeing one means checking out an end of the range and re-running** — the declaration keeps the trap from being silent; it does not measure the fact for you.

package/.claude/commands/euthyna.md

@@ -1,6 +1,6 @@
 ---
 description: 代码安全审计：按 euthyna 纪律审一段代码、一次变更或一条漏洞结论，产出带证据的报告
-argument-hint: "<路径 或 diff 范围>"
+argument-hint: "<模式词 或 路径 / diff 范围>"
 allowed-tools: Read, Grep, Glob, Bash, Task
 ---
 
@@ -11,7 +11,7 @@ allowed-tools: Read, Grep, Glob, Bash, Task
 按 euthyna 技能执行一次完整审计：
 
 1. **先加载纪律**：找到 euthyna 技能目录（`~/.claude/skills/euthyna/`、项目 `.claude/skills/euthyna/` 或 `.agents/skills/euthyna/`），读 `SKILL.md`，需要时再读 `references/`。找不到就明说「技能缺失」，不要凭印象执行。
-2. **按入口决策树走**：单条漏洞结论 → 阶段 C；一次变更 → 阶段 B；依赖面 → 阶段 A；整体审计 → 阶段 B 为主。
+2. **按入口决策树走**：单条漏洞结论 → 阶段 C；一次变更 → 阶段 B；依赖面 → 阶段 A；整体审计 → 阶段 B 为主。**模式词优先于下面全部步骤**：参数命中 `SKILL.md`「模式词（斜杠命令）」表里的模式时，只执行该模式映射的那一条命令并按其结果收口——`help` 只打印那张表，不跑任何命令、不做审计、不写报告；未命中模式词时，才走下面的通用审计步骤，其余文字按审计目标处理。
 3. **先测量再读码**：diff 有删除行先跑 `history`；谈测试覆盖先跑 `coverage`；依赖声明先跑 `deps`（操作手册在 `references/fact-producers.md`）。
 4. **每条结论过六道门禁**：证据到 `文件:行号`、可复现命令、影响说明；拿不出证据的降级为「观察」。
 5. **三态裁定**：`BUG #N TRUE POSITIVE / FALSE POSITIVE / INCONCLUSIVE`。

package/.cursor/commands/euthyna.md

@@ -5,7 +5,7 @@
 按 euthyna 技能执行一次完整审计：
 
 1. **先加载纪律**：找到 euthyna 技能目录（`~/.cursor/skills/euthyna/`、项目 `.cursor/skills/euthyna/`，或 npm 全局包内的 `.agents/skills/euthyna/`），读 `SKILL.md`，需要时再读 `references/`。找不到就明说「技能缺失」，不要凭印象执行。
-2. **按入口决策树走**：单条漏洞结论 → 阶段 C；一次变更 → 阶段 B；依赖面 → 阶段 A；整体审计 → 阶段 B 为主。
+2. **按入口决策树走**：单条漏洞结论 → 阶段 C；一次变更 → 阶段 B；依赖面 → 阶段 A；整体审计 → 阶段 B 为主。**模式词优先于下面全部步骤**：参数命中 `SKILL.md`「模式词（斜杠命令）」表里的模式时，只执行该模式映射的那一条命令并按其结果收口——`help` 只打印那张表，不跑任何命令、不做审计、不写报告；未命中模式词时，才走下面的通用审计步骤，其余文字按审计目标处理。
 3. **先测量再读码**：第一条命令跑 `euthyna audit --base <分叉点> --repo <被审计仓库>`（history + deps 一次跑完）；谈测试覆盖再跑 `coverage`（操作手册在 `references/fact-producers.md`）。
 4. **每条结论过六道门禁**：证据到 `文件:行号`、可复现命令、影响说明；拿不出证据的降级为「观察」。
 5. **三态裁定**：`BUG #N TRUE POSITIVE / FALSE POSITIVE / INCONCLUSIVE`。

package/.github/prompts/euthyna.prompt.md

@@ -7,7 +7,7 @@ description: 代码安全审计：按 euthyna 纪律审一段代码、一次变
 按 euthyna 技能执行一次完整审计：
 
 1. **先加载纪律**：找到 euthyna 技能目录（项目 `.github/skills/euthyna/` 或 `.agents/skills/euthyna/`，个人 `~/.copilot/skills/euthyna/`），读 `SKILL.md`，需要时再读 `references/`。找不到就明说「技能缺失」，不要凭印象执行。
-2. **按入口决策树走**：单条漏洞结论 → 阶段 C；一次变更 → 阶段 B；依赖面 → 阶段 A；整体审计 → 阶段 B 为主。
+2. **按入口决策树走**：单条漏洞结论 → 阶段 C；一次变更 → 阶段 B；依赖面 → 阶段 A；整体审计 → 阶段 B 为主。**模式词优先于下面全部步骤**：参数命中 `SKILL.md`「模式词（斜杠命令）」表里的模式时，只执行该模式映射的那一条命令并按其结果收口——`help` 只打印那张表，不跑任何命令、不做审计、不写报告；未命中模式词时，才走下面的通用审计步骤，其余文字按审计目标处理。
 3. **先测量再读码**：第一条命令跑 `euthyna audit --base <分叉点> --repo <被审计仓库>`（history + deps 一次跑完）；谈测试覆盖再跑 `coverage`（操作手册在 `references/fact-producers.md`）。
 4. **每条结论过六道门禁**：证据到 `文件:行号`、可复现命令、影响说明；拿不出证据的降级为「观察」。复现命令执行前须向用户报备（见技能「执行纪律」节）。
 5. **三态裁定**：`BUG #N TRUE POSITIVE / FALSE POSITIVE / INCONCLUSIVE`。

package/.opencode/commands/euthyna.md

@@ -1,8 +1,10 @@
 ---
 description: Run the euthyna code security audit CLI
 ---
-Run the euthyna CLI with these arguments and report the measured result:
+If the arguments match a mode word in the euthyna skill’s "Modes (slash commands)" table,
+translate them per that table and run the mapped command; the table is maintained in the
+skill, not here. Otherwise run the CLI with the arguments as given:
 
     euthyna $ARGUMENTS
 
-If `euthyna` is not installed, use `npx -y euthyna $ARGUMENTS` instead. Quote the command's output verbatim, exit code included — never estimate or re-derive numbers. If the euthyna skill is installed (`.agents/skills/euthyna/` or `~/.agents/skills/euthyna/`), read its SKILL.md and interpret the output under the six-gate adjudication format; claims without evidence are downgraded to observations.
+If `euthyna` is not installed, run the **same mapped arguments** through `npx -y euthyna …` — a mode word resolves through the table first, so the fallback never executes `euthyna <mode>` literally, and `help` still runs nothing. Quote the command's output verbatim, exit code included — never estimate or re-derive numbers. If the euthyna skill is installed (`.agents/skills/euthyna/` or `~/.agents/skills/euthyna/`), read its SKILL.md and interpret the output under the six-gate adjudication format; claims without evidence are downgraded to observations.

package/README.md

@@ -180,6 +180,7 @@ replying in chat.
 ```sh
 npm install -g euthyna
 euthyna audit --repo <path> --base main --head HEAD            # history + deps in one run
+euthyna audit --graph                                          # the same attribution, drawn (see below)
 euthyna coverage --coverage coverage/coverage-final.json --symbol <name>
 euthyna deps --repo <path> --all                               # or --dep <name> for a single dep
 euthyna gate <adjudication-report.md> --verify --cwd <repo>    # mechanically check the six gates
@@ -212,6 +213,15 @@ removed and are now being added back. Origin tracing is on by default (deleted l
 are attributed to the commit that first introduced their content); `--no-origins`
 falls back to blame's last-modifier attribution, which is faster.
 
+`--graph` on `audit` or `history` draws what `history` already computed — the range, the commit
+that last modified each deleted line, and the commit that first introduced its content — as
+Mermaid source, renderable straight into a GitHub comment. It measures nothing new and never
+colours a node by risk; a missing second edge is a neutral fact, not a clearance. `--base` may
+be left out entirely: the fork point is then inferred as `merge-base(<the audited head>, origin/main)` and
+said three times over — on the range line, among the criteria not evaluated (`range-inferred`),
+and as a `code` on the `--json` channel — because an inferred range reaches the fork point only,
+and a quietly smaller history is the one thing this output must not be able to imply.
+
 ### Exit codes are part of the contract
 
 Surveying eight measurement plugins in this ecosystem found **none of them publishes a

package/__init__.py

@@ -2,7 +2,7 @@
 
 The CLI (``bin/euthyna.js``, installed by ``npm install -g euthyna``) produces
 the deterministic facts; this plugin registers ``/euthyna`` so a user can invoke
-the four CLI subcommands from inside a Hermes session without leaving chat. The
+the CLI's subcommands from inside a Hermes session without leaving chat. The
 handler shells out to the real CLI and returns its output verbatim — it does not
 reimplement any measurement, and it injects nothing into the conversation.
 
@@ -15,19 +15,27 @@ CLI prints comes back as the command result.
 import shutil
 import subprocess
 
-# Ponytail: one flat dict, not a command framework — there are exactly four
-# subcommands and the CLI already owns usage/exit codes.
+# The subcommands /euthyna reaches. This is the single source the guard in
+# test/hermes-plugin.test.js compares against the CLI's own dispatch, so a new
+# command there is red here until it is wired — which is how `audit` (the
+# entry point since 0.4.0) went seven releases unnoticed behind a hand-written
+# list of four.
+_FORWARDS = ("audit", "coverage", "deps", "gate", "help", "history")
+
 _USAGE = """euthyna slash command — usage:
 
+  /euthyna audit <path> [<path>...]            history + dependency surface in one run
   /euthyna history <path> [<path> <rev>...]   deleted-code provenance & security classification
   /euthyna coverage <path>                    symbol invocation counts from a coverage run
   /euthyna deps <path>                        dependency pinned versions from lockfiles
   /euthyna gate <report> [--verify]           validate an audit report against the six gates
+  /euthyna help                               the CLI's own usage, with every flag
 
 Args after the subcommand are passed to the CLI unchanged. Requires the CLI:
 npm install -g euthyna (Node >= 20)."""
 
 
+
 def _find_cli():
     """Return the absolute path of the euthyna CLI, or None if not installed."""
     for name in ("euthyna", "euthyna.cmd", "euthyna.exe"):
@@ -40,10 +48,13 @@ def _find_cli():
 def _run(raw_args: str):
     """Handle /euthyna: forward <subcommand> <args...> to the CLI, return its output."""
     argv = raw_args.split()
-    if not argv or argv[0] in ("help", "-h", "--help"):
+    # `-h`/`--help` print this command's own quick usage; bare `help` is forwarded
+    # so the flag list has exactly one owner — the CLI's help, which the skill and
+    # the docs both quote.
+    if not argv or argv[0] in ("-h", "--help"):
         return _USAGE
     sub, rest = argv[0], argv[1:]
-    if sub not in ("history", "coverage", "deps", "gate"):
+    if sub not in _FORWARDS:
         return f"unknown subcommand: {sub}\n\n{_USAGE}"
 
     cli = _find_cli()
@@ -73,8 +84,8 @@ def register(ctx):
     ctx.register_command(
         "euthyna",
         handler=_run,
-        description="euthyna security audit: run history/coverage/deps/gate fact producers",
-        args_hint="<history|coverage|deps|gate> <args…>",
+        description="euthyna security audit: drive the fact-producing CLI (audit is the single entry point)",
+        args_hint="<audit|history|coverage|deps|gate|help> <args…>",
     )
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "euthyna",
-  "version": "0.8.0",
-  "description": "Deterministic fact producers for security auditing: which deleted code came from a security fix, and which changed symbols no test ever executed.",
+  "version": "0.9.1",
+  "description": "Audit framework for AI coding agents: produces the deterministic facts a model cannot compute — deleted-code provenance, symbol invocations, dependency pins — and adjudicates every claim against six gates, downgrading what cannot produce evidence to an observation. Not a scanner.",
   "type": "module",
   "main": "./plugin/index.js",
   "bin": {

package/plugin.yaml

@@ -1,6 +1,6 @@
 name: euthyna
-version: 0.8.0
-description: euthyna audit discipline — slash commands that drive the euthyna fact-producing CLI (history / coverage / deps / gate)
+version: 0.9.1
+description: euthyna audit discipline — the /euthyna slash command driving the euthyna CLI, whose single entry point is `euthyna audit`
 license: Apache-2.0
 homepage: https://github.com/slow-stack/euthyna
 tags:

package/src/cli.js

@@ -21,7 +21,8 @@ import { collectCoverageFacts } from './facts/coverage.js';
 import { collectDependencyFacts, listDependencies, detectManifest, manifestTypeForFile } from './facts/deps.js';
 import { parseGateReport, validateFindings, verifyFinding, renderGateReport } from './gate.js';
 import { makeReport, renderReport, safeTextLines, KIND } from './contract.js';
-import { repoToplevel, revParse, git } from './git.js';
+import { provenanceGraph } from './graph.js';
+import { repoToplevel, revParse, mergeBase, git } from './git.js';
 import { resolveLang, T, isLang, DEFAULT_LANG } from './lang.js';
 
 export const EXIT = Object.freeze({
@@ -71,8 +72,8 @@ euthyna —— 给 AI 编码 agent 用的确定性事实产出器
 它不是扫描器。它只回答两个模型算不准的问题，并把答案写成带证据的事实。
 
 用法:
-  euthyna audit    --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json]
-  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json]
+  euthyna audit    [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
+  euthyna history  [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
   euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--source <dir>] [--json]
   euthyna deps     [--repo <dir>] [--lockfile <file>] (--dep <name> | --all) [--json]
   euthyna gate     <报告文件> [--verify] [--cwd <dir>] [--json]
@@ -83,11 +84,17 @@ euthyna —— 给 AI 编码 agent 用的确定性事实产出器
   audit      一次跑完变更面审计：history + deps（枚举 lockfile 全部依赖），合并报告
              这是技能文档默认推荐入口；coverage 因需要覆盖率文件和符号名不在其中
   history    本次变更删掉了哪些代码、它们分别由哪个提交引入、该提交是不是安全修复
-             --base        必填，比较的基线版本（如 main、HEAD~5、某个 commit）
+             --base        可选：省略时按 merge-base(HEAD, origin/main) 推断分叉点。
+                           推断会写在「范围」那一行，并在「未评估的判据」里加一条 range-inferred：
+                           推断出的范围只到分叉点，不是被审历史的全貌。两个引用都解析不出来时报错，
+                           不退回去猜 HEAD~1
              --head        可选，默认 HEAD
              --pickaxe     额外检查「曾被移除又加回来」的新增行（有探针上限）
              --no-origins  关闭来源追溯；默认用 git log -S 把删除行归属到「最初引入」
                            该内容的提交（有探针上限，比纯 blame 慢）
+             --graph     输出 Mermaid 来源谱系图：范围 → 最后修改这些行的提交 → 最初引入
+                           其内容的提交（第二条边来自 -S 追溯，--no-origins 时没有）。
+                           图只画测到的状态与行数，不画严重性；与 --json 互斥，只适用于 history 与 audit
   coverage   某个符号在测试运行中到底有没有被调用过
              --coverage  覆盖率数据文件，按形状自动识别 c8 / istanbul、
                          coverage.py JSON、Go -coverprofile 文本、lcov tracefile
@@ -124,8 +131,8 @@ It is not a scanner. It answers only the two questions a model cannot compute
 reliably, and writes the answers as facts with evidence.
 
 Usage:
-  euthyna audit    --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json]
-  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json]
+  euthyna audit    [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
+  euthyna history  [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
   euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--source <dir>] [--json]
   euthyna deps     [--repo <dir>] [--lockfile <file>] (--dep <name> | --all) [--json]
   euthyna gate     <report file> [--verify] [--cwd <dir>] [--json]
@@ -140,12 +147,21 @@ Commands:
              and symbol names only the adjudicator knows)
   history    which lines did this change delete, which commit introduced them,
              and was that commit a security fix?
-             --base        required, the baseline revision to compare against
+             --base        optional: omitted means the fork point is inferred as
+                           merge-base(HEAD, origin/main). The inference is stated on the range
+                           line and declared as range-inferred among the criteria not evaluated —
+                           an inferred range reaches the fork point, not the whole history. When
+                           neither ref resolves the run stops rather than guessing HEAD~1
              --head        optional, defaults to HEAD
              --pickaxe     also check added lines that were once removed and now return (probe-capped)
              --no-origins  disable origin tracing; by default git log -S attributes deleted
                            lines to the commit that FIRST introduced their content
                            (probe-capped, slower than plain blame)
+             --graph     print a Mermaid provenance graph: the range → the commit that last
+                           modified the deleted lines → the commit that first introduced their
+                           content (the second edge comes from -S tracing; --no-origins has
+                           none). It draws measured states and line counts, never severity;
+                           mutually exclusive with --json, history and audit only
   coverage   was this symbol ever actually invoked by a test run?
              --coverage  the coverage data file; identified by shape as c8 / istanbul,
                          coverage.py JSON, a Go -coverprofile, or an lcov tracefile
@@ -254,18 +270,6 @@ async function runHistory(flags, lang) {
     };
   }
 
-  if (!flags.base) {
-    return { exit: EXIT.USAGE, error: t('history 需要 --base <rev>', 'history requires --base <rev>') };
-  }
-
-  const base = await revParse(toplevel, String(flags.base));
-  if (!base) {
-    return {
-      exit: EXIT.USAGE,
-      error: t(`无法解析 --base "${flags.base}" 为一个提交`, `cannot resolve --base "${flags.base}" to a commit`)
-    };
-  }
-
   const head = await revParse(toplevel, String(flags.head ?? 'HEAD'));
   if (!head) {
     return {
@@ -274,6 +278,12 @@ async function runHistory(flags, lang) {
     };
   }
 
+  const range = await resolveRangeBase({ flags, cwd: toplevel, head, t });
+  if (range.error) {
+    return { exit: EXIT.USAGE, error: range.error };
+  }
+  const base = range.base;
+
   // Origin tracing is the default (see runAudit); --no-origins opts out.
   const origins = flags['no-origins'] !== true;
 
@@ -286,9 +296,13 @@ async function runHistory(flags, lang) {
     lang
   });
 
+  if (range.ref) {
+    notEvaluated.push(rangeInferenceDeclaration({ ref: range.ref, head }, t));
+  }
+
   const report = makeReport({
     producer: producerFor(HISTORY_PRODUCER, lang),
-    subject: { repo: toplevel, base, head },
+    subject: { repo: toplevel, base, head, ...(range.ref ? { rangeSource: range.ref } : {}) },
     facts,
     evaluated,
     notEvaluated
@@ -412,6 +426,56 @@ async function runDeps(flags, lang) {
  * symbol names only the adjudicator knows, so there is nothing honest to
  * auto-measure there.
  */
+/**
+ * Declare the range the run inferred, in the shape every other declaration uses:
+ * a `notEvaluated` entry with a `code`, so the JSON channel carries it and a
+ * reader of the terminal output meets it in the caveat list.
+ *
+ * Pure, so the wording is testable in both languages without building a repository.
+ */
+export function rangeInferenceDeclaration({ ref, head }, t) {
+  const short = (sha) => (sha ?? '').slice(0, 10);
+  return {
+    kind: KIND.HISTORY,
+    code: 'range-inferred',
+    reason: t(
+      `未给 --base，比较范围按 merge-base(${short(head)}, ${ref}) 推断——这不是被审历史的全貌，换范围请显式传 --base <rev>`,
+      `no --base given: the range was inferred as merge-base(${short(head)}, ${ref}). That is not the whole history under review — pass --base <rev> to audit another range`
+    )
+  };
+}
+
+/**
+ * Resolve `--base`, or infer the fork point when the caller gave none.
+ *
+ * The inference is where an argument-free run could quietly narrow what is
+ * audited — a smaller range deletes edges and reads as cleaner — so the rule used
+ * comes back with the value and the caller must declare it. It forks from the
+ * resolved `--head`, not from whatever happens to be checked out: asking about
+ * another commit and getting this commit's ancestor would report a range nobody
+ * requested. There is no fallback to HEAD~1: with no remote-tracking branch to
+ * fork from, this says so and the run does not happen.
+ */
+export async function resolveRangeBase({ flags, cwd, head, t }) {
+  if (flags.base !== undefined) {
+    const base = await revParse(cwd, String(flags.base));
+    if (!base) {
+      return { error: t(`无法解析 --base "${flags.base}" 为一个提交`, `cannot resolve --base "${flags.base}" to a commit`) };
+    }
+    return { base };
+  }
+  for (const ref of ['origin/main', 'origin/HEAD']) {
+    const base = await mergeBase(cwd, head, ref);
+    if (base) return { base, ref };
+  }
+  return {
+    error: t(
+      '未给 --base，且 origin/main 与 origin/HEAD 都无法解析出分叉点——请显式传 --base <rev>',
+      'no --base given, and neither origin/main nor origin/HEAD resolves to a fork point — pass --base <rev>'
+    )
+  };
+}
+
 /**
  * Decide whether the manifest `audit` measured is the manifest --head holds.
  *
@@ -460,10 +524,6 @@ async function runAudit(flags, lang) {
   const t = T(lang);
   const cwd = path.resolve(flags.repo ? String(flags.repo) : process.cwd());
 
-  if (!flags.base) {
-    return { exit: EXIT.USAGE, error: t('audit 需要 --base <rev>', 'audit requires --base <rev>') };
-  }
-
   // --- history half (mirrors runHistory's repo/base/head resolution) ---
   const toplevel = await repoToplevel(cwd);
   if (!toplevel) {
@@ -486,14 +546,6 @@ async function runAudit(flags, lang) {
     };
   }
 
-  const base = await revParse(toplevel, String(flags.base));
-  if (!base) {
-    return {
-      exit: EXIT.USAGE,
-      error: t(`无法解析 --base "${flags.base}" 为一个提交`, `cannot resolve --base "${flags.base}" to a commit`)
-    };
-  }
-
   const head = await revParse(toplevel, String(flags.head ?? 'HEAD'));
   if (!head) {
     return {
@@ -502,6 +554,12 @@ async function runAudit(flags, lang) {
     };
   }
 
+  const range = await resolveRangeBase({ flags, cwd: toplevel, head, t });
+  if (range.error) {
+    return { exit: EXIT.USAGE, error: range.error };
+  }
+  const base = range.base;
+
   const origins = flags['no-origins'] !== true;
   const history = await collectHistoryFacts({
     cwd: toplevel,
@@ -558,10 +616,13 @@ async function runAudit(flags, lang) {
   const facts = [...history.facts, ...depFacts];
   const evaluated = [...history.evaluated, ...depEvaluated];
   const notEvaluated = [...history.notEvaluated, ...depNotEvaluated];
+  if (range.ref) {
+    notEvaluated.push(rangeInferenceDeclaration({ ref: range.ref, head }, t));
+  }
 
   const report = makeReport({
     producer: producerFor(AUDIT_PRODUCER, lang),
-    subject: { repo: toplevel, base, head },
+    subject: { repo: toplevel, base, head, ...(range.ref ? { rangeSource: range.ref } : {}) },
     facts,
     evaluated,
     notEvaluated
@@ -729,11 +790,31 @@ export async function main(argv = process.argv.slice(2)) {
   const lang = resolveLang({ flag: flagLang });
   const t = T(lang);
 
+  // `--graph` is a render mode, not an extra channel: a graph with a JSON
+  // document glued to it on one stdout makes a CI step that parses either one
+  // fail without saying which.
+  if (flags.graph && flags.json) {
+    process.stderr.write(
+      safeTextLines(t('--graph 与 --json 互斥，一次只选一种输出', '--graph and --json are mutually exclusive; choose one output') + '\n')
+    );
+    return EXIT.USAGE;
+  }
+
   if (!command || command === 'help' || flags.help) {
     process.stdout.write(helpText(lang));
     return EXIT.CLEAN;
   }
 
+  // Only `history` and `audit` produce deleted-line attribution. Drawing the
+  // provenance graph for another command prints a range node with no edges, which
+  // reads as "no provenance found" — the one thing this must not imply.
+  if (flags.graph && command !== 'history' && command !== 'audit') {
+    process.stderr.write(
+      safeTextLines(t('--graph 只适用于 history 与 audit', '--graph applies to history and audit only') + '\n')
+    );
+    return EXIT.USAGE;
+  }
+
   let result;
   if (command === 'history') {
     result = await runHistory(flags, lang);
@@ -767,6 +848,10 @@ export async function main(argv = process.argv.slice(2)) {
 
   if (flags.json) {
     process.stdout.write(`${JSON.stringify(result.report, null, 2)}\n`);
+  } else if (flags.graph && result.report) {
+    // The graph is terminal output like every other render: safeTextLines keeps
+    // its line structure and neutralises control bytes a repo path could carry.
+    process.stdout.write(safeTextLines(`${provenanceGraph(result.report)}\n`));
   } else if (result.report) {
     renderReport(result.report, { lang });
   }

package/src/contract.js

@@ -203,10 +203,18 @@ export function renderReport(report, { write: rawWrite = console.log, lang = DEF
   const unknown = facts.filter(f => f.status === STATUS.UNKNOWN);
 
   write('');
-  write(`euthyna ${producer.name} — ${producer.purpose || ''}`.trim());
+  // The producer name is `euthyna-history`, `euthyna-audit`, …: it already names
+  // the tool, so the header prints it as the contract emits it — the same string
+  // the `--json` `producer` field carries.
+  write(`${producer.name} — ${producer.purpose || ''}`.trim());
   write(`${t('目标: ', 'Target: ')}${subject.repo ?? subject.coverageFile ?? t('(未指定)', '(unspecified)')}`);
   if (subject.base || subject.head) {
-    write(`${t('范围: ', 'Range: ')}${subject.base ?? '?'}..${subject.head ?? 'HEAD'}`);
+    write(
+      `${t('范围: ', 'Range: ')}${subject.base ?? '?'}..${subject.head ?? 'HEAD'}` +
+        // An inferred range is a decision the tool made on the reader's behalf, so
+        // it is said on the line that states the range — not only in the caveat list.
+        (subject.rangeSource ? t(`（推断：与 ${subject.rangeSource} 的分叉点）`, ` (inferred: the fork point from ${subject.rangeSource})`) : '')
+    );
   }
   write('');
 

package/src/git.js

@@ -81,6 +81,22 @@ export async function revParse(cwd, rev) {
   return out.trim() || null;
 }
 
+/**
+ * The fork point between two revisions, or null when git cannot name one.
+ *
+ * `from` is passed in rather than assumed to be the checked-out HEAD: a run that
+ * was asked about another commit must fork from *that* commit, or the range it
+ * reports was never the one requested.
+ */
+export async function mergeBase(cwd, from, rev) {
+  const out = await git(['merge-base', from, rev], { cwd, allowFailure: true });
+  const sha = out.trim();
+  // git prints the hash alone on success; anything else (an error text that got
+  // past allowFailure, an empty result) is not a fork point. A repository picks
+  // its own object format, so both the 40-char and the 64-char id are valid.
+  return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha) ? sha : null;
+}
+
 /**
  * One-line summaries for a set of commits, as a Map of hash -> {subject, author, date}.
  * Uses a single `git log` invocation so the cost does not scale per commit.

package/src/graph.js

@@ -0,0 +1,73 @@
+import { KIND, safeText } from './contract.js';
+
+/**
+ * A Mermaid view over the provenance facts `euthyna history` already emits.
+ *
+ * It measures nothing. A commit subject is whatever an author wrote, and it
+ * lands inside a `"..."` label, so every label goes through the same control-byte
+ * escape the terminal boundary uses before it reaches the graph source.
+ *
+ * Line counts live on the edges: one commit can be attributed twice (the last
+ * modifier of some lines, the origin of others), and a Mermaid node keeps only
+ * the last label written for an id — a count in the node label would silently
+ * delete the other one.
+ */
+export function provenanceGraph(report) {
+  const { subject, facts } = report;
+  const short = (hash) => (hash ?? '').slice(0, 8);
+  // The id is the full hash: two commits that share a prefix are two commits,
+  // and a merged node would say otherwise without saying anything.
+  const id = (hash) => `C_${hash ?? ''}`;
+  // `&` first, so the entities added next are not doubled into nothing; then `#`,
+  // because Mermaid reads `#123;` and `#name;` inside a label as an entity.
+  const escapeLabel = (text) =>
+    text.replace(/&/g, '&amp;').replace(/#/g, '#35;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+  // `detail.commitSubject` belongs to `evidence.commit`, which is the origin
+  // commit on a pickaxe fact and the owning commit on a blame fact. Only
+  // deleted-line attribution counts: `audit` merges dependency facts in here too.
+  const subjects = new Map();
+  for (const fact of facts) {
+    if (fact.kind === KIND.HISTORY && fact.detail?.commitSubject) subjects.set(fact.evidence?.commit, fact.detail.commitSubject);
+  }
+
+  const declared = new Set(['R']);
+  const node = (hash, byFile) => {
+    const key = id(hash);
+    if (declared.has(key)) return key;
+    declared.add(key);
+    const text = subjects.get(hash) ?? '';
+    const rest = byFile.length > 1 ? ` +${byFile.length - 1}` : '';
+    const where = byFile.length ? ` ${byFile[0].file}${rest}` : '';
+    // One pass over the whole label: the path is as much the repository's own
+    // text as the commit subject is, and it may contain `"` or a control byte.
+    return `${key}["${escapeLabel(safeText(`${short(hash)}${where}${text ? ` ${text}` : ''}`))}"]`;
+  };
+
+  const range = `${subject.base ?? '?'}..${subject.head ?? 'HEAD'}`;
+  const out = ['graph TD', `  R["${escapeLabel(safeText(range))}"]`];
+
+  for (const fact of facts) {
+    // A dependency fact has no commit: drawing it would emit a node with an empty
+    // id that reads as "a commit with no lines".
+    if (fact.kind !== KIND.HISTORY) continue;
+    const detail = fact.detail ?? {};
+    const origin = detail.originMethod === 'pickaxe' ? detail.originCommit : null;
+    // The deleted lines hang off whoever last touched them inside the audited
+    // range; the origin commit is where the content came from.
+    const blamed = origin ? detail.blameCommit : fact.evidence?.commit;
+    const byFile = detail.byFile ?? [];
+    const count = detail.blamedLines ?? 0;
+
+    out.push(`  R -->|${count}| ${node(blamed, byFile)}`);
+    if (origin) out.push(`  ${id(blamed)} -->|${count}| ${node(origin, byFile)}`);
+  }
+
+  // Dotted, and named by kind: `nothing here was deleted` and `this could not be
+  // measured` look the same once the facts are gone.
+  for (const [n, item] of (report.coverage?.notEvaluated ?? []).entries()) {
+    out.push(`  R -.-> U_${n}["${escapeLabel(safeText(`${item.kind}: ${item.reason}`))}"]`);
+  }
+
+  return out.join('\n');
+}