pwn 0.5.636 → 0.5.638

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41a8a5c5d750508d4f3904d7a05151719e2c86fa4cf20001a3aab0985910963d
-  data.tar.gz: 7af0757b53bdfa6c97d86a9415a2cbf41ca9447b3f9e438b95b2424f5d835cbf
+  metadata.gz: c889fade648cffc3bfe73e8a168b4e5353f3eb1fe652fa1b1839f9733c630bc8
+  data.tar.gz: c02957f5bc40cb4d8a3dc18d5c078540f5395118ade25df55379c6399c264d03
 SHA512:
-  metadata.gz: 8053f31ef3138368e50c1b6920fa7804945f508daabc31191ba2a9578f3c31f7e6629e1ca901a409ec82e4cefdf3a824fa48bcfe4fdcd8ab4a1a9da0f168e1da
-  data.tar.gz: 592bfb24c2c2a610813fcd5b8431478d4774ef312405f446393db9cbb305c2c223b129a0714b9b464adc9976e682b1754a4e5d760d0ca28b00ba99778df21d7a
+  metadata.gz: 97e57a81e839aaafcd83921d258ab2a95d9b7671120ef9c72a0df742c2ddfd4a84bb2d92a1b5fc426979910aea82e1b192226e1dfaddac218a057791ca892012
+  data.tar.gz: 1d89d4153ec4cd0b1604f2a8e4a735d00606d45111f9ad1db92b302968a510fbedfd6a588022ab1120fac4ed9413e7aac3e0694b6cd4200e65cfcf162ed2375e

data/.github/workflows/install-matrix.yml

@@ -84,7 +84,12 @@ jobs:
             ruby: dnf install -y ruby ruby-devel redhat-rpm-config gcc gcc-c++ make git
           - image: archlinux:latest
             pm: pacman
-            ruby: pacman -Sy --noconfirm ruby base-devel git
+            # ruby-stdlib/ruby-bundled-gems: Arch splits erb/etc. out of the
+            # base `ruby` package; sed: Arch's /etc/gemrc defaults to
+            # `--user-install` which puts pwn/rspec binstubs off PATH.
+            ruby: >-
+              pacman -Sy --noconfirm ruby ruby-stdlib ruby-bundled-gems rubygems base-devel git &&
+              { sed -i '/--user-install/d' /etc/gemrc || true; }
     env:
       DEBIAN_FRONTEND: noninteractive
       PWN_FRESH_INSTALL: '1'
@@ -117,6 +122,13 @@ jobs:
           gem install --no-document rspec
           ruby -r pwn -e 'puts "pwn #{PWN::VERSION} ruby #{RUBY_VERSION} #{RUBY_PLATFORM}"'
 
+      - name: expose gem binstubs on PATH
+        # Distros disagree on where `gem install` writes executables (system
+        # bindir on apt/dnf, ~/.local/share/gem/.../bin on Arch's default
+        # --user-install). Put both on PATH so `pwn` / `rspec` resolve on
+        # every leg without hard-coding per-distro paths.
+        run: ruby -e 'puts Gem.bindir; puts File.join(Gem.user_dir, "bin")' >> "$GITHUB_PATH"
+
       - name: dry-run — every package name resolves for this distro
         run: pwn setup --profile full --dry-run --yes
 

