openspec: Phase 6 T6 — Rung-2 chemical gradients + adaptive chemosensory sensor (plan)

[chrisjz]

Draft — planning artifact for review, not implementation. This PR is the authored + self-reviewed OpenSpec change for Phase 6 Tranche 6 (env fidelity). No code yet; it's the proposal/design/specs/tasks the implementation PRs will work from.

Scope (full T6, one change)

Per the phase6-tracking tracker T6 rows, on top of the T5 continuous-2D substrate (Gate 2 GO, logbook 027):

• PRIMARY — adaptive/biphasic chemosensory sensor. Background-tracking leaky integrator + relative (Weber/fold-change) coding; log-concentration kept as a documented baseline. Exact readout deliberately settled by the step-input gate (co-primary candidates: derivative-channel fold-change (dC/dt)/(C+ε) vs instantaneous magnitude contrast).
• Static signal-specific Fick gradient geometry. Frozen analytic Gaussian kernel A·exp(−r²/4Dt) with per-signal D; exponential kernel stays default-off → grid byte-stable.
• Float source placement + true Euclidean fields on the continuous substrate (lifts the T5 §3.4 deferrals; drops the current int-rounded distance).
• Continuous-substrate fidelity renderer (non-gating seed; adapt the pygame PIXEL path).
• Analysis gate: step-input adaptation-transient validation (load-bearing) + env-fidelity-gain quantification + T6 logbook.
• Dynamic-diffusion PDE is an explicitly-gated stretch, not in scope.

Capabilities

• New: chemical-gradient-fidelity (static Fick geometry + adaptive sensor + step-input validation).
• Modified: continuous-2d-environment (float sources + Euclidean/continuous-field) and klinotaxis-sensing (adaptive transform on the chemosensory cores).

Self-review (nematode-review-spec)

No blocking findings; all file:line references verified against current code. Three should-fix items resolved before this PR: S1 STAM-reuse softened to a shared leaky-integrator utility (no public baseline API exists); S2 adaptive transform scoped explicitly to chemosensory channels (*_klinotaxis_core logic is duplicated across ~9 functions, no chokepoint); S3 fold-change regularised (dC/dt)/(C+ε) (singular at C≈0). Config integration points named; Fick kernel scoped to chemical (not predator) fields.

openspec validate add-rung2-chemical-gradients --strict: valid. Targeted pre-commit: green.

Deliberately deferred to implementation/empirics (not gaps)

• Exact adaptive readout form → settled by the D7 step-input gate (+ bounded D6 iteration sub-tranche).
• Per-signal D / t_assay calibration → anchored to the tuned continuous decay≈8.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added specifications for adaptive chemosensory sensing with background tracking and fold-change encoding.
  • Added chemical gradient fidelity requirements using Fick-shaped geometry with per-signal diffusion parameters.
  • Added continuous environment enhancements including float-based source placement and Euclidean distance calculations.
  • Added klinotaxis sensing updates for heading-aware lateral concentration sampling.
  • Added implementation plan for Phase 6 Rung-2 upgrades.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 293d5643-b166-47b1-ade4-360138ea396e

📥 Commits

Reviewing files that changed from the base of the PR and between 49b3301 and f4ce7eb.

📒 Files selected for processing (7)

• openspec/changes/add-rung2-chemical-gradients/.openspec.yaml
• openspec/changes/add-rung2-chemical-gradients/design.md
• openspec/changes/add-rung2-chemical-gradients/proposal.md
• openspec/changes/add-rung2-chemical-gradients/specs/chemical-gradient-fidelity/spec.md
• openspec/changes/add-rung2-chemical-gradients/specs/continuous-2d-environment/spec.md
• openspec/changes/add-rung2-chemical-gradients/specs/klinotaxis-sensing/spec.md
• openspec/changes/add-rung2-chemical-gradients/tasks.md

---

📝 Walkthrough

Walkthrough

This pull request introduces the complete design, specification, and implementation roadmap for the Phase 6 Rung-2 chemical gradients upgrade. The changes define an adaptive chemosensory sensing model, a static Fick-shaped gradient field geometry with float-based continuous-2D source placement, heading-aware klinotaxis sampling, continuous-substrate rendering capabilities, and an ordered task checklist with validation gates.

Changes

Rung-2 Chemical Gradients Upgrade

