Merge pull request #371 from PyAutoLabs/feature/complete-archive-highlights

docs(complete): curate the Highlights band of complete/index.md

Author: Jammy2211

complete/AGENTS.md

@@ -23,14 +23,23 @@ X" reads one record, not a 6000-line file.
 
 ## How to look something up (token-light — RAG is dead)
 
-1. Read `complete/index.md` (the curated navigation — grouped `[[slug]]` links
-   with one-line hooks, grouped by date, `unknown` last). It is **generated**
-   from the records by `scripts/lifecycle.py index` — regenerate with
+1. Read `complete/index.md` (the navigation — ordinary markdown links,
+   `[<slug>](<YYYY>/<MM>/<slug>.md)`, each with a one-line hook, grouped by
+   date, `unknown` last; not `[[wiki-links]]`). It is **generated** from the
+   records by `scripts/lifecycle.py index` — regenerate with
    `lifecycle.py index --apply`; a hand-curated **Highlights** band between the
    `CURATED` markers survives regeneration.
 2. Follow one or two links to the records you need.
 3. Only then grep a specific `complete/<YYYY>/<MM>/` bucket.
 
+### What earns a Highlights line
+
+Three things and nothing else: a **trap that cost a session**, a **decision that
+will be re-asked**, an **architecture invariant** worth not re-deriving. ~25-30
+entries under theme headings is the whole budget; a record that merely shipped
+something stays in the generated list. The hook states the **lesson, not the
+task** — a noun phrase, no dates, no PR numbers, two wrapped lines at most.
+
 ## Provenance
 
 - Records are **written by the ship skills** via

complete/index.md

@@ -11,7 +11,110 @@ markers; everything below GENERATED is rebuilt.
 <!-- CURATED:START -->
 ## Highlights
 
