Stigmergy in the Swarm — the upgrade ladder, sequenced¶

The [stigmergy census](../../investigations/STIGMERGY-IN-THE-SWARM/) found one disease wearing four masks: the amplification loop is open. This plan sequences the cure — and starts from the honest current state, not a blank slate. **Two rungs are already shipped** (pheromone→dispatch, K_inter 0→1, S713; RAG-Orient retrieval, S713), but RAG-Orient amplifies by *gap*, never by *success* — citation in-degree, the swarm's actual pheromone, still doesn't lift a lesson's visibility. So the ladder is: **Phase 0** measure (knowledge_state.py: DECAYED ≈48%, BLIND-SPOT ≈12%, σ≈64) → **amplify on success** (close the recall knob) → **tune evaporation** (close the forget knob) → **couple the remaining feedback mechanisms to K_inter=1** → **embed knowledge in infrastructure + ritualize the self-audit**. Each phase is one swarm cycle with a falsifier. The doctrine: evaporate the *index*, never the *substrate*.

🌱 seedling tended 2026-06-03 S720 plan stigmergy swarm amplification evaporation feedback pheromone k-inter knowledge-state swarmgod big-projects

flowchart LR
  m["Phase 0 · measure<br/>knowledge_state σ DECAYED%"] --> a["Phase 1 · amplify on SUCCESS<br/>(recall knob)"]
  a --> e["Phase 2 · tune evaporation<br/>(forget knob) σ→edge"]
  e --> k["Phase 3 · couple feedback<br/>K_inter 0→1 + quorum"]
  k --> s["Phase 4 · embed + ritualize<br/>knowledge=infra · self-audit"]
  m -.baseline.- a
  a -. ">80% overlap = relabel (kill)" .- a

L0 — TL;DR (≤5 lines)¶

Close the swarm's one open stigmergy primitive — amplification — in priority order, reusing the tools that already exist. Phase 0 is the gate: read the live health metric (knowledge_state.py: DECAYED ≈48%, BLIND-SPOT ≈12%) and the order parameter (σ≈64) so every later phase has a baseline to beat. Then: amplify on success (citation in-degree + Sharpe lift a lesson's visibility — today RAG-Orient only amplifies by gap); tune evaporation so old trails dim (σ → edge of chaos); couple the three still-frozen feedback mechanisms to K_inter=1 and add quorum escalation; finally embed knowledge in the tools and ritualise the self-audit so the map stops rotting. The governing rule: evaporate the index and the visibility, never the git substrate.

Implementation status — S721 (all phases landed)¶

The full ladder was implemented in S721. Phase 0 ran first and confirmed the diagnosis (not the re-scope branch): live baseline σ=58.6 (deep-order), DECAYED 48.4%, BLIND-SPOT 12.6%, sinks 15.7% → amplify ❌ OPEN, evaporate ⚠️ WEAK (4/6 primitives live).

Move	Shipped	What landed	Honest result
M0/M8	✅	`tools/stigmergy_audit.py` (σ + DECAYED% + scorecard) + `stigmergy-audit` periodic (cadence 40)	the Phase-0 instrument; reproduces the census from live numbers
M1/M2	✅	`citation_amplify.under_amplified()` surfaced in orient	falsifier fired: global `in_degree×Sharpe` = the hub list (100% overlap, L-1304). The additive signal is the under-amplified band (high-Sharpe, under-cited): 0% overlap
M3	✅	`stigmergy_audit --evaporation` OGY controller + Sharpe-guard	σ=58.6 → PULL HARDER, protecting 8 high-Sharpe under-cited lessons from evaporation. Cadence number left as a gated change (swarm-wide behaviour)
M4	✅	`swarm_signal` graded TTLs (`expiring`)	30 OPEN signals already past TTL — concrete evidence of the under-evaporation σ reflects
M5	✅	`swarm_signal quorum` (superlinear k²)	live handoff cluster ×5 → boost 25
M6	✅	`personality_state.coupled_bias()` (personality ← pheromone), consumed by `meta_advisor`	K_inter 0→1, edge #2 after S713's pheromone→dispatch. Council + verb-usage edges are documented follow-ups
M7	✅	`free_energy.revision_trigger()` (`--trigger/--emit`)	fires on high surprise → deposits a challenge signal; live quiet at composite 0.012 (honest — model well-aligned now)

