pwn 0.5.661 → 0.5.662

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a771af76d15bb7d7bf172b6c096f5902b5dd868793593e889b2376885cf84c19
-  data.tar.gz: 4beecdae03ebe816005ebdefa85d131bf12ea32c9e0585f759b25b11681412c7
+  metadata.gz: 4df999d2170ed79823d65f8ec78c2f2b7e54f818d965f1758e9c51370723a70d
+  data.tar.gz: 701ecebc0de769e0e299a10969002e9dd64581e0e033224ffc93be7137c2db08
 SHA512:
-  metadata.gz: f413d3853e97f512b1a600503f47509f0afc0918a6dbe4be2b1efd9d23e4acc267d2eba6d82a7fdf6a6b2ac6408003c084a486c2cdc8d4ea4e0cf4f14651d59f
-  data.tar.gz: 599d5fdeab672da7018878e4a836d4fd9fdf76fb27e797208aabee9fb3a359ae988c42f39f1c09c17352c80d826ecf35445d7b0a245c8fc15af54675a783506c
+  metadata.gz: cd2d20216c848affe6ab50549054c589d2805d152da9d446768dfafb501c762ee23abdffbab22ddce38bfd11950de1101b051ae4266da6a47c37226655f8795a
+  data.tar.gz: 6c03147a77c31db940b5d14b55bd6848a4cfa7bd549dc622326d614e94b439baceaab106ba37588b8931567245c42eaaf0aba28dcbc899093b0b9151b457520b

data/README.md

@@ -41,9 +41,33 @@ Full page: [What is PWN](documentation/What-is-PWN.md)
 
 #### **Why PWN** ####
 
+Here's what `grok-4.5` has to say about pwn (more specifically `pwn-ai`):
+```
+pwn.ai:grok/grok-4.5/0:500K[CURRENT_VERSION]:002 >>> Briefly describe your take on the reinforced learning feedback loop implemented within `pwn-ai` in clear, concise English so that a human understands your response.
+
+[ <TIMESTAMP> → pwn-ai → task ]   Goal: Briefly describe your take on the reinforced learning feedback loop implemented within `pwn-ai` in clear, concise English so that a human understands your response.
+  Tangible tasks (6) — each task may leverage one or more tools to complete its objective(s):
+    task 1/6: Review available knowledge of pwn-ai architecture and any reinforced learning elements
+    task 2/6: Identify the key stages of the feedback loop used for reinforcement
+    task 3/6: Summarize how actions, rewards, and model updates connect in that loop
+    task 4/6: Draft a brief plain-English explanation of the overall take on the loop
+    task 5/6: Refine the draft for clarity and conciseness suitable for a human reader
+    task 6/6: Present the final short description
+
+... performs tasks ...
+
+**My take, in plain English:**
+
+pwn-ai’s reinforcement loop is mostly **learning in context**, not only weight training.
+
+On every turn the agent acts with tools. Each result is scored in a few ways: quick “did this tool call really fail?” checks, longer-term tool success stats, and—when a final answer lands—a judge that scores whether the *goal* was actually met, plus per-step credit for which tool calls helped or hurt. Failures become fingerprints (mistakes) with fixes; wins become outcomes, exemplars, memory lessons, and sometimes skills. All of that is written back into the next prompt as “what worked,” “what not to repeat,” and “which tools pay off,” so behavior improves on the following run without waiting for a model train.
+
+Around that core sit self-checks: a sentinel that distrusts inflated success rates when the judge disagrees, night jobs that practice the worst repeating mistakes, and optional export of preference pairs for a gated LoRA update when a trainer and GPU exist. So the loop is: **act → measure honestly → remember (and fix) → bias the next act**—with real weight updates as an optional outer ring, not the main daily path.
+```
+
 Offensive work is hard because the *tools* do not fit together. PWN's fix is
-simple: every capability is a plain Ruby method with the same `opts = {}`
-shape. That one idea means the *same* code runs:
+simple: every capability is a ruby module that can be used with other modules to produce
+a diverse set of security "drivers". That one idea means the *same* code runs:
 
 - live in the REPL
 - from an LLM agent in a tool loop

