pwn 0.5.743 → 0.5.745

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8089c1c616fe3d19f70170b55204b0dd762a14faa40432e6acf421bd6d55197d
-  data.tar.gz: 6633cdc11ab8b811913d6b6e30608a79fa85c06c5bde599d4155c9c63d5a3884
+  metadata.gz: f3d60fd604a668b531459517b97dfee6448f9485679bd4c25bfe3ec12090cee9
+  data.tar.gz: 64a4dd65248017933e877c03db222ce61741e60044a03a1c9c9a1297ca7a4fde
 SHA512:
-  metadata.gz: 83c1b09ae27724b7e5df7972f018f11b7bee7f77e38d295c45395bf4c828f6c57e9736306687ae243e1fc05dc4dd63e4b33407d4101b916c2e32a8b241f39958
-  data.tar.gz: 19ad087ec133a1194b2fd60d7348edff887b94940647b5a0e34792fa5084742dcb7a04f213ee17b404e4fffda5fc1b8db4821fd1bc6c047c0867c96a2752d8af
+  metadata.gz: 1792ff5aea6a7c406248ab0fd6647732c490e56450afdf768840f340b4d7b4847a2d2cd996ff1349b3ca1a1bbfc05be40310225345e675937cc16022aaad5ec3
+  data.tar.gz: 7155e5d3cfca02bda195d0b0f926b85d6cd95b306b570d5956484ae237d360b36628a979e2d98a2c5ce3008343c7cecc1d14f12d0a986dbc577923a9f7905930

data/Gemfile

@@ -49,7 +49,7 @@ gem 'jwt', '3.3.0'
 gem 'libusb', '0.8.0'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
-gem 'mcp', '1.5.1'
+gem 'mcp', '1.6.0'
 gem 'meshtastic', '0.0.184'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.26.0'

data/Rakefile

@@ -11,6 +11,10 @@ require 'rdoc/task'
 require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
+task :silence_rspec_filter_banner do
+  ENV['PWN_RAKE_SPEC'] = '1'
+end
+Rake::Task[:spec].enhance([:silence_rspec_filter_banner])
 
 RuboCop::RakeTask.new do |rubocop|
   config_file = '.rubocop.yml'

data/documentation/Agent-Tool-Registry.md

@@ -12,7 +12,7 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 |---|---|---|
 | `http` | `http_proxy_start` · `http_proxy_stop` · `http_proxy_entries` · `http_proxy_rules` · `http_replay` | `PWN::Plugins::MitmProxy`: native HTTP HAR capture/replay; opaque CONNECT tunnels |
 | `terminal` | `shell` · `job_run` · `job_status` · `job_tail` · `job_result` · `job_kill` | Foreground host commands plus `PWN::Plugins::Jobs` durable supervisors |
