chore: delete stale .md docs, pinning the load-bearing facts first - #123
Merged
Conversation
…to code Ahead of deleting the standalone .md docs, move the content that still matters to where it is consumed: - verify_signing_secrets.yml: the cert-acquisition walkthrough (Developer ID Application cert, the G2 intermediate-chain gotcha, .p12 export with the intermediate baked in, App Store Connect API key) + the six-secret table move into the workflow header; release.yml's signing section now points there. - prepare_release.yml: the manual pre-release checks the automated suite cannot cover (distributed navigator drag, real GPU FV/OM run, no-GPU check of the packaged app, IPF colour-key legend, clean shutdown, and the post-tag gh-release-view asset check) become literal checkboxes in the auto-generated release PR body. - runner.ts stopSpyDE: document the open Windows shutdown-wedge bug (quit during a streaming find-vectors batch stops the stdin tick that keeps the hidden backend scheduled; e2e waits for '[fv-batch] finalized' before closing). - spyde/models/registry.py: the ship-a-revised-model contract (train -> validate via benchmark_neural_spots -> upload to HF under a NEW versioned filename, never overwrite -> edit registry.json) moves into the module docstring; models/__init__.py, find_vectors_action.py and pyproject.toml now point at it instead of models/RELEASING.md.
Everything that still mattered was pinned into code/workflow comments in the previous commit (signing walkthrough, release manual checks, model release contract, shutdown-wedge bug). The plan/audit/roadmap/benchmark narrative files were stale working documents; per project policy facts live in tests, docstrings and commit messages, not committed .md files. Kept: CLAUDE.md and every README.md (root, spyde/actions, electron/tests).
- README.md: the two electron/PACKAGING.md links now point at electron-builder.yml / pythonEnv.ts / bundle-python.mjs (where the packaging mechanics are documented). - CLAUDE.md: benchmarks.md/DISTRIBUTION_PLAN.md pointers dropped — the measured numbers were already inline. - Workflows: build.yml points at release.yml; release.yml and prepare_release.yml comments no longer cite RELEASING/PACKAGING/ DISTRIBUTION_PLAN; electron-builder.yml + entitlements.mac.plist point at verify_signing_secrets.yml for the signing walkthrough. - Python/TS comments: 'see benchmarks.md' tails dropped where the numbers are inline (compute_dispatch, update_functions, _session_files, benchmark_* harnesses, test_chunk_dispatch_guard, test_movie_chunking, test_nav_cached_read); plan-file pointers (NOTEBOOK_PARITY_PLAN, VECTOR_ORIENTATION_MAPPING_PLAN, RELEASE_0_3_0_PLAN, NEURAL_INTEGRATION_PLAN, DISTRIBUTION_PLAN) replaced with the contract statement itself or the relevant benchmark-script/test path. No contract statements removed. - benchmark_3nm_spots.py keeps its benchmark_3nm_spots_results.md mentions: that is the script's own (now untracked) output file.
CSSFrancis
marked this pull request as ready for review
August 7, 2026 17:21
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Deletes 34 tracked .md files (-17,181 lines): all root plan/audit/roadmap docs, benchmarks.md, docs/superpowers/**, docs/future_tasks.md, electron/{PACKAGING,SIGNING}.md, spyde/models/RELEASING.md. Kept: CLAUDE.md and every README.md (root, spyde/actions, electron/tests).
Facts pinned BEFORE deletion (commit-by-commit: pins, deletions, reference cleanup):
.github/workflows/verify_signing_secrets.yml, next to the six secrets it validates: Developer ID Application cert (not Installer/Distribution), the G2 intermediate-chain gotcha, .p12-with-intermediate export, App Store Connect API key, post-build verification. Pointers from release.yml / electron-builder.yml.gh release view --json assetscheck under "After merging".electron/src/main/runner.tsstopSpyDE(), directly above theclearIntervalthat causes it; records the[fv-batch] finalizede2e workaround and that the app-side fix is open.spyde/models/registry.pymodule docstring (validate via benchmark_neural_spots, upload under a NEW versioned filename, never overwrite, registry.json + sha256).Reference cleanup across 33 files: README's PACKAGING.md links repointed, CLAUDE.md's benchmarks.md pointers dropped (numbers were already inline), every dangling "see X.md" comment either trimmed or replaced by the inlined fact / benchmark-script path. No contract statements removed.
Verification: pyyaml parse on all edited workflows, py_compile on all edited .py,
pytest spyde/tests/migrated/test_model_registry.pygreen, fullgit grepsweep for deleted filenames clean.