scout-essentials 1.9.0 → 1.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 526dfca4b8e68e08295052cb58f86b37b346857f0eb80ada50406b2683921de6
-  data.tar.gz: b2babc599d88a5e429fbcc1aad07e3f7d62483c3a73c1b56492a5847f7238319
+  metadata.gz: aa2a5b23a4e6627229255301bd5e8e9263e20333314e3334ed0359b6d387496b
+  data.tar.gz: 1c2fd66f3b370a1325ab60d877cda1ba2d19f1c41930bc4e45c879cbf1aafec0
 SHA512:
-  metadata.gz: 5041b9210824ce7add63097c50f67745af42c212197c33816ddef4a11e187e09c75d3e342b4d9e56d4a5e6132717cc5cef078518540e74494d98f7deb819c28b
-  data.tar.gz: 695290651c1db53bf9bfcd93f1567126f4eaba1c494d46b0cc6c4bbb221c4fcdd924a5c29d0ca25d8173b2b67fdbac46cfc344d59e9d28f58f8d30f19b71ea16
+  metadata.gz: a6c8151e1d4323e586c85eeb28bf4a1ada40f829d7b7c2e35f52f442e7f03ceed5a0ca64d5c93ef38033849fc9d3d7ce95e325d76bfe953068dd51594a6f6a2c
+  data.tar.gz: 3db4ca0f364ecfb5a4949a030f9ed35952e7d338e75663d46b185bf939f10821066efd80c8b80c852bd382da4fc8c4114293743977b5faabcf44d4f3dd3a16b3

data/.vimproject

@@ -11,6 +11,11 @@ scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
   cmd
 
   timeout
