euthyna 0.2.0 → 0.3.1

package/.agents/skills/euthyna-en/references/dependency-audit.md

@@ -0,0 +1,116 @@
+# Stage A: dependency audit
+
+> This audits "what you depend on", not "your own code". Answer: **what risk does this newly introduced / upgraded dependency bring?**
+>
+> Prerequisite: the three non-skippable rules in `../SKILL.md`. **This stage never reads a dependency's source.**
+
+---
+
+## A.0 What this stage does and does not do
+
+| Does | Does not |
+|---|---|
+| verify manifest files and lockfiles, resolve exact versions | judge whether the project can install or build (**never installs, never builds, never executes**) |
+| fetch vulnerabilities, staleness, and maintenance status with deterministic tools | license compliance audit |
+| translate tool output into judgments | scan the target's own source for vulnerabilities or secrets (that is Stage B / Stage C) |
+| state clearly which criteria are **not evaluable** | improvise for ecosystems the collector does not support (say "not supported", do not force it) |
+
+**This stage only reads registries, advisories, and repository metadata.**
+
+---
+
+## A.1 Why not build your own measurement tools
+
+This framework **deliberately does not reimplement** dependency scanning. Not out of laziness:
+
+1. Mature tools already cover this; rewriting only introduces new risk, and the measurement logic itself must be deterministic
+2. Vulnerability data sources (OSV and others) are continuously updated; a self-maintained copy is guaranteed to go stale
+3. **This stage's value is in the judgment, not in the measurement**
+
+So this stage's producer is an **orchestration layer**: it calls off-the-shelf tools, normalizes their output into facts, and marks what was not measured.
+
+Available discovery sources (use whichever is installed — **audit the source before installing**):
+
+| Purpose | Candidates |
+|---|---|
+| dependency vulnerabilities (with fixed versions) | any OSV-based scanner |
+| lockfile and manifest parsing | built into the tool, or package-manager commands such as `npm ls` / `pnpm why` |
+| introduction time (which commit added it) | `git log --oneline --follow -- <lockfile>` |
+
+> ⚠️ **Load detection and fallback**: the process must still run to completion when **none** of these tools are installed.
+> On fallback, mark the criterion "not evaluated" truthfully — **do not** fill the gap with CVE data from model memory:
+> that is exactly what this framework forbids.
+
+---
+
+## A.2 Step one: confirm the inputs
+
+**The target directory must have one of** `package.json` / `pyproject.toml` / `requirements*.txt` / `go.mod`.
+If none exists, **say so and stop** — do not improvise an audit for an ecosystem the collector does not parse.
+
+**Exactly resolvable**: `package-lock.json`, `npm-shrinkwrap.json`, `uv.lock`, `go.mod` for Go 1.17+.
+
+**Not resolvable**: `yarn.lock`, `pnpm-lock.yaml`, `poetry.lock`.
+When these are present, **say so**, fall back to the pinned or latest published version, and mark it as an approximation.
+
+**Check the network identity**: the unauthenticated GitHub API allows only 60 requests/hour. The collector issues several requests per dependency;
+unauthenticated, repository-class criteria will be broadly not evaluable — **say so, instead of silently degrading or retrying to death**.
+
+---
+
+## A.3 Three states, not two
+
+Every dependency, every criterion, lands in exactly one of three states:
+
+| State | Meaning |
+|---|---|
+| evaluated · clean | actually checked, and no problem under this criterion |
+| evaluated · flagged | actually checked, and there is a problem |
+| **not evaluable for a stated reason** | could not be checked — **the reason must be written down for this item** |
+
+**A missing measurement is never a clean conclusion.**
+
+When the collector exits non-zero, it is **refusing to report** — **quote its message verbatim; do not retry, do not work around**.
+A run that measured nothing produces "not evaluable", **not** "no issues found".
+
+### Quoting discipline
+
+- "no advisories" only means "none **within the evaluated scope**" — look at the coverage table before citing a clean conclusion
+- **numbers must be quoted verbatim** — no re-deriving, no rounding, no dressing up
+- **finding nothing is not an endorsement**
+
+---
+
+## A.4 What the model can add and the collector cannot
+
+Measurement belongs to the tools; judgment belongs to the model. This is the value the model should add:
+
+| Add | Caveat |
+|---|---|
+| which one **this reader should act on first** | order by risk, not alphabetically |
+| upgrade path | patch or major? a major version means breaking changes |
+| replacement candidates for deprecated dependencies | **verify the candidate actually exists in the registry before naming it**, and mark this as judgment, not measurement |
+| install-script risk | can the flagged install script be avoided with `--ignore-scripts` |
+
+---
+
+## A.5 Report style
+
+This stage's reports are often **pasted into tickets verbatim**, so:
+
+- no person, no abbreviations, no exclamation marks
+- active voice with **the matter as the subject**: write "upgrading to 1.19.0 clears all 25 advisories", not "I recommend upgrading axios"
+- no intensifiers (very / significant / fortunately)
+- **no guesses about motives**
+- tense: audit actions in past tense, dependency state in present tense, consequences in future tense
+- recommendations state only **the action and its cost** — **no naming of responsible parties**
+
+---
+
+## A.6 Handoff to Stage C
+
+Issues reported by the dependency audit usually do **not** need Stage C — their evidence comes from vulnerability databases and is already determinate.
+
+But there is one class of exception: **"is this vulnerability actually reachable in this project"**.
+If the affected function of a dependency vulnerability has no call path here at all, that is an **assertion to be adjudicated**,
+not an established fact. When you meet this, go to Stage C.

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

