Session CONV-37

Resume Prompt

Stage 1 launch plan теперь живёт в 15 редактируемых фрагментах под docs/rendered/stage-1-parts/ (00-overview … 14-open-questions). Master (все 4 стадии в одном файле) и stage-1.html — авто-генерируемые артефакты с GENERATED-баннером, не редактировать вручную. Build pipeline: scripts/build-launch-plan-master.py собирает оба выхода из 15 фрагментов + 4 launch-plan-*.html партов (v3-full, future, appendices, changelog). GitHub Action .github/workflows/build-launch-plan-master.yml пересобирает их на каждом push'е, который трогает фрагменты или парты. Известный лаг: bot-коммит ребилда НЕ триггерит deploy (GITHUB_TOKEN limitation) — preview обновится со следующим обычным push'ем, либо вручную через gh workflow run "Deploy rendered HTML to preview.offplan.online". PAT skip'ut. Preview: https://preview.offplan.online/launch-plan-master.html

Summary

Built a fragment-based build pipeline for the launch plan. Stage 1 split into 15 editable HTML fragments in docs/rendered/stage-1-parts/ (overview + intro + foundational + 11 phases + open questions), with scripts/build-launch-plan-master.py assembling both launch-plan-stage-1.html (Stage 1 в сборе) and launch-plan-master.html (all 4 stages + appendices + changelog in one). GitHub Action .github/workflows/build-launch-plan-master.yml auto-rebuilds both outputs on any push that touches a fragment or one of the 4 remaining source parts (v3-full, future, appendices, changelog). End-to-end loop verified working: pushed initial commit → action ran in 15s → bot committed regenerated outputs as e91cf1f. Hit a race condition mid-rebase with a parallel Claude session that was actively committing admin-panel files; resolved via merge strategy plus manual conflict fix on the meta-tag head. Manually triggered the deploy workflow (gh workflow run) to confirm preview.offplan.online serves the new master URL.

Changes

• scripts/build-launch-plan-master.py — new, ~460 lines — assembles stage-1 + master from 15 fragments + 4 parts; rewrites cross-file links asymmetrically (stage-1 → master.html#X, master → internal #X)
• scripts/_extract_stage_1_fragments.py — new, ~248 lines — one-off splitter that read current stage-1.html and produced the 15 fragment files; kept in repo for posterity
• .github/workflows/build-launch-plan-master.yml — new, ~84 lines — triggers on push to fragments or source parts, regenerates outputs, commits back via github-actions[bot]
• docs/rendered/stage-1-parts/00-overview.html … 14-open-questions.html — 15 new fragments. Each is a standalone HTML with head + slim hero + content between <!-- ══ FRAGMENT CONTENT START ══ --> / <!-- ══ FRAGMENT CONTENT END ══ --> sentinels + footer. Openable in browser individually.
• docs/rendered/launch-plan-stage-1.html — converted from hand-edited (388 KB) to auto-generated (539 KB after merge with parallel session's CONV-36 additions). Has GENERATED banner at top.
• docs/rendered/launch-plan-master.html — new auto-generated artifact (~728 KB) — all 4 stages + team + process + appendices A–G in one document

Decisions

Fragment granularity = phases (15 files), not per-task. Offered the user 3 options (keep crude 5-parts / split only Stage 1 / fine-grain everywhere). Chose middle path because Stage 1 is the active surface that needs frequent editing while Stages 2-4 + appendices are stable. Per-task would be ~150 files — too granular, harder to navigate.

Fragments are standalone HTMLs with sentinel comments, not raw partials. Each fragment has head + hero + footer so it opens in browser as its own styled mini-page (useful for previewing single-phase changes). Builder strips boilerplate and keeps only content between <!-- ══ FRAGMENT CONTENT START ══ --> and <!-- ══ FRAGMENT CONTENT END ══ -->. Raw partials rejected because users can't preview them visually without context.

Skip PAT for bot auto-commits. Default GITHUB_TOKEN means bot commits don't trigger downstream actions, so deploy lags by 1 push behind the bot's regenerated outputs. Accepted because: (a) parallel Claude session commits frequently so preview catches up quickly, (b) manual gh workflow run is 5 seconds when immediate refresh is needed, (c) PAT setup is 10 min if lag becomes annoying. Rejected: setting up PAT now (premature optimisation for current usage).

Used merge (not rebase) when remote diverged because of race condition with parallel Claude session actively editing files. The rebase attempted 13 commits worth of replay and kept hitting conflicts on stage-1.html due to the moving target. Switched to merge → single 5-line conflict on meta-tag head → manually combined remote's meta tags with my new title. Rebase would have been cleaner history but unworkable given the race.

Next Steps

1. Try editing a fragment (e.g. docs/rendered/stage-1-parts/05-phase-1-3.html between the FRAGMENT CONTENT sentinels) to verify the full loop end-to-end from a real content edit — push → action rebuilds → bot commits → preview catches up.
2. If preview deploy lag becomes annoying, set up PAT (10-min job): GitHub Settings → Developer settings → Fine-grained PAT → repo scope offplan-online/os, permissions Contents Read+Write → store as BOT_PAT secret → update workflow's persist-credentials to use it.
3. Optionally apply the same fragment pattern to other big plans (e.g. plans/permission-and-tenancy-model.md) if they grow unwieldy.

Open Questions

• Whether docs/rendered/launch-plan-v3-full.html (now Stage 2 + Team + Process + Appendix A + Appendix F) should also be split into fragments, or stay coarse-grained.
• Whether master.html's <meta> tags should be customised (currently inherits Stage-1-specific summary / tags=launch,stage-1 / group=launch-plan since head comes from a stage-1 fragment).

Context for next session

• Parallel Claude session active in same workspace during this entire session — committed admin-panel files autonomously (01-onboarding.html, 02-overview.html, 02b-overview-guest.html, 01-quick-build.html, ADR 0014/0011 updates, plan SPEC-AMEND v1.2, etc.). Origin moved 3 times during my work. If this is still the case next session, expect race conditions on shared files. Workaround used this session: merge instead of rebase.
• Bot's auto-rebuild commit (e91cf1f) sits on origin/main but deploy-rendered.yml did NOT fire on it (GITHUB_TOKEN limitation, by design). Manually triggered the deploy at end of session via gh workflow run — preview.offplan.online is current as of that.
• The one-off extraction script scripts/_extract_stage_1_fragments.py is kept in repo for posterity. Safe to re-run; overwrites all 15 fragment files. Only useful if rebaselining from a different launch-plan-stage-1.html (e.g. someone hand-edited it accidentally).
• Bot's commits look like: chore: rebuild launch-plan-{stage-1,master}.html (auto) with author github-actions[bot]. Easy to spot in git log.
• Notion CONV unique_id is now at 36 (mine). The parallel session's docs/sessions/CONV-36.md (committed in 059a569) reports Notion-35 with a +1 local offset — confirming the offset convention. My local file is CONV-37 to preserve sequence.