Layer / File(s)	Summary
Design Rationale & Scope openspec/changes/add-rung2-chemical-gradients/.openspec.yaml, openspec/changes/add-rung2-chemical-gradients/design.md, openspec/changes/add-rung2-chemical-gradients/proposal.md	Metadata and proposal establish the Rung-2 upgrade scope within the T6→T7 dependency chain, contrasting current Rung-0 (no adaptation, exponential-decay gradients, integer-snapped geometry) with intended Phase 6 fidelity improvements in sensing and field geometry. Goals include adaptive-threshold/biphasic chemosensory sensing, static Fick-shaped gradient geometry, float source placement with Euclidean distances, continuous-substrate rendering, and step-input transient validation; excluded are dynamic diffusion PDEs, brain-interface changes, discrete-grid changes, and thermosensory adaptation.
Field Geometry: Fick Kernel & Continuous-2D Sources openspec/changes/add-rung2-chemical-gradients/specs/chemical-gradient-fidelity/spec.md, openspec/changes/add-rung2-chemical-gradients/specs/continuous-2d-environment/spec.md	Specification of static frozen analytic Fick (Gaussian) kernel C(r) = A · exp(−r² / (4·D·t_assay)) with per-signal diffusion coefficients, replacing exponential-decay as an opt-in mode while preserving exponential as default. Continuous-2D sources placed at float coordinates with true Euclidean distance computation for food capture and nearest-food distance; discrete grid environment remains byte-stable with integer sources and Manhattan distances. Design decisions D1–D7 detail architectural placement of adaptation within SensingMode, field-kernel mode selection, float confinement, and renderer extensions for overlays and sub-cell placement.
Sensing: Heading-Aware Klinotaxis & Adaptive Chemosensory openspec/changes/add-rung2-chemical-gradients/specs/continuous-2d-environment/spec.md, openspec/changes/add-rung2-chemical-gradients/specs/klinotaxis-sensing/spec.md	Heading-aware klinotaxis sampling on continuous-2D fields: lateral concentration samples taken perpendicular to agent heading_rad at real-valued positions (no integer-cell snapping), left/right readings recorded by STAM with temporal derivative (dC/dt) computed from history. Adaptive chemosensory sensor uses leaky-integrator background tracking and config-selectable biphasic relative readout (magnitude contrast and/or derivative-channel fold-change with regularization) scoped to chemosensory channels; disabling preserves existing non-adaptive tanh pipeline. Klinotaxis spec mandates CoreFeatures with classical_dim=3 and oracle-to-*_klinotaxis module substitutions with conditional adaptive output to strength and/or binary based on channel-interaction mode.
Design Risks, Migration & Open Questions openspec/changes/add-rung2-chemical-gradients/design.md	Trade-offs identified: adaptive sensor tuning interdependencies, float/discrete environment boundary safety (mitigated via byte-stability tests), concentration scale shifts from kernel replacement (mitigated via retuning timing), adaptation's interaction with other environment upgrade deltas, and renderer scope limits. Migration strategy uses config-flag mode selection (exponential default vs Fick opt-in), opt-in adaptive sensor behavior, and float confinement to continuous environment for rollback to Rung-0 without code changes. Open questions address adaptive readout form selection (magnitude contrast vs fold-change and channel-interaction contract), per-signal diffusion parameter calibration, and renderer overlay depth/visualization scope.
Implementation Roadmap & Validation Gate openspec/changes/add-rung2-chemical-gradients/tasks.md	Ordered task checklist for T6 implementation: static Fick-mode geometry with kernel mapping, config selection, grid byte-stability regression, and unit tests; float source placement and Euclidean field sampling with sub-cell continuous updates and byte-stability checks; adaptive chemosensory sensor with leaky-integrator background, multiple readout modes (magnitude-contrast, derivative fold-change, singularity handling), klinotaxis core wiring with disabled-path equivalence, expanded SensingConfig surface, and focused test coverage; optional bounded parameter-sweep iteration gated on underfitting; continuous-substrate renderer with concentration/gradient/sensor-state overlays and screenshot export; step-input transient validation and env-fidelity quantification (static Fick vs baseline); documentation/tracker/logbook deliverables; and strict pre-merge validation requiring test suite clean state and pre-commit success.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• SyntheticBrains/nematode#203: Re-scoped Rung 2 to static Fick-shaped gradient geometry paired with adaptive chemosensory sensing (demoting dynamic diffusion PDE), which directly matches the main PR's newly added frozen analytic Fick kernel and adaptive chemosensory sensor deliverables.
• SyntheticBrains/nematode#216: Introduces the continuous-2D and klinotaxis/Euclidean baseline specifications, which the main PR further refines with float source placement and heading-aware perpendicular left/right sampling at real-valued positions.
• SyntheticBrains/nematode#127: Implements the SensingMode.KLINOTAXIS oracle→*_klinotaxis module substitution and wiring, which directly supports the main PR's specification of adaptive sensor integration into klinotaxis via apply_sensing_mode() and conditional output to strength/binary.

Poem

🐰 A chemist's dream in bunny verse:
Fick fields bloom where sources dance,
Sensors learn to feel the pull—
Floats and Gaussians advance!
Tasks laid out, step-input waits,
Rung two climbs toward T7's gates. 🧪✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: a Phase 6 T6 OpenSpec proposal for Rung-2 chemical gradients and adaptive chemosensory sensor implementation planning.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch openspec/add-rung2-chemical-gradients

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!