data/bin/pwn_ai_red_team

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'htmlentities'
+require 'pwn'
+
+opts = PWN::Env[:driver_opts]
+PWN::Driver::Parser.new do |options|
+  options.on('-eENGINE', '--target-engine=ENGINE', '<Required - AI Engine Under Test (openai|anthropic|grok|gemini|ollama)>') do |e|
+    opts[:target_engine] = e
+  end
+
+  options.on('-mMODEL', '--target-model=MODEL', '<Optional - Specific Model on the Target Engine (Defaults to engine default)>') do |m|
+    opts[:target_model] = m
+  end
+
+  options.on('-rROLE', '--system-role=ROLE', '<Optional - System Prompt Applied to the Target for Every Payload>') do |r|
+    opts[:system_role_content] = r
+  end
+
+  options.on('-dDIR', '--dir-path=DIR', '<Optional - Report Output Directory (Defaults to ".")>') do |d|
+    opts[:dir_path] = d
+  end
+
+  options.on('-tTHREADS', '--max-threads=THREADS', '<Optional # Test Cases to Run Simultaneously (Default 5)>') do |t|
+    opts[:max_threads] = t
+  end
+
+  options.on('-TCASE', '--test-cases=CASE', '<Optional Comma-Delimited Test Cases to Invoke (-l for List)>') do |c|
+    opts[:chosen_test_cases] = c
+  end
+
+  options.on('-l', '--[no-]list-test-cases', '<Optional List Available Test Cases to Invoke and Exit>') do |l|
+    opts[:list_test_cases] = l
+  end
+
+  options.on('-nREPORTNAME', '--report-name=REPORTNAME', '<Optional Report Name (Defaults to, "<engine>-<model>-<timestamp>")>') do |n|
+    opts[:report_name] = n
+  end
+
+  options.on('-s', '--[no-]start-reporting-server', '<Optional - Start Simple HTTP Server for Reporting>') do |s|
+    opts[:start_reporting_server] = s
+  end
+end.parse!
+
+begin
+  timestamp = Time.now.strftime('%Y-%m-%d_%H:%M:%S%z')
+
+  pwn_env_path = opts[:pwn_env_path]
+  pwn_dec_path = opts[:pwn_dec_path]
+
+  pwn_provider = 'ruby-gem'
+  pwn_provider = ENV.fetch('PWN_PROVIDER') if ENV.keys.any? { |s| s == 'PWN_PROVIDER' }
+
+  green = "\e[32m"
+  end_of_color = "\e[0m"
+
+  dir_path = opts[:dir_path] ||= '.'
+
+  target_engine = opts[:target_engine]
+  target_model = opts[:target_model]
+  system_role_content = opts[:system_role_content]
+
+  max_threads = opts[:max_threads]
+  max_threads ||= 5
+
+  chosen_test_cases = opts[:chosen_test_cases]
+  list_test_cases = opts[:list_test_cases]
+
+  report_name = opts[:report_name]
+  report_name ||= "#{target_engine}-#{target_model || 'default'}-#{timestamp}"
+
+  start_reporting_server = opts[:start_reporting_server]
+
+  # Define Test Cases to Run & Start Thread Pool
+  if chosen_test_cases && !list_test_cases
+    test_cases = chosen_test_cases.to_s.scrub.chomp.strip.delete("\s").split(',').map(&:to_sym)
+  else
+    test_cases = %i[
+      ExcessiveAgency
+      InsecureOutputHandling
+      Jailbreak
+      ModelDenialOfService
+      Overreliance
+      PayloadSplitting
+      PromptInjection
+      SensitiveInformationDisclosure
+      SystemPromptExtraction
+      TokenSmuggling
+    ].sort.uniq
+  end
+
+  if list_test_cases
+    test_cases.each { |tc| puts "#{green}#{tc}#{end_of_color}" }
+    exit
+  end
+
+  raise "ERROR: Invalid Directory #{dir_path}" unless File.directory?(dir_path)
+
+  results_hash = {
+    report_name: HTMLEntities.new.encode(
+      report_name.to_s.scrub.strip.chomp
+    ),
+    data: []
+  }
+
+  mutex = Mutex.new
+
+  PWN::Plugins::ThreadPool.fill(
+    enumerable_array: test_cases,
+    max_threads: max_threads
+  ) do |test_case|
+    rt_arr = PWN::AI::RedTeam.const_get(
+      test_case.to_s.scrub
+    ).scan(
+      target_engine: target_engine,
+      target_model: target_model,
+      system_role_content: system_role_content
+    )
+
+    rt_arr.each { |hash_line| mutex.synchronize { results_hash[:data].push(hash_line) } }
+  end
+
+  # Generate HTML Report
+  print "#{File.basename($PROGRAM_NAME)} Generating Report..."
+  PWN::Reports::AIRedTeam.generate(
+    dir_path: dir_path,
+    results_hash: results_hash,
+    report_name: report_name
+  )
+  puts 'complete.'
+
+  # Start Simple HTTP Server (If Requested)
+  if start_reporting_server
+    listen_ip = '127.0.0.1'
+    listen_ip = '0.0.0.0' if pwn_provider == 'docker'
+    listen_port = PWN::Plugins::Sock.get_random_unused_port.to_s
+    puts "For Scan Results Navigate to: http://127.0.0.1:#{listen_port}/#{report_name}.html"
+
+    system(
+      'pwn_simple_http_server',
+      '--bind-ip',
+      listen_ip,
+      '--port',
+      listen_port
+    )
+  end
+rescue SystemExit, Interrupt
+  puts "\nGoodbye."
+end