-_(curate hard-won records here — survives regeneration.)_
+### JAX, numerics & performance
+
+- [xla-cpu-eigen-pool-deadlock](2026/08/xla-cpu-eigen-pool-deadlock.md) — a JAX
+  CPU hang that is XLA's own Eigen pool re-entered by ducc0's FFT; one call is
+  one lottery ticket, so reproduce in a loop and read the HLO.
+- [jax-vmap-materialisation-hang](2026/08/jax-vmap-materialisation-hang.md) —
+  "and then silence" is the silence of stderr alone: a SIGKILLed child loses its
+  whole block-buffered stdout, so set `PYTHONUNBUFFERED` before quarantining.
+- [numba-hst-curvature-matrix-speedup](2026/08/numba-hst-curvature-matrix-speedup.md)
+  — instrument before optimising, and never route a sliding PSF window through
+  an FFT convolver unreversed; a symmetric test kernel hides the error.
+- [multistart-nan-step-diagnostics](2026/08/multistart-nan-step-diagnostics.md)
+  — an eager `jnp` reduction outside the jit costs more than the host transfer
+  it avoids; fuse per-step diagnostics into the jitted call.
+- [regularization-jax-gradient-gaps](2026/08/regularization-jax-gradient-gaps.md)
+  — an inherited term that silently evaluates to zero is the worst failure mode,
+  wrong but finite; a factorization fallback must be all-or-nothing.
+- [cluster-f-jax-baseline-oom](2026/05/cluster-f-jax-baseline-oom.md) — verify a
+  triage cluster against current main before mass-fixing: transient library
+  state ages failures out faster than the report cycle.
+
+### Release, build & CI drift
+
+- [sub-312-install-tombstone](2026/08/sub-312-install-tombstone.md) — rehearse a
+  release on TestPyPI: build isolation, the tenant firewall and a lagging JSON
+  index all bite before upload, and resolution is read off the simple index.
+- [intra-family-dep-floors](2026/08/intra-family-dep-floors.md) — an ad-hoc venv
+  inherits the dev `PYTHONPATH` and imports the source tree, so it can falsely
+  confirm an install fix; `pip --dry-run` cannot be read as a resolution.
+- [release-validation-tri-state](2026/08/release-validation-tri-state.md) — an
+  absent rehearsal is not a failed one; readiness prints a cached verdict over
+  an embedded report copy, so re-ingesting changes nothing until re-aggregation.
+- [smoke-surface-retime-sweep](2026/08/smoke-surface-retime-sweep.md) — a parked
+  script cannot report its own rot: SLOW markers hide real errors, and a
+  dispatch-only harness is green by absence until someone dispatches it.
+- [script-size-guard-git-based](2026/08/script-size-guard-git-based.md) — a
+  committed size snapshot rots; diff each changed script against its own blob at
+  the merge-base instead, leaving no baseline to update and nothing to protect.
+- [pre-build-stages-untracked-wip](2026/08/pre-build-stages-untracked-wip.md) —
+  `git add <dir>/` stages untracked files, so release automation that
+  formats-then-stages publishes stray work; validate before the first push.
+
+### Samplers & inference
+
+- [nautilus-test-mode-degenerate-corner](2026/08/nautilus-test-mode-degenerate-corner.md)
+  — a degenerate posterior is degenerate in its weights, not its row count;
+  guard corner plots on the Kish effective sample size.
+- [ep-hierarchical-scale-collapse-guard](2026/08/ep-hierarchical-scale-collapse-guard.md)
+  — a guard's unit test can be green while the guard cannot fire; feed it the
+  recorder's real output shape, and check the new tests fail on the base.
+- [stored-sample-reconstruction-guard](2026/08/stored-sample-reconstruction-guard.md)
+  — a stored sample that current model validation rejects must recover to the
+  next valid one or raise a typed exception, never a raw internal one.
+- [heart-red-guarded-sample-escape](2026/08/heart-red-guarded-sample-escape.md) —
+  a correct rejection guard is not enough while other paths reconstruct or
+  re-serve the rejected sample; find every consumer before declaring it fixed.
+- [clipper-validation-campaign](2026/08/clipper-validation-campaign.md) — budget
+  decides the answer: grade the alive-versus-step curve rather than a survival
+  percentage, and read an all-zero counter arm as broken, not as a null result.
+- [delaunay-nan-probe-fix](2026/08/delaunay-nan-probe-fix.md) — a probe that
+  builds pathological input through the public constructor inherits the public
+  validation; poison below the boundary the guard defends.
+
+### Lensing science
+
+- [point-solver-magnification-plane-redshift](2026/08/point-solver-magnification-plane-redshift.md)
+  — in a multi-plane tracer the solver must evaluate at the source's own plane;
+  two halves of one likelihood disagreeing means a half-wired argument.
+- [group-subhalo-lens-dict](2026/07/group-subhalo-lens-dict.md) — a multi-galaxy
+  script's deflector count comes from its own dataset's `main_lens_centres.json`,
+  and extra galaxies are a separate collection from main lens galaxies.
+- [nfw-truncated-potential-accuracy](2026/08/nfw-truncated-potential-accuracy.md)
+  — where a profile has a published analytic potential, port it rather than
+  re-tune the MGE approximation; `grad(psi) = alpha` is the check that finds it.
+- [over-sample-trailing-one-to-two](2026/07/over-sample-trailing-one-to-two.md) —
+  a lensed-source arc is never evaluated at sub-size 1: MGE Gaussians alias at
+  1x1 and degrade gradient searches, so adaptive schemes floor at 2x2.
+- [adapt-image-cache-mask-validation](2026/07/adapt-image-cache-mask-validation.md)
+  — a stale adapt-image cache imitates an indexing bug; a completed pipeline
+  never re-evaluates the likelihood, and `Paths.restore` re-extracts the zip.
+- [adapt-linear-regularization](2026/08/adapt-linear-regularization.md) — correct
+  a shipped regularization convention by adding sibling classes, never by
+  mutating the existing ones: identifiers and aggregator reloads must stay valid.
+
+### Mind / Brain infrastructure
+
+- [agent-failure-modes](2026/07/agent-failure-modes.md) — the measured taxonomy
+  of how agents fail here: refusals work where informs do not, and a guard's
+  first live hour is where its false positives surface.
+- [api-gate-clause-scope](2026/07/api-gate-clause-scope.md) — a `PreToolUse` gate
+  must scope its interpreter state per shell clause; a latched flag scans a later
+  clause's file arguments and blocks on symbols nothing was going to call.
+- [spawn-drift-self-heal](2026/08/spawn-drift-self-heal.md) — hand-written test
+  fixtures let the real workflow drift past the guard; point a generator's tests
+  at the actual files they exist to protect.
+- [registry-integrity-check](2026/08/registry-integrity-check.md) — a registry
+  nobody retires entries from costs a whole task-selection session; check that
+  every entry's prompt path resolves and contradicts no other lifecycle state.
+- [worktree-claim-parser-forms](2026/08/worktree-claim-parser-forms.md) — cloud
+  clones are shallow, so a history sweep silently returns nothing; check
+  `--is-shallow-repository` before concluding anything from git history.
+- [lifecycle-state-split](2026/07/lifecycle-state-split.md) — the Mind ran two
+  parallel lifecycles, prompt files and the ledger, until draft/active/complete
+  made the file's location the state; one source of truth per fact.
 <!-- CURATED:END -->
 
 <!-- GENERATED:START — edit records, not this block; regenerate with `lifecycle.py index --apply` -->

