docs: add audited project entry point

1 files changed, 109 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..692df58
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# Somato-Dendritic Innovation Learning (SDIL)
+
+SDIL is a non-backpropagation learning project motivated by the neuron-specific
+somato-dendritic residuals reported by Harnett and colleagues. Its central
+algorithmic hypothesis is narrow: a mixed apical compartment should teach from
+the component that is unexpected given the same neuron's ordinary somatic
+state, rather than from raw apical activity.
+
+For hidden population `l`, the implemented rule is
+
+```text
+a_l       = A_l c + ordinary apical traffic
+a_hat_l   = P_l(h_l), fitted during neutral periods
+r_l       = a_l - a_hat_l
+Delta W_l = eta (r_l * local postsynaptic gain) h_(l-1)^T.
+```
+
+`A_l` is calibrated from antithetic node perturbations without reverse-mode
+differentiation or weight transport. That learned-feedback mechanism is
+inherited from Lansdell, Prakash, and Kording (2020); it is not claimed as
+novel. The candidate contribution is the neutral-period, per-cell innovation
+operation under mixed apical traffic, together with its theory, causal audit,
+and scaling behavior. See `NOVELTY.md` for the exact prior-art boundary.
+
+## Current audited evidence
+
+- On flattened CIFAR-10, SDIL loses only `0.214 +/- 0.349` accuracy points from
+  hidden depth 5 to 60, while DFA's early-layer teaching alignment falls from
+  `0.514` to `0.047`. This is depth preservation on a depth-flat task, not yet
+  evidence that added depth is useful.
+- With strong soma-predictable apical traffic, raw and norm-matched raw
+  learning fall to `10.38%` and `10.31%`, while innovation learning retains
+  `97.35%`. The paired innovation gain over norm-matched raw is
+  `87.038 +/- 0.607` points across five seeds.
+- Direct, unamortized node perturbation passes the controlled useful-depth
+  diagnosis, but costs `68.4x` ordinary forward-equivalent work. The learned
+  apical vectorizer, rather than the local eligibility rule, is the current
+  useful-depth bottleneck.
+- A low-query K1/every-4 calibration protocol retains `112.9%` of the K16 gain
+  over DFA with 16x fewer logical queries, 11x less calibration work, and 5.3x
+  less total forward-equivalent work in the frozen MLP protocol.
+
+The broad endogenous-traffic gate and the Harnett desired-velocity/online-control
+screen failed. Those results are retained and explicitly constrain the paper:
+SDIL does not currently explain the reported error-derivative signature, and
+the residual mechanism is supported for traffic predictable from the chosen
+somatic statistic rather than arbitrary top-down context. `ROADMAP.md` and
+`ORAL_B.md` contain the frozen gates and complete negative branches.
+
+## Publication-facing artifacts
+
+- `RESULTS.md`: audited positive and negative results;
+- `THEORY.md`: estimator variance, descent conditions, conditional innovation,
+  timescales, and hardware-independent cost;
+- `BASELINES.md`: matched and native-author baseline ledger;
+- `ROADMAP.md`: accept/oral evidence gates and their state;
+- `ORAL_A.md`: frozen standard CIFAR ResNet funnel;
+- `REVIEW_SCORECARD.md`: adversarial ICLR-style score trajectory;
+- `results/figs/`: deterministic PDF/PNG main figures, captions, and a source
+  hash manifest.
+
+The three current main figures show the local-method Pareto frontier, credit
+assignment versus depth, and the load-bearing innovation ablation. Every final
+cell has exactly seeds 0--4 and clean git provenance; the strict renderer
+refuses missing or protocol-mixed cells.
+
+## Verification
+
+The lab environment currently used for audited CPU checks is
+`/home/yurenh2/miniconda3/envs/ep_pascal`. Run:
+
+```bash
+experiments/finalize_claims.sh
+```
+
+This regenerates the figures and manifest, enforces the frozen Pareto/scaling
+gates, verifies baseline and protocol mechanics, checks the local-rule smoke
+tests, evaluates the theory identities, and rebuilds the audited tables.
+
+The convolutional infrastructure can be checked independently:
+
+```bash
+/home/yurenh2/miniconda3/envs/ep_pascal/bin/python3 experiments/cifar_image_smoke.py
+/home/yurenh2/miniconda3/envs/ep_pascal/bin/python3 experiments/conv_local_smoke.py
+```
+
+These checks cover deterministic CIFAR splitting/augmentation, the standard
+CIFAR `6n+2` ResNet topology, exact local convolution and BatchNorm
+eligibilities, the BatchNorm-coupled perturbation objective, predictor fitting,
+translation-shared feedback, and parameter/cost accounting.
+
+`experiments/finalize_accept.sh` additionally requires strict imports of the
+frozen BurstCCN and Dual Propagation author-code runs. It is intentionally red
+until both long native jobs are complete. Standard ResNet accuracy proceeds
+through A1--A4 in `ORAL_A.md`; untouched test seeds cannot run unless the prior
+validation gate passes.
+
+## Result discipline
+
+Every publication-facing run records the source revision, tracked-tree state,
+full arguments, split identity, seed, evaluation count, wall time, query/MAC
+accounting, and final finiteness. Development, validation, and untouched
+confirmation results are never pooled. Failed gates close their branch instead
+of triggering seed deletion or post-hoc threshold changes.
+
+The current strict reviewer estimate is `5/10` (borderline reject, confidence
+`4/5`): the mechanism and depth-preservation results are strong, but standard
+useful-scale confirmation is pending. The score changes only after an audited
+frozen stage, not after a pilot or a presentation improvement.