@@ -0,0 +1,129 @@
+# The fact contract (adjudication-layer consumption guide)
+
+> This is a **consumption guide**, not a design document. It answers: after receiving a fact, what can the adjudication layer infer from it, and what can it not.
+>
+> The full contract is in the repository's `docs/fact-contract.md`.
+
+---
+
+## What a fact looks like
+
+```jsonc
+{
+  "id": "fact-007",
+  "kind": "history",                 // fact kind
+  "statement": "This change deleted 4 lines of code from commit ab877f9d70...",
+  "status": "established",           // established | refuted | unknown
+  "evidence": { "file": "src/a.js", "line": 104, "commit": "ab877f9d70" },
+  "method": "command",
+  "command": "git blame --porcelain -L 104,104 <rev> -- src/a.js",
+  "confidence": "exact",             // exact | approximate
+  "detail": { }                      // kind-specific structured payload
+}
+```
+
+---
+
+## The three consumption rules
+
+### Rule 1: `unknown` is not "clean"
+
+The three states are a hard convention:
+
+| status | What the adjudication layer can do |
+|---|---|
+| `established` | May draw conclusions from it |
+| `refuted` | May draw conclusions from it (in reverse) |
+| **`unknown`** | **Nothing can be inferred**. It is neither support nor opposition — it is "don't know" |
+
+Treating `unknown` as "no problem" is the only usage error in this contract that is fatal.
+
+### Rule 2: `approximate` may not participate in gates
+
+Facts with `confidence: approximate` are **explicitly excluded from gate adjudication**.
+
+This is not conservatism — it comes from practice: some tools synthesize an approximate result when "scope cannot be determined",
+and explicitly mark it as **not participating in blocking even in enforcement mode**. This framework follows the same convention.
+
+Gates only consume `exact`.
+
+### Rule 3: when data is missing, read the coverage table first
+
+The report's `coverage.notEvaluated` lists **what was not measured, and why**.
+
+**Before citing any "clean" conclusion, read this section first.**
+When `notEvaluated` is non-empty, do not read it as "tested, no problem".
+
+---
+
+## What facts do **not** contain (this is design, not an omission)
+
+| Not present | Why |
+|---|---|
+| Scores (score / 0–100) | Scores cannot be recomputed; they would become "using a score as a gate" |
+| Severity levels | Severity is a **judgment**, not a fact |
+| Fix suggestions | Same as above |
+| "may" / "probably" | Weasel words mask gaps |
+
+**Measurement stays measurement; judgment stays judgment.** If a fact carries `severity: high`,
+it means the layer that produced it already made the decision for the adjudication layer — and that decision cannot be recomputed.
+
+---
+
+## How to read each fact kind
+
+### `history` — the origin of deleted code
+
+| Field | How to read it |
+|---|---|
+| `detail.classification` | `security` / `fix` / `none`. **The classifier's two error costs are asymmetric**: missing a security commit is more dangerous than over-reporting, so it is biased wide |
+| `detail.byFile` | **How many lines per file**. `blamedLines` is the total and may span multiple files — do not assume the file in the evidence contains everything |
+| `detail.commitSubject` | The commit message verbatim. **Do not look only at the classification; read the message itself** |
+| `command` | A directly executable reproduction command, with the real line ranges |
+
+**Note**: `history` only says "which commit this line comes from and whether that commit looks like a security fix";
+it does **not** say "deleting it is a vulnerability". The latter is the adjudication layer's business.
+
+### `reintroduction` — removed and added back
+
+A non-`null` `detail.securityOrigin` means: the line's occurrence count was once changed by a commit whose message contains security keywords.
+Combined with "the line does not exist in the base revision", you can infer **it was removed before and has now been added back**.
+
+**This does not equal "this is a regression"** — it equals "someone needs to look here". The adjudication layer decides from this whether to raise priority.
+
+### `test_coverage` — invocation counts
+
+⚠️ **This kind can only falsify, never confirm.**
+
+| Fact | What it lets you infer |
+|---|---|
+| Invocation count = 0 (`status: established`) | ✅ **Really never invoked**. All behavior depending on it was never exercised |
+| Invocation count > 0 (`status: unknown`) | ❌ **Cannot** infer "executed". Entering a function does not equal any specific call site having run |
+
+Reason: the underlying coverage data reports **call sites that never executed as covered** (straight-line code after a thrown exception is the classic case),
+so the "covered" direction is unreliable in itself. **The producer has no "executed" output at all** — this is deliberate.
+
+Corollary: **do not** use "non-zero count" to close a "not tested here" concern. To prove something actually executed,
+only a demonstration that truly reaches that call site can do it.
+
+### `artifact` — artifact evidence
+
+The report file, plus the exit code and case count of the demonstration run. **Gates 1 and 4 rely on it.**
+
+How to read it: the exit code and case count must be **actually captured output**, not expected values.
+A "pass" with 0 cases is not a pass.
+
+---
+
+## Producer exit codes
+
+The accompanying CLI's exit codes are an external contract, usable directly in CI:
+
+| Code | Meaning | How the adjudication layer should react |
+|---|---|---|
+| `0` | Measured, no security-related findings | Continue normally |
+| `10` | Measured, and at least one `security`-classified fact exists | **Raise priority**; do not treat it as a conclusion directly |
+| `1` | Usage error | Fix the command |
+| **`2`** | **Could not measure at all** | **Must not be read as clean**. Either switch measurement methods or mark the relevant criteria as not evaluable |
+
+The difference between `2` and `0` is the essence of why this contract exists: **failing to measure and measuring clean are two different things.**

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