data/documentation/How-PWN-Works.md

@@ -28,7 +28,7 @@ hardware).
 | Module | Role |
 |---|---|
 | `Loop` | plan → **TaskSummarizer** briefs → dispatch tool_calls → observe → repeat until final answer; tightens runway when recent turns exhausted the budget |
-| **`TaskSummarizer`** | Executive UX: `emit_plan!` (full goal once) · `about_to` per tool batch (`tool_counts_phrase` + `intent_phrase`) · `last_brief_fp` dedup · plan_idx advance |
+| **`TaskSummarizer`** | Executive UX: English tasks primary  -  `emit_plan!` · `about_to` as `task k/n` + via tools · Loop `plan_context` injection · clearer `plan_idx` advance |
 | `Registry` | JSON-Schema function definitions grouped into 12 **toolsets** · **78 tools** |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / EXTROSPECTION blocks |

data/documentation/pwn-ai-Agent.md

@@ -117,16 +117,18 @@ full `Loop.run` under a persona overlay) that share a JSONL bus. See
 
 | Surface | When | Content |
 |---|---|---|
-| `emit_plan!` | User submit | **Full** goal + ordered tangible tasks (each task may need many tools) |
-| `about_to` | Before each tool batch | `Next: shell×2 (search) [task 2/5: ...]` - capabilities + counts + intent, not raw argv |
-| `record!` | After each tool | Silent by default; advances `plan_idx`; verbose progress only if `task_summary_verbose` |
-| `flush!` | End of turn | Optional closing brief |
+| `emit_plan!` | User submit | **Full** goal + ordered plain-English tangible tasks (each may need many tools) |
+| `about_to` | Before each tool batch | **Primary:** `task k/n: <english>`  -  **secondary:** `via shell×2 (search)` (not raw argv) |
+| `plan_context` / `active_task_prompt` | Into Loop messages | Same English tasks steer tool choice (not TUI-only) |
+| `record!` | After each tool | Advances `plan_idx`; emits English advancement brief when the index moves; verbose progress only if `task_summary_verbose` |
+| `flush!` | End of turn | Optional closing brief with active `task k/n` |
 
 **Dedup rules (operational):**
 
 - Fingerprint = whitespace-normalized brief; `last_brief_fp` match → return `nil` (no emit).
 - Intent verbs distinguish batches that share tools (`shell` search ≠ `shell` edit).
-- Goal string only on the plan line when a plan exists (`why_bit(with_goal: !has_plan)`).
+- Goal string only on the plan line when a plan exists (`why_bit(with_goal:)` when no plan bit).
+- Advancement needs a PRM +1 streak or a clear phase shift after tools on the active task (not a blind every-3-tools hop).
 - REPL contract: `on_tool.call('task', full_summary_text, '')` - result empty, no truncation.
 
 **Budget pressure:** when unresolved `agent_loop` / `assistant_answer` budget-exhaustion fingerprints dominate, `Loop.budget_exhaustion_hot?` tightens the live turn (stricter `max_iters` on local engines than remote), forces a text-only tail, skips counterfactual forks, and still flushes task state + Learning on the exhaust path.

data/lib/pwn/ai/agent/learning.rb

@@ -485,14 +485,43 @@ module PWN
             Thread.current[:pwn_pending_pref] = nil
           end
 
+          # Soft plan-quality feature (W3) — tag only; not full DPO.
+          plan_cov = nil
+          if defined?(Reward) && Reward.respond_to?(:plan_coverage)
+            begin
+              plan_for_cov = opts[:plan]
+              plan_for_cov = opts[:ts_state][:plan] if plan_for_cov.nil? && opts[:ts_state].is_a?(Hash)
+              if plan_for_cov.nil? && defined?(TaskSummarizer)
+                # Recover numbered tasks from the final/request only when caller
+                # did not pass a plan — still keeps TaskSummarizer out of the
+                # credit path (parse is pure text).
+                plan_for_cov = nil
+              end
+              if !plan_for_cov.nil? || opts[:final].to_s.length.positive?
+                plan_cov = Reward.plan_coverage(
+                  plan: plan_for_cov || [],
+                  final: opts[:final],
+                  request: opts[:request],
+                  session_id: session_id
+                )
+                stages_run << :plan_coverage if plan_cov && plan_cov[:total].to_i.positive?
+              end
+            rescue StandardError => e
+              warn "[pwn-ai/learning] plan_coverage swallowed: #{e.class}: #{e.message}"
+            end
+          end
+
           stages_run << :note_outcome