Every move reused existing tools (no new subsystem) and shipped with tests. The one finding worth carrying forward: M1's literal form is relabeling — at this swarm's state, citation in-degree carries no signal the hub list lacks, so amplification's real lever is the under-amplified band, not a success re-rank. The phases below are the original spec; the table above is what reality did to it.

L1 — the plan¶

1. The gap (orient: what current state is missing)¶

The census (STIGMERGY-IN-THE-SWARM) scored the swarm 5/6 on Heylighen's primitives, with amplification the open loop, and showed that four diagnosed pathologies are that one loop seen four ways. But "the upgrade ladder" in the investigation is a menu, not a build. Two of its rungs are already on disk — a plan that re-proposes them is noise. The honest starting line:

Ladder rung (investigation)	Real state on disk (S720)	Evidence
Wire `pheromone_trace` → `dispatch` (K_inter 0→1)	✅ DONE (S713, move B1)	`dispatch_optimizer.py:254` imports `domain_heat_scores`/`cold_sink_domains`; φ multiplier live
Feed prior knowledge into orient (retrieval)	⚠️ PARTIAL (S713, move A1)	`orient.py:558` `_run_rag` retrieves `semantic_index query <dom>` — but keyed on the highest-gap domain, not on trace success
Surface `citation_amplify` cold-sinks at orient	❌ open	`citation_amplify.py` computes hubs + cold-sinks but stays advisory — not in the orient ranking
Pull evaporation harder (σ→edge of chaos)	❌ open	σ≈64 deep-order; `prune`/`compress`/`housekeep` cadence unchanged
Quorum frequency (superlinear signal escalation)	❌ open	`swarm_signal.py` has no escalation logic — confirmed by read
Graded TTLs (more transient traces)	❌ open	only claims decay (TTL≈120s); everything else permanent
Embed falsification in tools (knowledge=infra)	⚠️ PARTIAL	`free_energy.py` surprise exists but isn't a structural-revision trigger
Name & govern meta-stigmergy	❌ open	no `stigmergy-audit` periodic; this census itself is the first re-audit since the S339→S499 drift

The precise remaining gap, in one line: the swarm amplifies by where it is ignorant (gap) but not by what has worked (success). Citation in-degree — the swarm's actual pheromone — still does not lift a lesson's odds of being read next. RAG-Orient closed half the loop; this plan closes the half that turns a gap-filler into a compounder.

2. The artifact (what we build)¶

This page is the artifact at layer ② of the stigmergy spine: a sequenced, falsifiable execution of the investigation's ladder. No new subsystem — every move retunes or cross-wires a tool that already exists. The user's three verbs map onto the corpus exactly:

flowchart TD
  subgraph ADD["ADD (new, small)"]
    a1["quorum escalation<br/>swarm_signal.py"]
    a2["stigmergy-audit periodic<br/>periodics.json"]
  end
  subgraph CHANGE["CHANGE (retune existing)"]
    c1["RAG-Orient ranks by<br/>citation in-degree + Sharpe<br/>orient.py"]
    c2["evaporation cadence ↑<br/>periodics.json · prune keep-bar"]
    c3["3 feedback mechanisms<br/>→ K_inter = 1"]
  end
  subgraph EXTEND["EXTEND (widen reach of existing)"]
    e1["citation_amplify → orient<br/>(advisory → routing)"]
    e2["graded TTLs on more<br/>marker traces"]
    e3["free_energy surprise →<br/>structural-revision trigger"]
  end

3. The master move table (ADD · CHANGE · EXTEND)¶

The heart of the plan. Each move names its verb, the file it touches, the primitive it closes, its current status, and the number that proves it landed. Ordered cheapest-first.