data/bin/pwn_setup

@@ -44,6 +44,12 @@ pwn_driver = PWN::Driver::Parser.new do |options|
     opts[:yes] = o
   end
 
+  options.on('-t', '--terminal',
+             '<Optional - Opt-in SHIFT+ENTER multi-line support: prints ~/.tmux.conf lines and, ' \
+             'under Terminator, installs the PWNShiftEnter GTK plugin (with confirmation)>') do |o|
+    opts[:terminal] = o
+  end
+
   options.on('-n', '--dry-run',
              '<Optional - Print the commands that would run, do not execute>') do |o|
     opts[:dry_run] = o
@@ -61,14 +67,22 @@ begin
       dry_run: opts[:dry_run]
     )
     exit 1 unless r && r[:after] && r[:after][:incompatible].empty?
-  elsif opts[:deps] || opts[:profile]
+  elsif opts[:terminal]
+    PWN::Setup.terminal(
+      yes: opts[:yes],
+      dry_run: opts[:dry_run]
+    )
+  elsif (opts[:deps] || opts[:profile]) && !opts[:check]
     PWN::Setup.deps(
       profile: opts[:profile],
       yes: opts[:yes],
       dry_run: opts[:dry_run]
     )
   else
-    r = PWN::Setup.check
+    # `pwn setup`                       → doctor gate on EVERYTHING
+    # `pwn setup --check`               → same
+    # `pwn setup --check --profile net` → gate ONLY on the :net profile
+    r = PWN::Setup.check(profile: opts[:profile])
     exit 1 unless r[:ok]
   end
 rescue Interrupt

data/build_gem.sh

@@ -35,6 +35,9 @@ if [[ $old_ruby_version == $new_ruby_version ]]; then
   rvmsudo /bin/bash --login -c "cd ${pwn_root} && bundle exec rake rerdoc"
   echo "Invoking bundle-audit Gemfile Scanner..."
   rvmsudo /bin/bash --login -c "cd ${pwn_root} && bundle exec bundle-audit"
+  # Restore ownership of artifacts (rdoc/, pkg/, Gemfile.lock, etc.) generated
+  # under rvmsudo above so a subsequent unprivileged `rake` / `git` can operate.
+  sudo chown -R $USER:$USER "$pwn_root"
 else
   cd $pwn_root && ./upgrade_ruby.sh $new_ruby_version $old_ruby_version
 fi

data/documentation/Agent-Tool-Registry.md

@@ -6,21 +6,25 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 
 ![Tool registry](diagrams/agent-tool-registry.svg)
 
-## Toolsets → Tools  (10 toolsets · 61 tools)
+## Toolsets → Tools  (10 toolsets · 71 tools)
 
 | Toolset | Tools | Backed by |
 |---|---|---|
 | `terminal` | `shell` | `Open3.capture3` on the host |
 | `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process |
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
-| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (agentskills.io; legacy flat `*.md` still read) |
+| `skills` | `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) |
 | `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
-| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · `learning_purge_noise` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` |
+| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** · **`learning_purge_noise`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` + `~/.pwn/finetune/` |
 | `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
-| `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) → `~/.pwn/extrospection.json` |
+| `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` |
 | `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
 
+The `learning` toolset is deliberately fat: **Mistakes** (negative feedback),
+**Reward** (ORM/PRM/sentinel/DPO ledger) and **Curriculum** (self-play, HER,
+regression-gated LoRA) are all facets of the same self-improvement loop -
+see [Reinforcement Learning](Reinforcement-Learning.md).
 
 ## Dynamic tool-set slimming (`ai.agent.tool_router`)
 