+          outcome_tags = ['auto', 'loop', v[:verdict].to_s]
+          outcome_tags << plan_cov[:tag] if plan_cov && plan_cov[:tag]
+          outcome_tags << "plan_cover=#{plan_cov[:score]}" if plan_cov && plan_cov[:total].to_i.positive?
           note_outcome(
             task: opts[:request].to_s[0, 120],
             success: ok,
             score: v[:score],
             details: "#{v[:verdict]}(#{v[:score].round(2)}) #{v[:rationale]} | #{opts[:final].to_s[0, 200]}",
             session_id: session_id,
-            tags: ['auto', 'loop', v[:verdict].to_s]
+            tags: outcome_tags
           )
 
           stages_run << :fold_judge

data/lib/pwn/ai/agent/loop.rb

@@ -453,10 +453,26 @@ module PWN
           # S4 — adversarial plan review grounded in THIS host's telemetry.
           # P17 — never fork red_team when budget fingerprints dominate: it is
           # another mini agent loop and compounds iteration-budget exhaustion.
+          rt = nil
           if defined?(Curriculum) && !hot
             rt = Curriculum.red_team_plan(request: opts[:request], plan: plan)
             messages << { role: 'user', content: rt } if rt
           end
+          # P2 — unify TaskSummarizer plan object with surviving outline so the
+          # task line and adversarial/plan_first plan are one thing. Index-only;
+          # credit stays in Reward. Optional: only when ts_state is live.
+          if defined?(TaskSummarizer) && opts[:ts_state].is_a?(Hash)
+            outline = [plan.to_s, rt.to_s].reject { |s| s.to_s.strip.empty? }.join("\n")
+            begin
+              TaskSummarizer.unify_plan!(
+                state: opts[:ts_state],
+                outline: outline,
+                source: rt ? :red_team : :plan_first
+              )
+            rescue StandardError => e
+              warn "[pwn-ai/loop] unify_plan! swallowed: #{e.class}: #{e.message}"
+            end
+          end
           # W3/P22 — extract predicted p(success) for calibration tracking.
           # Accept p(success)=0.7 | p(success) = .7 | confidence=0.7 on last lines.
           predicted = plan[/p\(\s*success\s*\)\s*=\s*([01]?(?:\.\d+)?)/i, 1]&.to_f
@@ -706,13 +722,33 @@ module PWN
           nil
         end
 
+        # Push active English task into model messages when plan_idx changes.
+        # Uses TaskSummarizer.active_task_prompt (full plan_context on first
+        # force, compact focus thereafter). No-ops when already injected.
+        private_class_method def self.inject_task_focus!(opts = {})
+          state = opts[:state]
+          messages = opts[:messages]
+          return nil unless state.is_a?(Hash) && messages.is_a?(Array)
+          return nil unless defined?(TaskSummarizer) && TaskSummarizer.enabled?
+
+          text =
+            (TaskSummarizer.active_task_prompt(state: state, force: opts[:force]) if TaskSummarizer.respond_to?(:active_task_prompt))
+          return nil if text.to_s.strip.empty?
+
+          messages << { role: 'user', content: text }
+          text
+        rescue StandardError => e
+          warn "[pwn-ai/loop] inject_task_focus! swallowed: #{e.class}: #{e.message}"
+          nil
+        end
+
         # On user-request submit: break the goal into tangible tasks and
         # emit the FULL plan on the pwn-ai task line (no truncation).
         private_class_method def self.task_summary_plan!(opts = {})
           state = opts[:state]
           return nil unless state && defined?(TaskSummarizer) && TaskSummarizer.enabled?
 
-          line = TaskSummarizer.emit_plan!(state, request: opts[:request])
+          line = TaskSummarizer.emit_plan!(state: state, request: opts[:request])
           emit_task_summary(line: line, on_tool: opts[:on_tool]) if line
           line
         rescue StandardError