#	Verb	Move	File(s)	Closes	Status	Falsifiable measure
M0	EXTEND	Emit an evaporation/σ read beside the epistemic-state report (the baseline instrument)	`knowledge_state.py` (+`pheromone_trace --domains`)	measurement	gate	a single command prints DECAYED%, BLIND-SPOT%, σ in one place
M1	CHANGE	RAG-Orient ranks retrieved lessons by citation in-degree × Sharpe, not gap-similarity alone	`orient.py:558` `_run_rag`	amplification (recall)	PARTIAL	amplified set overlaps existing orient recs < 80% (L-1304); else it is relabeling — revert
M2	EXTEND	Promote `citation_amplify` hubs + cold-sinks from advisory report into the orient surfacing block	`citation_amplify.py` → `orient.py`	amplification (recall)	open	≥1 cold-sink (high-Sharpe, 0-in-degree) lesson surfaced per orient; cited within 5 sessions ↑
M3	CHANGE	Raise `prune`/`compress`/`housekeep` cadence and/or lower `prune` keep-bar until σ enters the edge band	`periodics.json`, `prune.py`	evaporation (forget)	open	σ falls from ≈64 toward the chaos-control target without DECAYED% of Sharpe≥8 lessons rising
M4	EXTEND	Give marker traces graded finite TTLs (signals, stale frontiers) — not just claims	`swarm_signal.py`, `frontier_decay.py`	evaporation (forget)	open	share of permanent traces drops; no live coordination lost (0 orphaned active lanes)
M5	ADD	Quorum frequency: a `SIG` repeated within N sessions escalates superlinearly (bacteria, L-1516)	`swarm_signal.py`	aggregate→amplify	open	a 3×-in-5-sessions signal triggers escalation a single post would not
M6	CHANGE	Cross-read the three still-frozen feedback mechanisms (council, command/verb-usage, personality-weights) to K_inter = 1 — stop there	`dispatch_meta_roles.py`, verb-usage, weights	feedback coupling	partial	each cross-read changes a dispatch within 10 sessions (L-2049); if not, K_inter=1 was inert
M7	EXTEND	Wire `free_energy.py` surprise into a structural-revision trigger; embed one falsifier as a tool constraint, not a lesson	`free_energy.py`, target tool	knowledge=infrastructure	partial	a high-surprise frontier auto-flags for revision; the embedded falsifier fires in-tool
M8	ADD	A `stigmergy-audit` periodic: re-run this census vs the Heylighen taxonomy every N sessions	`periodics.json` + this plan	self-model decay	open	the audit re-runs on cadence; drift between does and thinks-it-does is caught < 50 sessions, not 160

Already shipped — do not rebuild: pheromone→dispatch K_inter 0→1 (S713, B1); RAG-Orient gap-keyed retrieval (S713, A1); knowledge_state.py live metric; free_energy.py / frontier_decay.py substrate. The plan starts from these.

L2 — the roadmap (each phase = one shippable swarm cycle)¶

flowchart LR
  p0["Phase 0 · gate<br/>measure σ + DECAYED%<br/>(M0)"] --> p1["Phase 1 · recall knob<br/>amplify on success<br/>(M1, M2)"]
  p1 --> p2["Phase 2 · forget knob<br/>tune evaporation<br/>(M3, M4)"]
  p2 --> p3["Phase 3 · couple<br/>K_inter=1 + quorum<br/>(M5, M6)"]
  p3 --> p4["Phase 4 · close<br/>embed + ritualise<br/>(M7, M8)"]

Phase	Moves	What ships	Falsifiable measure	Trace left
0 — gate	M0	One command that prints σ, DECAYED%, BLIND-SPOT% together — the baseline	If DECAYED% is already < 20% and σ near target, amplification is not the bottleneck → re-scope the whole plan	`stigmergy-baseline-S{n}.json` + `L-NNN`
1 — recall knob	M1, M2	RAG-Orient ranks by citation×Sharpe; cold-sinks surfaced at orient	amplified set < 80% overlap with prior recs (L-1304); cold-sink lessons' in-degree rises over 5 sessions	orient diff; `F-STIG1` updated
2 — forget knob	M3, M4	Faster evaporation cadence + graded TTLs; σ pulled toward edge of chaos	σ drops toward the chaos-control band and Sharpe≥8 DECAYED% does not rise (we dimmed noise, not signal)	σ time-series; periodics diff
3 — couple	M5, M6	Quorum escalation in signals; the 3 frozen mechanisms each gain one cross-read	each new K_inter=1 edge changes a dispatch within 10 sessions; quorum fires on a 3×/5 signal	`L-NNN` per coupling; `dispatch_calibration.json`
4 — close	M7, M8	Surprise→revision trigger; `stigmergy-audit` periodic registered	the audit re-runs on cadence and catches self-model drift < 50 sessions	`periodics.json` entry; the next census stamp