-| `pwn` | `pwn_eval` · `sbom_scan` · `r2_functions` · `r2_disasm` · `gdb_run_to_crash` · `nmap_scan` · `nuclei_scan` · `browser_goto` · `loot_query` | `TOPLEVEL_BINDING.eval` in the live REPL process, after `ToolGuard`; SBOM engines via `PWN::Plugins::SBOM`; r2pipe JSON via `PWN::Plugins::Radare2`; gdb MI3 crash reports via `PWN::Plugins::GDBMI`; nmap XML ingest/diff via `PWN::Plugins::NmapIt`; nuclei/httpx JSONL findings via `PWN::Plugins::Nuclei`; TransparentBrowser navigation captures screenshot/DOM/HAR via `browser_goto`; engagement loot via `PWN::Plugins::Vault` |
+| `pwn` | `pwn_eval` · `sbom_scan` · `r2_functions` · `r2_disasm` · `gdb_run_to_crash` · `nmap_scan` · `nuclei_scan` · `browser_goto` · `loot_query` | `TOPLEVEL_BINDING.eval` in the live REPL process, after `ToolGuard`; SBOM engines via `PWN::Plugins::SBOM` store CVE leads as recon observations, not findings; r2pipe JSON via `PWN::Plugins::Radare2`; gdb MI3 crash reports via `PWN::Plugins::GDBMI`; nmap XML ingest/diff via `PWN::Plugins::NmapIt`, which skips a known port unless `refresh: true`; nuclei/httpx JSONL via `PWN::Plugins::Nuclei` writes a recon observation (a template match is not a finding) and accepts a `Recon.handoff` record; TransparentBrowser navigation captures screenshot/DOM/HAR via `browser_goto`; engagement loot via `PWN::Plugins::Vault` |
 | `mcp` | `mcp` | `PWN::AI::MCP` session broker → any `PWN::AI::MCP::*` stdio client |
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` · **`memory_lean`** | `PWN::Memory` → `~/.pwn/memory.json` |
 | `skills` | `skills_consolidate` · **`skills_recall`** · `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (**[agentskills.io](https://agentskills.io) spec**; legacy flat `*.md` auto-migrated) |
@@ -20,7 +20,7 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 | `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · **`learning_gc_stores`** · **`learning_purge_noise`** · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`mistakes_lean`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`reward_warm_sentinel`** · **`reward_scrub_preferences`** · **`reward_preference_balance`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** · **`curriculum_offline_judge`** · **`curriculum_preference_balance`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` + `~/.pwn/finetune/` |
 | `reward` | **`reward_generator_mix`** | `PWN::AI::Agent::Reward.generator_mix` → online preference source-mix controller (`preferences.jsonl`) |
 | `curriculum` | **`curriculum_practice_kpi`** | `PWN::AI::Agent::Curriculum.practice_kpi` → `~/.pwn/curriculum_kpi.jsonl` |
-| `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
+| `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json`. ESR is `verified_exploit_tools / vulnerable_tools`. ASR is `successful_attacks / total_attack_attempts`. |
 | `policy` | **`policy_stats`** · **`policy_evaluate`** · **`policy_recommend`** | `PWN::AI::Agent::Policy` → `~/.pwn/policy.json` + `~/.pwn/policy_traj.jsonl` |
 | `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · **`extro_rf_tune`** · **`extro_osint`** · **`extro_serial`** · **`extro_telecomm`** · **`extro_packet`** · **`extro_vision`** · **`extro_voice`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ Serial/Packet/OCR/Voice/BareSIP/TransparentBrowser/GQRX) → `~/.pwn/extrospection.json` |
 | `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |

data/documentation/CLI-Drivers.md

@@ -59,6 +59,16 @@ pwn_setup --migrate --fix        # ~/.pwn state doctor + autofix (PWN::Migrate)
 See [Installation](Installation.md) for the full profile table, the
 `PWN::Setup` API and the `PWN::Migrate` state-file registry.
 
+## Offline policy evaluation with `pwn-ai`
+
+`pwn-ai --policy evaluate --baseline PATH --candidate PATH` prints two frozen
+held-out reports without opening a vault or starting an AI session. The separate
+`--policy promote` and `--policy rollback` actions require an explicit target and
+both `--approve-policy-change` and `--policy-writers-stopped`. They never start
+network tasks or automatically promote on success. See
+[Policy-Benchmark](Policy-Benchmark.md#offline-operator-cli) for runnable local
+commands, receipt preservation, fresh replay gates, and limitations.
+
 ## Typical CI usage
 
 ```yaml

data/documentation/How-PWN-Works.md

@@ -77,7 +77,9 @@ POLICY · EXTROSPECTION · RECENT TURNS) are re-injected into the next system
 prompt.
 Nightly hygiene cron trims `~/.pwn` stores. Curriculum practice, offline
 judge, and weekly LoRA train ship seeded but disabled; turn them on with
-`cron_enable` when you want that loop:
+`cron_enable` when you want that loop.
+
+`Metrics.esr` is `verified_exploit_tools / vulnerable_tools`. `Metrics.asr` is `successful_attacks / total_attack_attempts`. `Learning.rsi_tick` compares ESR with the previous snapshot and writes a lesson when it falls. A file hash, a nuclei template match, or a CVE id does not move ESR. Only a reproduced exploit does.
 
 ![Self-improvement loop](diagrams/pwn-ai-feedback-learning-loop.svg)
 

data/documentation/Installation.md

@@ -187,6 +187,7 @@ What `--migrate` does:
    directory layout) → **deep-merge** any keys the current
    `PWN::Config.env_template` added into your encrypted `~/.pwn/pwn.yaml`
    **without overwriting your values** (re-encrypted with the same key/IV).