@@ -0,0 +1,258 @@
+# Fact producers: when to run them, how, and how to read the output
+
+> This skill ships two **deterministic measurements**, provided by a zero-dependency Node CLI.
+> They answer questions the model cannot compute accurately — **not** "what vulnerabilities exist".
+>
+> This page is the operations manual: when you must run them, how to write the commands, and which section of the output decides what conclusion you may draw.
+> For what you can and cannot infer from a fact once you have it, see `fact-contract.md`.
+
+---
+
+## 1. First, where the commands live
+
+The CLI is **not in the skill directory** — it is a separate program of this project. In order of availability:
+
+| Situation | How to write it | Notes |
+|---|---|---|
+| Installed | `euthyna history …` | `euthyna` is the command name declared by the package |
+| Project checkout available | `node <euthyna repo>/bin/euthyna.js history …` | the most common form |
+| Neither | — | **mark the criterion as "not evaluable"**; do not substitute a manual estimate |
+
+### ⚠️ A real pitfall: relative paths only work inside the euthyna repository
+
+`node bin/euthyna.js …` only works **when the current directory happens to be the euthyna repository**.
+When auditing, your current directory is the **audited project**, so:
+
+```
+Error: Cannot find module 'D:\axe-core\axe-core\bin\euthyna.js'
+```
+
+`history` has `--repo` — pass the repository path explicitly and it runs from any directory:
+
+```powershell
+node <euthyna repo>/bin/euthyna.js history --base <rev> --repo <audited repo>
+```
+
+- `--repo` refers to the **audited repository**, not the euthyna path
+- `--base` / `--head` both resolve relative to the **audited repository**, independent of the current directory
+- the coverage command has no `--repo` — write the coverage file as an **absolute path**
+
+Both commands were verified: run from `D:\` with `--repo` pointing at another repository, exit codes matched expectations.
+
+---
+
+## 2. `history` — the origin of deleted code
+
+### When you must run it
+
+| Trigger scenario | Corresponding stage |
+|---|---|
+| Reviewing a change (PR / diff / commit) where **code was deleted** | Stage B |
+| The user asks "did this change weaken some protection" | Stage B |
+| You need to determine whether some code was "removed and added back" | Stage B |
+
+**If the diff contains deleted lines, run it first.** This is not optional: a diff that looks "very clean" because a check was deleted
+is exactly what a security regression usually looks like, and a model cannot blame hundreds of deleted lines one by one and then trace back through commit history.
+
+### Commands
+
+```powershell
+# basic: which commits do this change's deleted lines come from, and do those commits look like security fixes
+node <euthyna repo>/bin/euthyna.js history --base <pre-change revision> --repo <audited repo>
+
+# additionally check for "removed and added back" lines (has a probe cap; slower than the basic version)
+node <euthyna repo>/bin/euthyna.js history --base <pre-change revision> --pickaxe --repo <audited repo>
+
+# attribute deleted lines to the commit that "originally introduced" the content (not blame's "last modifier"; has a probe cap)
+node <euthyna repo>/bin/euthyna.js history --base <pre-change revision> --origins --repo <audited repo>
+```
+
+`--base` is the **pre-change revision** (the PR's fork point); `--head` defaults to `HEAD`.
+When the fork point is uncertain, use the result of `git merge-base <target branch> HEAD`.
+
+### Attribution semantics (two inherent approximations; established ≠ exact)
+
+`history`'s attribution and classification each carry a **hard-coded approximation** — know them before reading the output:
+
+1. **Attribution: blame is "last modified", not "originally introduced".** If a security-fix line was later touched by formatting/refactoring (moved, copied), blame attributes the origin to the last commit that touched it. `--origins` uses `git log -S <line content>` to locate the commit that **originally introduced** the content; when the two differ, the fact writes out both commits (`detail.blameCommit` = last modified, `evidence.commit` = originally introduced) and states so. `--origins` only traces lines ≥ 12 characters long (for overly generic lines, `-S` would point at the first commit of the entire history, which is not the origin); when it is not enabled, the output states this under "criteria not evaluated".
+2. **Classification: look at the commit message first, then the commit diff, then the deleted line itself.** When the message is vague ("update utils") but the diff touches a dangerous API, or the deleted line is itself security code (e.g. `if (!authorized) return`), it is marked `security` — the basis is recorded in `detail.classificationBasis` (`message` / `diff` / `deleted-line`). The deliberately wide bias is intentional: missing a security commit is more dangerous than over-reporting.
+
+### What the output looks like (real capture)
+
+```
+euthyna euthyna-history — attribution and security classification of deleted code
+Target: D:/axe-core/axe-core
+Range: 8390a5a9…..397f5fce…
+
+Established (8)
+  • This change deleted 4 lines of code from commit ab877f9d70, spread across 2 files. Commit message: "fix(link-in-text-block): don't match style or script text (#3775)", classification: fix
+       Evidence: lib/checks/color/link-in-text-block-evaluate.js (ab877f9d70)
+       Reproduce: git blame --porcelain -L 104,104 -L 114,114 8390a5a9… -- lib/checks/…
+
+⚠ Criteria not evaluated (missing data is not clean):
+  • reintroduction: --pickaxe not enabled; reintroduced lines were not checked
+
+Evaluated criteria:
+  • history: 105 (euthyna-history)
+```
+
+### How to read it
+
+| What you see | What it means |
+|---|---|
+| `classification: security` under "Established" | **Raise the risk to maximum**, unless you can prove that code is no longer needed |
+| `classification: fix` | Not a security fix, but **read the commit message itself** — the classifier is biased wide; do not rely on the label alone |
+| `spread across N files` | The file in the evidence **does not contain all** deleted lines. Do not assume only that one file is affected |
+| The "⚠ Criteria not evaluated" section at the bottom | When this section is non-empty, you **must not** read this run as "checked, no problem" |
+| `Established (0)` with an empty not-evaluated section | There really are no deleted lines. This is a **completed measurement**, not a failure |
+
+**Do not run `git blame` yourself and read commit messages by eye.** The machine adjudicates the same diff twice with identical results; a human may read it twice with different results.
+
+---
+
+## 3. `coverage` — symbol invocation counts
+
+### When you must run it
+
+| Trigger scenario | Corresponding stage |
+|---|---|
+| The report will say "this function **has test coverage**" | Stage B / C |
+| The report will say "this function **has no test coverage**" | Stage B / C |
+| A conclusion depends on "that path was exercised by tests" | Stage C |
+
+In other words: **run it before writing anything about "tested or not tested"**.
+
+### Commands
+
+```powershell
+node <euthyna repo>/bin/euthyna.js coverage `
+  --coverage <absolute path to coverage file> `
+  --symbol <symbol name> --symbol <symbol name>
+```
+
+`--symbol` is repeatable — query several at once. Add `--file` to restrict to a single file.
+
+**Both coverage formats are read** (auto-detected, no parameters needed):
+
+| Format | Source | Notes |
+|---|---|---|
+| c8 / v8-to-istanbul `coverage-final.json` | JS projects (c8 lands at `coverage/coverage-final.json` by default) | Per-file `fnMap` + `f` (invocation-count array) |
+| coverage.py JSON (format 3) | Python projects (produced by `coverage json`) | Top-level `{meta, files}`; in `functions`, "function name → list of executed lines", **no invocation counts**. Functions never called are still in the list with empty `executed_lines` |
+
+The coverage.py production commands (Python targets):
+
+```powershell
+uv run --with coverage python -m coverage run `
+  --include="*/src/<package>/<file>.py" `
+  -m pytest <test-file> -o addopts="" -p no:randomly
+uv run --with coverage python -m coverage json -o <output path>.json
+```
+
+> Two Python-specific caveats (measured in the crewAI case study):
+> 1. **Disable xdist** (`-o addopts=""`) — coverage does not collect subprocess traces by default, so with `-n auto`
+>    the report is empty. Override the repository's xdist defaults with `-o addopts=""`.
+> 2. Restricting by file path with `--include` is more reliable than `--source` for src layouts (`--source=<package name>` may report
+>    `module-not-imported`).
+
+Where the coverage file comes from: if the project produces one, use it. When the project does not, **either run its tests once with the project's own tooling to produce it, or mark the criterion as "not evaluable"**.
+
+### What the output looks like (real capture; one query hitting both result kinds)
+
+```
+euthyna 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
+       Evidence: …\src\handlers.js:29
+
+Unknown (1)
+  • Symbol checkPermission was invoked 2 time(s), but a non-zero invocation count **cannot** prove any specific call site ran — this fact can only falsify, never confirm
+       Evidence: …\src\authz.js:4
+```
+
+### How to read it (this section is the easiest part of the whole tool to misuse)
+
+| Fact | What it lets you infer |
+|---|---|
+| Count 0, `status: established` | ✅ **Really never invoked**. You may say "this path was never exercised" on that basis |
+| Count > 0, `status: unknown` | ❌ **Nothing can be inferred**. Having entered the function ≠ the specific call site you asked about ran |
+
+The reason is fully explained in `fact-contract.md`: the underlying coverage data reports **call sites that never executed as covered**
+(straight-line code after a thrown exception is the classic case), so the "covered" direction is unreliable in itself.
+**The producer has no "executed" output at all — this is deliberate.**
+
+Corollary: **do not** use "non-zero count" to close a "not tested here" concern. To prove something actually executed,
+only a demonstration that truly reaches that call site can do it (Gate 4 of Stage C).
+
+---
+
+## 4. Exit codes: what to do with each code
+
+| Code | Meaning | What you should do |
+|---|---|---|
+| `0` | Measured, no security-related findings | Continue. **But remember to read the "Criteria not evaluated" section** |
+| `10` | Measured, at least one `security`-classified fact exists | **Raise priority**, then run each one through Stage C. Do not treat it as a conclusion directly |
+| `1` | Usage error | Fix the command (`--base` mistyped, empty symbol name, etc.). This is not a measurement result |
+| **`2`** | **Could not measure at all** | **Must not be read as clean**. Either switch measurement methods or mark the relevant criteria as "not evaluable" |
+
+The difference between `2` and `0` is the essence of why this contract exists: **failing to measure and measuring clean are two different things.**
+
+### Common situations that reach `2`
+
+| Situation | What the output says | Handling |
+|---|---|---|
+| The directory is not inside a git repository | Not evaluated: not in any git repository | Switch to a real repository, or mark not evaluable |
+| The coverage file does not exist | Not evaluated: `ENOENT`, tests not run | Produce coverage, or mark not evaluable |
+| The symbol name is misspelled / does not exist | Symbol not found | Verify the symbol name; if it truly does not exist, state that it is outside the measurement scope |
+
+**None of these count as "clean".** The report must write them into "Criteria not evaluated" with the reason stated.
+
+---
+
+## 5. Where they fit into the workflow
+
+```
+Stage B (change-surface audit)
+  ├─ deleted lines present ────► history            → the result decides whether risk is raised to maximum
+  ├─ regression judgment ──────► history --pickaxe  → the result decides whether to treat it as a "regression"
+  └─ test coverage to discuss ─► coverage           → can only falsify; a non-zero count is not evidence
+
+Stage C (claim verification)
+  └─ conclusion depends on "tested or not" ──► coverage → it constrains the truth of Gate 4 (demonstration)
+```
+
+**Producers give facts, not verdicts.** They say "this line comes from a security-fix commit",
+**not** "deleting it is a vulnerability" — the latter is Stage C's business.
+
+---
+
+## 6. `gate` — programmatic gate validation (not a measurement)
+
+`history` / `coverage` produce facts; `gate` **does not measure** — it checks whether an audit report's self-declaration
+conforms to the 6-gate contract. The report format is in SKILL.md's "adjudication format" section.
+
+```powershell
+node <euthyna repo>/bin/euthyna.js gate <report file>
+node <euthyna repo>/bin/euthyna.js gate <report file> --verify --cwd <audited repo>
+```
+
+| What you see | What it means |
+|---|---|
+| Exit code `0` | Every finding carries the evidence it should: TP has `path:L123` evidence + reproduce command + impact + all six gates passed; FP has a FAIL gate; INCONCLUSIVE has a not-evaluated gate |
+| Exit code `10` | Some finding was **downgraded to "observation"** — missing evidence / missing reproduction / gates contradicting the verdict. Read the downgrade reason; fill the gap or change the conclusion to an observation |
+| Exit code `2` | The report cannot be read, or contains no verifiable findings. **Not clean** |
+| `--verify`'s reproduction-check ✗ | The reproduce command actually ran but did not succeed — "says it reproduces" does not count |
+
+`gate` only validates what the report itself says; it does not audit the target repository. So it cannot replace adjudication — it only guarantees
+that a conclusion without evidence is not handed over wearing the face of "established".
+
+---
+
+## 7. Known limits (do not use beyond them)
+
+- `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 defaults to blame's "last modified" semantics; use `--origins` for "originally introduced" (has a probe cap, and only traces lines ≥ 12 characters). 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`).
+- `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.
+- Neither **produces scores, severity, or fix suggestions**. That is the contract, not an omission.