@@ -41,6 +45,8 @@ CORE_TOOLS  = shell · pwn_eval · memory_remember · memory_recall
 ```ruby
 PWN::AI::Agent::Registry.definitions(relevance: 'nmap sweep 10.0.0.0/8', top_k: 10)
 PWN::AI::Agent::Registry.rank(query: 'run a shell command')   # inspect ranking
+PWN::AI::Agent::Registry.toolsets                              # → the 10 names above
+PWN::AI::Agent::Registry.all.count                             # → 71
 ```
 
 Frontier engines leave `tool_router` off and receive the full set.
@@ -75,6 +81,7 @@ recon:
   engine: ollama
 ```
 
-**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Mistakes](Mistakes.md) · [Swarm](Swarm.md)
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Mistakes](Mistakes.md) ·
+[Reinforcement Learning](Reinforcement-Learning.md) · [Swarm](Swarm.md)
 
 [← Home](Home.md)

data/documentation/CLI-Drivers.md

@@ -1,47 +1,52 @@
 # CLI Drivers - `bin/pwn_*`
 
-53 headless executables, each a thin `OptionParser` wrapper over one plugin
-(or one workflow). They exist so CI/CD can call PWN without a REPL or an LLM.
+53 headless executables (52 `pwn_*` + `pwn`), each a thin `OptionParser`
+wrapper over one plugin (or one workflow). They exist so CI/CD can call PWN
+without a REPL or an LLM.
 
 ![Driver anatomy](diagrams/driver-framework.svg)
 
 ## Full list
 
 ```text
-pwn                              pwn_jenkins_thinBackup_aws_s3
-pwn_android_war_dialer           pwn_jenkins_update_plugins
-pwn_autoinc_version              pwn_jenkins_useradd
-pwn_aws_describe_resources       pwn_mail_agent
-pwn_bdba_groups                  pwn_msf_postgres_login
-pwn_bdba_scan                    pwn_nessus_cloud_scan_crud
-pwn_burp_suite_pro_active_rest_api_scan   pwn_nessus_cloud_vulnscan
-pwn_burp_suite_pro_active_scan   pwn_nexpose
-pwn_char_base64_encoding         pwn_nmap_discover_tcp_udp
-pwn_char_dec_encoding            pwn_openvas_vulnscan
-pwn_char_hex_escaped_encoding    pwn_pastebin_sample_filter
-pwn_char_html_entity_encoding    pwn_phone
-pwn_char_unicode_escaped_encoding  pwn_rdoc_to_jsonl
-pwn_char_url_encoding            pwn_sast
-pwn_crt_sh                       pwn_serial_check_voicemail
-pwn_defectdojo_engagement_create pwn_serial_msr206
-pwn_defectdojo_importscan        pwn_serial_qualcomm_commands
-pwn_defectdojo_reimportscan      pwn_serial_son_micro_sm132_rfid
-pwn_diff_csv_files_w_column_exclude  pwn_setup
-pwn_domain_reversewhois          pwn_shodan_graphql_introspection
-pwn_fuzz_net_app_proto           pwn_shodan_search
-pwn_gqrx_scanner                 pwn_simple_http_server
-pwn_jenkins_create_job           pwn_web_cache_deception
-pwn_jenkins_create_view          pwn_www_checkip
-pwn_jenkins_install_plugin       pwn_www_uri_buster
+pwn                                pwn_mail_agent
+pwn_android_war_dialer             pwn_msf_postgres_login
+pwn_autoinc_version                pwn_nessus_cloud_scan_crud
+pwn_aws_describe_resources         pwn_nessus_cloud_vulnscan
+pwn_bdba_groups                    pwn_nexpose
+pwn_bdba_scan                      pwn_nmap_discover_tcp_udp
+pwn_burp_suite_pro_active_rest_api_scan   pwn_openvas_vulnscan
+pwn_burp_suite_pro_active_scan     pwn_pastebin_sample_filter
+pwn_char_base64_encoding           pwn_phone
+pwn_char_dec_encoding              pwn_rdoc_to_jsonl
+pwn_char_hex_escaped_encoding      pwn_sast
+pwn_char_html_entity_encoding      pwn_serial_check_voicemail
+pwn_char_unicode_escaped_encoding  pwn_serial_msr206
+pwn_char_url_encoding              pwn_serial_qualcomm_commands
+pwn_crt_sh                         pwn_serial_son_micro_sm132_rfid
+pwn_defectdojo_engagement_create   pwn_setup
+pwn_defectdojo_importscan          pwn_shodan_graphql_introspection
+pwn_defectdojo_reimportscan        pwn_shodan_search
+pwn_diff_csv_files_w_column_exclude  pwn_simple_http_server
+pwn_domain_reversewhois            pwn_web_cache_deception
+pwn_fuzz_net_app_proto             pwn_www_checkip
+pwn_gqrx_scanner                   pwn_www_uri_buster
+pwn_jenkins_create_job             pwn_xss_dom_vectors
+pwn_jenkins_create_view            pwn_zaproxy_active_rest_api_scan
+pwn_jenkins_install_plugin         pwn_zaproxy_active_scan
+pwn_jenkins_thinBackup_aws_s3
+pwn_jenkins_update_plugins
+pwn_jenkins_useradd
 ```
 
 Run any with `--help` for its flags.
 
-## `pwn_setup` - post-install doctor & capability provisioner
+## `pwn_setup` - post-install doctor / provisioner / state migrator
 
 The one driver that isn't a plugin wrapper. It grows a bare `gem install pwn`
 into a fully-armed host by installing OS headers / external tools for whatever
-capability profile you ask for. Also reachable as `pwn setup` and
+capability profile you ask for, **and** verifies/repairs every persisted
+`~/.pwn` state file after an upgrade. Also reachable as `pwn setup` and
 `pwn --setup[=PROFILE]`.
 
 ```bash
