iriq 0.1.0 → 0.30.2

data/completions/_iriq

@@ -0,0 +1,52 @@
+#compdef iriq
+# Zsh completion for the `iriq` CLI.
+#
+# Install (pick one):
+#   - Persist via Homebrew: brew install dpep/tools/iriq drops this file
+#     into Homebrew's zsh site-functions dir automatically.
+#   - Try in the current shell:
+#       source <(iriq completion zsh)
+#   - Or copy this file into a directory listed in $fpath and run
+#     `compinit` (typically run by your zshrc).
+
+_iriq() {
+    local context state state_descr line
+    typeset -A opt_args
+
+    _arguments -C \
+        '(-h --help)'{-h,--help}'[show usage]' \
+        '(-V --version)'{-V,--version}'[print version]' \
+        '(-p --parse)'{-p,--parse}'[parsed fields section]' \
+        '(-n --normalize)'{-n,--normalize}'[normalized section]' \
+        '(-c --canonical)'{-c,--canonical}'[canonical form section]' \
+        '(-e --explain)'{-e,--explain}'[annotated trace section]' \
+        '(-j --json)'{-j,--json}'[JSON output]' \
+        '(-J --ndjson)'{-J,--ndjson}'[newline-delimited JSON]' \
+        '(-N --no-hints)'{-N,--no-hints}'[use {type} placeholders, not {hint}]' \
+        '--hints[enable hint placeholders]' \
+        '--no-scheme-less[skip schemeless URL extraction]' \
+        '--scheme-less[enable schemeless URL extraction]' \
+        '--corpus[load/create a JSON or SQLite corpus]:corpus path:_files -g "*.(json|db|sqlite|sqlite3)"' \
+        '--host[host-keying strategy for clustering]:strategy:(full registrable reg none)' \
+        '--stats[print rolling aggregates]' \
+        '--reinfer[replay the source-IRI log]' \
+        '--propose-recognizers[propose new Recognizers from observed shapes]' \
+        '--cross-host-shapes[list route shapes seen across multiple hosts]' \
+        '--activate-above[auto-activate proposals at or above this confidence]:F:' \
+        '--min-observations[proposal threshold]:N:' \
+        '--min-coverage[proposal threshold]:F:' \
+        '--min-hosts[threshold for proposals and cross-host shapes]:N:' \
+        '1:command or file:->first' \
+        '*:file:_files' \
+        && return 0
+
+    case $state in
+        first)
+            _alternative \
+                'commands:command:(cluster completion)' \
+                'files:file:_files'
+            ;;
+    esac
+}
+
+_iriq "$@"

data/completions/iriq.bash

