shifty 0.5.0 → 0.6.0

data/docs/planning/artifacts/.round1-specialist-outputs.md

@@ -0,0 +1,196 @@
+# Round 1 verbatim specialist outputs (reference for synthesis & implementation)
+
+## software-architect (A1–A7)
+
+**A1: Apply policy at INGRESS (the consuming worker's pull), via a single intake seam plus a thin policy-applying supply proxy for in-task shifts.**
+Sites today: worker.rb:64 `value = supply&.shift`; worker.rb:66 `Fiber.yield @task.call(...)`; in-task `supply.shift` in filter_worker/batch_worker/trailing_worker (dsl.rb:56,86,122); direct `handoff`/Fiber.yield in source_worker/splitter_worker (dsl.rb:17,105,133). Make policy a property of *how a worker receives its value* (§6.2 names the receiving worker). Producer-side direct handoffs need nothing — their outputs are frozen at the downstream consumer's intake. Sketch:
+
+```ruby
+# worker.rb
+def workflow
+  @machine ||= Fiber.new do
+    loop do
+      value = intake(@supply&.shift)          # primary intake seam
+      if criteria_passes?
+        Fiber.yield perform_task(value, policy_supply)
+      else
+        Fiber.yield value                       # already policy-applied
+      end
+    end
+  end
+end
+
+def intake(value)
+  effective_policy.apply(value, worker: self)   # freeze / copy / passthrough
+end
+
+def perform_task(value, supply_proxy)
+  @task.call(value, supply_proxy, @context)
+rescue FrozenError => e
+  raise PolicyViolation.new(worker: self, policy: effective_policy,
+                            receiver: e.receiver, value: value, cause: e)
+end
+
+def policy_supply
+  @policy_supply ||= PolicySupply.new(@supply, self)  # #shift => intake(supply.shift)
+end
+```
+
+`PolicySupply` proxy replaces the raw `supply` as the task's 2nd arg, so filter/batch/trailing's in-task `supply.shift` transparently applies the same policy with zero task-body changes (three concrete uses today — Rule of Three met). §7.3 aliasing still caught: make_shareable freezes the actual object in place, so the producer's later mutation raises at the producer. Rejected simpler version: freeze at the single egress site — misses in-task shifts and makes producer policy govern the boundary, contradicting §5.2.
+
+**A2: `Shifty::Policy` module of three frozen singleton lambdas behind `resolve(name)`; precedence resolution stays inline on Worker.**
+
+```ruby
+# lib/shifty/policy.rb
+module Shifty
+  module Policy
+    Frozen   = ->(value, worker:) { Ractor.make_shareable(value) }   # wrapped for UnshareableValue
+    Isolated = ->(value, worker:) { make_shareable_copy_or_marshal(value) }
+    Shared   = ->(value, worker:) { value }
+
+    TABLE = {frozen: Frozen, isolated: Isolated, shared: Shared}.freeze
+    ALIASES = {hardened: :isolated}.freeze
+    def self.resolve(name)
+      name = canonical(name)   # applies ALIASES + :hardened deprecation warn
+      TABLE.fetch(name) { raise ArgumentError, "unknown policy #{name.inspect}" }
+    end
+  end
+end
+```
+
+Not a class hierarchy, not a mixin (policy is a collaborator, not worker state — contrast Taggable). Each apply wraps make_shareable/Marshal failures as UnshareableValue. Precedence inline:
+```ruby
+def effective_policy
+  @effective_policy ||= Policy.resolve(@policy || @pipeline_policy || Shifty.config.default_policy)
+end
+```
+
+**A3: Two attributes — `@policy` (explicit contract) and `@pipeline_policy` (default) — `.with_policy` walks the supply chain; Gang fans out to roster.**
+
+```ruby
+# worker.rb
+attr_accessor :pipeline_policy
+def initialize(p = {}, &block)
+  @policy = p[:policy]      # explicit contract, may be nil
+  @name   = p[:name]        # §5.5 diagnostics
+end
+
+def with_policy(name)
+  Policy.resolve(name)                       # validate eagerly
+  node = self
+  while node.respond_to?(:pipeline_policy=)  # walks Workers and Gangs
+    node.pipeline_policy = name
+    node = node.supply
+  end
+  self
+end
+```
+```ruby
+# gang.rb
+def initialize(workers = [], p = {})
+  self.pipeline_policy = p[:policy] if p[:policy]
+end
+def pipeline_policy=(name)
+  roster.workers.each { |w| w.pipeline_policy = name }
+end
+def with_policy(name)
+  self.pipeline_policy = name
+  self
+end
+```
+Gang#supply returns roster.first.supply, so the walk steps past a gang to its upstream after the gang fans out internally. Rejected: single @policy + declared? flag (forces branching); downstream-walk storage (workers don't know their consumer).
+
+**A4: Consolidate errors into lib/shifty/errors.rb under Shifty::Error base.**
+```ruby
+module Shifty
+  class Error < StandardError; end
+  class WorkerError < Error; end                # reparented, source-compatible
+  class WorkerInitializationError < Error; end  # moved from dsl.rb
+  class PolicyError < Error; end
+  class PolicyViolation  < PolicyError; end     # attrs: worker, policy, receiver, value, cause (§6.2)
+  class UnshareableValue < PolicyError; end     # attrs: worker, policy, value
+end
+```
+(PolicyConflict was proposed as class-only; user decision R2: dropped entirely.)
+
+**A5: Global config.**
+```ruby
+# lib/shifty/configuration.rb
+module Shifty
+  class Configuration
+    attr_accessor :default_policy
+    def initialize; @default_policy = :frozen; end
+  end
+  class << self
+    def config; @config ||= Configuration.new; end
+    def configure; yield config; end
+    def reset_configuration!; @config = Configuration.new; end  # test hook
+  end
+end
+```
+Effective policy memoized at first shift (topology assembled by then); per-handoff re-resolution unnecessary. Thread-safety documentation-only, consistent with worker.rb:117–130.
+
+**A6: `shifty/testing` (pure Ruby) and `shifty/rspec` (opt-in) as separate requires; neither loaded by `require "shifty"`.**
+- lib/shifty/testing.rb: `Shifty::Testing.run(worker, inputs:, policy: nil)` — feeds inputs through the framework so declared/effective policy is exercised (§9.2/§9.3); `Shifty::Testing.mutates_input?(worker, input)` — §6.4 detector: deep-copy, run, compare.
+- lib/shifty/rspec.rb: `RSpec.shared_examples "a policy-safe worker"` (ceiling test §9.4) and `mutate_input` matcher built on the detector.
+
+**A7: Fix trailing_worker to hand off `trail.dup`; route side_worker :hardened through the deprecation shim (Policy.canonical).** DSL constructors already splat options into Worker.new, so policy:/name: pass through for free; only trailing_worker and source_worker build options by hand and need explicit threading. Rejected: internally declaring trailing_worker `policy: :shared` — masks the aliasing instead of fixing it.
+
+**Deferred (YAGNI) per architect:** PolicyConflict validation (now dropped entirely per user); §8.3 shareable? fast path (reopen: benchmarks show copy cost material); Shifty::Value mixin (§11.5 — spec itself says stay unopinionated).
+**New files:** Phase 1: lib/shifty/errors.rb, lib/shifty/policy.rb, lib/shifty/configuration.rb. Phase 2: lib/shifty/testing.rb, lib/shifty/rspec.rb.
+
+## concurrency-analyst (F1–F22, empirical on Ruby 4.0.5 — re-verify on 3.2 CI)
+
+- F1/F2: policy is the *receiving* worker's, applied at intake. Exactly four `supply.shift` read sites (worker.rb:64; dsl.rb:55 filter; dsl.rb:86 batch; dsl.rb:122 trailing) — the minimal enforcement set; no value crosses twice, so no double-copy waste under :isolated.
+- F3: do NOT instrument `handoff`/Fiber.yield — `handoff` is a free DSL function with no access to the executing worker; every internal yield surfaces through the consumer's pull anyway.
+- F4: wrap the supply object ONCE per worker (decorator responding to #shift), substituted at worker.rb:64 and as task's 2nd arg — covers all four sites, zero dsl.rb changes.
+- F5: criteria-bypass path automatically covered (intake happens before the branch).
+- F6: Fiber-local storage registry — YAGNI; `self` is available everywhere needed.
+- **F7 (CRITICAL): make_shareable does NOT reject IO or singleton-methoded objects.** Empirical: proc → Ractor::IsolationError; lazy enumerator → Ractor::Error; IO/File → silently frozen (shareable=true); OpenStruct, Data, singleton-methoded Object → silently frozen. §3.3/§10.1's claims that IO raises are wrong; UnshareableValue never fires for IO unless detection is proactive.
+- **F8: make_shareable(io) freezes the LIVE IO in place** — same object, process-wide: a shared logger/$stdout/file handle frozen for every reference in the process. Materially worse than raising. The :frozen/:isolated wrapper must check IO-like values and raise UnshareableValue proactively BEFORE calling make_shareable.
+- **F9: make_shareable(io, copy: true) duplicates the fd then freezes the duplicate** — new fd opened, unusable, never closed: one leaked fd per :isolated handoff of an IO. Same remedy as F8.
+- F10: singleton-methoded values: Marshal raises TypeError ("singleton can't be dumped") but make_shareable(copy: true) succeeds — a value that failed LOUDLY under :hardened silently succeeds under :isolated. Own migration-guide bullet, own spec.
+- F11: §8.2 short-circuit confirmed structurally: make_shareable(copy: true) returns the SAME object for an already-deeply-frozen Data instance (no copy). CPU amortization still needs §8.4 benchmarks.
+- F12: @context/BatchContext never crosses Fiber.yield (batch hands off collection.compact — a new array); stays mutable per §12. Confirmed out of scope.
+- F13: trailing_worker hands off `trail` itself (dsl.rb:125) while continuing to unshift/pop it → next resume raises FrozenError under :frozen. Fix: hand off `trail.dup`. Required Phase-1 shipped-code fix.
+- F14–F16: batch_worker safe (fresh array per batch + hands off .compact's new array); splitter_worker safe (fresh local per call, hands off elements); filter_worker safe (no closure state). Do NOT "fix" defensively — note as confirmed-safe in spec matrix.
+- F17: side_worker mode: :hardened is the only :hardened reference in the codebase; map to policy: :isolated with deprecation warning.
+- F18: §5.4's Worker#task= does not exist (only lazy `@task ||= default_task`); restate #freeze! motivation as supply=/Roster rewiring.
+- F19: #freeze! must force-materialize the lazy default task (invoke ensure_ready_to_work!) on every worker BEFORE freezing, else a default-task worker raises confusing FrozenError at first shift.
+- F20: #freeze! must also freeze Roster's @workers array — otherwise Gang#append/Roster#push still rewire topology (they set supply= on the NEW unfrozen worker and mutate the array).
+- F21: bare `|` chains have no Roster — Worker#freeze! must walk the .supply chain backward to nil to discover members. Two discovery mechanisms (Gang vs Worker); document which uses which.
+- F22: post-freeze supply= raises plain FrozenError, which is already unambiguous — do NOT add a TopologyFrozenError wrapper (YAGNI; reopen on migration feedback showing confusion).
+
+## test-engineer (house style: rspec-given Given/When/Then; raise_error(/regex/) + structured accessor checks; real values, no doubles for policy behavior)
+
+Load-bearing policy × shape matrix (equivalence classes, not the 3×10 product):
+1. :frozen × Array — `<<` raises PolicyViolation; receiver.equal?(value).
+2. :frozen × Hash-containing-Array — nested mutation raises; receiver reachable-but-not-equal (proves deep traversal, feeds heuristic).
+3. :frozen × Data (scalar members) — v.with(...) returns new frozen instance; original untouched.
+4. :frozen × nil — passthrough.
+5. :isolated × Array — task mutates its copy freely; output includes mutation; upstream original unaffected.
+6. :isolated × Data-with-mutable-Array-member — copy's member mutable without affecting original.
+7. :shared × Array — mutation visible to holders of the same reference.
+8. :shared × IO — passes through untouched, no error.
+Boundary cases: (9) mid-task supply.shift under upstream :frozen raises PolicyViolation like primary intake (filter_worker); (10) splitter under :frozen — EACH yielded part frozen, not just the last (fails against a naive single-site implementation, deliberately); (11) trailing_worker under :frozen default must not raise + previously-returned trail unaffected by later shifts (proves trail.dup fix); (12) side_worker(policy: :isolated) { |v| v << :boo } — original value continues unmutated (mirrors existing :hardened assertions); (13) criteria-bypass value still policy-applied (Medium).
+Error diagnostics: (14) PolicyViolation structured accessors .worker/.policy/.receiver + message content; (15) receiver heuristic three branches — equal / reachable / unrelated-FrozenError (report both objects, no misattribution; §6.2 answers this); (16) UnshareableValue guidance text matches /:shared/; (17) violation.cause is the original FrozenError (cheap, high regression value).
+Shim & failure sets: (18) :hardened → :isolated behavioral equivalence + deprecation warning emitted once per declaration (capture $stderr; no ActiveSupport); (19) table-driven :isolated failure-set spec over IO/Proc/Lazy/singleton — expected outcomes CANNOT be authored from the spec (F7!); requires an implementation spike on the target Ruby first.
+Meta-tests: (20) Testing.run uses worker's effective policy by default (build policy: :isolated worker, no override, assert isolated semantics); (21) explicit policy: override; (22) mutate_input matcher passes/fails against real workers using the real detector; (23) shared example "a policy-safe worker" passes known-good/fails known-bad. Keep behavioral — assert on outputs and raised errors, not on how run() invokes make_shareable.
+Existing-suite impact: (24) dsl_spec.rb:149–164 `proc { |v| v << :boo }` breaks under :frozen → rewrite non-destructively (v + [:boo]) AND add companion spec with explicit policy: :shared preserving old behavior (the migration worked example); (25) dsl_spec.rb:166–174 :hardened context → retarget to :isolated, keep thin shim regression; (26) dsl_spec.rb:317–341 trailing_worker passes once trail.dup fix lands + new aliasing assertion. worker/gang/roster specs confirmed mutation-free — pass unmodified.
+File layout: lib/shifty/testing.rb → spec/shifty/testing_spec.rb; shared-example spec under spec/support/; matcher spec separate. Skipped (with triggers): nil × isolated/shared; String cells (same class as Array); full cartesian; identity-keyed-cache caveat (§11.2, no trigger); shareable? fast path (deferred by decision); PolicyConflict tests (now dropped per user).
+
+## junior-developer (F1–F13)
+
+F1: "major version" language needs 0.x translation; F1a :hardened removal horizon undefined (user: 1.0.0); F1b "vNEXT" placeholders → 0.6.0.
+F2: §5.4 assumes Worker#task= which doesn't exist.
+F3: four handoff sites, spec targets only one (resolved by A1/F4 ingress design).
+F4: trailing_worker/side_worker are shipped code broken under :frozen; phase assignment needed (→ Phase 1).
+F5: main shipped-inconsistent between PRs — OK if nothing is released; version bump + CHANGELOG land in the Phase-4 release PR.
+F6: wiki page list/audience/split undefined (user approved 7-page set).
+F7: CI matrix ruby.yml:21 = ['2.6','2.7','3.0'] — zero supported Rubies once floor is 3.2; matrix → ['3.2','3.3','3.4']; actions/checkout@v2 and SHA-pinned setup-ruby stale. Release blocker; Phase 1.
+F8: codeclimate-test-reporter pins simplecov ≤ 0.13 (2016), abandoned — drop while touching gemspec.
+F9: gemspec lacks required_ruby_version; add >= 3.2 together with CI change.
+F10: benchmark suite: no home/run-mode/dep decided; §8.2 amortization is load-bearing-but-unvalidated for the default; benchmarks land Phase 3 — if they contradict §8.2, revisit default before release.
+F11: stray .gem files in root/pkg (untracked, gitignored); Gemfile.lock gitignored (conventional for gems); release-phase sweep.
+F12: mutation detector + matcher + shared example sized; keep detector (powers migration tooling); both RSpec constructs are thin wrappers (kept per spec/user commitment).
+F13: name: vs tags (kept per §5.5); PolicyConflict vacuous (user: dropped); #freeze! justification corrected to supply=/Roster (kept, Phase 3).

data/docs/planning/artifacts/implementation-decision-log.md

@@ -0,0 +1,231 @@
+# Implementation Decision Log: Handoff Immutability Policies
+
+<!--
+This file records every implementation decision committed while planning Handoff Immutability Policies.
+Behavioral and implementation statements live in [../feature-implementation-plan.md](../feature-implementation-plan.md) —
+this file captures the question, rationale, evidence, and rejected alternatives for each decision.
+Round-by-round history lives in [implementation-iteration-history.md](implementation-iteration-history.md).
+Source spec: [../handoff-immutability-policies.md](../handoff-immutability-policies.md).
+Verbatim specialist outputs (referenced by A#/F#/test-# below): [.round1-specialist-outputs.md](.round1-specialist-outputs.md).
+
+The D-N counter is shared across the trivial and full sections.
+-->
+
+## Trivial decisions
+
+- D-14: `name:` kwarg retained (§5.5) — workers gain an optional `name:` for diagnostics alongside existing tags; kept per spec commitment and Joel's full-scope decision, no alternative worth debating. — Referenced in plan: Implementation Approach (Policy module and diagnostics).
+- D-15: Seven-page wiki set — Home, Handoff-Policies, Coding-Idioms-Under-Frozen, Migration-Guide-0.6, Testing-Workers, Worker-Types, Performance; drafted under `docs/wiki/`, pushed to the GitHub wiki repo after merge; README slims to a quick tour plus links (Joel, R2). — Referenced in plan: Decomposition and Sequencing (PR 4).
+- D-16: Drop `codeclimate-test-reporter` — the dev dep pins simplecov ≤ 0.13 (2016-era) and is effectively abandoned; removed while the gemspec is already open in PR 1 (junior-developer F8/C20). — Referenced in plan: Decomposition and Sequencing (PR 1).
+- D-17: Real values, no doubles for policy behavior — policy specs assert on real frozen/copied values and raised errors, not on how the framework invokes `make_shareable`; matches the repo's rspec-given house style (test-engineer). — Referenced in plan: Testing Strategy.
+- D-18: `shifty/testing` and `shifty/rspec` as separate opt-in requires — neither is loaded by `require "shifty"`; pure-Ruby harness split from the RSpec sugar (software-architect A6/C13). — Referenced in plan: Implementation Approach (testing layering), Decomposition and Sequencing (PR 2).
+- D-19: Global configuration object — `Shifty::Configuration` with `default_policy` (built-in `:frozen`) plus `Shifty.configure`/`config`/`reset_configuration!`; API shape committed by Joel, effective policy memoized at first shift (software-architect A5/C12). — Referenced in plan: Implementation Approach (config), Decomposition and Sequencing (PR 1).
+- D-20: `side_worker` accepts both `mode:` and `policy:` spellings — the lone `mode: :hardened` reference (dsl.rb:35) routes through `Policy.canonical` to `:isolated` with a one-time deprecation warning; both spellings pass through DSL option-splatting (software-architect A7, concurrency F17/C8). — Referenced in plan: Implementation Approach, Decomposition and Sequencing (PR 1).
+- D-21: Mutation detector plus both RSpec constructs ship in PR 2 — the detector powers migration tooling, and the `mutate_input` matcher and `"a policy-safe worker"` shared example are both thin wrappers over it; kept per spec §9.3 and Joel's full-scope decision (junior-developer F12/C23 Disputed→resolved). — Referenced in plan: Implementation Approach (testing layering), Testing Strategy, Decomposition and Sequencing (PR 2).
+- D-22: Release-phase repo sweep — remove stray `.gem` artifacts from repo root / `pkg`; confirm `Gemfile.lock` stays gitignored (conventional for a gem); housekeeping folded into PR 4 (junior-developer F11/C21). — Referenced in plan: Decomposition and Sequencing (PR 4).
+
+## Full decisions
+
+### D-1: Ingress-seam enforcement via PolicySupply decorator
+
+- **Question:** Where in the worker runtime is a handoff policy applied so that every value crossing a worker boundary is governed exactly once?
+- **Decision:** Apply policy at the **consuming worker's intake** (its supply pull), not at the producer's egress. Introduce a single `intake(value)` seam wrapping `worker.rb:64` (`value = supply&.shift`) and a thin `PolicySupply` decorator (responding to `#shift` as `intake(supply.shift)`) substituted as the task's 2nd argument at `worker.rb:66`. This covers all four `supply.shift` read sites (worker.rb:64; dsl.rb:55 filter, dsl.rb:86 batch, dsl.rb:122 trailing) with zero dsl.rb task-body changes. Producer-side `handoff`/`Fiber.yield` sites (source_worker, splitter_worker) get no instrumentation.
+- **Rationale:** §6.2 names the *receiving* worker in the error, so policy is a property of how a worker receives its value. Every value a producer yields surfaces through some consumer's pull, so the consumer intake is the complete and minimal enforcement set; no value crosses twice, so `:isolated` never double-copies. Wrapping the supply once per worker satisfies the Rule of Three (three in-task `supply.shift` uses exist today) without touching task bodies. §7.3 aliasing is still caught: `make_shareable` freezes the actual object in place, so a producer that keeps mutating a handed-off object raises at the producer.
+- **Evidence:** Independent convergence of software-architect A1 and concurrency-analyst F1–F4 (see [.round1-specialist-outputs.md](.round1-specialist-outputs.md)); enforcement sites enumerated at worker.rb:64/66, dsl.rb:55/86/122; discovery notes on the four `supply.shift` sites and producer-side `handoff`. C1–C3.
+- **Rejected alternatives:**
+  - Freeze at the single egress site (`Fiber.yield @task.call(...)`, worker.rb:66) — rejected because it misses in-task `supply.shift` in filter/batch/trailing workers and makes the *producer's* policy govern the boundary, contradicting §5.2 (worker declarations are the receiver's contract). Evidence: A1, F1.
+  - Instrument `handoff`/`Fiber.yield` producer sites — rejected because `handoff` is a free DSL function with no access to the executing worker, and every internal yield already surfaces at the consumer's pull (double coverage, no gain). Evidence: F3.
+- **Specialist owner:** software-architect (design), concurrency-analyst (handoff-site correctness).
+- **Revisit criterion:** A future worker type that consumes values without a `supply.shift` intake (e.g. a Ractor-backed worker, §11.6) would need a new enforcement seam.
+- **Dissent (if any):** None — specialists converged.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-2, D-3, D-4, D-7, D-12, D-13.
+- **Referenced in plan:** Implementation Approach (Architecture and Integration Points; Runtime Behavior), Decomposition and Sequencing (PR 1).
+
+### D-2: Proactive IO detection for UnshareableValue
+
+- **Question:** How is `UnshareableValue` (§6.2) raised for IO handles, sockets, and similar values, given the spec's stated assumption that `make_shareable` rejects them?
+- **Decision:** Detect IO-like values **proactively** in the `:frozen` and `:isolated` apply paths and raise `Shifty::UnshareableValue` *before* calling `Ractor.make_shareable`. Do not rely on `make_shareable` raising. Proc and `Enumerator::Lazy` continue to raise naturally and are wrapped as `UnshareableValue`.
+- **Rationale:** Empirical testing refutes spec §3.3/§10.1: `make_shareable` does **not** reject IO or singleton-methoded objects. It silently freezes a live IO in place — a process-wide side effect freezing a shared `$stdout`/logger/file handle for every reference in the process (materially worse than raising), and `copy: true` on an IO duplicates the fd, freezes the copy, and leaks one unusable fd per handoff. The spec's *intent* (UnshareableValue for uncopyable values) is preserved only if detection is proactive.
+- **Evidence:** concurrency-analyst F7 (CRITICAL), F8, F9, F10 — empirical on Ruby 4.0.5; C4, C5. Re-verification on the Ruby 3.2 CI floor is a PR-1 spike task (see D-8).
+- **Rejected alternatives:**
+  - Trust the spec and let `make_shareable` reject IO — rejected: empirically false; it silently freezes live IO process-wide (F8) and leaks fds under `copy: true` (F9).
+  - Reactive-only wrapping (catch whatever `make_shareable` raises) — rejected: for IO nothing is raised, so the damage is done silently before any wrap could fire (F7/F8).
+- **Specialist owner:** concurrency-analyst.
+- **Revisit criterion:** If the PR-1 spike on Ruby 3.2 finds `make_shareable` behavior differs materially from the 4.0.5 observations, the detection predicate and the `:isolated` failure-set table (test #19) are re-derived from the spike results.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-5, D-8, D-13.
+- **Referenced in plan:** Implementation Approach (Runtime Behavior; empirical spike), RAID Log (assumptions/risks), Testing Strategy.
+
+### D-3: Policy as three frozen singletons
+
+- **Question:** What structure implements the three policies and their name resolution (including the `:hardened` alias)?
+- **Decision:** A `Shifty::Policy` module holding three frozen singleton lambdas (`Frozen`, `Isolated`, `Shared`) behind `Policy.resolve(name)`, with a `TABLE` and an `ALIASES = {hardened: :isolated}` map; `canonical(name)` applies aliases and the `:hardened` deprecation warning. Not a class hierarchy, not a mixin. Each apply wraps `make_shareable`/Marshal failures (and the proactive IO check from D-2) as `UnshareableValue`.
+- **Rationale:** Policy is a collaborator, not worker state (contrast the `Taggable` mixin), so a module of stateless strategies is the smallest fit. `resolve`/`ALIASES` gives one place for validation and the deprecation shim. Three concrete policies exist today — no speculative extensibility.
+- **Evidence:** software-architect A2; C9. Existing `Taggable` mixin precedent in `lib/shifty/taggable.rb` (discovery notes).
+- **Rejected alternatives:**
+  - Class hierarchy of policy objects — rejected: no per-instance state to hold; adds ceremony over three stateless lambdas (A2).
+  - Mixin on Worker (Taggable-style) — rejected: policy is a collaborator applied to values, not worker identity/state (A2).
+- **Specialist owner:** software-architect.
+- **Revisit criterion:** A fourth policy, or per-policy configuration state, would justice a richer object model.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-4, D-9, D-20.
+- **Referenced in plan:** Implementation Approach (Policy module), Decomposition and Sequencing (PR 1).
+
+### D-4: Two-attribute policy precedence
+
+- **Question:** How is the worker > pipeline > global precedence (§5.2) represented and how does `.with_policy` propagate?
+- **Decision:** Two nullable attributes on Worker — `@policy` (explicit contract) and `@pipeline_policy` (default) — resolved by `Policy.resolve(@policy || @pipeline_policy || Shifty.config.default_policy)`, memoized in `effective_policy`. `.with_policy(name)` validates eagerly, then walks the `.supply` chain upstream setting `pipeline_policy=` on each node; Gang fans `pipeline_policy=` out across its roster and `Gang#supply` returns `roster.first.supply` so the walk steps past a gang.
+- **Rationale:** Two attributes let a nil `@policy` mean "undeclared" without a separate `declared?` flag or branching. There is no chain object for bare `|` chains — a pipeline is just the last worker (discovery notes) — so `.with_policy` must live on Worker and Gang and propagate via the supply chain. Workers do not know their consumer, so propagation walks upstream, not down.
+- **Evidence:** software-architect A3; C9. Discovery notes: composition links workers by setting `supply`; no pipeline object exists; Gang is the only reifying container.
+- **Rejected alternatives:**
+  - Single `@policy` plus a `declared?` flag — rejected: forces branching everywhere the flag is read (A3).
+  - Store policy by walking downstream to the consumer — rejected: workers hold no reference to their consumer, only to their supply (A3).
+- **Specialist owner:** software-architect.
+- **Revisit criterion:** A reified pipeline/chain object (if introduced later) would relocate `.with_policy` off Worker.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-19.
+- **Referenced in plan:** Implementation Approach (precedence), Decomposition and Sequencing (PR 1).
+
+### D-5: Consolidated error hierarchy
+
+- **Question:** Where do the new and existing error classes live, and under what base?
+- **Decision:** Consolidate errors into `lib/shifty/errors.rb` under a `Shifty::Error` base, with a `PolicyError` intermediate: `PolicyViolation < PolicyError` (attrs: worker, policy, receiver, value, cause) and `UnshareableValue < PolicyError` (attrs: worker, policy, value). Reparent existing `WorkerError`/`WorkerInitializationError` under `Shifty::Error` (source-compatible) and move `WorkerInitializationError` out of dsl.rb. No `PolicyConflict` class (see D-6).
+- **Rationale:** A single error file with a common base is idiomatic and lets callers rescue `Shifty::Error` broadly or `PolicyError` narrowly. Reparenting is source-compatible because the existing classes keep their names.
+- **Evidence:** software-architect A4; C10. `PolicyViolation`/`UnshareableValue` attribute lists from spec §6.2.
+- **Rejected alternatives:**
+  - Leave errors scattered across dsl.rb and worker.rb — rejected: no common ancestor for `rescue`, and the new policy errors need a home anyway (A4).
+  - Include a `PolicyConflict` class — rejected: nothing to raise it (see D-6).
+- **Specialist owner:** software-architect.
+- **Revisit criterion:** A new error family (e.g. topology errors) would extend, not revise, this hierarchy.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-2, D-6.
+- **Referenced in plan:** Implementation Approach (errors), Decomposition and Sequencing (PR 1).
+
+### D-6: PolicyConflict dropped entirely
+
+- **Question:** Does the plan ship a `PolicyConflict` class and build-time validation (spec §5.3, Phase 2)?
+- **Decision:** Drop `PolicyConflict` entirely — no class, no validation.
+- **Rationale:** The committed precedence rule (worker declarations authoritative, pipeline policy default-only, §11.4) leaves no violable rule to enforce, so there is nothing to raise. Joel (R2): "Since we're defaulting to frozen and allowing workers to opt out to something more permissive, we don't have a PolicyConflict... nothing to raise means no class, and we'll revisit later if we need to refine this."
+- **Evidence:** User input, R2 (verbatim above). software-architect A4 and junior-developer F13/C11 independently flagged the class as vacuous.
+- **Rejected alternatives:**
+  - Define the class now, defer only the detection logic — rejected: a class with no raiser is dead code future agents would copy; Joel chose to drop it outright (R2).
+  - Implement full build-time validation now — rejected: no rule exists to validate under the committed precedence semantics (A4, C11).
+- **Specialist owner:** software-architect.
+- **Revisit criterion:** A strict-Gang feature (§11.4) that lets a pipeline *forbid* worker-level loosening — that would introduce a violable rule and reopen the need for both the class and detection.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1 (flagged), R2 (decided).
+- **Dependent decisions:** —.
+- **Referenced in plan:** Implementation Approach (errors), Decomposition and Sequencing (PR 2 scope note), Deferred (YAGNI).
+
+### D-7: trailing_worker aliasing fix in Phase 1
+
+- **Question:** `trailing_worker` (dsl.rb:112–130) hands off its live closure `trail` array while continuing to `unshift`/`pop` it — under the `:frozen` default the next resume raises `FrozenError`. Where and how is this fixed?
+- **Decision:** Fix the shipped worker in **PR 1** to hand off `trail.dup` (a snapshot), not the live array. batch/splitter/filter workers are confirmed safe as written and are **not** defensively changed.
+- **Rationale:** This is exactly the aliasing bug class the policy exists to catch (§7.3), but it is in Shifty's own shipped DSL, so it must be fixed rather than merely documented. It travels with the mechanism (PR 1) because the `:frozen` default lands there. batch (fresh array + `.compact` new array), splitter (fresh local per call), and filter (no closure state) do not alias, so touching them would add risk for no benefit.
+- **Evidence:** concurrency-analyst F13–F16 (trailing aliases at dsl.rb:125; others safe); junior-developer F4; test-engineer #11/#26; C7.
+- **Rejected alternatives:**
+  - Internally declare `trailing_worker policy: :shared` — rejected: masks the aliasing instead of fixing it, and denies trailing_worker users the `:frozen` guarantee (software-architect A7).
+  - Leave it and document as a known break — rejected: it is first-party code; shipping a framework whose own DSL breaks under its own default is not acceptable.
+- **Specialist owner:** concurrency-analyst.
+- **Revisit criterion:** None expected; regression is guarded by test #26.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-12, D-13.
+- **Referenced in plan:** Implementation Approach (Runtime Behavior), Decomposition and Sequencing (PR 1), Testing Strategy.
+
+### D-8: Ruby 3.2 floor and CI matrix in Phase 1
+
+- **Question:** Which PR owns `required_ruby_version >= 3.2` and the CI matrix rewrite?
+- **Decision:** Land `required_ruby_version >= 3.2` in the gemspec and rewrite the CI matrix from `['2.6','2.7','3.0']` to `['3.2','3.3','3.4']` (plus refreshing stale `actions/checkout@v2` and the SHA-pinned setup-ruby) in **PR 1**, as a prerequisite to trusting any policy spec. The PR-1 spike re-verifies the D-2 `make_shareable` observations on the 3.2 floor.
+- **Rationale:** The current matrix tests only Rubies *below* the new floor, so without this change every policy spec runs on unsupported, wrong-behavior Rubies. `Data` idioms (§7.2) and mature `make_shareable` need ≥ 3.2. This is a release blocker that gates the correctness of everything else in PR 1.
+- **Evidence:** junior-developer F7, F9; C15; resolved by evidence/aggregation (OQ-4). CI matrix at `.github/workflows/ruby.yml:21`; gemspec lacks `required_ruby_version` (discovery notes).
+- **Rejected alternatives:**
+  - Put CI/gemspec changes in the Phase-4 release PR — rejected: policy specs in PRs 1–3 would run on unsupported Rubies with different `make_shareable`/Data behavior, invalidating them (F7, OQ-4).
+  - A separate prerequisite PR before PR 1 — rejected: adds a fifth PR for a change that naturally belongs with the mechanism it enables; one-PR-per-phase is the committed shape.
+- **Specialist owner:** junior-developer (raised); PM (sequencing).
+- **Revisit criterion:** None; floor is fixed for the 0.6.0 line.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-2.
+- **Referenced in plan:** Decomposition and Sequencing (PR 1), RAID Log.
+
+### D-9: :hardened deprecation horizon
+
+- **Question:** In 0.x terms, when is the deprecated `:hardened` option removed?
+- **Decision:** `:hardened` is **deprecated in 0.6.0** (mapped to `:isolated` with a one-time warning via `Policy.canonical`) and **removed at 1.0.0**. Docs state "deprecated in 0.6.0, removed in 1.0.0."
+- **Rationale:** The spec speaks of "one major version, then removed," which is undefined in a pre-1.0 line. Joel (R2) set the concrete horizon: keep the shim through the 0.x series and drop it at the 1.0.0 boundary, which is the natural major-version break.
+- **Evidence:** User input, R2. junior-developer F1/C16 flagged the undefined 0.x horizon (OQ-1).
+- **Rejected alternatives:**
+  - Remove at the next minor (0.7.0) — rejected: too aggressive for a deprecation users have not yet seen; Joel chose the 1.0.0 boundary (R2).
+  - Keep indefinitely — rejected: leaves a dead alias and the Marshal-divergence caveat (C5) live forever (R2).
+- **Specialist owner:** software-architect (shim), PM (horizon).
+- **Revisit criterion:** If 1.0.0 slips materially, re-confirm the removal still rides that release.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1 (flagged), R2 (decided).
+- **Dependent decisions:** D-20.
+- **Referenced in plan:** Implementation Approach, Decomposition and Sequencing (PR 1), Deferred/Migration notes.
+
+### D-10: Manual-run benchmark directory
+
+- **Question:** Where do the §8.4 benchmarks live, how are they run, and what dependency do they add?
+- **Decision:** A `benchmark/` directory with `benchmark-ips` as a **dev** dependency, **manual-run** (not in CI), results published to the wiki Performance page. Benchmarks land in **PR 3**. If they contradict the §8.2 amortization claim, the `:frozen` default is revisited before release.
+- **Rationale:** The §8.2 amortization claim is load-bearing for choosing `:frozen` as default but is uncited until measured. Running benchmarks in CI would make the suite slow and flaky for a measurement that is consulted occasionally; manual runs with published results fit a gem with no perf SLO.
+- **Evidence:** junior-developer F10/C19/C6; resolved by aggregation (OQ-6). No benchmark tooling exists today (discovery notes).
+- **Rejected alternatives:**
+  - CI-run benchmarks — rejected: slow/flaky CI for an occasionally-consulted measurement; replaced by manual runs + published results (OQ-6).
+  - Skip benchmarks — rejected: the default-policy choice rests on the unvalidated §8.2 claim (F10); measurement is required before release.
+- **Specialist owner:** junior-developer (raised); PM (sequencing).
+- **Revisit criterion:** Benchmarks show `:frozen` amortization does not hold on representative value shapes → revisit the default before 0.6.0 ships (RAID R1).
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** —.
+- **Referenced in plan:** Decomposition and Sequencing (PR 3), RAID Log, Deferred (YAGNI) (CI-run benchmarks).
+
+### D-11: Version bump and CHANGELOG in Phase-4 PR
+
+- **Question:** When do the version bump to 0.6.0 and the CHANGELOG entry land, given one PR per phase and shipped-but-unreleased `main` between PRs?
+- **Decision:** The version bump (`lib/shifty/version.rb` → 0.6.0) and the CHANGELOG entry land in the **Phase-4 (release) PR**, together with the README rewrite, wiki drafts, PR-26 doc reconciliation, and the gem build. `main` may carry unreleased behavior between PRs 1–3.
+- **Rationale:** Nothing is published until Joel builds and pushes 0.6.0, so `main` being shipped-but-not-yet-released between phase PRs is harmless; deferring the version/CHANGELOG to the release PR keeps a single coherent release note rather than four partial bumps. This is a process-convention call, not an evidenced one.
+- **Evidence:** junior-developer F5/C17 (Anecdotal — process convention); reframed the release-timing question, resolved by convention (OQ-5).
+- **Rejected alternatives:**
+  - Bump version per-phase PR — rejected: four intermediate versions for one logical release; no publish happens between them so the bumps carry no signal (F5).
+- **Specialist owner:** junior-developer (reframed); Joel (publishes).
+- **Revisit criterion:** If any phase PR is released independently, that PR must carry its own bump/CHANGELOG.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** —.
+- **Referenced in plan:** Decomposition and Sequencing (PR 4), Definition of Done.
+
+### D-12: Terminal output governance out of scope
+
+- **Question:** The value the last worker's `shift` returns to user code crosses no consumer intake and is therefore un-governed by any policy. Is that a gap to close?
+- **Decision:** Leave terminal output un-governed; document it in the wiki/migration guide. No framework mechanism wraps the final `shift`.
+- **Rationale:** Spec §2 scopes policies to *worker boundaries*; the terminal caller is not a worker, so there is no boundary to govern. The one shipped aliasing hazard at the terminal (trailing_worker) is removed by D-7, so the residual is documentation only.
+- **Evidence:** aggregator synthesis from A1/F1; C25; resolved by evidence against spec §2 scoping.
+- **Rejected alternatives:**
+  - Govern terminal output by wrapping the final `shift` — rejected: the terminal caller is outside the worker-boundary model the policies are scoped to (§2); adding a special case there would be scope creep with no boundary to protect (C25).
+- **Specialist owner:** software-architect.
+- **Revisit criterion:** If a use case emerges where user code downstream of the last worker needs the same mutation guarantees, reconsider a terminal policy.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** —.
+- **Referenced in plan:** Implementation Approach (Runtime Behavior), Decomposition and Sequencing (PR 4, wiki).
+
+### D-13: Equivalence-class test matrix
+
+- **Question:** How much of the policy × value-shape space does the test suite cover?
+- **Decision:** Cover **8 load-bearing equivalence-class cells** (not the full 3×10 cartesian), plus 5 boundary-case behaviors (#9–13), 4 error-diagnostic contracts (#14–17), the deprecation shim + a table-driven `:isolated` failure-set spec (#18–19), 4 meta-tests for the testing harness (#20–23), and 3 existing-spec migrations (#24–26). The `:isolated` failure-set table (#19) cannot be authored from the spec and requires an implementation spike on the target Ruby first (per D-2). Real values throughout, no doubles.
+- **Rationale:** The full cartesian is mostly redundant — String behaves as Array, nil × isolated/shared is trivial — so equivalence classes give the same confidence at a fraction of the maintenance. The failure-set table must be spiked because the spec's rejection claims are empirically wrong (D-2).
+- **Evidence:** test-engineer full prioritized plan; C22. Existing specs that break under `:frozen`: dsl_spec.rb:149–164, 166–174, 317–341.
+- **Rejected alternatives:**
+  - Full 3×10 policy × value-shape cartesian — rejected: String duplicates Array, nil cells are trivial passthrough; equivalence classes cover the load-bearing behavior with far less to maintain (test-engineer).
+- **Specialist owner:** test-engineer.
+- **Revisit criterion:** A new value shape with distinct freeze/copy behavior (outside the existing equivalence classes) adds a cell.
+- **Dissent (if any):** None.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** —.
+- **Referenced in plan:** Testing Strategy, Decomposition and Sequencing (all PRs).

data/docs/planning/artifacts/implementation-iteration-history.md

@@ -0,0 +1,73 @@
+# Implementation Iteration History: Handoff Immutability Policies
+
+<!--
+This file records how the implementation plan evolved across discussion rounds.
+Committed decisions live in [implementation-decision-log.md](implementation-decision-log.md)
+and the primary plan lives in [../feature-implementation-plan.md](../feature-implementation-plan.md).
+Source spec: ../handoff-immutability-policies.md (design doc; no plan-a-feature artifacts,
+so no T# technical notes exist and the T#-contradiction classification does not apply).
+-->
+
+## R1: Parallel specialist review
+
+- **Specialists engaged:** concurrency-analyst, software-architect, test-engineer, junior-developer (project-manager reserved for synthesis; deterministic aggregation used per skill).
+- **New input provided:** Initial feature spec (`../handoff-immutability-policies.md`), discovery notes (`.discovery-notes.md`), and Joel's nine committed decisions (0.6.0, all four phases, Ruby ≥ 3.2 floor, API shape, one PR per phase, wiki via docs/wiki/, :hardened→:isolated, no shareable? fast path, Joel publishes gem).
+
+- **Claim ledger:**
+
+| # | Claim | Raised by | Category | State |
+|---|-------|-----------|----------|-------|
+| C1 | Policy must be enforced at the consumer's intake (supply pull), via a supply-wrapping decorator substituted at worker.rb:64 and as the task's 2nd arg at worker.rb:66; covers all four `supply.shift` sites (worker.rb:64, dsl.rb:55, dsl.rb:86, dsl.rb:122) with zero dsl.rb task-body changes | concurrency-analyst (F1–F4), software-architect (A1) — independent convergence | design | Evidenced |
+| C2 | Producer-side `handoff`/`Fiber.yield` sites (source_worker, splitter_worker) need no instrumentation — every yielded value surfaces through the consumer's pull | concurrency-analyst (F3), software-architect (A1) | design | Evidenced |
+| C3 | criteria-bypass path (worker.rb:68) is automatically covered by intake-side enforcement | concurrency-analyst (F5) | edge-case | Evidenced |
+| C4 | **Spec §3.3/§10.1 are factually wrong**: `make_shareable` does NOT reject IO or singleton-methoded objects — it silently freezes live IO in place (process-wide side effect) and `copy: true` on IO leaks a file descriptor. Only Proc and Enumerator::Lazy raise. UnshareableValue must be raised proactively for IO-like values | concurrency-analyst (F7–F9), empirical on Ruby 4.0.5 | assumption-refuted | Evidenced (re-verify on 3.2 CI) |
+| C5 | Marshal-vs-make_shareable divergence includes a silent-behavior-change case: singleton-methoded values failed loudly under :hardened (Marshal) but silently succeed under :isolated (make_shareable) — migration guide must call this out separately | concurrency-analyst (F10) | edge-case | Evidenced |
+| C6 | §8.2 already-shareable short-circuit confirmed structurally (copy: true returns same object for frozen Data); CPU amortization claim still needs §8.4 benchmarks | concurrency-analyst (F11), junior-developer (F10) | ambiguity | Evidenced (partial) |
+| C7 | trailing_worker (dsl.rb:112–130) hands off its live closure array and breaks under :frozen — required Phase-1 shipped-code fix (`trail.dup`); batch/splitter/filter workers confirmed safe as written | concurrency-analyst (F13–F16), junior-developer (F4), test-engineer (#11) | edge-case | Evidenced |
+| C8 | side_worker `mode: :hardened` (dsl.rb:35,40–41) maps to policy: :isolated with deprecation warning via Policy.canonical; shim must accept both `mode:` and `policy:` spellings | concurrency-analyst (F17), software-architect (A7), test-engineer (#18) | design | Evidenced |
+| C9 | Policy strategies as three frozen singletons in `Shifty::Policy` with `resolve(name)` + ALIASES; not a class hierarchy, not a mixin; precedence as two nullable attributes (@policy contract, @pipeline_policy default) resolved by `||`-chain; `.with_policy` walks the supply chain upstream, Gang fans out to roster | software-architect (A2, A3) | design | Evidenced |
+| C10 | Errors consolidate into lib/shifty/errors.rb under Shifty::Error base with PolicyError intermediate; existing WorkerError/WorkerInitializationError reparented (source-compatible) | software-architect (A4) | design | Evidenced |
+| C11 | `PolicyConflict` build-time validation has nothing to enforce: committed decision (worker wins, pipeline default-only, §11.4) leaves no violable rule. Define the class, defer the detection | software-architect (A4), junior-developer (F13) | YAGNI-candidate | Evidenced |
+| C12 | Global config: `Shifty::Configuration` object + `Shifty.configure`/`config`/`reset_configuration!`; effective policy memoized at first shift | software-architect (A5) | design | Evidenced |
+| C13 | shifty/testing (pure Ruby) and shifty/rspec (opt-in) as separate requires, neither loaded by `require "shifty"` | software-architect (A6) | design | Evidenced |
+| C14 | §5.4 cites a `Worker#task=` writer that does not exist; #freeze! motivation must be restated (supply= + Roster rewiring). #freeze! must (a) force-materialize lazy @task first, (b) freeze Roster @workers array, (c) walk .supply chain for bare `\|` chains | concurrency-analyst (F18–F21), junior-developer (F2) | assumption-refuted + design | Evidenced |
+| C15 | CI matrix (.github/workflows/ruby.yml:21) tests only 2.6/2.7/3.0 — zero supported Rubies under the 3.2 floor; matrix rewrite + required_ruby_version are a Phase-1 prerequisite, plus stale actions | junior-developer (F7, F9) | assumption-refuted | Evidenced |
+| C16 | "major version" language throughout spec needs 0.x translation; :hardened removal horizon ("one major version, then removed") is undefined in 0.x terms | junior-developer (F1) | spec-level | Evidenced |
+| C17 | main will be shipped-but-undocumented-inconsistent between phase PRs; version bump + CHANGELOG should land in the Phase-4 (release) PR | junior-developer (F5) | ambiguity | Anecdotal (process convention) |
+| C18 | Wiki page list, audience, and README/wiki split undefined; docs/wiki/ doesn't exist; information-architect input recommended at Phase 4 | junior-developer (F6) | spec-level | Evidenced |
+| C19 | Benchmark suite has no home/run-mode/dependency decision; §8.2 amortization is load-bearing-but-uncited for the :frozen default | junior-developer (F10) | ambiguity | Evidenced |
+| C20 | codeclimate-test-reporter dev dep pins simplecov ≤ 0.13 (2016-era), effectively abandoned — drop while touching gemspec | junior-developer (F8) | edge-case | Evidenced |
+| C21 | Stray .gem files in repo root / pkg; Gemfile.lock gitignored (conventional for a gem) — release-phase sweep item | junior-developer (F11) | polish | Evidenced |
+| C22 | Test plan: 8 load-bearing policy×shape equivalence-class cells (not full cartesian), 4 boundary-case behaviors, 4 error-diagnostic contracts, deprecation shim + empirical failure-set table (spike required before authoring), meta-tests for Testing.run/matcher/shared example, 3 existing specs break under :frozen default (dsl_spec.rb:151, 166–174, 317–341) and double as migration worked examples; real values throughout, no doubles | test-engineer (full plan) | test-coverage | Evidenced |
+| C23 | Mutation detector + both RSpec constructs sized as large Phase-2 surface; matcher and shared example both ship vs one | junior-developer (F12) vs spec §9.3 commitment | YAGNI-candidate | Disputed (resolved: spec + user committed all; both are thin wrappers over the detector) |
+| C24 | name: kwarg (§5.5) vs existing tags for diagnostics | junior-developer (F13) | YAGNI-candidate | Resolved by spec commitment (§5.5, user decision: full scope) |
+| C25 | Terminal-output governance: under intake-side enforcement, the value returned by the LAST worker's `shift` to user code crosses no consumer intake and is un-governed | aggregator (from A1/F1 synthesis) | edge-case | Resolved by evidence: spec §2.1 scopes policies to worker boundaries; terminal caller is not a worker. Document in wiki/migration guide; trailing_worker fix (C7) removes the one shipped aliasing hazard |
+
+- **Open Questions raised:**
+  - OQ-1 (from C16): What is the :hardened removal horizon in 0.x terms? → escalate to user with recommendation "removed at 1.0.0".
+  - OQ-2 (from C11): Defer PolicyConflict detection logic (class only) — deviation from spec §13 Phase 2 scope? → escalate to user with recommendation "defer with reopening trigger".
+  - OQ-3 (from C18): Wiki page list and README/wiki split → propose page list to user.
+  - OQ-4 (from C15): Which phase owns CI matrix + required_ruby_version? → resolved by evidence/aggregation: Phase 1 PR (prerequisite for trusting policy specs on supported Ruby).
+  - OQ-5 (from C17): Version bump + CHANGELOG timing → resolved by convention: Phase-4 release PR; main may carry unreleased behavior between PRs since nothing is published until 0.6.0.
+  - OQ-6 (from C19): Benchmark home/run-mode → resolved by aggregation: `benchmark/` directory, benchmark-ips as dev dependency, manual-run (not CI), results published to wiki Performance page; if results contradict §8.2 the default is revisited before release (risk logged).
+  - OQ-7 (from C4): Spec correction for make_shareable rejection set → resolved by evidence: spec *intent* (UnshareableValue for IO) is preserved via proactive IO detection in Policy application; spec doc + README/wiki text corrected in Phase 4. Empirical re-verification on Ruby 3.2 CI is a Phase-1 spike task.
+- **Spec-maturity tags:** plan-level: C1–C15, C17, C19–C25 (majority); spec-level: C16 (junior-developer), C18 (junior-developer). 2 spec-level findings from 1 specialist — **gate NOT tripped** (threshold: ≥5 from ≥3 specialists). No T# notes exist, so T#-contradiction does not apply.
+- **Resolution source:** OQ-4, OQ-5, OQ-6, OQ-7, C25 — evidence/deterministic aggregation. OQ-1, OQ-2, OQ-3 — user input (batched escalation, see R2).
+- **Decisions produced:** D-1, D-2, D-3, D-4, D-5, D-7, D-8, D-10, D-11, D-12, D-13 (full); D-14, D-16, D-17, D-18, D-19, D-20, D-21, D-22 (trivial). D-6 and D-9 flagged this round (C11→OQ-2, C16→OQ-1) but decided in R2.
+- **Changed in plan:** Implementation Approach; Decomposition and Sequencing; RAID Log; Testing Strategy; Definition of Done; Deferred (YAGNI).
+- **Next-step recommendation (deterministic):** Blocked pending user input on OQ-1/OQ-2/OQ-3 (single batched escalation); all other findings resolve to synthesis inputs. No re-engagement handoffs required — specialist outputs converge with no disputes surviving aggregation.
+
+## R2: User escalation (batched OQ-1/OQ-2/OQ-3)
+
+- **Specialists engaged:** none — direct user escalation with recommendations, per Step 6.
+- **New input provided:** Joel's answers to the three surviving Open Questions.
+- **Claim ledger:** no new claims; three resolutions:
+  - OQ-1 → `:hardened` deprecated in 0.6.0, **removed at 1.0.0**. Docs state "deprecated in 0.6.0, removed in 1.0.0".
+  - OQ-2 → **PolicyConflict dropped entirely** (no class, no validation). Joel: "Since we're defaulting to frozen and allowing workers to opt out to something more permissive, we don't have a PolicyConflict... nothing to raise means no class, and we'll revisit later if we need to refine this." Reopening trigger: a strict-Gang feature (§11.4) that can forbid worker-level loosening.
+  - OQ-3 → seven-page wiki set approved as proposed (Home, Handoff-Policies, Coding-Idioms-Under-Frozen, Migration-Guide-0.6, Testing-Workers, Worker-Types, Performance); README keeps the quick tour and links into the wiki.
+- **Open Questions raised:** none.
+- **Spec-maturity tags:** n/a (no new findings).
+- **Resolution source:** OQ-1, OQ-2, OQ-3 — user input (verbatim above).
+- **Decisions produced:** D-6 (PolicyConflict dropped), D-9 (:hardened removed at 1.0.0), D-15 (seven-page wiki set).
+- **Changed in plan:** Implementation Approach; Decomposition and Sequencing (PR 2 PolicyConflict removed, PR 4 wiki set); Deferred (YAGNI); Definition of Done.
+- **Next-step recommendation (deterministic):** Go to synthesis — zero unresolved Open Questions, zero pending handoffs, round produced no new findings.