@@ -727,8 +763,8 @@ module PWN
           return nil unless state && defined?(TaskSummarizer) && TaskSummarizer.enabled?
 
           line = TaskSummarizer.about_to(
-            opts[:name],
-            opts[:args],
+            name: opts[:name],
+            args: opts[:args],
             state: state,
             request: opts[:request],
             tools: opts[:tools]
@@ -746,7 +782,12 @@ module PWN
           state = opts[:state]
           return nil unless state && defined?(TaskSummarizer)
 
-          line = TaskSummarizer.record!(state, opts[:name], opts[:args], opts[:result])
+          line = TaskSummarizer.record!(
+            state: state,
+            name: opts[:name],
+            args: opts[:args],
+            result: opts[:result]
+          )
           # record! is silent by default; only verbose progress returns a line
           emit_task_summary(line: line, on_tool: opts[:on_tool]) if line
           line
@@ -758,7 +799,7 @@ module PWN
           state = opts[:state]
           return nil unless state && defined?(TaskSummarizer)
 
-          line = TaskSummarizer.flush!(state)
+          line = TaskSummarizer.flush!(state: state)
           # Closing brief only — still no result payload on the task row
           emit_task_summary(line: line, on_tool: opts[:on_tool]) if line
           line
@@ -780,7 +821,7 @@ module PWN
           session_id = opts[:session_id]
           on_tool = opts[:on_tool]
           # Live coalesced "what am I doing" lines for the TUI (not a model tool).
-          ts_state = (TaskSummarizer.fresh(request: request) if defined?(TaskSummarizer) && TaskSummarizer.enabled?)
+          ts_state = (TaskSummarizer.fresh(request: request) if defined?(TaskSummarizer) && TaskSummarizer.enabled? && Thread.current[:pwn_reflect_depth].to_i.zero?)
           engine = active_engine
           local  = engine == :ollama
           system_role_content = opts[:system_role_content] ||= PWN::AI::Agent::PromptBuilder.build(session_id: session_id, request: request)
@@ -789,6 +830,10 @@ module PWN
           expose_current_session(session_id: session_id)
           Mistakes.check_user_correction(request: request, session_id: session_id) if defined?(Mistakes)
 
+          # Initial tool pool from the user request (bootstrap only). After
+          # TaskSummarizer.emit_plan! we re-rank using English tangible tasks
+          # so generated tasks — not the bare request — drive which tools
+          # the model may call.
           tools    = Registry.definitions(enabled: opts[:enabled_toolsets], relevance: request)
           messages = [{ role: 'system', content: system_role_content }]
           messages.concat(Learning.exemplars_for(request: request)) if local && defined?(Learning) && Learning.respond_to?(:exemplars_for)
@@ -797,15 +842,32 @@ module PWN
 
           # Show full tangible-task breakdown as soon as the user submits.
           task_summary_plan!(state: ts_state, request: request, on_tool: on_tool)
+          # Re-bind tools from English plan so task list is the sole driver of
+          # tool exposure/ranking (Registry keyword router + CORE).
+          if ts_state.is_a?(Hash) && defined?(TaskSummarizer) && TaskSummarizer.respond_to?(:relevance_query)
+            rq = TaskSummarizer.relevance_query(state: ts_state, request: request)
+            tools = Registry.definitions(enabled: opts[:enabled_toolsets], relevance: rq) unless rq.to_s.strip.empty?
+          end
+          # English-task-as-primary: inject the same tangible tasks into model
+          # context so tool selection follows the plan, not only the TUI banner.
+          inject_task_focus!(messages: messages, state: ts_state, force: true)
 
           predicted = nil
           Thread.current[:pwn_plan_predicted] = nil
           cal_state = calibration_state
           force_plan = cal_state[:force_plan]
           if (force_plan || agent_flag(key: :plan_first, default: local) || budget_exhaustion_hot?) && !Array(tools).empty?
-            predicted = plan_first(messages: messages, request: request)
+            predicted = plan_first(messages: messages, request: request, ts_state: ts_state)
             # P22 — prefer explicit return; fall back to thread stash
             predicted = Thread.current[:pwn_plan_predicted] if predicted.nil?
+            # unify_plan! may have rewritten English tasks — force refresh focus.
+            # Re-rank tools from (possibly unified) English plan; never from
+            # PLAN: tool-call scaffold jargon (unify_plan! refuses that).
+            if ts_state.is_a?(Hash) && defined?(TaskSummarizer) && TaskSummarizer.respond_to?(:relevance_query)
+              rq = TaskSummarizer.relevance_query(state: ts_state, request: request)
+              tools = Registry.definitions(enabled: opts[:enabled_toolsets], relevance: rq) unless rq.to_s.strip.empty?
+            end
+            inject_task_focus!(messages: messages, state: ts_state, force: true)
           end
           if budget_exhaustion_hot?
             hot_hint = if active_engine == :ollama
@@ -837,6 +899,9 @@ module PWN
           max_iters.times do |i|
             # 3.1 — compact history on local so tool dumps don't fill num_ctx
             compact_history!(messages: messages) if local
+            # English-task-as-primary: when plan_idx advanced, tell the model
+            # which plain-English task is active before the next tool batch.
+            inject_task_focus!(messages: messages, state: ts_state)
 
             # P17 — on the final iteration, strip tools and demand a plain-text
             # answer. Without this the model happily emits one more tool_calls
@@ -934,7 +999,7 @@ module PWN
                 next
               end
               append_session(session_id: session_id, role: 'assistant', content: text)
-              Learning.auto_introspect(session_id: session_id, request: request, final: text, predicted: predicted) if defined?(Learning) && should_auto_introspect?(local: local, turn_fails: turn_fails, iter: i)
+              Learning.auto_introspect(session_id: session_id, request: request, final: text, predicted: predicted, plan: ts_state && ts_state[:plan], ts_state: ts_state) if defined?(Learning) && should_auto_introspect?(local: local, turn_fails: turn_fails, iter: i)
               task_summary_flush!(state: ts_state, on_tool: on_tool)
               return text
             end
@@ -1039,7 +1104,7 @@ module PWN
                 )
               end
               append_session(session_id: session_id, role: 'assistant', content: msg)