+
+  cortex_coder
+  cortex_coder.analyze
+
+  testing_basics
  }
  doc=doc{
   Improvements.md
@@ -23,21 +28,33 @@ scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
    HandlingStreams.md
    LoggingAndProgress.md
    ProducingResources.md
+   RemoteData.md
    RunningCommands.md
    WorkingWithFiles.md
   }
   developer=developer{
    AnnotationSystem.md
    Architecture.md
+   Configuration.md
+   CoreUtilities.md
    DesignPrinciples.md
+   DocumentationPractices.md
+   ErrorHandling.md
+   LockingAndConcurrency.md
    PathResolution.md
    PersistenceAndResources.md
    StreamingModel.md
+   Testing.md
   }
  }
  lib=lib {
   scout-essentials.rb
   scout=scout{
+   testing.rb
+   testing=testing{
+    availability.rb
+    scout_state.rb
+   }
    annotation.rb
    annotation=annotation{
     annotated_object.rb
@@ -141,7 +158,7 @@ scout-essentials=/$PWD filter="*.rb *.txt *.md *.conf *.yaml" {
    test_tmpfile.rb
    annotation=annotation{
     test_array.rb
-    }
+   }
    misc=misc{
     test_digest.rb
     test_filesystem.rb

data/Rakefile

@@ -21,6 +21,15 @@ Juwelier::Tasks.new do |gem|
   gem.add_runtime_dependency 'yaml'
   gem.add_runtime_dependency 'rake'
   gem.add_runtime_dependency 'listen'
+
+  # Juwelier's default file list comes from Git's tracked files. Include these
+  # current additions explicitly so an uncommitted working-tree build packages them.
+  gem.files += %w[
+    doc/developer/Testing.md
+    lib/scout/testing.rb
+    lib/scout/testing/scout_state.rb
+    test/scout/test_testing.rb
+  ]
 end
 Juwelier::RubygemsDotOrgTasks.new
 require 'rake/testtask'

data/VERSION

@@ -1 +1 @@
-1.9.0
+1.9.3

data/doc/Improvements.md

@@ -224,3 +224,23 @@ to a temporary cache dir or raising a clearer error message.
 | Bugs (🔴) | 0 |
 | Improvements (🟡) | 15 |
 | Done (🟢) | 1 |
+
+---
+
+## Promotion ledger
+
+- **2026-09-12** — `research/doc-practices-guide.md` (491 lines, Critic-
+  reviewed 93/100) promoted to
+  `doc/developer/DocumentationPractices.md`. Evidence labels (`[V]` /
+  `[R1]` / `[R2]` / `[REPT]`) and all Critic-mandated caveats preserved
+  verbatim in the page. Provenance retained in the Cortex artifacts
+  `doc-guide/*` and `search/doc-guide-source-map.md`, and in the three
+  sessions `~/chats/scout-essentials/cortex_coder`,
+  `~/chats/scout-gear/cortex_coder`, `~/chats/scout-ai/cortex_coder`.
+  The source file was retired in a follow-up commit after independent
+  verification (Critic PASS 97/100); its unique §17 associated-elements
+  inventory is preserved in the Cortex closure artifact
+  `doc-guide/promotion-record.md`. Gemspec file list reconciled (4 additions:
+  `doc/developer/DocumentationPractices.md`,
+  `research/doc-structure.md`, `research/lock-namespace-blindness.md`,
+  `research/probing-guide.md`).

data/doc/StartHere.md

@@ -40,7 +40,7 @@ Log.info "wrote 2 lines"
 Transitive pulls: `scout/open` (hence `Open`, `CMD`, `NamedStream`),
 `scout/annotation` (hence `Annotation`), `scout/misc` (via
 `scout/tmpfile`/`scout/open`). Notably **not** loaded by the umbrella
-require (verified by probe `tmp/rewrite_C/probe_01_requires.rb`):
+require (against the current `lib/`):
 
 - `NamedArray` — `require 'scout/named_array'`
 - `Hook` (a **top-level** `module Hook`, *not* `Misc::Hook`) —
@@ -105,6 +105,7 @@ ruby -Ilib -Itest test/scout/test_misc.rb
 
 **Developer guides** — how the library *works*:
 
+- [Testing](developer/Testing.md) — test layout, generic and Scout-specific support, and isolation conventions
 - [Architecture](developer/Architecture.md)
 - [Design Principles](developer/DesignPrinciples.md)
 - [Annotation System](developer/AnnotationSystem.md)
@@ -115,8 +116,10 @@ ruby -Ilib -Itest test/scout/test_misc.rb
 - [Error Handling](developer/ErrorHandling.md)
 - [Locking and Concurrency](developer/LockingAndConcurrency.md)
 - [Core Utilities](developer/CoreUtilities.md)
+- [Documentation Practices](developer/DocumentationPractices.md)
 
 **Research artifacts** (`../research/`) are non-normative supporting
-material: `research/doc_audit/*` holds the per-claim audit ledgers,
-`research/behavior-probes.md` the probe transcripts, and
-`research/implementation-inventory-*.md` the file:line inventories.
+material: design and behaviour analyses written while this
+documentation was produced. The behaviour they describe is captured in
+`doc/` and in the `test/` suite, which now carry the same facts in
+executable form.

data/doc/developer/AnnotationSystem.md

@@ -6,16 +6,12 @@ makes `Path`, `Resource` and `NamedArray` work, so understanding it is a
 prerequisite for [Path Resolution](PathResolution.md) and
 [Persistence and Resources](PersistenceAndResources.md).
 
-Everything on this page is backed by `tmp/rewrite_C/probe_01..04.rb` and
-probes P36–P42 in `research/behavior-probes.md`, run against the current
-`lib/scout/annotation*.rb`.
-
 ## Load path
 
 `lib/scout-essentials.rb` does **not** require `scout/annotation` directly.
 `Annotation` becomes available because `scout/path` requires it
 (`lib/scout/path.rb:1`), so `require 'scout-essentials'` gives you the
-constant (`Object.const_defined?(:Annotation) => true`, probe_03) — but a
+constant (`Object.const_defined?(:Annotation) => true`) — but a
 library that only wants annotations can `require 'scout/annotation'` on its
 own.
 
@@ -49,7 +45,7 @@ SampleInfo.setup('S004', %w[Human Liver])          # positional, same order
 SampleInfo.setup { 'S005' }                         # block-as-object
 ```
 
-Rules verified in probe_01/probe_02:
+Rules:
 
 - **In-place extension.** `setup` calls `obj.extend SampleInfo` on the object
   you pass and returns **that same object** (`setup(s).equal?(s) => true`) —
@@ -60,7 +56,7 @@ Rules verified in probe_01/probe_02:
   `setup` rescues it and returns the *plain* object with no metadata.
 - **`:annotation_types` is reserved.** Each annotated object gets an
   `@annotation_types` array; declaring `annotation :annotation_types` collides
-  with it (probe_01: writing to it raised `NoMethodError` against `nil`).
+  with it; writing to it raised `NoMethodError` against `nil`.
 
 ## Introspection and serialisation
 
@@ -108,7 +104,7 @@ s.annotation_id     # => "860c73f490edb8115064663b7f579d73"
 - `Annotation.setup(obj, "A|B", hash)` — the generic deserialiser. The type
   string is split on `|`, each name resolved with `Object.const_get`. **Unknown
   names only warn and are skipped** (`Log.warn "Annotation NoSuchAnnotation not
-  defined"`, probe_01) — no exception.
+  defined"`) — no exception.
 
 ### Instance-side helpers
 
@@ -123,10 +119,10 @@ s.annotation_id     # => "860c73f490edb8115064663b7f579d73"
 
 ## Round-trips and copies
 
-- **Marshal round-trips** annotations (P42, probe_01): the singleton modules
+- **Marshal round-trips** annotations: the singleton modules
   survive dump/load.
-- **Only `dup` loses them; `clone` keeps them** (probe_02:
-  `dup is_annotated? => false`, `clone is_annotated? => true, .a => 1` —
+- **Only `dup` loses them; `clone` keeps them**
+  (`dup is_annotated? => false`, `clone is_annotated? => true, .a => 1` —
   `clone` copies the singleton class, `dup` does not): to re-annotate a `dup`
   copy the metadata explicitly with `annotation_hash` →
   `Annotation.setup` / `MyModule.setup`, or call `#annotate` on the copy.
@@ -147,7 +143,7 @@ arr.first.organism     # => "Human"
 Overrides provided in `lib/scout/annotation/array.rb`:
 
 - `[]` `(pos, clean = false)` — the element is re-annotated unless the second
-  argument is truthy, in which case it is returned clean (probe_09: a fresh
+  argument is truthy, in which case it is returned clean (a fresh
   array's `fresh[0, true]` is an un-annotated `String` while `fresh[1]` is
   annotated);
 - `first`, `last`, `each_with_index`, `each`, `inject`, `collect`, `select` —
@@ -156,8 +152,7 @@ Overrides provided in `lib/scout/annotation/array.rb`:
 - `subset(list)`, `remove(list)` — set operations (`&`, `-`) with
   re-annotation.
 
-**Limits** — live probe `tmp/rewrite_C/probe_09_annotated_array.rb` (method
-owners plus actual results): `map`, `zip`, `filter_map`, `flat_map`,
+**Limits** (method owners audited against `lib/`): `map`, `zip`, `filter_map`, `flat_map`,
 `each_slice`, `values_at` and `count` are **not overridden** (their owner is
 `Array`/`Enumerable`) and return plain results with no annotations — `ary.map
 { |x| x }` yields `[false, false, false]` under `Annotation.is_annotated?`,
@@ -165,7 +160,7 @@ while `ary.each` yields `[true, true, true]`, and `zip` keeps annotations only
 on the container-side elements.
 
 **Requirement:** elements must be extendable. `AnnotatedArray` over an Array
-of `Integer`s raises `TypeError: can't define singleton` (probe_09) — use
+of `Integer`s raises `TypeError: can't define singleton` — use
 Strings or other extendable objects.
 
 ## NamedArray is a separate thing

data/doc/developer/Configuration.md

@@ -24,8 +24,6 @@ token on `::` and returns `[token, priority]`:
 | `key:` / `key:<name>` | 20 | the key itself; LOWEST priority |
 | `token::N` | N | explicit numeric suffix always wins over the defaults |
 
-Verified by `tmp/rewrite_D/probe_11_token_probe.rb`:
-
 ```text
 workflow:x   => ["workflow:x", 4]
 task:x       => ["task:x", 3]
@@ -44,8 +42,8 @@ plain value.
 ## A worked example
 
 A common misreading is "workflow overrides task". The numbers say the
-opposite — `line` (1) outranks `workflow` (4). `tmp/rewrite_D/probe_13_get_internals.rb`
-stacks all four tokens on one key and shows the chain end-to-end:
+opposite — `line` (1) outranks `workflow` (4). Stacking all four tokens on
+one key shows the chain end-to-end:
 
 ```ruby
 def fresh(k); Scout::Config::CACHE.delete(k); end
@@ -73,11 +71,11 @@ Scout::Config.get(k,'workflow:W','task:T')
 ```
 
 Within one priority bucket the LAST `set` wins (`priorities[prio].unshift`,
-`lib/scout/config.rb:83`; verified `probe_13` `two task entries => "second"`).
+`lib/scout/config.rb:83`; two entries set with `task:` leave the *second*
+as the winner).
 
 Explicit suffixes punch through the table, both ways — `::1` promotes an
-entry above every default token, `::30` buries it below `key:` (probe_13,
-cases `q6`/`q7`). Note the suffix is per-entry, not per-key: it re-prices one
+entry above every default token, `::30` buries it below `key:` (cases `q6`/`q7`). Note the suffix is per-entry, not per-key: it re-prices one
 `set` call, it does not change the token for later calls.
 
 ### Implicit caller tokens
@@ -85,8 +83,7 @@ cases `q6`/`q7`). Note the suffix is per-entry, not per-key: it re-prices one
 Every `Config.get` appends `file:<caller>` and `line:<caller>:<n>` derived
 from `caller` (`lib/scout/config.rb:119-127`), after filtering out frames
 matching the legacy rbbt regexes (see *Legacy internals* below). Entries set
-with those tokens match without being named in the call (verified
-`probe_12`, `matched by implicit caller file token => "v"`).
+with those tokens match without being named in the call.
 
 ## `etc/config` files
 
@@ -103,9 +100,7 @@ key value token
 (`lib/scout/config.rb:27-31`). `find_all` returns paths in `map_order`
 (`current, user, home, local, global, usr, lib, fast, cache, bulk, ...`), so
 the **reverse** order loads the *most specific* file (e.g. `$PWD/etc/config`)
-**first** and `$HOME/.scout/etc/config` last. Two files setting the same key
-with the same (implicit `key:`) token were tested by
-`tmp/rewrite_D/probe_23_findall_order.rb`:
+**first** and `$HOME/.scout/etc/config` last.
 
 ```text
 map_order    => [:current, :user, :home, ...]
@@ -130,33 +125,30 @@ one key it auto-adds the `key:<name>` token (`add_entry`,
 `Config.get(key, *tokens)` (`lib/scout/config.rb:94-155`) does four things
 after resolving the winner:
 
-1. **`'false'` becomes `false`** — the ONLY string-to-object coercion.
-   Verified in `tmp/rewrite_D/probe_10_env.rb`: `'false'` → `false`
-   (FalseClass), but `'TRUE'`, `'0'` and `'42'` all stay Strings.
-2. **`'nil'` becomes `nil`** (probe_10).
+1. **`'false'` becomes `false`** — the ONLY string-to-object coercion
+   (`'TRUE'`, `'0'` and `'42'` all stay Strings).
+2. **`'nil'` becomes `nil`**.
 3. **`env:VAR[,VAR2]`** in the resolved value is replaced by the first set
-   environment variable, and `get` returns `nil` if none is set (probe_10,
-   `'from-env'`).
+   environment variable, and `get` returns `nil` if none is set.
 4. Every `get` appends `[key, value, tokens]` to `GOT_KEYS` — an audit trail
-   of what was asked and answered (probe_10). `with_config` snapshots and
-   restores it.
+   of what was asked and answered. `with_config` snapshots and restores it.
 
 Options hash as last argument:
 
 - `:default => v` — used when no entry matches.
-- `:env => 'VAR1,VAR2'` — first set env var becomes the default (probe_10).
+- `:env => 'VAR1,VAR2'` — first set env var becomes the default.
 
 A `Symbol` key raises `TypeError` — the cache is keyed by `key.to_s`, but
 `CACHE[key.to_s]` is called after `match` has already used the raw key;
 `Config.get(:symbol)` raises `TypeError: no implicit conversion of Symbol
-into String` (probe_10). Use String keys.
+into String`. Use String keys.
 
 ## `with_config` and `process_config`
 
 `with_config { ... }` (`lib/scout/config.rb:157-166`) dups every `CACHE`
 bucket and `GOT_KEYS`, yields, and restores both in an `ensure`. Anything
 `set` inside the block is rolled back — including sets made by code you
-call (probe_10: `inside => "inside"`, `after => "outside"`). It is the
+call (`inside => "inside"`, `after => "outside"`). It is the
 mechanism that keeps config changes from leaking out of a sub-operation.
 
 `Config.process_config(config)` (`lib/scout/config.rb:168-180`) interprets
@@ -165,11 +157,9 @@ a CLI `--config` argument, in this order:
 1. existing file path → `load_file`
 2. name of an existing `Scout.etc.config_profile[config]` file → `load_file`
 3. otherwise a `"key value token..."` string. The `::N` suffix is mandatory
-   in the stored token: any token without one gets `prio = "0"`, i.e. the
-   token is re-emitted as `token::0`.
+  in the stored token: any token without one gets `prio = "0"`, i.e. the
+  token is re-emitted as `token::0`.
 
-Verified by `tmp/rewrite_D/probe_17b.rb` / `probe_17c.rb`. The subtle part
-of case 3 is that the stored token keeps the suffix, so `process_config
 "k3 cli workflow::0"` stores the token `workflow::0`, whose *name* is the
 bare string `workflow` at priority 0 (stronger than `task`=3,
 `file`=2, `line`=1, `key:`=20), and it does **not** match a call like
@@ -190,8 +180,8 @@ carrying an explicit smaller `::N` — but only for lookups that pass the bare
 
 ## Environment variables read by the gem
 
-Verified by grep over `lib/` and, where noted, executed probes
-(`tmp/rewrite_D/probe_10_env.rb` covers the `env:`/`:env` machinery; the
+Established by grep over `lib/`
+(covers the `env:`/`:env` machinery; the
 rest are read directly from source):
 
 | variable | read by | effect |
@@ -221,7 +211,7 @@ frames whose path matches those patterns are skipped when deriving
 ## Thread-safety
 
 There is no mutex anywhere in `lib/scout/config.rb` (`Scout::Config` has no
-`Mutex` ivar; verified `tmp/rewrite_D/probe_09_threads_fork.rb`). `CACHE`
+`Mutex` ivar; 
 and `GOT_KEYS` are plain shared structures and `add_entry` does
 read-modify-write (`CACHE[key] ||= []; CACHE[key] << ...`). Concurrent
 `set`/`get` from threads is therefore unprotected; the gem's own processes

data/doc/developer/CoreUtilities.md

@@ -14,8 +14,6 @@ The small modules everything else in the stack is built on:
 type and every `Hash` operation still works. Reads and writes are
 indifferent between String and Symbol keys.
 
-Verified by `tmp/rewrite_D/probe_06_indiferent_misc.rb`:
-
 ```ruby
 h = IndiferentHash.setup({ 'a' => 1 })
 h[:b] = 2
@@ -38,7 +36,7 @@ h.keys     # => ["a", "b"]      (first-written form is kept)
 ### The destructive pair
 
 `process_options(hash, *keys)` **destroys** the keys it extracts — it
-`delete`s them (verified: `process_options(opts, :a, :b)` leaves
+`delete`s them (`process_options(opts, :a, :b)` leaves
 `{:extra=>3}`). `pull_keys(hash, :prefix)` returns the sub-hash under that
 prefix key AND removes it from the original
 (`pull_keys({persist: true, x: 1}, :persist)` => `{:persist=>true}`, hash
@@ -56,8 +54,7 @@ in the coercion list — see the asymmetry below.
 (`/\w+=(\"[^\"]*\"|[^\s\"]+)/`), strips surrounding quotes, and splits a
 value containing a comma into an Array. Its coercion ladder is shorter than
 `string2hash`'s: `true`/`false` are **not** special-cased at all, so both
-survive as Strings (verified `tmp/rewrite_D/probe_20_parse_options_false.rb`:
-`parse_options('a=false')` => `{"a"=>"false"}`,
+survive as Strings (`parse_options('a=false')` => `{"a"=>"false"}`,
 `parse_options('a=1,b=2')` => `{"a"=>["1", "b=2"]}` — the comma split eats
 the second pair — and `parse_options('a="x y"')` => `{"a"=>"x y"}`).
 `print_options(options)` is the inverse, re-quoting values with spaces.
@@ -67,11 +64,10 @@ branch (`options.rb:110`) is dead code for the plain case: `a=false` goes
 through `options[key] = value` and the String survives. The only way the
 branch is reached is when `false` is the *value* of a pair that the default
 `#` separator has already split off — and the executed result is still
-`"false"` in every probed form (`tmp/rewrite_D/probe_21_s2h_false_traced.rb`).
+the executed result is still `"false"` in every form.
 `parse_options` has no boolean branches at all. `Scout::Config.get`, by
 contrast, turns a stored `'false'` into the boolean `false` (see
-[Configuration.md](Configuration.md)). Verified by
-`tmp/rewrite_D/probe_19_false_coercion.rb` and `probe_20_parse_options_false.rb`:
+[Configuration.md](Configuration.md)).
 
 ```text
 string2hash('a=true')            => {"a"=>true}
@@ -94,7 +90,7 @@ single pair because the separator never appears — the value is the literal
 `IndiferentHash.serializable(obj)` (`serialize.rb`) returns a deep copy of
 Hash/Array structures. Arrays longer than 100 are truncated: first 70 +
 `'...'` + last 30 + the marker `"TRUNCATED only 100 out of N shown"`
-(probe_06: 250-element array => 102 elements, marker last). Use it for
+(250-element array => 102 elements, marker last). Use it for
 logging fingerprints, not for round-tripping data.
 
 ### CaseInsensitiveHash
@@ -104,8 +100,7 @@ logging fingerprints, not for round-tripping data.
 `values_at` are overridden; writes are plain `Hash` writes. Reads are
 downcase-mapped against the *first* case seen for each key, so a Symbol
 key can never be found by a String lookup (Symbol has no meaningful
-downcase mapping in `downcase_keys`). Verified by
-`tmp/rewrite_D/probe_24_cihash_writes.rb`:
+downcase mapping in `downcase_keys`).
 
 ```text
 ci = CaseInsensitiveHash.setup({"Key" => 1})
@@ -117,7 +112,18 @@ ci[:third]      => 7
 ```
 
 Treat it as a read-side convenience for String-keyed hashes; it is not an
-indifferent-access container.
+indifferent-access container. One more trap: the downcase map is
+memoized on the first *missed* case-insensitive lookup and **never
+invalidated by later writes** — if you look up a missing key before
+storing it, the stored key stays invisible to case-insensitive reads:
+
+```text
+ci["fourth"]   # => nil     (builds @downcase_keys WITHOUT "Fourth")
+ci["Fourth"] = 9
+ci["fourth"]   # => nil     (stale map; only ci["Fourth"] works)
+```
+
+Build the hash completely (or call `ci.instance_variable_set(:@downcase_keys, nil)` to reset) before relying on case-insensitive reads.
 
 ## NamedArray
 
@@ -143,9 +149,34 @@ So `count`/`first`/`last`/`zip` are Array's, and any field that happens to
 be named like an Array method is unreachable through the accessor. The
 `key` is exposed via `all_fields` (`[key, fields].compact.flatten`).
 
+### Name resolution is exact-first, then fuzzy — and fuzzy can bite
+
+`identify_name` (`lib/scout/named_array.rb:22`) resolves a String
+selector in this order: **exact match** on `to_s` equality → numeric
+string as a position → **fuzzy match** via `field_match`
+(`lib/scout/named_array.rb:10`) → `nil`. The fuzzy step accepts:
+
+- a field containing `(selector)` — `'Human'` finds `Organism(Human)`
+- a field that is `selector + ' ' + …` or the reverse — `'Sample'`
+  finds `'Sample other'`
+
+Matching is **case-sensitive** (`'alpha'` does not find `'Alpha'`), and
+a miss is silent:
+
+```ruby
+row["nope"]        # => nil      (no error)
+row["nope"] = 3    # no-op       (returns 3, stores nothing)
+row.positions("nope")  # => nil
+row.values_at("nope")  # raises TypeError (nil position reaches Array#values_at)
+```
+
+The practical risk: a slightly wrong column name can silently resolve
+to a *different* column via the fuzzy prefix rule, so prefer exact
+names — or `row.positions(name)` first when unsure.
+
 ## Misc.format family
 
-All from `lib/scout/misc/format.rb`, verified by probe_06/probe_15:
+All from `lib/scout/misc/format.rb`:
 
 | call | result |
 |---|---|
@@ -164,8 +195,7 @@ leading `-` for negatives. The parser is `str.scan(/(\d+)(\w*)/)` and `\w*`
 is greedy, so **each number may be followed by only one unit token**.
 `"1h30m"` is scanned as the single pair `["1", "h30m"]`; `"h30m"` is not in
 the token table, so the product becomes `1 * nil` and raises
-`TypeError: nil can't be coerced into Integer`. Verified by probe_06 and
-`tmp/rewrite_D/probe_16_timespan_exact.rb`:
+`TypeError: nil can't be coerced into Integer`.
 
 ```text
 Misc.timespan('1h')    => 3600
@@ -176,6 +206,7 @@ Misc.timespan('1y')    => 31536000
 Misc.timespan('1:30')  => 90    (HH:MM clock form)
 Misc.timespan('-1h')   => -3600
 Misc.timespan('1h30m') => TypeError: nil can't be coerced into Integer
+Misc.timespan('1h 30m') => 5400  (a space separates the pairs — works)
 Misc.timespan('1x')    => TypeError: nil can't be coerced into Integer
 Misc.timespan('2')     => 2   (bare number uses the default unit, seconds)
 ```
@@ -189,8 +220,7 @@ add the seconds yourself.
 `"9dd4e461268c8034f5c8564e155c67a6"`). `Misc.file_md5(path)` hashes the
 file **contents**; when the digest falls back to a plain `Misc.digest` on a
 path string, it hashes the **path string**, not the content — a missing
-`/nope/x` still yields a digest (`14470bb0...`) instead of raising
-(probe_06). Check `File.exist?` yourself if that distinction matters.
+`/nope/x` still yields a digest (`14470bb0...`) instead of raising. Check `File.exist?` yourself if that distinction matters.
 
 ## `Misc.insist`
 
@@ -203,7 +233,7 @@ See [ErrorHandling.md](ErrorHandling.md) for the retry protocol with
 auto-required** (verify with `defined?(Hook)` => nil after
 `require 'scout-essentials'`; it becomes a constant only after
 `require 'scout/misc/hook'`). It exposes `Hook.extended`, `Hook.apply` and
-`hook_method` (probe_06). `Hook.apply(hook_class, base_class)` redefines the
+`hook_method`. `Hook.apply(hook_class, base_class)` redefines the
 methods the two classes share on `base_class`, aliasing the originals as
 `orig_<name>` and dispatching first to the registered hooks, honouring an
 optional `claim(*args)` predicate on each hook. It is the mechanism behind
@@ -214,7 +244,7 @@ tool registration in `CMD::TOOLS`-style setups.
 Root: `TmpFile.tmpdir` => `$HOME/tmp/scout/tmpfiles` (here
 `/home/mvazque2/tmp/scout/tmpfiles` — a machine-specific example value),
 overridable with `TmpFile.tmpdir=`;
-`TmpFile.user_tmp('sub')` => `$HOME/tmp/scout/sub` (probe_05/probe_15).
+`TmpFile.user_tmp('sub')` => `$HOME/tmp/scout/sub`.
 
 ### Naming conventions (`tmp_for_file`, `lib/scout/tmpfile.rb:98-118`)
 
@@ -227,7 +257,7 @@ overridable with `TmpFile.tmpdir=`;
 | `:md5` tail | digest of the remaining options |
 | `MAX_FILE_LENGTH = 150` | names longer than this are truncated |
 
-Verified shapes (probe_05, re-run as probe_13 for gate 2; `...` is
+Supported shapes (`...` is
 `TmpFile.tmpdir`, here `~/tmp/scout/tmpfiles`):
 
 ```text
@@ -245,14 +275,14 @@ the name and, because `other_options` is then non-empty, still gets the
 **`nil` is not `#{}`**: `tmp_for_file('/a/b/c', nil, ...)` raises
 `NoMethodError: super: no superclass method 'include?' for nil` from
 `process_options` — pass an explicit empty Hash as the second argument when
-you use `other_options` (probe_13).
+you use `other_options`.
 
 ### `with_file` leaks on raise
 
 `TmpFile.with_file(content, erase, options)` writes the temp file, yields
 it, then `Open.rm_rf tmpfile if Open.exist?(tmpfile) && erase` — there is
 **no `ensure`**. If the block raises, the temp file stays on disk
-(probe_05: file still present after `raise "boom"`; removed normally when
+(file still present after `raise "boom"`; removed normally when
 the block succeeds). Add your own `begin/ensure` around `with_file` when the
 block can fail. See [ErrorHandling.md](ErrorHandling.md).
 

data/doc/developer/DesignPrinciples.md

@@ -3,8 +3,6 @@
 The handful of conventions that hold across `lib/scout`. Everything below is
 observable in the source of this repo; nothing here is aspirational.
 
-Everything below is backed by `tmp/rewrite_C/probe_11_design.rb`
-(probe_11), which reproduces each claim from a clean `require`.
 
 ## Composition by annotation
 
@@ -32,7 +30,7 @@ The public namespaces (`Path`, `Open`, `CMD`, `Persist`, `Misc`, `Log`,
 `Resource`, `SOPT`, `IndiferentHash`, `TmpFile`, `Annotation`) are modules
 whose methods are module-functions or class methods. Subclassing one of them
 is not an option — `Persist` is a `Module`, so `class X < Persist` raises
-`TypeError: superclass must be an instance of Class` (probe_11). The reuse
+`TypeError: superclass must be an instance of Class`. The reuse
 pattern is `extend` (`resource/path.rb`, `annotation/annotated_object.rb`).
 
 ## Options hashes over positional flags
@@ -72,7 +70,7 @@ class KeepBar      < Exception; end   # log/progress/util.rb: keep the bar
 bare `rescue` *does* catch.)
 
 The point is deliberate: a bare `rescue => e` (which rescues
-`StandardError`) **does not intercept them** — probe_11 raises each in turn
+`StandardError`) **does not intercept them**
 inside `begin ... rescue => e` and shows the signal escapes the bare
 `rescue`. A producer that wants the caller to keep the stream it was handed
 raises `DontClose` (carrying the result in `.payload`), and `Open.open`'s
@@ -90,8 +88,8 @@ Practical rules:
 - aborting a `CMD` pipe surfaces as `Aborted` (a `StandardError`) or as the
   `AbortedStream` **module** that is `extend`ed onto the stream object —
   these are what streaming consumers should rescue
-  ([Streaming Model](StreamingModel.md); probe_11 shows
-  `AbortedStream` is a Module, not a Class).
+  (see [Streaming Model](StreamingModel.md); `AbortedStream` is a
+  Module, not a Class).
 
 ## Atomic writes
 
@@ -116,9 +114,9 @@ Anything that produces a file other users may read concurrently goes through
 
 Cleanup is explicit, not automatic. `TmpFile.with_file` removes the temporary
 file only when the block ends normally — there is no `ensure` around the
-`yield`, so an exception leaves the file behind (probe_11; verified against
-`lib/scout/tmpfile.rb:71-73`). Likewise stream closing depends on the signal classes
-above, and progress bars rely on `Log::ProgressBar.remove_bar` being called.
+`yield`, so an exception leaves the file behind. Likewise stream closing
+depends on the signal classes above, and progress bars rely on
+`Log::ProgressBar.remove_bar` being called.
 When correctness matters, put the cleanup in an `ensure` or use
 `Open.consume_stream`.