@@ -0,0 +1,70 @@
+# Bash completion for the `iriq` CLI.
+#
+# Install (pick one):
+#   - Persist via Homebrew: brew install dpep/tools/iriq automatically
+#     drops this script into Homebrew's bash-completion dir.
+#   - Try it out in the current shell:
+#       source <(iriq completion bash)
+#   - Persist to ~/.bashrc:
+#       echo 'source <(iriq completion bash)' >> ~/.bashrc
+#   - Or write to your system's bash completion dir:
+#       iriq completion bash > /usr/local/etc/bash_completion.d/iriq
+
+_iriq() {
+    local cur prev words cword
+    _init_completion 2>/dev/null || {
+        cur="${COMP_WORDS[COMP_CWORD]}"
+        prev="${COMP_WORDS[COMP_CWORD-1]}"
+    }
+
+    # Argument completion for flags that take a value.
+    case "$prev" in
+        --corpus)
+            # Corpus paths are file-shaped. _filedir picks up *.json / *.db
+            # / *.sqlite / *.sqlite3 by default extension; the user can also
+            # tab through any path.
+            _filedir
+            return
+            ;;
+        --host)
+            COMPREPLY=( $(compgen -W "full registrable reg none" -- "$cur") )
+            return
+            ;;
+        --min-observations|--min-hosts|--min-coverage|--activate-above)
+            # Numeric argument — no completion candidates.
+            return
+            ;;
+        completion)
+            COMPREPLY=( $(compgen -W "bash zsh" -- "$cur") )
+            return
+            ;;
+    esac
+
+    # If the current token starts with `-`, complete flags.
+    if [[ "$cur" == -* ]]; then
+        local flags="-h --help -V --version -p --parse -n --normalize -c --canonical -e --explain
+                     -j --json -J --ndjson -N --no-hints --hints --no-scheme-less
+                     --scheme-less --corpus --host --stats --reinfer
+                     --propose-recognizers --activate-above --cross-host-shapes
+                     --min-observations --min-coverage --min-hosts"
+        COMPREPLY=( $(compgen -W "$flags" -- "$cur") )
+        return
+    fi
+
+    # First non-flag positional may be a subcommand or a file/IRI.
+    if [[ $COMP_CWORD -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "cluster completion" -- "$cur") )
+        # Also offer files for the auto-extract path (iriq ./access.log).
+        local files
+        files=$(compgen -f -- "$cur")
+        if [[ -n "$files" ]]; then
+            COMPREPLY+=( $files )
+        fi
+        return
+    fi
+
+    # Otherwise fall back to file completion (e.g. `iriq cluster <file>`).
+    _filedir
+}
+
+complete -F _iriq iriq

data/docs/ARCHITECTURE.md