@@ -49,10 +54,11 @@ pwn_setup                        # read-only doctor; exit 1 if degraded
 pwn_setup --list-profiles
 pwn_setup --profile web --yes    # CI-friendly, non-interactive
 pwn_setup --deps --dry-run       # print the apt/dnf/pacman/brew/port commands only
+pwn_setup --migrate --fix        # ~/.pwn state doctor + autofix (PWN::Migrate)
 ```
 
-See [Installation](Installation.md) for the full profile table and
-`PWN::Setup` API.
+See [Installation](Installation.md) for the full profile table, the
+`PWN::Setup` API and the `PWN::Migrate` state-file registry.
 
 ## Typical CI usage
 

data/documentation/Configuration.md

@@ -20,6 +20,9 @@ generates the decryptor.
 > [doctor](Installation.md#pwn-setup--the-post-install-doctor--provisioner)
 > reports whether `~/.pwn/`, `pwn.yaml`, its decryptor, and an AI-engine key
 > are present, and exits non-zero for CI if any are missing.
+> After `gem update pwn`, run `pwn setup --migrate --fix` — `PWN::Migrate`
+> deep-merges any keys the new `PWN::Config.env_template` added into your
+> encrypted `pwn.yaml` **without overwriting your values**.
 
 ---
 
@@ -263,6 +266,11 @@ PWN::Config.refresh_env
 | `ai.agent.plan_first` | Boolean \| `nil` | `nil` (auto: `true` when `ai.active == ollama`) | `PWN::AI::Agent::Loop.plan_first` | Plan-then-act pre-pass: the model must emit a numbered tool plan (as an assistant message) *before* it may dispatch anything. Cheap chain-of-thought scaffolding for local models. |
 | `ai.agent.tool_router` | Boolean | `false` | `PWN::AI::Agent::Registry.definitions` | Dynamic tool-set slimming: expose only `Registry::CORE_TOOLS` + the top-K keyword-relevant schemas for *this* request. Ties break on historical `Metrics` success rate so the router itself is a learned component. |
 | `ai.agent.escalation_persona` | String \| `nil` | `nil` | `PWN::AI::Agent::Loop.escalate` → `Swarm.ask` | Circuit-breaker: once a local model accumulates ≥ `Loop::ESCALATE_AFTER_FAILS` in-turn failures, ask this Swarm persona for a 3-line corrective hint (injected as a synthetic tool result). The local model still authors the final answer so Learning/Metrics stay attributed. |
+| `ai.agent.critic` | Boolean | `false` | `PWN::AI::Agent::Curriculum.critic` (S3) | Tool-armed constitutional self-critic reviews (and may `shell`/`extro_verify`) every final answer before it is returned. |
+| `ai.agent.red_team_plan` | Boolean | `false` | `PWN::AI::Agent::Curriculum.red_team_plan` (S4) | Adversarial review of the `plan_first` numbered plan, grounded in Metrics/Mistakes/`extro_drift` telemetry, before the first dispatch. |
+| `ai.agent.counterfactual` | Boolean | `false` | `PWN::AI::Agent::Curriculum.counterfactual` (S2) | On `[REPEATING]`, fork an alt-persona branch, judge both, and record the `(loser, winner)` DPO preference pair. |
+| `ai.agent.hindsight` | Boolean | `true` | `PWN::AI::Agent::Curriculum.hindsight` (C3) | Hindsight Experience Replay — relabel a failed trajectory as `success:true` for whatever it *did* accomplish. Free positive samples from failures. |
+| `ai.agent.verify_as_reward` | Boolean | `false` | `PWN::AI::Agent::Reward.verify_as_reward` (E3) | Ground the LLM judge score by browser-verifying any checkable claim in the final via `extro_verify`; verdict caps/floors `Reward.judge`. |
 | `ai.agent.extrospection.web.anchors` | Array\<String\> | `DEFAULT_WEB_ANCHORS` | `PWN::AI::Agent::Extrospection.probe_web` | URLs the headless browser fingerprints on `extro_snapshot(sections:[:web])`. Alias: `web_anchors`. |
 | `ai.agent.extrospection.web.proxy` | String | - | `Extrospection.probe_web` / `.verify` / `.watch` | Upstream proxy for `PWN::Plugins::TransparentBrowser` (e.g. `tor`, `http://127.0.0.1:8080`). |
 | `ai.agent.extrospection.web.max_anchors` | Integer | `8` | `Extrospection.probe_web` | Cap on anchors rendered per snapshot. |