-              Learning.auto_introspect(session_id: session_id, request: request, final: msg, predicted: predicted) if defined?(Learning) && should_auto_introspect?(local: local, turn_fails: turn_fails, iter: i)
+              Learning.auto_introspect(session_id: session_id, request: request, final: msg, predicted: predicted, plan: ts_state && ts_state[:plan], ts_state: ts_state) if defined?(Learning) && should_auto_introspect?(local: local, turn_fails: turn_fails, iter: i)
               task_summary_flush!(state: ts_state, on_tool: on_tool)
               return msg
             end
@@ -1068,14 +1133,7 @@ module PWN
             )
           end
           append_session(session_id: session_id, role: 'assistant', content: final_msg)
-          if defined?(Learning) && should_auto_introspect?(local: local, turn_fails: turn_fails, iter: max_iters)
-            Learning.auto_introspect(
-              session_id: session_id,
-              request: request,
-              final: final_msg,
-              predicted: predicted
-            )
-          end
+          Learning.auto_introspect(session_id: session_id, request: request, final: final_msg, predicted: predicted, plan: ts_state && ts_state[:plan], ts_state: ts_state) if defined?(Learning) && should_auto_introspect?(local: local, turn_fails: turn_fails, iter: max_iters)
           task_summary_flush!(state: ts_state, on_tool: on_tool)
           final_msg
         end

data/lib/pwn/ai/agent/reflect.rb

@@ -30,7 +30,24 @@ module PWN
       # local Ollama model EXECUTE the task while a frontier model WRITES
       # the durable lessons about it — the local model then reads back
       # distilled reasoning it could never have produced itself.
+      #
+      # IMPLEMENTATION NOTE
+      # -------------------
+      # Reflect.on MUST call the engine's text .chat API directly — never
+      # Loop.run. Nesting Loop.run re-enters TaskSummarizer/PromptBuilder/
+      # auto_introspect and produces SystemStackError at the Pry after_read
+      # boundary whenever module_reflection is enabled. A thread-local
+      # depth counter still gates re-entrant Reflect.on (e.g. chat_for_plan
+      # inside an outer agent turn that also judges/reflects).
       module Reflect