@@ -0,0 +1,223 @@
+# iriq architecture
+
+As of v0.28.0, this describes the system that's actually in the repo —
+Phase 1 of the rearchitecture roadmap (target model below) is complete,
+and Phase 2 has added the learning layer on top. Originally written as
+the *target* model at the start of Phase 1; the implementation has
+caught up.
+
+`ROADMAP.md` tracks what's still pending (inter-position correlations,
+near-shape clustering, and Phase 3 productize items).
+
+For the inner details, read the source: `lib/iriq/{recognizer,position,
+shape,evidence,event,reducer,recognizer_proposal,synthesized_recognizer,
+cross_host_shape,corpus}.rb` and their Go counterparts at the repo root.
+
+## Core principle
+
+The system pivots around **Position** (a slot in a host's structure) and
+**Evidence** (what we know about a Position). Strings are observations;
+types are inferences. Everything composable hangs off these two nouns.
+
+## Core types
+
+### Identifier (existing, mostly unchanged)
+
+A parsed IRI: scheme, host, port, path_segments, query_params, fragment,
+plus `kind ∈ {:url, :urn}` and the urn `nss`. Produced by `Parser` from a
+candidate string; produced in bulk by `Extractor` from free text.
+
+### Position (new)
+
+A stable identity for a slot in a host's structure.
+
+```
+Position {
+  host:    string        # normalized per host_strategy (full|registrable|none)
+  scope:   :path | :query
+  locator: path_prefix   # for :path — the typed-shape prefix that led here
+         | param_name    # for :query — the ?key= name
+}
+```
+
+Two Identifiers occupy the *same* Position when their hosts agree and their
+typed prefix agrees. "Typed prefix" means the prefix rendered with inferred
+types (`/users/{integer}/...`), not raw values. This makes Position identity
+robust to the specific values seen.
+
+### Recognizer (new)
+
+A pluggable classifier for a single (or small family of) types.
+
+```
+Recognizer#try(string) -> { type:, confidence:, canonical:, notes: } | nil
+```
+
+- `type` is a symbol from the recognized vocabulary (uuid, date, integer, …).
+- `confidence` is in `[0, 1]`. Calibrated against
+  `spec/fixtures/calibration/`.
+- `canonical` is the canonical form (e.g. ISO date for `:date`, uppercased
+  ISO 4217 for `:currency`). `nil` means "use the input as-is".
+- `notes` is an optional array of strings the Trace view may surface.
+
+Recognizers are independent. There is no global ordering. The
+**SegmentClassifier becomes an ensemble** that runs each Recognizer and
+picks the highest-confidence answer above a floor. `:literal` is the
+fallback when no Recognizer fires above the floor.
+
+### Evidence (new)
+
+The universal substrate for explanation. A small fixed schema, emitted by
+both classification and inference.
+
+```
+Evidence {
+  position: Position
+  kind:     :lexical | :corpus | :recognizer | :neighbor | :policy
+  payload:  { ... kind-specific fields ... }
+  weight:   float in [0, 1]      # contribution to the final inference
+}
+```
+
+Examples:
+- `:recognizer` payload: `{ name:, type:, lexical_confidence: }`
+- `:corpus` payload: `{ observations:, distinct_values:, cardinality_frac: }`
+- `:neighbor` payload: `{ prior_literal:, inferred_hint: }`
+- `:policy` payload: `{ rule:, applied: }` (e.g. "ipv4→ip umbrella collapse")
+
+`Trace` and `Explanation` are *views* over a list of Evidence. They render
+strings for human consumption but the data shape is shared.
+
+### Shape (new — replaces PathShape strings as the identity)
+
+An ordered list of typed Positions for a single Identifier path:
+
+```
+Shape { positions: [Position], inferred_types: [Symbol] }
+```
+
+`Shape#render(:string)` produces the human-readable form (`/users/{user_id}`)
+that today's `PathShape` produces. Cluster identity is the structural Shape,
+not the string. String renderings are derived for display, not for keying.
+
+### Cluster (existing; refactored)
+
+Same role: a group of Identifiers sharing (host, Shape). Internals shift to
+key on structural Shape; aggregation (`PositionStats`) is unchanged.
+Inference (variability promotion, enum detection, etc.) moves *out* of
+Cluster and into its own stage so it can be re-run over stored evidence
+without re-feeding observations.
+
+### Reducer (new)
+
+A function over the event stream that maintains a materialized view.
+
+```
+Reducer#apply(event, state) -> state
+```
+
+Examples ship in v1:
+- `HostCountsReducer`
+- `PositionStatsReducer`
+- `ClusterReducer`
+- `FingerprintReducer`
+
+Storage backends store the event log (or, equivalently, the materialized
+views — backends choose). Adding a new metric is: write a Reducer, declare
+its state shape; no other module changes.
+
+## Pipeline (target end-state)
+
+```
+text
+ └─► Extractor       ─► [candidate strings]
+       └─► Parser    ─► Identifier
+             └─► Recognition  ─► annotated segments + per-segment Evidence
+                   └─► Events ─► Storage event log
+                                  └─► Reducers ─► materialized views
+                                                   (PositionStats, Clusters, ...)
+                                        ├─► Inference  ─► per-Position type + Evidence
+                                        └─► Rendering  ─► normalized string / Shape view
+```
+
+Each stage is a separate module with input/output contracts. Inference
+re-reads materialized views; it does not require re-running the pipeline.
+
+## What this fixes (vs. the today code)
+
+- **No more string-fingerprint cluster keys.** Classifier tuning no longer
+  fractures clusters.
+- **No more order-dependent first-match classifier.** Add a Recognizer
+  without considering global ordering.
+- **`SegmentClassifier` stops being a god module.** Recognizers own their
+  patterns and canonical forms; reference data (locales, currencies,
+  countries) lives in `ReferenceData::*`; display names / variability
+  predicate live in a small `Policy` / `Naming` module.
+- **One Normalizer.** Mechanical mode is "NullEvidence" — no special case.
+- **Two-axis type taxonomy.** Lexical shape and semantic role can grow
+  independently. Cardinality character is a *property of Position*, not of
+  type — `:year`, `:http_status`, `:enum` collapse into "integer-shape +
+  bounded-cardinality" expressed via Evidence.
+- **Re-runnable inference.** Threshold tuning no longer requires
+  re-observation.
+- **One explanation substrate.** Trace, Explanation, future schema export,
+  future PR-diff annotator are all views over Evidence.
+
+## What stays the same
+
+- `Identifier` as the parsed record.
+- `Parser` + `Extractor` — already cleanly separated.
+- `Storage::*` backends (Memory, Json, Sqlite). Internals change to persist
+  events rather than ad-hoc counters, but the file-extension routing API
+  (`Corpus.open(path)`) stays.
+- Public CLI surface (`exe/iriq`, the Go `cmd/iriq` binary).
+- The four `Iriq.*` module methods: `parse`, `normalize`, `explain`,
+  `extract`.
+
+## Extensibility (where it stands)
+
+- **Recognizer registry**: per-classifier and mutable as of v0.26.
+  `SegmentClassifier#register_recognizer` appends to the instance's
+  ensemble; `SegmentClassifier::DEFAULT` is the module-level singleton
+  that fresh corpora share, and the first `Corpus#activate_proposal`
+  call swaps to a private classifier so activations don't leak.
+  External users registering their own Recognizer subclasses works
+  today via the same API; an *external* registry / discovery surface
+  (load Recognizers from a config file or env var) is still future
+  work.
+- **ProposalStrategy**: pluggable via `Iriq::ProposalStrategy::DEFAULTS`.
+  Adding a strategy = define a class with `#propose(storage, **opts)`
+  and append. v1 ships one strategy (PrefixUnderscoreId); next-segment
+  / cross-position correlation strategies are pending Phase 2 work.
+- **Reducer registry**: the dispatch table `Iriq::Reducer::DEFAULTS`
+  maps `Event` subclasses to reducer lambdas. Adding a metric = define
+  an `Event` subtype, write a Reducer, register it. The registry is
+  exposed as a constant; safe to monkeypatch in user code, though no
+  public registration API ships yet.
+- **Storage backends**: three ship (Memory, JSON, SQLite). Adding a
+  fourth = implement the `Storage` interface (lib/iriq/storage/memory.rb
+  is the canonical reference), wire it into `Storage.open` extension
+  routing, add it to `script/cli_parity.sh`.
+
+## Learning layer (Phase 2, on top of the substrate above)
+
+The Phase 1 substrate gives us typed observations, structured Shape,
+and re-runnable inference. Phase 2 builds the learning pipeline on top:
+
+- **Source-IRI log** (v0.21). Storage persists every observed canonical
+  IRI alongside the materialized views. `Corpus#reinfer` drops the
+  views and replays the log through the current classifier + reducers
+  — lets us tune thresholds or swap the classifier without re-feeding.
+- **RecognizerProposal** (v0.23). A struct describing a learned
+  pattern: prefix / suggested_type / positions / hosts / coverage /
+  confidence / observation_count / sample_values / strategy.
+  Emitted by ProposalStrategy implementations; not auto-applied.
+- **SynthesizedRecognizer** (v0.26). Built from a proposal's prefix;
+  regex `^<prefix>[A-Za-z0-9]+$`, `Specificity::SEMANTIC`. Same
+  Recognizer interface as the built-ins (UUID, Date, Integer) — the
+  ensemble doesn't know the difference.
+- **CrossHostShape** (v0.27). Read-side: route shapes that recur
+  across multiple hosts. Independent evidence of semantic pattern.
+- **Confidence formula** (v0.28). `min(1.0, coverage + 0.05 *
+  (host_count - 1))`. Single-host proposals are unchanged; cross-host
+  proposals get boosted. `--activate-above F` checks confidence.

data/docs/ROADMAP.md

@@ -0,0 +1,190 @@
+# iriq roadmap
+
+A multi-quarter plan to lift iriq from a single-pass string classifier into an
+event-driven inference system over typed Positions. Pre-release; we will break
+APIs freely and bump minor versions per shipped feature.
+
+Source of the plan: principal-engineer architectural review on 2026-05-30,
+captured in the project history.
+
+## Where to pick up next time
+
+Last updated: 2026-05-31, current version **v0.28.0**.
+
+**Phase 1**: complete (v0.11 → v0.19). The structural foundation —
+Recognizer ensemble, Position, Shape, Evidence, single Normalizer,
+events + reducers — is all in place.
+
+**Phase 2**: 5 of 7 items shipped (v0.21 → v0.28).
+- ✅ Re-runnable inference (library + CLI)
+- ✅ Learned recognizers (library + propose CLI + auto-activate CLI)
+- ✅ Cross-host learning (catalog + confidence integration)
+- ⏭️ **Inter-position correlations** — next up. When slot A's value
+  predicts slot B's type, surface that ("after `/orgs/{org_id}/` the
+  next segment is almost always `users` or `repos`"). Read-side query
+  over existing cluster + position stats; no storage changes needed.
+  Estimated scope: similar to cross-host shape learning. One commit.
+- ⏭️ **Near-shape clustering** — edit-distance over Shapes catches
+  near-duplicates that today require exact match. Bigger scope — needs
+  a Shape distance metric, candidate-pair search, and CLI for
+  inspection. Two or three commits.
+
+**Phase 3**: not started. Schema export, PII mode, streaming observatory,
+external recognizer registry.
+
+**Housekeeping done**: Ruby 3.3 dropped (4d49509), shell completion
+with brew auto-install (v0.25), homebrew skill updated, README has the
+full learning-loop documentation, all CLI flags reflected in `-h` and
+completion scripts. Homebrew formula tracks 0.28.0.
+
+**Recommended next commit**: inter-position correlations. The
+read-side seam is clean (walk clusters, group segments by their
+predecessor) and the payoff is concrete (next-segment hints for
+corpus-informed normalization). Falls out of the existing data with
+no schema changes.
+
+## Operating ground rules (decisions on file)
+
+- **Backward compatibility:** none required while pre-1.0. Break what you must.
+  Bump the minor version per feature.
+- **Public API surface:** narrow on purpose. The four `Iriq.*` module methods
+  and the CLI are the contract; everything else may move freely. Dev speed
+  beats API stability for now.
+- **Ruby ↔ Go parity:** still the goal. The current discipline (Ruby-first,
+  fixture regen, Go-mirror, parity test) stays in force as the *acceptance
+  gate*; ordering within a single feature commit is implementer's call.
+- **Performance:** no hard target. Don't be wasteful. Watch out for obvious
+  regressions (per-segment allocation in hot paths, redundant classify calls,
+  etc.) but no benchmark gates yet.
+- **Extensibility:** internal-only is fine for v1. Design the seams so an
+  external recognizer registry is a small follow-up, not a redesign.
+- **Calibration data:** we generate and check in our own. See task #3.
+- **Commit discipline:** one feature, one commit, immediate push. Tests must
+  pass: `bundle exec rspec && go test ./... && script/cli_parity.sh`.
+
+## Phase 1 — Year 1: structural foundation
+
+Status: **complete**. All 9 tasks shipped in a single session, v0.11.0 → v0.19.0.
+
+Goal: stop being a 554-line `SegmentClassifier` doing five jobs. Land the
+substrate that the year-2 learning work compounds on.
+
+Ordered task list (each was a commit checkpoint, each bumped a minor version):
+
+1. ✅ **Docs + plan** — this file and `ARCHITECTURE.md`. Shipped at 866525f.
+2. ✅ **Recognizer interface (uuid, date, integer)** — carved three
+   Recognizers out of `SegmentClassifier`. No behavior change; first-match
+   equivalent. Shipped in v0.12.0 (b3cc889).
+3. ✅ **Calibration corpus** — 202 labeled segments across 25 types at
+   `spec/fixtures/calibration/segments.json`, generated by
+   `script/build_calibration.rb`. Loaded by both Ruby (`calibration_spec`)
+   and Go (`calibration_test.go`) as a regression suite + future
+   calibration target. Shipped in v0.13.0 (f9eb980).
+4. ✅ **Scored ensemble** — added Specificity bands (SEMANTIC, STRUCTURED,
+   BOUNDED, TYPED, PATTERN, FALLBACK) on each Recognizer's Verdict and an
+   Ensemble helper that picks max(specificity × confidence) with stable
+   earlier-wins tie-break. Shipped in v0.14.0 (924f1ba).
+5. ✅ **Position promoted to first-class** — Position is { host, scope ∈
+   {:path,:query}, locator } — a typed slot in a host's URL structure.
+   Storage contracts now take Position; SQLite schema gained a `scope`
+   column (bumped to v2). Shipped in v0.15.0 (954e7a6).
+6. ✅ **Structured Shape** — Shape is a value object: an ordered list of
+   typed segment entries plus Render() / Equal() over the structured form.
+   PathShape became a thin wrapper. Cluster gained `#shape_object`.
+   Shipped in v0.16.0 (97a60c2).
+7. ✅ **Evidence records + Trace as view** — Evidence is the structured
+   substrate for explanation: three subject kinds (segment / position /
+   cluster), five sources (lexical / recognizer / corpus / neighbor /
+   policy). Ruby Trace was rewritten to build Evidence internally and
+   render it into the same `{value, type, output, notes}` hash. Go ships
+   the Evidence types but kept Trace internals hand-coded (output parity
+   preserved). Shipped in v0.17.0 (9e1133e).
+8. ✅ **One Normalizer** — folded mechanical Normalizer and
+   corpus-informed Corpus#normalize into one entry point with an evidence
+   source. NullEvidence provides classifier-only behavior; Corpus
+   implements the same RenderPath / RenderQuery interface for
+   corpus-informed rendering. Shipped in v0.18.0 (24ad168).
+9. ✅ **Events + reducers** — Corpus.observe now builds an ordered Event
+   list (HostSeen, PathLengthSeen, RawShapeSeen, FingerprintSeen,
+   per-segment PositionSeen, ClusterAddition) and applies each through
+   the Reducer registry. Adding a new metric = define a new Event +
+   Reducer; no other module changes. Event list is transient today;
+   future commit can persist it for re-runnable inference. Shipped in
+   v0.19.0 (891fd12).
+
+End of Phase 1 deliverable: the same CLI surface, but the internals are an
+evidence-driven inference system over typed Positions with pluggable
+recognizers and re-runnable-inference-ready event emission.
+
+## Phase 2 — Year 2: learning that compounds on the new substrate
+
+Each of these is a non-trivial multi-PR initiative.
+
+- ✅ **Re-runnable inference (library)** — source-IRI log persisted alongside
+  materialized views; `Corpus#reinfer` drops the views and replays the log
+  through events + reducers. Lets users tune thresholds or swap the
+  classifier without re-feeding IRIs. Shipped in v0.21.0.
+- ✅ **Re-runnable inference (CLI)** — `iriq --corpus PATH --reinfer`
+  replays the log and prints a before/after summary. Parity scenarios
+  added for JSON + SQLite backends. Shipped in v0.22.0.
+- **Inter-position correlations** — when slot A's value predicts slot B's
+  type, surface that. Catches things like "the segment after `/orgs/{org_id}/`
+  is almost always `users` or `repos`".
+- ✅ **Learned recognizers** — full loop:
+    * `Corpus#propose_recognizers` scans observed values via pluggable
+      ProposalStrategy strategies (v0.23.0). v1 ships PrefixUnderscoreId
+      (detects `ghp_…`, `cus_…`, `sk_…` shapes at slug/opaque_id
+      positions).
+    * `iriq --corpus PATH --propose-recognizers [--json]` CLI flag with
+      tunable `--min-observations` / `--min-coverage` / `--min-hosts`
+      thresholds (v0.24.0).
+    * `Corpus#activate_proposal(p)` promotes a proposal into a live
+      SynthesizedRecognizer on the corpus's classifier, persists it,
+      and reinfers. Reopens re-apply via `Corpus.open`. Doesn't leak
+      to the module-level DEFAULT classifier — corpora are isolated
+      (v0.26.0).
+    * `iriq --corpus PATH --propose-recognizers --activate-above F`
+      auto-activates every proposal at or above coverage F (v0.26.0).
+- ✅ **Cross-host learning** — full integration:
+    * `Corpus#cross_host_shapes(min_hosts:)` lists route shapes that
+      recur across multiple hosts (independent evidence of semantic
+      pattern, not host-local quirk). CLI `--cross-host-shapes`. v0.27.0.
+    * Cross-host count wires into `RecognizerProposal#confidence`:
+      each additional host beyond the first adds 0.05 (capped at 1.0).
+      Single-host proposals get `confidence == coverage`; cross-host
+      proposals get boosted. `--activate-above F` checks confidence
+      (not raw coverage). Proposals are sorted by confidence desc.
+      v0.28.0.
+- **Near-shape clustering** — edit-distance over Shapes catches
+  near-duplicates that today require exact match.
+
+## Phase 3 — Year 3: productize
+
+Speculative; revisit after Phase 2.
+
+- Exported learned schemas (OpenAPI-ish: routes per host with inferred
+  types per Position).
+- Privacy/PII mode (recognizer-driven redaction policies).
+- Streaming observatory with shape-drift alerts.
+- External recognizer registry (the public surface for what Phase 1 keeps
+  internal).
+
+## Risks tracked
+
+- **Parity tax compounds.** Every refactor is 2× surface. If a refactor's Go
+  port slips a release, mark it explicitly in CHANGELOG and treat it as tech
+  debt — don't let it sit.
+- **Confidence calibration is theater without truth data.** Task #3 ships
+  before #4 for that reason.
+- **Recognizer-set versioning.** Once we ship pluggable recognizers, stored
+  corpora need to know which recognizer-set produced them. Plan: stamp
+  `recognizer_set_id` into `PositionStats` at observation time. Defer
+  implementation until Phase 2.
+
+## How to use this document
+
+- Update it as decisions change. It is not a frozen artifact.
+- Each completed Phase 1 task: tick it off, add a one-line "shipped in vX.Y.Z"
+  pointer. Don't delete history.
+- Bigger plan changes (reorder, scope cut, scope grow): leave the prior
+  list intact and append a "Plan change YYYY-MM-DD" note explaining why.

data/iriq.gemspec

@@ -4,18 +4,19 @@ Gem::Specification.new do |s|
   s.name        = "iriq"
   s.version     = Iriq::VERSION
   s.authors     = ["Daniel Pepper"]
-  s.description = "Semantic IRI/URI/URL/URN parsing, normalization, classification, and clustering."
-  s.files       = `git ls-files * ':!:spec'`.split("\n")
+  s.description = "IRI extraction, normalization, and clustering."
+  s.files       = `git ls-files * ':!:spec' ':!:script' ':!:bin' ':!:rust' ':!:go'`.split("\n")
   s.bindir      = "exe"
   s.executables = ["iriq"]
   s.homepage    = "https://github.com/dpep/iriq"
   s.license     = "MIT"
-  s.summary     = "Semantic IRI normalization and clustering."
+  s.summary     = "IRI extraction, normalization, and clustering."
 
-  s.required_ruby_version = ">= 3.2"
+  s.required_ruby_version = ">= 3.4"
 
   s.add_development_dependency 'debug', '>= 1'
   s.add_development_dependency 'rspec', '>= 3.10'
   s.add_development_dependency 'rspec-debugging'
   s.add_development_dependency 'simplecov', '>= 0.22'
+  s.add_development_dependency 'sqlite3', '>= 1.6'
 end