@@ -371,9 +379,14 @@ agent system prompt.
 
 `pwn.yaml` is the only file you edit; everything else is machine-written
 state. See **[Persistence](Persistence.md)** for the full map
-(`memory.json`, `memory.idx`, `learning.jsonl`, `mistakes.json`,
-`metrics.json`, `extrospection.json`, `sessions/`, `skills/`,
-`finetune/`, `cron/`, `agents.yml`, `swarm/`).
+(`.schema`, `memory.json`, `memory.idx`, `learning.jsonl`,
+`preferences.jsonl`, `mistakes.json`, `metrics.json`,
+`reward_sentinel.json`, `extrospection.json`, `sessions/`,
+`skills/<name>/SKILL.md`, `curriculum/`, `finetune/`, `cron/`,
+`agents.yml`, `swarm/`, `backup/`, `quarantine/`).
+
+`pwn setup --migrate` verifies (and `--fix` autorepairs) every
+one of them against the running gem version.
 
 Multi-agent personas are **not** configured here - they live in
 `~/.pwn/agents.yml` and are managed with `agent_spawn` / `agent_list`

data/documentation/Contributing.md

@@ -5,10 +5,11 @@
 ```text
 lib/pwn/                # all namespaces
 lib/pwn/setup.rb        # PWN::Setup - doctor/provisioner data tables
+lib/pwn/migrate.rb      # PWN::Migrate - ~/.pwn state doctor / auto-migrator
 lib/pwn/plugins/        # 66 plugin modules
 lib/pwn/ai/agent/       # agent core
 lib/pwn/ai/agent/tools/ # LLM tool registrations
-bin/                    # 53 pwn_* drivers (incl. pwn_setup)
+bin/                    # 52 pwn_* drivers + pwn (incl. pwn_setup)
 spec/                   # RSpec (incl. conventions_spec)
 documentation/          # this wiki + diagrams
 ```
