Consolidate facility research into a two-tier research/ tree#422
Closed
xmap wants to merge 4 commits into
Closed
Conversation
…d docs tree The ALBA/Sirius/Elettra _research_brief.md files are internal development dossiers (uncertainty flags, ask-staff lists, speculative CORA seam reads), not dual-audience deployment pages. Sitting under docs_dir they risk publishing as orphan pages. Move them beside the existing internal-dev precedent in research/<facility>/ so the published deployment tree stays staff-facing. Co-Authored-By: Claude <noreply@anthropic.com> (cherry picked from commit 028b37d)
…ility>/ with a two-tier layout Research artifacts had grown into five inconsistent shapes across two trees: RE corpora under research/<facility>-reverse-engineering/ (APS, ESRF), a brief under research/psi/, briefs inside the published docs tree (docs/deployments/<id>/_research_brief.md for NSRRC), briefs stranded on unmerged branches (ALBA, Elettra, Sirius), and modeled fleets with no artifact at all. Two homes for one artifact, and depth inversely correlated with how much each fleet was actually modeled. Unify on one home and one shape: - All facility research lives under research/<facility>/ (drop the -reverse-engineering suffix; survey.md says what it is). - Two tiers: research/<facility>/survey.md (facility survey: roster, control stack, data stack, seam, staff questions) and research/<facility>/beamlines/<bl>/ (per-beamline device topology: facts.md + beamline.candidate.yaml). - Move the NSRRC brief out of the published docs tree into research/nsrrc/, so docs/deployments/ stays staff-facing only. This also re-homes the ALBA, Elettra, and Sirius briefs that were stranded off-main, fixing SYRMEP's dangling links. - Bring ALS and PETRA III surveys (facilities with no deployment yet) under research/ rather than the docs tree. Repoint every reference: deployment index/model pages, scripts/reverse_engineer (extractor now emits to beamlines/), beamline.yaml provenance comments, and .gitignore. Templates and a research/ index follow in subsequent commits. Co-Authored-By: Claude <noreply@anthropic.com>
Two templates so the next facility and the next beamline are fill-in-the-blanks rather than reinvention: _templates/survey.md (Tier 1, distilled from the PSI brief, the strongest exemplar) and _templates/facts.md (Tier 2, distilled from the APS facts.md shape). Both bake in the reading-posture and confidence-flag conventions and the mine-as-data-not-spec rule. research/README.md is the single entry point: it documents the two-tier model, why research stays separate from the published docs tree, the honest facility-by-facility state (survey / device-pass / deployment), and how to add a facility. The facility table records "needed" for modeled Sites that lack a Tier-1 survey rather than hiding the gap. Co-Authored-By: Claude <noreply@anthropic.com>
Diamond, NSLS-II, SLAC, and the Australian Synchrotron were modeled deployment-by-deployment (reading each beamline's public controls source at build time) before this research tree was organized, so they had no standing facility survey. Add a retrospective survey.md for each: the roster, the modellable set, the control stack, and the CORA seam, recorded after the fact so every modeled Site has a Tier-1 home. Only MAX IV now lacks one. Also normalize the APS and ESRF survey H1 titles to "<facility> research brief" (they were the old README titles) so the whole tree reads consistently. Co-Authored-By: Claude <noreply@anthropic.com>
Coverage report
This PR does not seem to contain any modification to coverable code. |
Owner
Author
|
Closing in favor of the local-only research direction. The research/ tree is now gitignored (per merged #420/#421) as the user's private upstream practice, not a shared tracked tree. The disciplined two-tier structure, templates, and backfilled surveys from this PR are being preserved on-disk locally (gitignored). A separate PR will fix the public deployment pages that incorrectly link into the now-untracked research/ paths, citing the external upstream sources instead. |
4 tasks
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.
Summary
Reorganizes
research/so facility research has one home and one shape. Audit found five inconsistent structures across two trees, with research depth inversely correlated to how much each fleet was actually modeled, plus a stranded relocate commit and dangling links on main.research/<facility>/:survey.md(Tier 1, facility survey) +beamlines/<bl>/{facts.md,beamline.candidate.yaml}(Tier 2, per-beamline device topology). Dropped the-reverse-engineeringsuffix;extracted/->beamlines/.docs/deployments/nsrrc/_research_brief.mdintoresearch/nsrrc/survey.md, so the published deployment tree stays staff-facing. Re-homed the ALBA/Elettra/Sirius briefs that were stranded off-main (cherry-picked the existing relocate commit), which fixes SYRMEP's dangling links on main.tomcatbrief (byte-identical duplicate ofresearch/psi/); brought the ALS and PETRA III surveys (facilities with no deployment yet) underresearch/.research/_templates/survey.mdandfacts.md(distilled from the PSI and APS exemplars) andresearch/README.mdas the single entry point documenting the two-tier model and the honest facility-by-facility state.scripts/reverse_engineer(extractor now emits tobeamlines/),beamline.yamlprovenance comments,.gitignore.Test plan
pytest tests/unit/deployments/— 541 passedmake docs-build(mkdocs--strict) — exit 0, no orphan-page warnings for moved briefsreverse-engineering/_research_brief/extracted/path references🤖 Generated with Claude Code