+        ENGINE_MODS = {
+          openai: 'PWN::AI::OpenAI',
+          grok: 'PWN::AI::Grok',
+          ollama: 'PWN::AI::Ollama',
+          anthropic: 'PWN::AI::Anthropic',
+          gemini: 'PWN::AI::Gemini'
+        }.freeze
+
         # Supported Method Parameters::
         # response = PWN::AI::Agent::Reflect.on(
         #   request: 'required - String - What you want the AI to reflect on',
@@ -55,21 +72,36 @@ module PWN
 
           ai_module_reflection = PWN::Env[:ai][:module_reflection]
 
+          # Re-entrancy guard: nested Reflect.on (TaskSummarizer inside a
+          # Reflect call, Reward.judge during auto_introspect, etc.) returns
+          # nil so the outer caller can fall back. Never Loop.run from here.
+          return nil if Thread.current[:pwn_reflect_depth].to_i.positive?
+
           if ai_module_reflection && request.length.positive?
             override = opts[:engine] || PWN::Env.dig(:ai, :reflect_engine)
             model    = opts[:model]  || PWN::Env.dig(:ai, :reflect_model)
             engine   = (override || PWN::Env[:ai][:active]).to_s.downcase.to_sym
-            valid_ai_engines = PWN::AI.help.reject { |e| e.downcase == :agent }.map(&:downcase)
+            valid_ai_engines = ENGINE_MODS.keys
             raise "ERROR: Unsupported AI engine. Supported engines are: #{valid_ai_engines}" unless valid_ai_engines.include?(engine)
 
             warn "AI Reflection is enabled.  Ensure #{engine} has been authorized for use and/or requests are sanitized properly." unless suppress_pii_warning
-            response = with_engine(engine: override, model: model) do
-              PWN::AI::Agent::Loop.run(
-                request: request.chomp,
-                system_role_content: system_role_content,
-                enabled_toolsets: [],
-                spinner: spinner
-              )
+            Thread.current[:pwn_reflect_depth] = Thread.current[:pwn_reflect_depth].to_i + 1
+            begin
+              response = with_engine(engine: override, model: model) do
+                engine_chat(
+                  engine: engine,
+                  request: request.chomp,
+                  system_role_content: system_role_content,
+                  spinner: spinner
+                )
+              end
+            ensure
+              d = Thread.current[:pwn_reflect_depth].to_i - 1
+              if d.positive?
+                Thread.current[:pwn_reflect_depth] = d
+              else
+                Thread.current[:pwn_reflect_depth] = nil
+              end
             end
           end
 
@@ -78,7 +110,23 @@ module PWN
           raise e
         end
 
-        # Temporarily override PWN::Env[:ai][:active] so Loop.run routes to
+        # Direct provider .chat — never Loop.run (avoids after_read stack blow).
+        private_class_method def self.engine_chat(opts = {})
+          engine = opts[:engine].to_s.downcase.to_sym
+          mod_name = ENGINE_MODS[engine]
+          raise "ERROR: Unsupported AI engine: #{engine}" unless mod_name
+
+          mod = Object.const_get(mod_name)
+          raise "ERROR: #{mod_name} does not implement .chat" unless mod.respond_to?(:chat)
+
+          mod.chat(
+            request: opts[:request],
+            system_role_content: opts[:system_role_content],
+            spinner: opts[:spinner]
+          )
+        end
+
+        # Temporarily override PWN::Env[:ai][:active] so engine_chat routes to
         # the teacher engine, restoring afterwards even on raise. No-op when
         # engine is nil/blank or PWN::Env[:ai] is frozen.
         private_class_method def self.with_engine(opts = {})

data/lib/pwn/ai/agent/reward.rb

@@ -210,6 +210,84 @@ module PWN
           []
         end
 