@@ -44,7 +45,13 @@ rake            # rubocop + rspec - must be zero offenses
    set, reference it from `PWN::Setup::PROFILES`. That single edit makes
    `pwn setup` install it on every OS and every install path (gem, git,
    Docker, Packer, Vagrant, CI). **Do not** add a new bash provisioner.
-7. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
+7. **If it persists a new file under `~/.pwn/`**, add **one entry** to
+   `PWN::Migrate::STATE_FILES` in `lib/pwn/migrate.rb` (owner, kind,
+   `:fix` strategy, shallow verifier). If the change breaks *existing*
+   files, bump `PWN::Migrate::SCHEMA_VERSION` and append an idempotent
+   lambda to `PWN::Migrate::MIGRATIONS`. `pwn setup --migrate --fix`
+   then heals every user's `~/.pwn` on upgrade.
+8. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
    relevant `.dot` in `documentation/diagrams/dot/` → `./build.sh`.
 
 ## Commit / release

data/documentation/Cron.md

@@ -24,6 +24,26 @@ invokes `PWN::Cron.run(<id>)` on schedule.
 | `cron_enable` / `cron_disable` | Toggle without deleting |
 | `cron_remove` | Delete from `jobs.yml` (does **not** scrub crontab - `crontab -e` yourself) |
 
+## Seeded self-improvement jobs (`PWN::Cron.install_defaults`)
+
+`pwn setup --migrate` (schema `v1`) seeds two jobs into every fresh
+`~/.pwn/cron/jobs.yml`:
+
+| Name | Schedule | Ruby |
+|---|---|---|
+| `curriculum_practice_nightly` | `0 3 * * *` | `PWN::AI::Agent::Curriculum.practice(limit: 3)` |
+| `curriculum_train_weekly` | `0 4 * * 0` | `PWN::AI::Agent::Curriculum.train_and_gate(dry_run: true)` |
+
+The first practises the top unresolved `Mistakes` under `Reward.judge` and
+auto-`resolve`s any it now solves; the second exports SFT + DPO datasets to
+`~/.pwn/finetune/`, LoRA-trains a `pwn-vN+1` local model, replays the
+`Mistakes.top` set on both, and only promotes the new adapter when it wins.
+Set `dry_run: false` (via `pwn-ai-cron` or `cron_create`) once a local
+trainer is installed. See [Reinforcement Learning](Reinforcement-Learning.md).
+
+`cron_disable(id:)` turns either off; `install_defaults` is idempotent and
+never overwrites a job you already have with the same name.
+
 ## Example
 
 ```ruby
@@ -57,6 +77,6 @@ yyyy-mm-dd]` so the injected MEMORY block stops calcifying into
 confidently-wrong priors - see [Extrospection § revalidate_memory](Extrospection.md).
 
 **See also:** [Sessions](Sessions.md) · [Extrospection](Extrospection.md) ·
-[CLI Drivers](CLI-Drivers.md)
+[Reinforcement Learning](Reinforcement-Learning.md) · [CLI Drivers](CLI-Drivers.md)
 
 [← Home](Home.md)

data/documentation/Diagrams.md

@@ -1,6 +1,6 @@
 # PWN Data-Flow Diagrams
 
-27 SVG diagrams, all rendered from Graphviz sources in
+28 SVG diagrams, all rendered from Graphviz sources in
 [`diagrams/dot/`](diagrams/dot/) with a single shared visual theme
 (see [`_THEME.md`](diagrams/dot/_THEME.md)). Rebuild everything with:
 
@@ -55,11 +55,15 @@ groups) so lines never criss-cross.
 [source](diagrams/dot/mistakes-negative-feedback.dot) · doc: [Mistakes](Mistakes.md)
 ![mistakes-negative-feedback](diagrams/mistakes-negative-feedback.svg)
 
+### Reinforcement Learning - Reward + Curriculum
+[source](diagrams/dot/reinforcement-learning.dot) · doc: [Reinforcement Learning](Reinforcement-Learning.md)
+![reinforcement-learning](diagrams/reinforcement-learning.svg)
+
 ### Multi-Provider LLM Integration
 [source](diagrams/dot/ai-integration-tool-calling.dot) · doc: [AI Integration](AI-Integration.md)
 ![ai-integration-tool-calling](diagrams/ai-integration-tool-calling.svg)
 
