Telescope runs calendar (issue #37)

.gitignore

@@ -154,7 +154,19 @@ _html/
 # Project initialization script
 .initialize_new_project.sh
 
+docs/notebooks/data/**
+docs/notebooks/eso_programmatic.py
+Didymos_runs
+
 # Serena MCP
 .serena/
 
-docs/notebooks/data/**
+# Django MEDIA_ROOT — downloaded DataProduct files (src/fomo/settings.py)
+src/data/
+
+# Claude Code / GSD tooling (local install + machine-specific config)
+.claude/
+
+# graphify skill — generated knowledge-graph cache/build output
+.planning/graphs/
+graphify-out/

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
         name: Clear output from Jupyter notebooks
         description: Clear output from Jupyter notebooks.
         files: \.ipynb$
-        exclude: ^docs/pre_executed
+        exclude: ^docs/notebooks/pre_executed
         stages: [pre-commit]
         language: system
         entry: jupyter nbconvert --clear-output

docs/conf.py

@@ -42,6 +42,15 @@
 templates_path = []
 exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
+# The pre-commit sphinx-build hook overrides exclude_patterns to skip
+# notebooks/* for speed (avoids executing/rendering .ipynb files on every
+# commit). That intentionally leaves docs/notebooks.rst's toctree entry
+# pointing at an excluded document during local pre-commit builds, which
+# would otherwise emit a 'toctree contains reference to excluded document'
+# warning on every commit. Full builds (ReadTheDocs, CI) don't apply that
+# override, so this only ever suppresses the pre-commit-local false positive.
+suppress_warnings = ['toc.excluded']
+
 # This assumes that sphinx-build is called from the root directory
 master_doc = 'index'
 # Remove 'view source code' from top of page (for html, not python)
@@ -56,3 +65,5 @@
 autoapi_member_order = 'bysource'
 
 html_theme = 'sphinx_rtd_theme'
+# Add following to allow notebook execution errors (e.g. interactive cells)
+nbsphinx_allow_errors = True

docs/design/GSD_Claude_notes.md

@@ -0,0 +1,196 @@
+## Initial setup of Serena etc
+
+* Ensure `uv` is install from Astral
+* Run `uv tool install -p 3.11 serena-agent`
+* Run `serena init`
+* Edit '~/.serena/serena_config.yml' and ensure large files e.g. FITS, HDF5 etc are excluded:
+```
+ignored_paths:
+- "*.fits"
+- "*.fits.*"
+- "*.bsp"
+- "*.ecsv"
+- "*.bin"
+- "*.pt"
+- "*.7z"
+- "*.zip"
+- "*.db"
+- "*.hdf5"
+```
+* Run `serena setup claude-code`
+* To add to the global configuration to use for all probjects:
+claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
+* Created an alias:
+alias ccs='claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"'
+to launch Claude Code with Serena and get it, particulary Opus models, to use it per [Serena Claude Code docs][https://oraios.github.io/serena/02-usage/030_clients.html#claude-code]
+
+
+# Notes on using GSD in Claude for issue37 branch
+
+## Phase 1
+
+### Planning
+
+No notes.
+
+### Middle of Phase 1 (Start of execution)
+  ▶ Next Up
+
+  Execute Phase 1 — run both plans (Wave 1 then Wave 2)
+
+  /clear then:
+
+  /gsd-execute-phase 1
+
+  ───────────────────────────────────────────────────────────────
+
+  Also available:
+  - cat .planning/phases/01-site-ephemeris-helper/*-PLAN.md — review plans
+  - /gsd-plan-phase 1 --research — re-research first
+  - /gsd-review --phase 1 --all — peer review plans with external AIs
+
+  ───────────────────────────────────────────────────────────────
+
+  Note for execute-phase: the project's default node is v14, which is too old for gsd-tools.cjs (needs ES2021 ||=). Use
+  /home/tlister/.nvm/versions/node/v20.20.2/bin/node when invoking the tool, or prepend it to PATH.
+
+
+### Security gate questions 
+❯ Great. I didn't understand the choice about the security gate; explain further
+
+  Read 1 file, ran 1 shell command 
+
+● Here's the full picture on what that security gate is and what running it would involve:
+
+  What it is
+
+  GSD has an optional "secure phase" workflow (/gsd:secure-phase 01) that runs a STRIDE-style threat-mitigation audit against a completed phase.
+  It's controlled by .planning/config.json:
+
+  "security_enforcement": true,
+  "security_asvs_level": 1,
+  "security_block_on": "high"
+
+  When enabled, it's meant to be part of the phase-completion checklist — execute-phase.md's aggregate_results step checks whether
+  {phase}-SECURITY.md exists, and if it doesn't, it's supposed to surface a suggestion to run it.
+
+  How it would work for Phase 01
+
+  1. It reads 01-01-PLAN.md/01-02-PLAN.md for a <threat_model> block (trust boundaries + a STRIDE threat register with dispositions).
+  2. Our plans didn't author a <threat_model> block (telescope_runs.py isn't the kind of phase where STRIDE planning was prompted — it's a pure
+  computation module, no new attack surface, no user input, no auth/data boundaries).
+  3. Because of that, register_authored_at_plan_time: false → the workflow falls into "retroactive-STRIDE mode": it spawns gsd-security-auditor,
+  which has to invent a threat register from scratch by reading the implementation files, then verify mitigations against that invented register.
+  4. If it finds any "open" threats (even speculative/low-relevance ones for a module with no I/O, no auth, no untrusted input), it would either
+  present them for accept/block, or block phase advancement until resolved.
+
+  Why I framed it as a "choice"
+
+  For a module like telescope_runs.py — pure math over Observatory DB records and astropy, no network calls, no user input, no new permissions —
+  a STRIDE audit is largely going to produce either:
+  - nothing meaningful (good, but ~5 min subagent run for no signal), or
+  - low-value "threats" invented to fill the register (e.g. "what if Observatory.timezone is attacker-controlled" — which isn't really a security
+  boundary here, just the WR-03 robustness issue we already fixed).
+
+  So the choice was really: run the formal gate now (costs a subagent run, may produce noise, but satisfies the config's enforcement requirement
+  and creates 01-SECURITY.md) vs. skip it (the config says it's required, but the phase's actual risk profile doesn't warrant it).
+
+  I didn't make that call for you — I just surfaced that the gate exists and is unsatisfied. If you want, I can run /gsd:secure-phase 01 now;
+  given what we've already covered in code review (WR-02/03 input-validation gaps, now fixed), I'd expect it to come back clean or with only
+  "accepted risk" items.
+
+### Usage (at end of day/session)
+
+   Settings  Status   Config   Usage   Stats
+
+   Session
+
+   Total cost:            $4.51
+   Total duration (API):  9m 41s
+   Total duration (wall): 27m 52s
+   Total code changes:    146 lines added, 32 lines removed
+   Usage by model:
+      claude-sonnet-4-6:  2.7k input, 47.4k output, 6.6m cache read, 399.0k cache write ($4.51)
+
+   Current session
+   ██████████████████████████████████████████████████ 100% used
+   Resets 5:39pm (America/Los_Angeles)
+
+   Current week (all models)
+   █████████████▌                                     27% used
+   Resets Jun 16, 9:59pm (America/Los_Angeles)
+
+   What's contributing to your limits usage?
+   Approximate, based on local sessions on this machine — does not include other devices or claude.ai
+
+   Last 24h · these are independent characteristics of your usage, not a breakdown
+
+   90% of your usage came from subagent-heavy sessions
+    Each subagent runs its own requests. Be deliberate about spawning them — and 
+    consider configuring a cheaper model for simpler subagents.
+
+   11% of your usage was at >150k context
+    Longer sessions are more expensive even when cached. /compact mid-task, /clear 
+    when switching to new tasks.
+
+   49% of your usage came from plugin "gsd"
+    Review what this plugin contributes — its agents, skills, and MCP tools all 
+    count toward your limit.
+
+   Skills                  % of usage
+   /gsd:plan-phase                 9%
+   /gsd:code-review                5%
+   /gsd:discuss-phase              4%
+   /gsd:new-project                3%
+   /gsd:execute-phase              3%
+   /gsd:map-codebase               1%
+   /gsd:phase                      1%
+
+   Subagents               % of usage
+   gsd:plan-phase                  9%
+   gsd:execute-phase               8%
+   gsd-executor                    6%
+   gsd:code-review                 3%
+   gsd:map-codebase                2%
+   gsd-roadmapper                  1%
+
+   Plugins                 % of usage
+   gsd                            49%
+
+   d to day · w to week
+
+   Usage credits
+   █████▋                                             11% used
+   $4.50 / $40.00 spent · Resets Jul 1 (America/Los_Angeles)
+
+
+## Fixing up issues after phase 3
+Run:
+/gsd-code-review 03 --fix
+
+After that, plus an additional fix to truncate microseconds and change the example Magellan instrument from LDSS3 
+● Both phases of v1.1 are complete and all code review fixes have been applied. The STATE.md is slightly stale (it still
+says "verifying"), but in practice the branch is ready. Your options:
+
+1. Create a PR now — everything is in good shape; the verification was already done before the code review, and the
+fixes were all polish (error handling, temp-dir leak, encoding, microseconds). Run /gsd-pr-branch or just gh pr
+create.
+2. Re-verify first (/gsd-verify-work) — if you want a formal second pass on the verification artifact now that CR-01
+and the microseconds fix have changed behavior. Low stakes since none of the fixes changed correctness of the
+astronomy or the idempotency logic.
+3. Close the milestone (/gsd-complete-milestone) — archives the v1.1 planning artifacts and sets up for the next
+milestone (Stage 3 queue-window banners, or Stage 4 observation-record sync, depending on what you want to tackle
+next).
+
+
+## Phase 4
+
+▶ Next Up — Telescope Runs Calendar
+
+Phase 4: LCO Queue Sync Command — sync_lco_observation_calendar --proposal <code> syncs LCO ObservationRecords to CalendarEvents with banner → placed-block → terminal-state lifecycle
+
+/clear then:
+
+/gsd-discuss-phase 4 — gather context and clarify approach before planning
+
+Also: /gsd-plan-phase 4 — skip discussion, plan directly

docs/design/design.rst

@@ -32,3 +32,15 @@ Component
 
 .. image:: /design/SSSC-Followup_Observations_of_Moving_Objects-Component.png
     :alt: Component diagram for FOMO
+
+Design Notes
+------------
+
+.. toctree::
+   :maxdepth: 1
+
+   telescope_runs_calendar
+   tom_calendar_vs_yse_pz_calendar
+   gsd_experiment
+   eso_feasibility_spike
+   uncertain_scheduling_spike