+   Schema 5 adds `ai.agent.skill_review` (`recommend` when the key is absent).
 
 Everything is idempotent and dry-run capable. The plain `pwn` launcher also
 prints a one-line drift warning on startup whenever `~/.pwn/.schema`
@@ -268,6 +269,7 @@ The first `pwn` launch creates `~/.pwn/` and an **encrypted**
 - `cwe`
 - `capec`
 - `att&ck`
+- `humanizer`
 
 Source lives in the gem at `etc/default_skills/`. `PWN::Config.install_default_skills`
 walks every `SKILL.md` recursively (idempotent SOP copies; never overwrites an

data/documentation/Policy-Benchmark.md

@@ -220,6 +220,82 @@ fields except `elapsed_seconds`. They contain no wall-clock timestamps, random
 IDs or temporary paths. The original training report still contains the timing
 and metadata variability described above.
 
+## Offline operator CLI
+
+`pwn-ai --policy evaluate|promote|rollback` reuses `PolicyEvaluation`; it never
+starts a session, loads the encrypted configuration, runs `Learning.rsi_tick`,
+or invokes the agent loop. It cannot be combined with `--ai`, replay, mission,
+or other session options. Evaluation accepts existing explicit frozen snapshots,
+runs suites 0 and 1, and prints a JSON **array** suitable for `--reports`. It does
+not train or write the live policy. The Ruby API supports other indices 0..7.
+
+From a source checkout, this disposable demonstration stays entirely under a
+new `/tmp` directory (use `pwn-ai` instead of `ruby -Ilib bin/pwn-ai` for an
+installed executable):
+
+```sh
+umask 077
+work=$(mktemp -d /tmp/pwn-offline-policy.XXXXXX)
+ruby scripts/benchmark_policy.rb --heldout \
+  --snapshot-dir "$work/snapshots" --output "$work/benchmark.json"
+ruby -Ilib bin/pwn-ai --policy evaluate \
+  --baseline "$work/snapshots/off.json" --candidate "$work/snapshots/on.json" \
+  > "$work/reports.json"
+cp "$work/snapshots/off.json" "$work/demo-live.json"
+```
+
+Review `reports.json` before deciding whether to proceed. For a real target,
+first stop **all** agent processes and other policy writers, take the baseline
+copy only after stopping them, and keep writers stopped through promotion and
+readback. The acknowledgement does not stop processes or acquire a writer lock.
+Concurrent promotions are also unsupported. Do not replace a real policy with
+these demonstration snapshots or infer live gains from this fixture experiment.
+
+Only if approving the change to the **disposable demo target**, run:
+
+```sh
+ruby -Ilib bin/pwn-ai --policy promote \
+  --baseline "$work/snapshots/off.json" --candidate "$work/snapshots/on.json" \
+  --reports "$work/reports.json" --live-policy "$work/demo-live.json" \
+  --approve-policy-change --policy-writers-stopped > "$work/promotion.json"
+cmp "$work/demo-live.json" "$work/snapshots/on.json"
+```
+
+The command re-executes both reports before considering replacement. It returns
+nonzero on refusal or malformed input; check the exit status and JSON, not just
+whether a redirected file exists. Keep the successful `promotion.json` receipt
+and digest-named backup. Use distinct, new output paths: shell redirection opens
+files before the CLI starts, so never redirect onto snapshots, the live target,
+or an existing receipt. A failed retry must not overwrite the successful receipt.
+
+Rollback is a separate explicit operator decision with the same stopped-writer
+requirement; it refuses intervening changes to the target:
+
+```sh
+ruby -Ilib bin/pwn-ai --policy rollback \
+  --receipt "$work/promotion.json" --live-policy "$work/demo-live.json" \
+  --approve-policy-change --policy-writers-stopped > "$work/rollback.json"
+cmp "$work/demo-live.json" "$work/snapshots/off.json"
+```
+
+Neither approval flag alone is sufficient. There is no default live path,
+automatic promotion, target discovery, network task, or model training in this
+CLI path. Reports and receipts are operator-owned local JSON, not executable
+configuration; neither can supply approval flags. Existing `Learning.rsi_tick`
+only snapshots measured rates and records a regression lesson. It does not call
+this gate, generate candidates, schedule practice, or approve changes. The
+broader online learning and curriculum paths remain unchanged and separate.
+
+Focused verification commands (no hardware, providers, or live models):
+
+```sh
+bundle exec rspec spec/lib/pwn/ai/cli_spec.rb \
+  spec/lib/pwn/ai/agent/policy_evaluation_spec.rb \
+  spec/lib/pwn/ai/agent/learning_spec.rb spec/lib/pwn/ai/agent/rsi_metrics_spec.rb
+bundle exec rubocop lib/pwn/ai/cli.rb spec/lib/pwn/ai/cli_spec.rb \
+  spec/lib/pwn/ai/agent/rsi_metrics_spec.rb
+```
+
 ## Explicit promotion and rollback
 
 This is an **operator-invoked local eligibility gate**, not automatic online

data/documentation/Recon-Findings-API.md

@@ -22,9 +22,11 @@ Use `affected_asset: asset[:id]` and `evidence_paths: asset[:evidence_paths]` in
 
 `record_structured` requires title, CWE identifier (`CWE-<positive integer>`), complete CVSS 3.0/3.1 base vector and matching numeric base score, affected_asset, nonempty existing readable absolute evidence_paths, nonempty PoC command/code string, attack_chain_refs array, remediation string, and numeric confidence 0..1. Chain refs must already exist in the same engagement. Invalid input raises before appending. CVSS 2/4, temporal/environmental vectors are explicitly unsupported (rejected, not normalized).
 
-Legacy `Findings.record`, query/report, chain, render, and SARIF output remain callable; legacy record is not the strict API. Agent record and chain operations are strict. Existing query/export tool operations remain available. Accepted structured rows mark `verification_status: not_executed`; evidence hashes prove captured bytes, not exploit execution. Severity is derived from the validated score. No automatic escalation for linked findings.
+Legacy `Findings.record`, query/report, chain, render, and SARIF output remain callable; legacy record is not the strict API. Agent record and chain operations are strict. Existing query/export tool operations remain available. Accepted structured rows store `severity: info` and `verification_status: not_executed`. A file hash proves the bytes were captured. It does not prove the PoC ran. The claimed score stays on the row, and the published severity rises only after `verify` returns `reproduced`. Linking findings does not raise severity by itself.
 
-`Findings.verify` / `finding_record op=verify` attests a working PoC from HTTP request/response files or a script execution log. The impact marker must appear in that evidence or the row stays `failed`. `Findings.retest` replays the same path after a fix (`still_open` vs `fixed`). `Findings.chain_impact` may raise combined severity only when a combined-impact file names every finding id. Issue work is unfinished while recorded findings remain `not_executed` (`issue_work_unverified`).
+`Findings.verify` and `Findings.retest` run the stored PoC or the ordered reproduction commands, capture that transcript, and only then search it for the impact string. A file the caller already filled with the impact string does not count. `retest` uses the same runner, so `fixed` means that command no longer prints the impact. `chain` refuses evidence shorter than 40 characters and does not raise `composite_severity` above the parent. `chain_impact` can raise it only when the combined-impact file names every id and shows the second effect. `PWN::Reports` refuses to print `high` or `critical` for a linked pair that is not `reproduced`, or whose combined-impact file does not name every id.
+
+Nuclei and SBOM write recon observations, not findings. A template match or a CVE id is a lead. `Recon.handoff` carries host, port, product, version, and the evidence path into `ExploitDev.ret2libc`, `Nuclei.scan`, and `Fuzz.triage`. `NmapIt.scan` and `Nuclei.scan` skip a port that already has an observation unless `refresh: true`.
 
 `PWN::AI::Agent::Swarm.ensure_specialists` / `agent_roster` writes recon, authz, injection, xss, and business_logic personas. SARIF export is `Findings.render`; `PWN::Plugins::Github.open_fix_pr` opens a remediation PR (tests stub the GitHub API).
 

data/documentation/Reinforcement-Learning.md

@@ -8,8 +8,16 @@ local adapter.
 `Curriculum.practice` -> `Reward.export_dpo` -> `Curriculum.train_and_gate`
 
 That path can promote a new local adapter when the candidate beats the current
-one. Without a trainer it still **exports** the datasets and a manual CLI. Live
-improvement does not wait on weights.
+one. Without a trainer it still **exports** the datasets and a manual CLI. Live improvement does not wait on weights.
+
+ESR and ASR are the rates RSI actually compares. ESR is `verified_exploit_tools / vulnerable_tools`. ASR is `successful_attacks / total_attack_attempts`. `Learning.rsi_tick` stores the pair and writes an `rsi` lesson when ESR falls. Tool telemetry and the judge score are separate. A passing suite is not either rate.
+
+RSI's rate tick does not generate or promote policy candidates. For the separate
+**offline operator evaluation** path, use `pwn-ai --policy evaluate` and review
+the fixed local held-out reports. Promotion and rollback each require explicit
+`--approve-policy-change --policy-writers-stopped` plus a named live policy path;
+neither runs automatically from RSI. See the executable commands, stopped-writer
+requirements, and benchmark limits in [Policy-Benchmark](Policy-Benchmark.md#offline-operator-cli).
 
 ![Reinforcement-learning loop](diagrams/reinforcement-learning.svg)
 

data/documentation/Reporting.md

@@ -24,6 +24,14 @@
 | `PWN::Plugins::JiraDataCenter` | Create issues from findings |
 | `PWN::Plugins::SlackClient` / `MailAgent` | Notify |
 
+## Severity and chain gates
+
+`Findings.record` and `record_structured` store `severity: info` and `verification_status: not_executed`. `verify` runs the stored PoC and searches that transcript. The claimed severity is published only when the status is `reproduced`.
+
+`PWN::Reports.report_payload` calls `refuse_unproven_combined!` before a chain leaves the process. It refuses to print `high` or `critical` for a linked pair that is not `reproduced`, or whose combined-impact file does not name every id. Max-of-two is not a chain.
+
+Nuclei and SBOM leads stay recon observations until a later `verify` reproduces them.
+
 ## Example
 
 ```ruby

data/documentation/Skills-Memory-Learning.md

@@ -1,8 +1,6 @@
 # Memory · Skills · Learning · Mistakes · Metrics · Policy - Introspection
 
-The **inward-facing** half of the pwn-ai feedback loop: how the agent measures
-its own performance, turns wins into permanent capability, and - critically -
-**learns from its own mistakes so it does not repeat them**.
+The inward half of the pwn-ai feedback loop: the agent writes what it did, and the next prompt can see it. Wins become skills. Failures become fingerprinted mistakes.
 
 ![Memory / Skills detail](diagrams/memory-skills-detailed.svg)
 
@@ -15,7 +13,17 @@ its own performance, turns wins into permanent capability, and - critically -
 | **Policy** | `policy.json` + `policy_traj.jsonl` | Loop `begin_episode` / `observe_step` / `finish` | `policy_stats` · `policy_evaluate` · `policy_recommend` | `POLICY` block - live tabular Q / REINFORCE. Advisory rank only. Disable with `ai.agent.policy: false`. |
 | **Learning** | `learning.jsonl` | `learning_note_outcome` · `learning_reflect` | `learning_outcomes` · `learning_stats` · `Learning.exemplars_for` | `LEARNING` block - recent outcomes + success_rate. Prior *successful* traces are also spliced in as **few-shot exemplars** for local models. |
 | **Mistakes** | `mistakes.json` | `mistakes_record` · `mistakes_resolve` · *auto on failure* | `mistakes_list` | `KNOWN MISTAKES` + `KNOWN FIXES` blocks - do-NOT-repeat + do-THIS-instead |
-| **Metrics** | `metrics.json` | *automatic* (every Dispatch) | `metrics_summary` | `TOOL EFFECTIVENESS` block - steer tool choice. **Segmented per engine** (`engine=...`) so a local model's telemetry never blends with a frontier model's. |
+| **Metrics** | `metrics.json` | *automatic* (every Dispatch) plus `Metrics.record_attempt` | `metrics_summary` | `TOOL EFFECTIVENESS` block, plus ESR and ASR on the health line. |
+
+## Exploit and attack rates
+
+`PWN::AI::Agent::Metrics` keeps two rates that RSI can compare across turns.
+
+ESR is `verified_exploit_tools / vulnerable_tools`. A tool enters `verified_exploit_tools` only when an exploit attempt for that tool name succeeds. A tool enters `vulnerable_tools` when the caller marks it vulnerable, or when a successful exploit names that target. Repeating the same tool does not change the counts. The rate stays nil until at least one vulnerable tool exists.
+
+ASR is `successful_attacks / total_attack_attempts`. Every attack attempt increments the denominator. A reproduced impact, a still-open retest, or an accepted `chain_impact` increments the numerator. This one is an attempt ratio, not a set of tool names.
+
+`Learning.rsi_tick` compares the current ESR with the previous snapshot. A drop writes a lesson tagged `rsi`. `Loop` already calls `Learning.auto_introspect`, and that path calls `rsi_tick`. A green rake is not an ESR sample. The default suite does not hit a live target.
 
 ## Memory write guard
 
@@ -122,6 +130,9 @@ bundled skills into `~/.pwn/skills/` when the name is missing:
 | `cwe` | Exhaustive test procedure per CWE ID (`references/CWE-<id>.md`) |
 | `capec` | Exhaustive attack-pattern procedure per CAPEC ID (`references/CAPEC-<id>.md`) |
 | `att&ck` | Exhaustive test procedure per ATT&CK technique (`references/T1059.001.md`) |
+| `humanizer` | Strip AI writing patterns from prose. Keep meaning and identifiers. |
+
+`PWN::AI::Agent::SkillReview` runs after introspection. A routine success does not create a skill. A tested procedure, a resolved recurring mistake, or an explicit correction can recommend an update to the closest skill under `~/.pwn/skills`. The default mode is `recommend`. `auto-safe` writes only a small addition that an execution fixture passed in three sessions, and it keeps a backup. It does not create skills, rewrite generated `pwn/` module skills, or save secrets and raw tool output. Set `ai.agent.skill_review` to `off`, `recommend`, or `auto-safe`.
 
 Source: `etc/default_skills/` in the gem. SOP edits in `~/.pwn/skills/<name>/SKILL.md`
 are never overwritten. Generated `~/.pwn/skills/pwn/**/SKILL.md` module skills

data/documentation/diagrams/dot/pwn-ai-feedback-learning-loop.dot

@@ -34,7 +34,7 @@ Escalate [label="escalate\n>=N fails → Swarm hint",        fillcolor="#c4b5fd"
   subgraph cluster_intro {
     label="INTROSPECTION  (self)"; fontcolor="#a7f3d0";
     style=rounded; color="#047857"; bgcolor="#022c22"; penwidth=2;
-    Metrics  [label="Metrics\nper-tool · PER-ENGINE\nsuccess · avg ms", fillcolor="#6ee7b7"];
+    Metrics  [label="Metrics\nESR = verified exploit tools / vulnerable tools\nASR = successful attacks / attempts", fillcolor="#6ee7b7"];
     Learning [label="Learning\nnote_outcome · reflect\nexemplars_for · SFT quality gate\nfact_check_local_final", fillcolor="#6ee7b7"];
     Mistakes [label="Mistakes\nrecord · resolve\nguard · correction_hint\n[REPEATING] · [REGRESSED]", fillcolor="#6ee7b7", penwidth=2];
     ReflectT [label="Reflect\nteacher-student\n(reflect_engine)", fillcolor="#6ee7b7", penwidth=2];
@@ -106,6 +106,7 @@ Escalate [label="escalate\n>=N fails → Swarm hint",        fillcolor="#c4b5fd"
   /* L2 → L3 */
   Metrics  -> Correlate [color="#34d399"];
   Learning -> Correlate [color="#34d399"];
+  Learning -> Metrics [label="rsi_tick\nESR drop writes a lesson", style=dashed, color="#34d399", constraint=false];
   Mistakes -> Correlate [color="#34d399"];
   Snapshot -> Correlate [color="#f59e0b"];
   Observe  -> Correlate [color="#f59e0b"];

data/documentation/diagrams/dot/reinforcement-learning.dot

@@ -47,8 +47,9 @@ digraph "PWN_Reinforcement_Learning" {
     W1 [label="preference ledger\ntrajectory pairs\nscrub + geometry filter\nwrite+export <=40%/src", fillcolor="#fda4af"];
     W2 [label="train_and_gate\nSFT+DPO → LoRA vN+1\ngate + preference diet\nexport_ready without trainer", fillcolor="#fda4af", penwidth=2];
     W3 [label="calibrate\np(success) vs actual → Brier", fillcolor="#fda4af"];
+    Rates [label="ESR verified_exploit_tools / vulnerable_tools\nASR successful_attacks / total_attack_attempts\nrsi_tick on an ESR drop", fillcolor="#fda4af"];
   }
-  {rank=same; W1; W2; W3}
+  {rank=same; W1; W2; W3; Rates}
 
   /* Persistence */
   subgraph cluster_files {
@@ -97,6 +98,7 @@ digraph "PWN_Reinforcement_Learning" {
   W2 -> Ollama [label="LoRA", color="#fb7185", penwidth=2];
   Fmis -> W2 [label="eval set", style=dashed, color="#fbbf24", constraint=false];
   W3 -> Loop [label="calibration", style=dashed, color="#fbbf24", constraint=false];
+  Loop -> Rates [label="rsi_tick", color="#34d399", style=dashed, constraint=false];
 
   /* cron seeds */
   Cron [label="⏱  PWN::Cron.install_defaults\npractice · offline_judge\ntrain dry_run · consolidate", fillcolor="#7dd3fc"];

data/documentation/diagrams/dot/reporting-pipeline.dot

@@ -17,6 +17,8 @@ digraph "PWN_Reports" {
     Fuzz [label="Plugins::Fuzz", fillcolor="#6ee7b7"];
     Uri  [label="URI Buster",    fillcolor="#6ee7b7"];
     Phone[label="BareSIP recon", fillcolor="#6ee7b7"];
+    Obs  [label="Nuclei · SBOM\nrecon observations\nnot findings", fillcolor="#6ee7b7"];
+    Find [label="Findings.record\nseverity info\nuntil verify", fillcolor="#6ee7b7"];
   }
   subgraph cluster_gen {
     label="Generators"; fontcolor="#fde68a"; style=rounded;
@@ -33,12 +35,16 @@ digraph "PWN_Reports" {
     JSON [label="JSON",                   fillcolor="#c4b5fd"];
     DD   [label="DefectDojo\nimport/reimport", fillcolor="#c4b5fd"];
     Jira [label="JiraDataCenter",          fillcolor="#c4b5fd"];
+    Gate [label="refuse_unproven_combined!\nhigh/critical needs reproduced\nchain file naming every id", fillcolor="#fda4af"];
   }
 
   Sast  -> Rsast  [color="#f59e0b"];
   Fuzz  -> Rfuzz  [color="#f59e0b"];
   Uri   -> Ruri   [color="#f59e0b"];
   Phone -> Rphone [color="#f59e0b"];
+  Obs   -> Find   [label="handoff", color="#34d399"];
+  Find  -> Gate   [label="verify transcript", color="#f59e0b"];
+  Gate  -> HTML   [color="#a78bfa"];
   Rsast  -> HTML [color="#a78bfa"];
   Rfuzz  -> JSON [color="#a78bfa"];
   Ruri   -> DD   [color="#a78bfa"];

data/documentation/diagrams/dot/zero-day-research-flow.dot

@@ -23,6 +23,8 @@ digraph "PWN_ZeroDay" {
     color="#a16207"; bgcolor="#422006";
     Fuzz [label="Fuzz · Sock\nPacket",        fillcolor="#fcd34d"];
     TB   [label="TransparentBrowser\nBurp replay", fillcolor="#fcd34d"];
+    Obs  [label="Recon.observe\nhost port product\nversion evidence", fillcolor="#fcd34d"];
+    Ver  [label="Findings.verify\ntranscript shows impact\nor severity stays info", fillcolor="#fcd34d"];
   }
   subgraph cluster_weapon {
     label="Weaponise"; fontcolor="#fecaca"; style=rounded;
@@ -39,8 +41,11 @@ digraph "PWN_ZeroDay" {
 
   Surface -> SAST [color="#38bdf8"];
   Surface -> AI   [color="#38bdf8"];
-  SAST -> Fuzz [color="#f59e0b"];
-  AI   -> TB   [color="#f59e0b"];
+  SAST -> Obs [color="#f59e0b"];
+  AI   -> Obs [color="#f59e0b"];
+  Obs  -> Ver [label="lead, not a finding", color="#f59e0b"];
+  Ver  -> Fuzz [color="#f59e0b"];
+  Ver  -> TB   [color="#f59e0b"];
   Fuzz -> Asm  [color="#fb7185"];
   TB   -> MSF  [color="#fb7185"];
   Asm  -> H1   [color="#a78bfa"];