tests/test_lifecycle_index.py

@@ -0,0 +1,79 @@
+"""Contract test for the curated Highlights band in `complete/index.md`.
+
+`lifecycle.py index --check` is a byte-for-byte round trip over the WHOLE file,
+so a hand-curated band that the renderer re-emits differently turns the CI drift
+check red on a file nobody touched. The band is also the only hand-written thing
+in a generated file — if regeneration ever ate it, the curation is lost silently
+and the index still looks healthy.
+
+Fictional fixtures only: `tests/**` is KEEP-copied verbatim into the public
+template (see `test_spawn_privacy.py`), so nothing here names a real repository,
+task or record.
+"""
+
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+
+import lifecycle  # noqa: E402
+
+
+BAND = """## Highlights
+
+### Flywheel calibration
+
+- [sprocket-calibration](2026/08/sprocket-calibration.md) — a torque baseline
+  measured on a warm rig cannot grade a cold one; re-measure both columns
+  back-to-back.
+- [widget-alignment](2026/08/widget-alignment.md) — the alignment jig reads its
+  own last result when the output directory is not cleared."""
+
+
+def _mind(root: Path, *, band: str) -> Path:
+    """A tiny fictional Mind: two dated records + an index carrying `band`."""
+    complete = root / "complete"
+    bucket = complete / "2026" / "08"
+    bucket.mkdir(parents=True)
+    (bucket / "sprocket-calibration.md").write_text(
+        "## sprocket-calibration\n- summary: re-measured the torque baseline\n"
+    )
+    (bucket / "widget-alignment.md").write_text(
+        "## widget-alignment\n- summary: cleared the jig output directory\n"
+    )
+    (complete / "index.md").write_text(
+        f"{lifecycle.CURATED_START}\n{band}\n{lifecycle.CURATED_END}\n"
+    )
+    return complete
+
+
+def _point_lifecycle_at(monkeypatch, root: Path, complete: Path) -> None:
+    monkeypatch.setattr(lifecycle, "ROOT", root)
+    monkeypatch.setattr(lifecycle, "COMPLETE_DIR", complete)
+    monkeypatch.setattr(lifecycle, "ARCHIVE_DIR", complete / "archive")
+    monkeypatch.setattr(lifecycle, "INDEX_MD", complete / "index.md")
+
+
+def test_a_curated_band_survives_index_regeneration_byte_for_byte(
+    tmp_path, monkeypatch
+):
+    """Headings and markdown-link bullets inside the CURATED markers must come
+    back out of `index --apply` unchanged, and `index --check` must then be
+    clean — the band and the renderer have to agree on every byte."""
+    complete = _mind(tmp_path, band=BAND)
+    _point_lifecycle_at(monkeypatch, tmp_path, complete)
+
+    assert lifecycle.cmd_index(SimpleNamespace(check=False, apply=True)) == 0
+
+    rendered = (complete / "index.md").read_text()
+    band_back = rendered.split(lifecycle.CURATED_START, 1)[1].split(
+        lifecycle.CURATED_END, 1
+    )[0]
+    assert band_back == f"\n{BAND}\n"
+    # the generated half is still built from the records themselves
+    assert "- [sprocket-calibration](2026/08/sprocket-calibration.md)" in (
+        rendered.split(lifecycle.GEN_START, 1)[1]
+    )
+
+    assert lifecycle.cmd_index(SimpleNamespace(check=True, apply=False)) == 0