-### Agent Tool Registry (10 toolsets · 61 tools)
+### Agent Tool Registry (10 toolsets · 71 tools)
 [source](diagrams/dot/agent-tool-registry.dot) · doc: [Agent Tool Registry](Agent-Tool-Registry.md)
 ![agent-tool-registry](diagrams/agent-tool-registry.svg)
 

data/documentation/Drivers.md

@@ -43,7 +43,7 @@ puts result
 | Artifact | Made with | Consumed by |
 |---|---|---|
 | `bin/pwn_<name>` | template above | shell / CI |
-| `~/.pwn/skills/<name>.md` | `learning_distill_skill` | every future pwn-ai prompt |
+| `~/.pwn/skills/<name>/SKILL.md` | `learning_distill_skill` | every future pwn-ai prompt |
 | `cron` job | `cron_create(ruby: '...')` | system crontab → unattended |
 
 **See also:** [CLI Drivers](CLI-Drivers.md) · [Cron](Cron.md) ·

data/documentation/General-PWN-Usage.md

@@ -14,9 +14,11 @@ $ pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/   # headless driver
 $ pwn setup                   # doctor: which PWN:: capabilities are usable here?
 $ pwn setup --profile web     # install what TransparentBrowser / Burp / ZAP need
 $ pwn setup --list-profiles   # core · ai · web · net · db · sdr · vision · voice · exploit · hardware · full
+$ pwn setup --migrate --fix   # after `gem update pwn`: verify + autofix ~/.pwn state
 ```
 
-See [Installation](Installation.md) for every flag and the `PWN::Setup` API.
+See [Installation](Installation.md) for every flag and the
+`PWN::Setup` / `PWN::Migrate` API.
 
 ## Inside the REPL
 
@@ -25,6 +27,7 @@ PWN.help                            # top-level help
 PWN::Plugins.constants.sort         # list all 66 plugins
 PWN::Plugins::NmapIt.help           # per-plugin usage
 PWN::Setup.check                    # capability doctor from inside the REPL
+PWN::Migrate.status                 # ~/.pwn state-file compatibility rows
 ls PWN::Plugins::BurpSuite          # Pry: list methods
 show-source PWN::SAST::SQL.scan     # Pry: read the code
 history                             # what you've typed → copy into a driver
@@ -36,11 +39,14 @@ history                             # what you've typed → copy into a driver
 |---|---|
 | `pwn-ai` | Enter the agent TUI (SHIFT+ENTER = newline, ENTER = submit) |
 | `pwn-asm` | Multi-line assembly ↔ opcode workbench |
+| `pwn-mesh` | Meshtastic serial / MQTT client (Ruby ≥ 4.0) |
 | `pwn-vault` | Decrypt → edit `~/.pwn/pwn.yaml` in `$EDITOR` → re-encrypt |
 | `pwn-ai-memory` | Inspect / edit `~/.pwn/memory.json` |
 | `pwn-ai-sessions` | List / view / delete transcripts |
 | `pwn-ai-cron` | List / run scheduled jobs |
 | `pwn-ai-delegate` | Hand a task to a Swarm persona |
+| `toggle-pwn-ai-debug` | Show/hide raw tool_calls JSON |
+| `toggle-pwn-ai-speaks` | TTS every final answer on/off |
 | `welcome-banner` | Redraw a random `PWN::Banner` |
 | `toggle-pager` | Pry pager on/off |
 

data/documentation/Home.md

@@ -20,7 +20,7 @@
 | [Installation](Installation.md) | `gem install pwn` → `pwn setup` doctor/provisioner · capability profiles · `--migrate` state doctor |
 | [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
 | [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
-| **[All Data-Flow Diagrams](Diagrams.md)** | **27 SVGs** in one scrollable page |
+| **[All Data-Flow Diagrams](Diagrams.md)** | **28 SVGs** in one scrollable page |
 
 ## 🚪 Entry Points