+        # ----------------------------------------------------------------
+        # Plan-quality soft signal (W3 feature / Learning tag)
+        # ----------------------------------------------------------------
+        # Cheap heuristic: did the final (+ optional tool trace) cover the
+        # tangible plan tasks? Not full DPO — trajectory-shaped pairs come
+        # later. Score is a soft feature for calibration / tagging only.
+        #
+        # Supported Method Parameters::
+        # r = PWN::AI::Agent::Reward.plan_coverage(
+        #   plan: 'required - Array of task strings or outline text',
+        #   final: 'required - assistant final answer',
+        #   request: 'optional - original user request',
+        #   trace: 'optional - Array of tool-result strings',
+        #   session_id: 'optional - load trace from session when trace empty'
+        # )
+        # => { score: 0.0..1.0, covered: N, total: M, missing: [...], tag: 'plan_cover_high|mid|low' }
+        public_class_method def self.plan_coverage(opts = {})
+          plan = opts[:plan]
+          tasks =
+            case plan
+            when Array then plan.map(&:to_s)
+            when String
+              if defined?(TaskSummarizer) && TaskSummarizer.respond_to?(:parse_outline_tasks)
+                TaskSummarizer.parse_outline_tasks(outline: plan)
+              else
+                plan.to_s.split(/\n+/).map { |l| l.sub(/\A(?:\d+[.):]|[-*•])\s+/, '').strip }
+              end
+            else
+              Array(plan).map(&:to_s)
+            end
+          tasks = tasks.map { |t| t.to_s.gsub(/\s+/, ' ').strip }.reject(&:empty?)
+          return { score: 0.0, covered: 0, total: 0, missing: [], tag: 'plan_cover_none' } if tasks.empty?
+
+          final = opts[:final].to_s
+          request = opts[:request].to_s
+          trace = Array(opts[:trace])
+          trace = load_trace(session_id: opts[:session_id]) if trace.empty? && opts[:session_id]
+          blob = "#{final}\n#{request}\n#{trace.join("\n")}".downcase
+
+          covered = []
+          missing = []
+          tasks.each do |task|
+            stems = task.downcase.scan(/[a-z0-9]{4,}/).uniq
+            # Drop ultra-generic plan fillers that would false-positive everything.
+            stems.reject! { |s| %w[result results report verify complete completion present carry work task step this that with from into].include?(s) }
+            if stems.empty?
+              covered << task
+              next
+            end
+            # A task is covered when >= half of its distinctive stems appear
+            # in final+trace (soft — not DPO-grade evidence).
+            hits = stems.count { |s| blob.include?(s) }
+            need = [1, (stems.length / 2.0).ceil].max
+            if hits >= need
+              covered << task
+            else
+              missing << task
+            end
+          end
+
+          total = tasks.length
+          score = (covered.length.to_f / total).round(3).clamp(0.0, 1.0)
+          tag =
+            if score >= 0.75 then 'plan_cover_high'
+            elsif score >= 0.4 then 'plan_cover_mid'
+            else 'plan_cover_low'
+            end
+          {
+            score: score,
+            covered: covered.length,
+            total: total,
+            missing: missing.first(6),
+            tag: tag
+          }
+        rescue StandardError
+          { score: 0.0, covered: 0, total: 0, missing: [], tag: 'plan_cover_error' }
+        end
+
         # ----------------------------------------------------------------
         # R3 — Reward-hacking sentinel
         # ----------------------------------------------------------------
@@ -1306,6 +1384,7 @@ module PWN
               # Tier 1 — reward signal
               PWN::AI::Agent::Reward.judge(request: req, final: text, session_id: sid)     # R1 ORM → {score:, verdict:, rationale:}
               PWN::AI::Agent::Reward.prm(request: req, session_id: sid)                    # R2 PRM → per-step credit
+              PWN::AI::Agent::Reward.plan_coverage(plan: tasks, final: text, session_id: sid) # soft plan-quality feature
               PWN::AI::Agent::Reward.sentinel                                              # R3 reward-hacking detector
               PWN::AI::Agent::Reward.reset_sentinel                                        # wipe corrupt window + distrust
               PWN::AI::Agent::Reward.warm_sentinel                                         # P10 fill R3 window from Learning outcomes