rsc-universal 0.1.1

package/skills/java/references/streams.md

@@ -0,0 +1,102 @@
+# Streams, Optional, Collectors (deep)
+
+Targets Java 21+; Gatherers are Java 24+ (final). The SKILL body has the essentials; this is
+the catalog and the decision table.
+
+## Collector catalog
+
+| Need | Collector |
+| --- | --- |
+| Immutable list | `Stream.toList()` (16+) |
+| Mutable list | `Collectors.toList()` |
+| Set | `Collectors.toSet()` |
+| Map | `Collectors.toMap(k, v)` (throws on dup key — pass a merge fn to allow) |
+| Group | `Collectors.groupingBy(classifier, downstream)` |
+| Partition (boolean) | `Collectors.partitioningBy(predicate)` |
+| Count / sum / avg | `counting()`, `summingLong(fn)`, `averagingDouble(fn)` |
+| Join strings | `Collectors.joining(", ", "[", "]")` |
+| Two collectors at once | `Collectors.teeing(c1, c2, merger)` |
+| Post-process result | `Collectors.collectingAndThen(c, finisher)` |
+| Reduce within a group | `Collectors.reducing(...)` or `mapping(fn, downstream)` |
+
+```java
+// teeing: min and max in one pass.
+record MinMax(int min, int max) {}
+MinMax mm = nums.stream().collect(Collectors.teeing(
+    Collectors.minBy(Integer::compare),
+    Collectors.maxBy(Integer::compare),
+    (lo, hi) -> new MinMax(lo.orElseThrow(), hi.orElseThrow())));
+```
+
+```java
+// toMap with a merge function to survive duplicate keys (otherwise IllegalStateException).
+Map<String, Payment> latest = payments.stream()
+    .collect(Collectors.toMap(Payment::id, p -> p, (a, b) -> b.newer(a) ? b : a));
+```
+
+## Custom collector
+
+```java
+// Collect into a domain accumulator when no built-in fits.
+Collector<Payment, ?, Ledger> toLedger = Collector.of(
+    Ledger::new,                 // supplier
+    Ledger::add,                 // accumulator
+    Ledger::merge);              // combiner (used only for parallel streams)
+Ledger l = payments.stream().collect(toLedger);
+```
+
+## flatMap, mapMulti, Gatherers
+
+```java
+// flatMap: one element -> a stream of elements.
+List<Item> items = orders.stream().flatMap(o -> o.items().stream()).toList();
+
+// mapMulti (16+): push 0..n results imperatively — cheaper than flatMap when you fan out little.
+List<String> tags = posts.stream()
+    .<String>mapMulti((post, sink) -> post.tags().forEach(sink))
+    .toList();
+```
+
+`Gatherers` (Java 24+, final) generalize intermediate ops — windowing, scanning, stateful
+folds — that `map`/`filter` cannot express:
+
+```java
+// Sliding windows of size 3.
+List<List<Integer>> windows = Stream.of(1,2,3,4,5)
+    .gather(Gatherers.windowSliding(3))
+    .toList();   // [[1,2,3],[2,3,4],[3,4,5]]
+```
+
+## Optional discipline
+
+```java
+// Good: chain, then resolve at the edge.
+String name = repo.find(id).map(User::name).orElseGet(() -> "anonymous");
+User u = repo.find(id).orElseThrow(() -> new NotFound(id));
+
+// Bad: isPresent + get is just a null check in disguise.
+Optional<User> o = repo.find(id);
+if (o.isPresent()) { return o.get().name(); } else { return "anonymous"; }
+```
+
+Rules: never `Optional` as a field or parameter; never `Optional.of(maybeNull)` (use
+`ofNullable`); for "no results" return an empty collection, not `Optional<List>`.
+
+## Parallel streams: rarely, and measure
+
+`stream().parallel()` only helps when the work is CPU-bound, the source splits cheaply
+(arrays, `ArrayList`, `IntStream.range`), the per-element cost is high, and the operations are
+stateless and associative. It *hurts* for I/O (it shares the common ForkJoinPool — use virtual
+threads instead, see `concurrency.md`), for small inputs, and for ordered/short-circuit ops.
+Default to sequential; reach for parallel only with a benchmark showing it wins.
+
+## Stream vs loop decision
+
+| Situation | Use |
+| --- | --- |
+| Transform/filter/aggregate a collection into a value | Stream |
+| Side effects (I/O, mutate external state) | Loop (a `forEach` mutating outside is a loop in disguise) |
+| Early `break` / `return` on a condition | Loop (or `findFirst`/`anyMatch` if it fits) |
+| Index-coupled logic (`a[i]` with `a[i-1]`) | Loop |
+| Deeply nested `flatMap`/`groupingBy` that no one can read | Loop with a clear accumulator |
+| One-pass min+max / two aggregates | Stream with `teeing` |