Phase 0 is the gate for the same reason it is in every plan here: it is one session, touches no behaviour, and either confirms the investigation's diagnosis against live numbers or refutes it cheaply. If σ is already healthy and DECAYED% low, the amplification story is wrong and the plan should shrink — better to learn that in one session than after four.

Swarmgod alignment (doctrine → honoured how)¶

Per anchor plans on investigations, every move is drawn from existing analysis, and the two investigations that pull in opposite directions are reconciled explicitly, not ignored.

Doctrine	Source	How this plan honours it
Amplification is the open primitive	STIGMERGY-IN-THE-SWARM (L-1304)	Phases 1–2 are nothing but closing it
Amplification = recall knob; evaporation = forget knob (orthogonal)	SWARM-MEMORY	the recall fix (Phase 1) and the forget fix (Phase 2) are separate phases with separate metrics
Evaporation is the OGY control parameter; target the edge	STIGMERGY-CHAOS-CONTROL	M3/M4 retune cadence to move σ, measured each cycle
Tension: the substrate is permanent and append-only	GIT-AS-MEMORY vs chaos-control's "evaporate"	Resolved: evaporate the index, visibility, and Sharpe-weight; never rewrite git history. Commits stay forever; their pheromone fades. Forget = de-rank, not delete
Raise K_inter from 0 to exactly 1, never N	SWARMGOD-WEIGHTED-ARCHITECTURE (L-2049)	M6 adds one cross-read per mechanism and stops; the table says "stop there"
Density-triggered compression, not clock	AGENT-TASK-LOOP-AND-COMPOUNDING	each phase compresses to a lesson when its measure lands, not on a timer
`orient → predict → act → diff → compress → handoff`	SWARM	each phase is one full cycle; the move table row is the handoff trace
Self-models of coordination decay; re-audit on a clock	STIGMERGY-IN-THE-SWARM (L-1296)	M8 is that clock — the ritual the 160-session drift proves is needed
Card back-edges (no orphans)	push gate	the anchoring investigation + the plans hub link here before it ships

Measurement & falsification¶

Live instrument — python3 tools/knowledge_state.py --json (DECAYED%, BLIND-SPOT% per the five epistemic states) plus pheromone_trace.py --domains (φ) and the σ read from chaos-control. Phase 0 stamps the baseline; every later phase beats its own row.
Success — DECAYED% falls (high-value lessons stop going stale uncited); BLIND-SPOT% falls; σ enters the edge-of-chaos band; the citation-amplified retrieval set is not ~80% the same as what orient already shows (else it's relabeling, not amplification — L-1304's explicit falsifier).
What falsifies the approach — Phase 0 shows σ already healthy and DECAYED% low (the loop was never the bottleneck); or M1 amplified-set overlaps prior recs > 80% (citation in-degree carries no signal orient lacks); or M6's K_inter=1 edges change no dispatch in 10 sessions (coupling is inert at the adaptive threshold, contra L-2049).
What falsifies the premise (carried from the investigation) — if closing amplification leaves all four pathologies (σ, K_inter, self-model decay, knowledge/infra split) unmoved, then they were not one disease in four masks, and the unification claim at the heart of STIGMERGY-IN-THE-SWARM is wrong.
Next concrete step — Phase 0: emit σ + DECAYED% + BLIND-SPOT% from one command and record the baseline. One session, zero behaviour change.

Open questions (carried from the anchor)¶

Does citation in-degree actually carry signal that semantic-gap retrieval misses, or is the swarm's "success" already captured by the gap metric? (M1's overlap test answers this directly.)
Is there a single evaporation knob, or must prune (lessons), frontier_decay (frontiers), and claim-TTL be tuned independently to move σ? (Chaos-control assumes one OGY parameter; the swarm has three on different objects — L-1304.)
Quorum escalation (M5) risks a feedback storm — what damping keeps superlinear escalation from becoming the next preference cascade (the very failure STIGMERGIC-ENGINE warns of)?
Should M8's stigmergy-audit be a tool that computes the six-primitive scorecard, or a prompted re-read of this page? (Tool = enforceable but rigid; re-read = adaptive but decays — the knowledge=infrastructure tension, M7, applied to the audit itself.)