Tracking: July 2026 maintenance audit (83 verified findings)

[mmcky]

Tracking issue for the July 2026 full-repository maintenance audit. Milestone: Maintenance audit 2026-07.

Complete (2026-09-24). All seven sub-issues are closed; v0.12.0 delivered the last five, and v0 moved to it after the staged canary run (decision 4). Two follow-ups in other repos are listed in the closing comment and in docs/dev/PLAN.md (#187).

A multi-agent sweep of every tracked file across 14 dimensions, then two adversarial verification passes: 135 raw findings, 63 rejected, 72 confirmed, 11 added by four completeness sweeps, 83 actioned. Nothing found is architectural.

The work, ordered by dependency

• ci: repair the container publish and validation pipeline #103 — repair the container publish and validation pipeline (infrastructure high-priority) — done in v0.9.0 (ci: repair the container publish and validation pipeline #111): uppercase ghcr.io/QuantEcon/… from github.repository_owner made buildx registry cache refs fail non-fatally, leaving builds cold and green (CHANGELOG.md:233-237); an unserialised workflow let an older commit win :latest (:238-240); a concurrency group shared across runs cancelled most of the lecture-validation matrix (:241-247); both unattended workflows now open a deduplicated failure issue via scripts/create-ci-failure-issue.sh (:194-200), the alerting nine red weeks in Feb–Apr 2026 lacked.
• fix(restore-jupyter-cache): save-mode outputs and fail-on-miss are broken #104 — restore-jupyter-cache save-mode outputs (bug high-priority) — done in v0.9.0 (fix(restore-jupyter-cache): repair save-mode outputs and fail-on-miss #112); unblocks the Optimize preview builds: phased plan for the fastest PR previews (tracking) #92 save-cache rollout. Top-level actions/cache@v6 declares only cache-hit, so save mode's outputs came back empty — cache-hit false on a perfect restore, fail-on-miss failing unconditionally; restore now always uses actions/cache/restore@v6, with a lookup-only: true step registering the job-end save hook (CHANGELOG.md:213-221). In CI since v0.10.0: both cache types × both modes, fail-on-miss both ways (CHANGELOG.md:141-151).
• fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105 — preview deploy errors, CLI pinning, fork guidance (bug security high-priority) — done in v0.12.0: the README fork-PR warning in docs(preview-*): warn against pull_request_target instead of recommending it (#105) #170; in fix(preview-*): surface deploy errors, pin the CLIs by lockfile, keep the Netlify token off argv (#105) #174, with the three sketch corrections below applied, wrangler's output and netlify's stdout stream through tee with set +e around the call and the exit code read from PIPESTATUS, and a failure ends in an ::error::; both CLIs are pinned by a lockfile per action, installed with npm ci (decision 2) and called by path; and the Netlify token, site ID, PR number, head SHA and build-dir moved into env:. Closes PLAN item 8.
• docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106 — Anaconda 2026.06 baseline and measured sizes (documentation high-priority) — done in v0.12.0: fix(ci): make the image-size job report both sizes, and fail when it cannot #172 made the size job report both figures and fail when it cannot; docs: 2026.06 baseline, measured image sizes, and READMEs reconciled with the shipped code (#106, #109, #99) #175 moved the stale sites to the 2026.06 baseline and every size site to the measured, labelled pair (full 3.33 GB compressed / 8.60 GB on disk, lean 2.93 GB / 7.32 GB; decision 3), corrected "Minimal TexLive", refreshed the PLAN disposition rows (adding Release gating: require a green canary before v0 moves (adds a v0-next staging tag) #135's) and added CONTRIBUTING's PLAN.md row.
• fix(actions): batch of small correctness fixes across the seven actions #107 — batch of small correctness fixes (bug) — done in v0.12.0 (fix(actions): #107 correctness batch and #109 code items #173), with the three sketch corrections below applied (conda env update -p on the active prefix, a LaTeX parse that splits on whitespace, an exact-token builder parse) and a LaTeX file with no packages made an ::error:: rather than the proposed warn-and-skip; new harness jobs (env-container-update, bjc-builders-parse); asset-url deleted. Closes PLAN item 7; its cosmetic --path-output residual moves to PLAN item 15 (docs(plan): refresh after v0.12.0 closed the July 2026 audit; finish PLAN item 15 #187).
• test: unify container smoke tests and make the fixture exercise the Dockerfiles #108 — unify container smoke tests, fix the fixture (infrastructure) — done in v0.12.0 (test(containers): exercise the real theme and FreeFont path in the smoke fixture (#108) #171): the fixture builds with quantecon_book_theme and Sphinx's default xelatex fontpkg, test-container.sh is deleted and the image README points at smoke-test.sh, and run-local-tests.sh passes -W --keep-going. Test Container was dispatched on the branch and was green on both images.
• docs: reconcile action READMEs and templates with the shipped code #109 — reconcile READMEs and templates with shipped code (documentation) — done in v0.12.0: the docs in docs: 2026.06 baseline, measured image sizes, and READMEs reconciled with the shipped code (#106, #109, #99) #175 (closing docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99 too), plus the build-jupyter-cache README's failure-only artifact wording in fix(actions): #107 correctness batch and #109 code items #173; the code items in fix(actions): #107 correctness batch and #109 code items #173 (latex-requirements-file, the cname warning, the template pin-drift check in the gate job); the template checkouts in templates: move actions/checkout onto its Node 24 major #168.

Decisions (2026-09-23)

1. PLAN item 10's docs trim comes later. The four docs: reconcile action READMEs and templates with the shipped code #109 items in docs/QUICK-REFERENCE.md (the alias: recipe, the cache-key row, the fabricated LaTeX log line, docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99's 404 snippet) are fixed in place now. The trim is its own editorial PR. This lets docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106 and docs: reconcile action READMEs and templates with the shipped code #109 land as one docs PR.

2. fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105 pins the CLIs with a package.json and package-lock.json in each preview action directory, installed with npm ci, plus an npm ecosystem entry in .github/dependabot.yml for both directories. Installing them into the images was rejected on three grounds. Dependabot cannot see a version string in action.yml. An image install does not reach non-container runners, which both READMEs support. And no ecosystem tracks tools installed in a Dockerfile: feat(containers): Node 24 LTS from nodejs.org, out of conda #166 bumps Node by hand for that reason.

3. docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106 publishes both image sizes, each labelled: compressed, from the registry manifest, and on-disk, from a pull on a hosted runner. It does this after the size job is fixed.

4. Releases carrying fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105 or fix(actions): batch of small correctness fixes across the seven actions #107 are staged. Merging to main reaches no action consumer. Moving v0 reaches every @v0 consumer on its next run, with nothing tested first: the Release gating: require a green canary before v0 moves (adds a v0-next staging tag) #135 gate is unbuilt, and the canary pins @v0, so it sees a release only after it ships. For these releases:

   1. Cut the exact vX.Y.Z tag and create the Release, but hold the v0 move.
   2. Open a same-repo canary PR with ci.yml pointed at @vX.Y.Z. That runs build-lectures and a real preview-netlify deploy with pull_request semantics.
   3. Dispatch the canary's cache.yml from a branch pointed at build-jupyter-cache@vX.Y.Z. That runs build-jupyter-cache's own steps, including fix(actions): batch of small correctness fixes across the seven actions #107's builder parse.
   4. Move v0 only when both are green.

   Known limits:

   • build-jupyter-cache calls setup-environment@v0 and build-lectures@v0 (build-jupyter-cache/action.yml:149, :164, :174, :184), so fix(actions): batch of small correctness fixes across the seven actions #107's setup-environment fixes reach that chain untested until v0 moves.
   • preview-cloudflare has no consumer and no known project to deploy to. It now has a project: the v0.12.0 staging ran a real deploy to the qe-preview-canary Pages project (ci: staged check of quantecon/actions v0.12.0 (not for merging) test-actions-lecture-intro#66). It still has no standing consumer; a permanent preview-cloudflare@v0 step in the canary is a follow-up.
   • The canary never sets create-release-assets, so publish-gh-pages' release-asset path stays unexercised.
   • The five exactly-pinned repos' Dependabot will offer the new tag as a bump PR as soon as the tag exists; merging stays human.
   • Rollback is git tag -f v0 <previous> plus a force push. It is undocumented (Release gating: require a green canary before v0 moves (adds a v0-next staging tag) #135).

   Container images do not stage: any merge touching containers/** rebuilds and pushes :latest immediately.

Found in the 2026-09-23 revalidation

Checked against main @ 44c0273. #165, #166 and #168 merged since the 2026-08-14 revalidation.

• The image-size job has never reported a size. test-container.yml's size job, added in test(containers): make the container fixture able to fail (#108) #125, logs jq: error … Cannot iterate over null for both images on every run since 2026-08-05 (e.g. runs 30981651170 and 35554068142), and stays green. The step has no shell:, so it runs as bash -e {0} without pipefail, and the pipeline takes tee's status. The v0.11.0 CHANGELOG line on compressed manifest-byte reporting describes a measurement that never produced a figure. Fixed in fix(ci): make the image-size job report both sizes, and fail when it cannot #172, a prerequisite for docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106's size sweep.
• Fix sketches that misfire as written. These are folded into the PRs.
  • fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105:
    • wrangler … 2>&1 | tee …; EXIT=${PIPESTATUS[0]} still aborts under the composite shell's -eo pipefail before EXIT= runs. It needs set +e around the pipeline, or || EXIT=….
    • The Netlify capture must tee stdout only. Merging stderr into the --json payload breaks json.load on a successful deploy, and the now non-fatal parse would then fail a green deploy.
    • npm ci does not put the CLI on PATH, so the deploy steps must call it by path.
  • fix(actions): batch of small correctness fixes across the seven actions #107:
    • The container-mode conda env update should target the environment that is actually active: -p from sys.prefix, not -n "$ENV_NAME". -n would silently create a fresh envs/quantecon on a host whose stack is in base, such as the GPU AMI as docs/GPU-AMI-SETUP.md:115-178 describes it.
    • The LaTeX parse must keep splitting on whitespace. A per-line mapfile makes pkg one argument, which apt rejects, so the issue's own inline-comment example would stay red.
    • The builder parse must split on commas and whitespace, trim, and skip empty tokens, or html, pdflatex and html, regress. With that, the only values that go from green to red are the ones the fix targets (html,pdf, nojupyter). Every known consumer passes exactly html.
  • docs: reconcile action READMEs and templates with the shipped code #109:
    • A new latex-requirements-file input on build-jupyter-cache must default to latex-requirements.txt. The runner passes an explicit '' through rather than applying the callee's default, so an empty default would break every standard-mode pdflatex user.
    • The template pin-drift check belongs in the harness gate job, because template-only PRs match the IGNORED regex and skip every other job.
• Stale: PLAN.md:25-29's consumers table. All six exact call sites are now on @v0.11.1, bumped by Dependabot between 2026-08-12 and 2026-08-24.
• Context for staging: the post-merge lecture-matrix validation has been red since fix(containers, build-lectures): trust the work tree so pages keep their "Last changed" header #165/feat(containers): Node 24 LTS from nodejs.org, out of conda #166 (run 35316939330; alerting in 🔴 CI failure: Test Container Builds #159), so a red result there is currently ambiguous. Diagnosed on 🔴 CI failure: Test Container Builds #159 (2026-09-24): lecture-python.myst's bayes_nonconj fails under numpyro 0.22.0 and its build sits at the 120-minute timeout, neither caused by this repo or its images.

Tracker structure

QEP-2 routes umbrella issues to native sub-issues with no Type label on the parent.

• Add fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105–docs: reconcile action READMEs and templates with the shipped code #109 as native sub-issues, plus closed ci: repair the container publish and validation pipeline #103 and fix(restore-jupyter-cache): save-mode outputs and fail-on-miss are broken #104 for the audit trail. — done; all seven are linked.
• Then remove the maintenance Type label — done, in that order: QEP-2's exemption from "unlabelled means needs triage" keys on the sub-issue relationship, so dropping it first would have left the tracker looking untriaged rather than structural.

Labelling and related issues

Labels follow QEP-2, now Accepted: infrastructure not maintenance for CI/build/deploy work, grouping by milestone rather than an audit label. security on #105 is a cross-cutting modifier, not a second Type. testing is retired to infrastructure/maintenance; #108 and #100 both moved, so nothing here uses it.

Nothing supersedes an existing issue. #100 (action-logic test coverage) stays open: its stage-1 harness shipped in v0.10.0, #108 covers only existing container tests being unable to fail, and its release-gating stage is tracked in #135. #99 folds into #109. #92 is open and unblocked. #83 and #14 were advanced here but closed elsewhere — #83 in v0.11.0 (#122, #123 variant in #127), which moots PLAN item 14 since create-failure-issue.sh was deleted rather than hardened, and #14 in v0.11.1 (#131). PLAN items 7 and 8 are done; item 15 is down to one cosmetic fix (#187).

The full ranked report — 83 findings, a 26-row quick-wins table, per-finding evidence — sits outside the repo.

[mmcky]

Revalidated 2026-08-14 against main @ e56d616. Every claim in the tracking body was re-checked against the current code; all of it still holds, and nothing merged since the 2026-08-11 update (#137, #139, #140) touches the open set. No body edits needed.

Per-issue verification:

• fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105 — wrangler@latest still unpinned (preview-cloudflare/action.yml:71); DEPLOY_OUTPUT=$(wrangler …) at :93 still aborts under -e on failure, leaving the output dump at :103 and the friendly error after it unreachable; the deployment-url extraction at :131-134 ends || true as noted. Line numbers have not drifted since the last update.
• docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106 — all seven Anaconda 2025.12 sites confirmed present (docs/ARCHITECTURE.md:12, docs/CONTAINER-GUIDE.md:9, containers/README.md:18, containers/quantecon/README.md:15 and :107, containers/quantecon-build/README.md:26 and :82) while both images ship anaconda=2026.06. The round ~8GB / ~3GB pairs and the ~60% smaller claim (containers/README.md:35) still contradict README.md:147-148's measured ~8.3 GB / ~3.2 GB; docs/QUICK-REFERENCE.md:22-23 and containers/VALIDATION.md:17-18 carry the round numbers too.
• fix(actions): batch of small correctness fixes across the seven actions #107 — 7 of 10 boxes remain, matching the body. The substring builder parse is live at build-jupyter-cache/action.yml:106 with the repeated tests now spanning :120-141 (three echo lines drifted it slightly past the cited :136). Both landed guards read always() && … != 'true' (:384, :649, plus a third at :534).
• test: unify container smoke tests and make the fixture exercise the Dockerfiles #108 — both residuals confirmed: containers/quantecon/tests/test-container.sh survives with containers/quantecon/README.md:227 (and :241) still pointing at it, and the fixture keeps html_theme: sphinx_book_theme / fontpkg: "" (minimal-jupyter-book/_config.yml:26, :28).
• docs: reconcile action READMEs and templates with the shipped code #109 — the docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99 fold-in target is unchanged: the "Pages 404?" snippet still recommends contents: write (docs/QUICK-REFERENCE.md:312-317).

Suggested order is unchanged: #105 (only remaining high-priority bug, and small) → #106 (needs sizes re-measured, not copied) → #107 → #108 → #109 folding in #99.

[quantecon-services]

Revalidated 2026-09-23 against main @ 44c0273, after #165, #166 and #168. Every open item in #105–#109 is still live.

The body now records:

• four decisions, including how releases that carry fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105/fix(actions): batch of small correctness fixes across the seven actions #107 are staged;
• a new finding: the image-size job has never produced a figure but stays green;
• corrections to fix sketches in fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105, fix(actions): batch of small correctness fixes across the seven actions #107 and docs: reconcile action READMEs and templates with the shipped code #109 that would misfire as written;
• line drift since 2026-08-14.

PR plan, each on its own branch:

• docs(preview-*): warn against pull_request_target instead of recommending it (#105) #170: the fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105 README fork-PR warning (open).
• The size-job fix, which unblocks docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106.
• fix(actions): batch of small correctness fixes across the seven actions #107, plus docs: reconcile action READMEs and templates with the shipped code #109's three code items.
• test: unify container smoke tests and make the fixture exercise the Dockerfiles #108's fixture residuals.
• docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106 and docs: reconcile action READMEs and templates with the shipped code #109 docs, as one PR.
• fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105's deploy and pinning changes, opened as a draft. It needs a real Netlify and Cloudflare deploy to verify.

---

Generated by Claude Code