package/skills/java/scripts/verify.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a Java project (compile + test).
+#
+# Usage:
+#   cd <your-project-root>   # the directory containing pom.xml or build.gradle(.kts)
+#   ./verify.sh
+#
+# Detects Maven vs Gradle, prefers the project wrapper (./mvnw / ./gradlew), and runs the
+# build's compile + test + verify (`mvn -q verify` or `gradle check`).
+# Missing build tools are skipped with a yellow warning (not a failure); a real
+# compile/test failure exits non-zero. Read-only: never mutates your source.
+#
+# Portability: runs on stock macOS bash 3.2 (no mapfile, no associative arrays,
+# no unguarded array expansions under `set -u`).
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# Detect the build system. Neither present is a usage error, not a check failure.
+build="none"
+if [ -f pom.xml ]; then
+  build="maven"
+elif [ -f build.gradle ] || [ -f build.gradle.kts ]; then
+  build="gradle"
+fi
+
+if [ "$build" = "none" ]; then
+  printf '%serror:%s no pom.xml or build.gradle(.kts) in %s - cd into your project root first.\n' \
+    "$RED" "$RESET" "$(pwd)" >&2
+  exit 2
+fi
+
+# Optional JDK version hint: warn (do not fail) if the major version is below 21.
+info "java -version"
+if have java; then
+  # `java -version` writes to stderr; first line e.g. 'openjdk version "25.0.1" ...'
+  ver_line="$(java -version 2>&1 | head -n1 || true)"
+  major="$(printf '%s' "$ver_line" | sed -n 's/.*version "\([0-9]*\).*/\1/p')"
+  if [ -n "$major" ] && [ "$major" -lt 21 ] 2>/dev/null; then
+    warn "JDK major $major detected; this skill targets 21+ (Java 25 LTS). $ver_line"
+  else
+    ok "$ver_line"
+  fi
+else
+  warn "java not found on PATH (is a JDK installed?)"
+fi
+
+case "$build" in
+  maven)
+    info "Maven verify (compile + test + verify)"
+    mvn_cmd=""
+    if [ -x ./mvnw ]; then
+      mvn_cmd="./mvnw"
+    elif have mvn; then
+      mvn_cmd="mvn"
+    fi
+    if [ -z "$mvn_cmd" ]; then
+      warn "no ./mvnw and no mvn on PATH; cannot build (https://maven.apache.org)"
+    else
+      if "$mvn_cmd" -q -DskipTests=false verify; then
+        ok "maven verify passed ($mvn_cmd)"
+      else
+        fail "maven verify failed ($mvn_cmd)"
+      fi
+    fi
+    ;;
+  gradle)
+    info "Gradle check (compile + test)"
+    gradle_cmd=""
+    if [ -x ./gradlew ]; then
+      gradle_cmd="./gradlew"
+    elif have gradle; then
+      gradle_cmd="gradle"
+    fi
+    if [ -z "$gradle_cmd" ]; then
+      warn "no ./gradlew and no gradle on PATH; cannot build (https://gradle.org/install/)"
+    else
+      if "$gradle_cmd" check; then
+        ok "gradle check passed ($gradle_cmd)"
+      else
+        fail "gradle check failed ($gradle_cmd)"
+      fi
+    fi
+    ;;
+esac
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/knowledge-ops/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: knowledge-ops
+description: "Use when an already-running 02-DOCS/ wiki needs day-to-day gardening — too many half-finished articles, a 600-line page that covers three unrelated topics, a note with no obvious home, orphan pages nothing links to, stale answers and superseded articles piling up, or two articles that contradict each other. This is the judgment layer over harness's automation: decide what is worth capturing (default: nothing), where it goes, how to title/split/merge it, build the See Also web, and prune to _archive (never delete). Triggers: 'limpia mi wiki', 'organiza mis notas', 'esto dónde va en la wiki', 'ordena la base de conocimiento', 'split this bloated article', 'where should this note live', 'scores.json says these three are orphans — fix the cross-links', 'prune the stale and superseded stuff'. NOT building, bootstrapping or sweeping the wiki engine (that is harness)."
+tags: [knowledge-ops, wiki, 02-docs, knowledge-base, curation, cross-linking, pruning, knowledge-meta]
+recommends: [harness, decision-records, meeting-notes, sop-builder, research-ops, codebase-onboarding]
+origin: risco
+---
+
+# Knowledge Ops — Garden the 02-DOCS Wiki
+
+*The engine is already running. `harness` built the `02-DOCS/` wiki and owns its automation — the inbox sweep, deterministic lint, scoring, gap detection, the self-improve loop. Your job is the four judgments that automation deliberately leaves to a human: what is worth capturing, how it should be shaped, how it connects, and what should retire. You are the gardener, not the machinery.*
+
+## Before you touch anything
+
+1. **Confirm `02-DOCS/wiki/` exists.** If there is no wiki, stop and say: "Run `harness` to build the `02-DOCS/` wiki first, then come back to garden it." Why: this skill operates an existing engine; it never creates one. See `../harness/SKILL.md`.
+2. **Read `wiki/harness/user-profile.md`** to set your verbosity (the harness accompaniment dial, L0–L3). Why: a non-technical owner wants decisions narrated; an expert wants terse diffs.
+3. **Read `wiki/index.md` and `wiki/scores.json` before any edit.** Why: you garden from the map and the score signal, never blind. `scores.json` tells you what is bloated, orphaned, or stale.
+
+If `wiki/log.md` shows a Maintenance Pass ran in the last few minutes, let it finish — do not race the automation.
+
+## The four operations
+
+Every gardening request is one of four operations. Identify which before you act.
+
+| Operation | You are doing this when… | Primary signal | Writes to |
+|-----------|--------------------------|----------------|-----------|
+| **Capture** | A note/source needs a decision: keep, where, at what altitude | new content in `inbox/`/`raw/` or a loose user note | `raw/` and/or `wiki/<topic>/<article>.md` |
+| **Structure** | An article is bloated, mistitled, or duplicated | length, a non-singular Overview, near-duplicate titles | `wiki/<topic>/`, `_archive/` |
+| **Link** | Pages are unreachable or under-connected | `scores.json` orphan_penalty (=5), low inbound count | `## See Also` in articles, `index.md` |
+| **Prune** | Answers are stale, articles superseded, conflicts unresolved, gaps bloated | freshness, conflict annotations, old `[FILLED]` gaps | `_archive/`, `log.md`, `gaps.md` |
+
+Whichever you do, append a line to `wiki/log.md` (append-only). The exact entry shapes per operation live in `references/gardening-playbook.md`.
+
+## Capture — the bar is high
+
+**Default is NO.** Capture only what a future reader or agent will need *and* cannot cheaply re-derive. Why: the wiki is a compounding *model*, not a dump — the Karpathy chaos→knowledge paradigm has the LLM write and the human read, so every page must earn its keep.
+
+Walk the altitude ladder, lowest rung first; stop at the first that fits:
+
+1. **Discard** — ephemeral, re-derivable, or already covered. Most things stop here.
+2. **Leave in `raw/` only** — a source worth keeping but not worth a synthesized article yet. It stays immutable in `raw/<topic>/`, no `wiki/` page.
+3. **Merge into an existing article** — adds a section or fact to a page that already exists. Prefer this over a new page.
+4. **New article** — last resort: a genuinely new, single-thesis subject with no home.
+
+Worked examples for each rung are in `references/gardening-playbook.md`.
+
+**Topic choice.** Reuse an existing topic before inventing one, and keep `wiki/` exactly **one level of subdirs** deep (the protocol's rule). 
+
+- Bad: `wiki/payments/stripe/webhooks/retries.md` (four levels deep).
+- Good: `wiki/payments/stripe-webhook-retries.md` (existing `payments/` topic, one level).
+
+## Structure — title, Overview, split, merge
+
+**Split** an article when any of these is true:
+
+- It carries **≥2 unrelated theses** (e.g. "Stripe retries" *and* "our refund SLA").
+- Its `## Overview` cannot be written as **one honest paragraph**.
+- It has grown past readability and the score signal flags it.
+
+Why: one article = one thesis keeps scoring, linking, and retrieval meaningful. After a split, fix `> Sources:` and `> Raw:` on both halves and repair `## See Also` so they reference each other. Recipe in the playbook.
+
+**Merge** near-duplicates into the **higher-scored** page; fold the loser's unique content in, then archive the loser to `wiki/<topic>/_archive/<loser>__YYYY-MM-DD.md` and redirect every inbound link to the survivor. Why: never lose history, never keep two competing truths.
+
+**Title.** A title is the article's address — make it a specific noun phrase, not a label.
+
+- Bad: `Notes on stuff.md`, `Misc.md`, `Stripe.md`.
+- Good: `stripe-webhook-retry-policy.md`, `refund-sla-and-escalation.md`.
+
+## Link — build the web, kill orphans
+
+Every article earns **≥1 inbound link** or is a conscious leaf you can justify. Why: an orphan is dead knowledge — nothing reaches it, so it scores `orphan_penalty = 5` and never improves.
+
+- Use `scores.json` as your worklist: sort by lowest score / orphan penalty, fix those first.
+- `## See Also` is **bidirectional** — if A links B, B links A.
+- Same-topic link: `[Refund SLA](refund-sla-and-escalation.md)`. Cross-topic link: `[OAuth setup](../auth/oauth-setup.md)`. Why: the protocol's relative-link convention; `../` crosses one topic boundary, matching the one-level layout.
+- When you add a genuinely new top-level subject, make sure `wiki/index.md` references it so the map stays complete.
+
+## Prune — archive, retire, arbitrate, compact
+
+**Prune is archival, never `rm`.** A superseded article moves to `wiki/<topic>/_archive/<article>__YYYY-MM-DD.md`; you do not delete it. Why: the safety rails forbid destructive loss, and `_archive/` is gitignored from compaction so it stays out of the way without vanishing.
+
+- **Conflicts:** you **flag** contradictions and the **human arbitrates**. Once they choose a winner, you may apply the resolution and annotate the loser — but you never auto-pick. Why: silently choosing a side is data corruption.
+- **Stale answers:** mark a page or archived copy with a `> ⚠ Stale — superseded YYYY-MM-DD` note rather than rewriting history.
+- **Compaction is bounded:** only `[FILLED YYYY-MM-DD]` gaps **older than 90 days** may be compacted, and only via a single marker in the log. `gaps.md` and `log.md` are append-only — gaps get a `[FILLED]` stamp, never a deletion.
+- **Log every prune** to `wiki/log.md`. Exact entry shapes per operation: `references/gardening-playbook.md`.
+
+A full worked prune session (stale + superseded + conflict + gap compaction, all logged) is in the playbook.
+
+## Safety rails (inherited from the protocol)
+
+These are hard constraints, not suggestions. They come from `../harness/references/wiki-protocol.md` — do not override them.
+
+1. **Preserve before overwrite.** Never overwrite an article without first copying the old version to `wiki/<topic>/_archive/<article>__YYYY-MM-DD.md`.
+2. **Never auto-resolve a conflict.** Flag it; the human arbitrates.
+3. **`gaps.md` and `log.md` are append-only.** Gaps get `[FILLED YYYY-MM-DD]`; nothing is ever edited out.
+4. **Log every change** to `wiki/log.md`.
+5. **Never touch an article whose `Updated` is < 24h ago** without explicit user say-so. Why: it is likely still being worked.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is wrong | Do instead |
+|--------------|-----------------|------------|
+| Capturing everything "to be safe" | The wiki rots into a dump; the model stops being a model | Raise the bar; default to discard or `raw/`-only |
+| `rm`-ing a superseded article | Loses history the rails protect | Archive to `_archive/<article>__YYYY-MM-DD.md` |
+| Auto-picking a winner in a contradiction | Silent data corruption; you guessed | Flag it; let the human arbitrate |
+| Re-running `harness` to fix a broken link | Wrong tool — the Maintenance Pass already auto-fixes links | Repair `## See Also` by hand; let automation handle the rest |
+| Nesting `wiki/a/b/c.md` | Breaks the one-level topic rule | Flatten to `wiki/<topic>/<article>.md` |
+| Editing a past `log.md` / `gaps.md` entry | Breaks the append-only audit trail | Append a new line |
+| Splitting on length alone | Two halves of one thesis are worse than one page | Split on thesis count, not line count |
+| Creating a new topic for a one-off note | Topic sprawl; reuse beats create | File under the nearest existing topic |
+
+## Hand-offs
+
+Route elsewhere when the request is not gardening an existing wiki:
+
+| Request | Route to |
+|---------|----------|
+| Build/bootstrap the wiki, run an inbox sweep, scaffold `01-TOOLS`, generate root `CLAUDE.md` | `harness` (`../harness/SKILL.md`) — it owns the engine |
+| Turn a meeting transcript into a recap with action items + owners | `meeting-notes` (`../meeting-notes/SKILL.md`) |
+| Author a decision record (ADR) with alternatives, status, review cadence | `decision-records` (you may *file* one; that skill *authors* the discipline) |
+| Document a repeatable procedure step by step | `sop-builder` (`../sop-builder/SKILL.md`) |
+| First-pass walkthrough of an unfamiliar codebase | `codebase-onboarding` |
+| Run a literature / source-gathering research project | `research-ops` |
+
+The sharp line: changing the wiki's machinery or filling it in bulk is `harness`. Exercising judgment over what an already-running wiki should contain and how it should be shaped is `knowledge-ops`.

package/skills/knowledge-ops/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — knowledge-ops
+
+`cases.yaml` is a behavioral spec, not an automated test runner — there is no
+script to execute. Use it two ways. First, the `should_trigger` /
+`should_not_trigger` prompts sharpen the description boundary: read each prompt
+and confirm the router would (or would not) reach for `knowledge-ops`, with the
+near-misses correctly routing to `harness` (engine/sweep), `meeting-notes`
+(transcript recap), `decision-records` (ADR), `sop-builder` (procedure), and
+`codebase-onboarding` (first-pass walkthrough). Second, run the `capability` case
+by hand: stand up a scratch messy `02-DOCS/wiki/` matching the scenario (a
+two-thesis 600-line article, two near-duplicates, three orphans in
+`scores.json`, a stale archive, an unresolved conflict, a homeless note), invoke
+the skill against it, and grade the result against the `must_include` rubric —
+every item is a pass/fail. There is no `verify.sh`: this is a judgment skill, and
+the only deterministically checkable thing (broken links / index drift) is
+already owned and auto-fixed by harness's Maintenance Pass.

package/skills/knowledge-ops/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: knowledge-ops
+
+should_trigger:
+  - prompt: "Mi wiki de 02-DOCS está hecha un desastre, hay un montón de artículos a medias — decide qué merece quedarse."
+    why: "Spanish capture/prune judgment over an existing wiki — exactly the gardener's first job (say no, keep what earns it)."
+  - prompt: "This wiki article is 600 lines and covers three different things — split it into separate pages."
+    why: "Structure/split: ≥2 theses, Overview can't be one paragraph. Core knowledge-ops operation."
+  - prompt: "Where should this note about our Stripe webhook retry logic live in the wiki — does it need its own article?"
+    why: "Capture topic-choice + altitude decision (merge vs new article), not engine work."
+  - prompt: "scores.json says these three articles are orphans — fix the cross-links so they're reachable."
+    why: "NON-OBVIOUS: link operation driven by the orphan_penalty score signal; reader must know scores.json is the worklist."
+  - prompt: "Poda la wiki: archiva lo que esté obsoleto y retira lo que ya esté superado."
+    why: "Spanish prune request — archival-not-delete, the _archive/ rail. Pure gardening."
+  - prompt: "Two articles in the wiki contradict each other on the refund window — which is right, fix it."
+    why: "Prune/conflict arbitration — flag for human, never auto-resolve; clearly the judgment layer."
+
+should_not_trigger:
+  - prompt: "Build my 02-DOCS wiki and run an inbox sweep over the files I dropped in inbox/."
+    route_to: harness
+    why: "Bootstrapping the engine and running the sweep is the machinery, owned by harness — not gardening an existing wiki."
+  - prompt: "Turn this meeting transcript into a recap with action items and owners."
+    route_to: meeting-notes
+    why: "One-shot extraction from a transcript, not wiki curation."
+  - prompt: "Write a decision record for why we chose Postgres over Mongo, with alternatives and status."
+    route_to: decision-records
+    why: "ADR authoring discipline. knowledge-ops may file an ADR but does not author it."
+  - prompt: "Document our newsletter publishing process step by step so anyone can run it."
+    route_to: sop-builder
+    why: "Procedure authoring, not gardening a knowledge wiki."
+  - prompt: "Walk me through this unfamiliar codebase so I understand how it's structured."
+    route_to: codebase-onboarding
+    why: "First-pass codebase exploration, not maintaining a 02-DOCS wiki."
+
+capability:
+  - scenario: >
+      Point the skill at a deliberately messy sample 02-DOCS/wiki/ containing: a
+      600-line article that mixes two unrelated theses; two near-duplicate pages
+      on the same subject; three articles scores.json marks as orphans
+      (orphan_penalty 5); one stale archived answer; one unresolved conflict
+      annotation between two pages; and a loose note someone dropped with no home.
+      Ask it to garden the wiki.
+    must_include:
+      - "Reads wiki/index.md and wiki/scores.json before making any edit."
+      - "Applies the capture bar to the loose note (discard / raw-only / merge — with a stated reason); does NOT reflexively create a new article."
+      - "Splits the 600-line article into two single-thesis articles and fixes Sources, Raw, and See Also on both halves."
+      - "Merges the two duplicates into the higher-scored page, archives the loser to _archive/<a>__YYYY-MM-DD.md, and redirects inbound links."
+      - "Repairs See Also so the three orphans gain bidirectional inbound links."
+      - "Prunes the superseded page to _archive/ (never rm); flags the stale archive with a '> ⚠ Stale' note instead of rewriting it."
+      - "Flags the conflict for human arbitration and does NOT auto-pick a winner."
+      - "Logs every operation to wiki/log.md; treats gaps.md and log.md as append-only; touches no article updated <24h ago without consent."

package/skills/knowledge-ops/references/gardening-playbook.md

@@ -0,0 +1,116 @@
+# Gardening playbook — knowledge-ops
+
+Offloaded depth for the four operations. The SKILL body holds the rules; this
+holds the worked recipes, examples, and the exact `wiki/log.md` entry shapes.
+All wiki conventions here trace to `../../harness/references/wiki-protocol.md`
+and `../../harness/references/wiki-article-template.md`.
+
+## The Capture altitude ladder, worked
+
+Default is discard. Climb only when a rung's criterion is met.
+
+1. **Discard** — re-derivable, ephemeral, or already covered.
+   - Example: "The build passed on commit abc123." Re-derivable from CI; discard.
+   - Example: a duplicate of a fact already in `wiki/payments/stripe-webhook-retry-policy.md`. Discard.
+
+2. **Leave in `raw/` only** — a real source, no synthesis warranted yet.
+   - Example: a vendor PDF of Stripe's pricing. Keep it immutable in
+     `raw/payments/stripe-pricing-2026.pdf` (or its extracted `.md`); do not
+     compile a `wiki/` page until someone actually needs the synthesized answer.
+
+3. **Merge into an existing article** — adds a fact/section to a page that exists.
+   - Example: "Stripe now retries webhooks for 3 days, up from 2." Append a dated
+     line to the body of `wiki/payments/stripe-webhook-retry-policy.md` and update
+     its `> Sources:`. No new page.
+
+4. **New article** — genuinely new, single-thesis, homeless subject.
+   - Example: "Our refund SLA and escalation path." Distinct thesis, no existing
+     home → new `wiki/payments/refund-sla-and-escalation.md`, then link it both
+     ways with the Stripe page and reference it in `wiki/index.md`.
+
+Topic rule in practice: before `mkdir wiki/<new-topic>/`, scan `index.md` for an
+existing topic that fits. One level of subdirs only — `wiki/<topic>/<article>.md`.
+
+## Split recipe — carve one article into two
+
+When an article carries ≥2 unrelated theses (or its Overview cannot be one
+paragraph):
+
+1. Name the theses. Each becomes its own single-thesis article with a specific
+   title (`stripe-webhook-retry-policy.md`, `refund-sla-and-escalation.md`).
+2. Move each thesis's body sections into its article. Write a fresh one-paragraph
+   `## Overview` for each.
+3. Fix metadata on both: `> Sources:` keeps only the author/org + date relevant to
+   that half; `> Raw:` keeps only the `../../raw/<topic>/<file>.md` links that back
+   that half.
+4. Repair `## See Also`: the two halves link each other; re-point any inbound
+   links from other pages to whichever half they actually meant.
+5. Archive the original to `_archive/<original>__YYYY-MM-DD.md` (preserve before
+   overwrite), then update `index.md`.
+6. Log it (see entry shapes below).
+
+## Merge recipe — fold near-duplicates into one
+
+1. Read both pages' scores in `scores.json`. The **higher score wins**
+   (`score = inbound_links*2 + sources_count + cited_count*0.5 + freshness_weight
+   - conflict_count*3 - orphan_penalty`).
+2. Fold the loser's unique content and `> Sources:`/`> Raw:` references into the
+   winner. Do not duplicate facts already present.
+3. Archive the loser to `wiki/<topic>/_archive/<loser>__YYYY-MM-DD.md`.
+4. Redirect every inbound link (grep the wiki for `(loser.md)` and `/loser.md)`)
+   to the survivor so nothing breaks.
+5. Update `index.md`; log it.
+
+## Worked prune session
+
+Scenario: `scores.json` flags one stale page, one superseded page, one
+unresolved conflict annotation, and a pile of old `[FILLED]` gaps.
+
+1. **Stale page** (`freshness_weight` at 0.1, content still correct): add a
+   `> ⚠ Stale — verify against source as of YYYY-MM-DD` note at the top. Do not
+   rewrite. Log.
+2. **Superseded page** (a newer article replaces it): copy to
+   `_archive/<article>__YYYY-MM-DD.md`, leave a one-line pointer to the successor
+   in the survivor's `## See Also`, remove the dead page from `index.md`. Never
+   `rm`. Log.
+3. **Conflict** (`conflict_count > 0`, two pages disagree): you do **not** decide.
+   Surface both claims to the human, get the ruling, then annotate the losing
+   claim with `> Superseded by [winner](winner.md) per owner decision YYYY-MM-DD`
+   and clear the conflict annotation. Log.
+4. **Gap compaction:** only `[FILLED YYYY-MM-DD]` gaps **older than 90 days** may
+   be compacted, via a single marker line in `log.md` — `gaps.md` stays
+   append-only; you never delete a gap entry.
+
+## `wiki/log.md` entry shapes
+
+`log.md` is append-only. Match the protocol's `## [YYYY-MM-DD] <op> | …` format.
+One line (or short block) per manual operation:
+
+```markdown
+## [2026-06-02] capture | new | wiki/payments/refund-sla-and-escalation.md
+Created from raw/payments/refund-policy-2026.md. New single-thesis subject; no existing home. See Also <-> stripe-webhook-retry-policy.md.
+
+## [2026-06-02] capture | raw-only | raw/payments/stripe-pricing-2026.md
+Kept source, no wiki article — no synthesized answer needed yet.
+
+## [2026-06-02] structure | split | wiki/payments/stripe-and-refunds.md -> stripe-webhook-retry-policy.md + refund-sla-and-escalation.md
+Two unrelated theses. Original archived to _archive/stripe-and-refunds__2026-06-02.md. Sources/Raw/See Also fixed on both halves.
+
+## [2026-06-02] structure | merge | wiki/auth/oauth.md + wiki/auth/oauth-setup.md -> oauth-setup.md
+Merged into higher-scored oauth-setup.md (score 7.5 vs 2.0). Loser archived to _archive/oauth__2026-06-02.md. 3 inbound links redirected.
+
+## [2026-06-02] link | see-also | wiki/payments/refund-sla-and-escalation.md
+Added bidirectional See Also to stripe-webhook-retry-policy.md; cleared orphan_penalty.
+
+## [2026-06-02] prune | archive | wiki/payments/old-retry-notes.md -> _archive/old-retry-notes__2026-06-02.md
+Superseded by stripe-webhook-retry-policy.md. Removed from index.md.
+
+## [2026-06-02] prune | conflict-resolved | wiki/payments/stripe-webhook-retry-policy.md
+Conflict on retry window arbitrated by owner: 3 days wins. Loser claim annotated. conflict_count cleared.
+
+## [2026-06-02] prune | compact | gaps.md
+Compacted 4 [FILLED] gaps older than 90 days into this marker. No gap entries deleted.
+```
+
+Keep entries terse and factual: date, op, target paths, one-line why. The log is
+the audit trail the rails depend on — never edit a past entry, only append.