Skip to content

docs: V1→V2 sweep — remove GitHub-Project provisioning, sync.py, Issue Types from user-facing docs#52

Merged
jurby merged 7 commits into
mainfrom
docs/v1-to-v2-sweep
May 31, 2026
Merged

docs: V1→V2 sweep — remove GitHub-Project provisioning, sync.py, Issue Types from user-facing docs#52
jurby merged 7 commits into
mainfrom
docs/v1-to-v2-sweep

Conversation

@jurby
Copy link
Copy Markdown
Contributor

@jurby jurby commented May 31, 2026

What

Sweeps the user-facing docs from the removed V1 GitHub-Project flow to V2 local-first. The V1 provisioning path (project_setup.py --org/--repo/--project-title, org Issue Types, custom fields, sub-issues, issue_map.yaml, bidirectional sync.py, project_views.py) was removed in 2.0.0, but these docs still described it as the current flow — the commands error (args gone) and mislead anyone following them.

V1 → V2 conversions applied

  • project_setup.py --org/--repo/--project-title + GitHub Project v2 creation → /edpa:setup vendors .edpa/engine/ + seeds configs (local-first, no gh)
  • issue_types.py / project_views.py / org Issue Types / custom fields → removed (V2 items are local .edpa/backlog/**/*.md via backlog.py add)
  • bidirectional sync.py (pull/push/diff/conflicts) → removed; the only optional GitHub integration is the --with-ci contribution-sync workflow (sync_pr_contributions.py, PR-thread signals → evidence[])
  • .claude/edpa/scripts|templates/.edpa/engine/scripts|templates/
  • project.yamledpa.yaml, heuristics.yamlcw_heuristics.yaml, .yaml backlog → .md
  • evaluate_cw.py (+ground_truth loop) → calibrate_signals.py Monte Carlo optimizer

Files (13)

  • RUNBOOK.md — §1 setup + §2 GitHub integration rewritten to V2; paths + version stamp
  • playbook.md — full V2 rewrite (1334→1132 lines): removed GH provisioning / issue_types / project_views / sync; fixed the false "backlog.py add is strictly GH-first" claim; redrew the architecture diagrams
  • E2E-TEST-PLAN.md / E2E-SKILLS-TEST-PLAN.md — test phases rewritten to the V2 local-first flow; dropped GH-Project / sync / --mode phases; /edpa:sync removed (no such command in V2)
  • github-setup.md — gutted to "Optional GitHub Integration" (PR-signal sync + /edpa:board)
  • edpa-token-setup.mdEDPA_TOKEN reframed for the edpa-contribution-sync.yml workflow (not the removed sync.py)
  • kashealth-pilot/{KASHEALTH-PILOT.md,preflight.sh,edpa.yaml.example} — local-first pilot setup; corrected the capacity invariant
  • methodology.md / auto-calibration.md — Monte-Carlo calibrate_signals.py (mirrors the edpa-autocalib skill)
  • mcp.md / org-lookup.md — path fixes

Left as historical (intentionally untouched)

docs/v2/{plan,concept,decisions}.md and docs/proposals/* — design/decision records that reference V1 as the thing that was replaced.

Loose ends for follow-up

  • docs/org-lookup.md documents lookup_org.py, which is not shipped in V2 (removed from the codebase). I added a status banner — you may prefer to delete the page or restore the feature.
  • web/src/pages/docs/edpa-token-setup.md (web mirror) still carries the V1 body — the release-checklist web-page step should apply the same conversion before the 2.1.8 release.

🤖 Generated with Claude Code

jurby added 4 commits May 31, 2026 22:45
…rovisioning + sync.py

- §1 /edpa:setup: vendors engine + seeds .edpa/ (no --org/--repo/--project-title,
  no Issue Types, no issue_map); real V2 output + flags
- §2: replace bidirectional sync.py (removed in 2.0.0) with the optional
  --with-ci PR-signal contribution-sync workflow
- prerequisites: local-first (python+git); gh only for optional sync
- paths plugin/edpa/scripts → .edpa/engine/scripts; python3.13 → python3
- smoke test: drop e2e GH-sync test + sync.py status
…ject/sync/issue_types

- playbook.md: removed GH Project provisioning (project_setup --org), issue_types,
  project_views, bidirectional sync.py; .claude/edpa → .edpa/engine; project.yaml →
  edpa.yaml, heuristics.yaml → cw_heuristics.yaml; .yaml backlog → .md; fixed false
  'backlog.py add is GH-first' claim; redrew architecture diagrams; CLI ref to V2
- E2E-TEST-PLAN.md + E2E-SKILLS-TEST-PLAN.md: rewrote test phases to the V2 local-first
  flow (vendor → backlog.py add → git evidence → engine close → reports); dropped
  GH-Project/sync/issue_map/--mode phases; /edpa:sync removed (no such command in V2)
- RUNBOOK.md: version stamp 2.1.7 → 2.1.8
…, MC calibrator, local-first pilot

- github-setup.md: gutted V1 GitHub-Project setup (Issue Types, custom fields, 4
  typed status fields, views, sync.py automations) → 'Optional GitHub Integration'
  (PR-signal contribution-sync + /edpa:board); kept ID convention/status/granularity
- edpa-token-setup.md: EDPA_TOKEN now powers edpa-contribution-sync.yml (sync_pr_
  contributions.py), not the removed sync.py; perms reframed (Contents+PR read)
- kashealth-pilot/{md,preflight.sh,edpa.yaml.example}: local-first setup, no GH
  Project/Issue Types; corrected capacity invariant; .yaml→.md; removed sync: block
- methodology.md §8.5 + auto-calibration.md: evaluate_cw.py(+ground_truth) →
  calibrate_signals.py Monte Carlo optimizer (mirrors edpa-autocalib skill)
- mcp.md, org-lookup.md: .claude/edpa/scripts → .edpa/engine/scripts; org-lookup
  banner notes lookup_org.py is not shipped in V2
…e/setup (CZ+EN) + tutorial + docs/

- playbook.astro CZ+EN: full V2 (removed GH-Project provisioning, issue_types, project_views,
  bidirectional sync.py; redrew architecture diagrams; .claude/edpa→.edpa/engine;
  project.yaml→edpa.yaml; heuristics.yaml→cw_heuristics.yaml; .yaml→.md backlog)
- methodology.astro CZ+EN: local-first framing; calibration → calibrate_signals.py MC optimizer
- guide.astro CZ+EN: V2 setup flow; EDPA_TOKEN step → optional PR-signal CI
- setup.astro CZ+EN: interactive wizard now emits edpa.yaml (was project.yaml); JS fn names/ids preserved
- tutorial.astro + docs/index.astro: V2 commands/descriptions
- docs/edpa-token-setup.md (web mirror): EDPA_TOKEN → contribution-sync workflow, not sync.py
- verified: full `astro build` green (28 pages)
@jurby
Copy link
Copy Markdown
Contributor Author

jurby commented May 31, 2026

Update: web (Astro) doc pages added to this sweep

Extended the sweep to the web docs/ tree. 11 Astro doc pages converted to V2 and astro build verified green (28 pages):

  • playbook.astro + en/playbook.astro — full V2 (GH-Project provisioning, issue_types, project_views, bidirectional sync.py removed; architecture diagrams redrawn)
  • methodology.astro + en/ — local-first framing; calibration → calibrate_signals.py MC optimizer
  • guide.astro + en/ — V2 setup flow; EDPA_TOKEN step → optional PR-signal CI
  • setup.astro + en/ — interactive wizard now emits edpa.yaml (JS fn names/ids/markup preserved)
  • tutorial.astro, docs/index.astro, docs/edpa-token-setup.md (web mirror)

This now covers 24 files (13 repo docs + 11 web). Total ≈ −300 LOC net.

Still V1 — marketing/pitch pages (NOT in this PR — need a messaging decision)

These present the old GitHub-Projects-centric flow and would mislead at the 2.1.8 release, but converting them is a product-positioning/voice call, not a mechanical doc fix:

  • index.astro (landing) — "Volitelný GitHub Projects sync pro PM UI" (×4) — V2 has PR-signal materialization, not bidirectional Projects sync
  • journey.astro — V1 slide deck: "Issue Types" / "GitHub Project" / "Custom Fields" slides + .claude/edpa/scripts/ commands
  • presentation/index.astro + presentation/kashealth.astro — pitch decks: "GitHub Projects + custom fields · Issue types, hierarchie, views · 4h", .claude/edpa/, engine.py, sync.py, … tree

evaluation.astro + calculator.astro were checked and are already V2-clean (the "rot" hits were cw_heuristics.yaml substring false-positives).

… drop GitHub-Projects pitch

- index.astro CZ+EN: 'GitHub Projects sync' positioning → local-first; optional GitHub =
  PR-signal contribution-sync; EN evidence table corrected from GitHub-schema to local-git
- journey.astro: V1 slides (Issue Types / GitHub Project / Custom Fields) → V2 (Lokální setup,
  Evidence-driven); .claude/edpa→.edpa/engine
- presentation/index.astro + kashealth.astro (CZ+EN): pitch decks → local-first (no GitHub
  Project / Issue Types / '4h setup'; sync.py removed from repo tree; edpa-setup vendors engine)
- verified: full astro build green (28 pages); slide counts / JS / backtick integrity preserved
@jurby
Copy link
Copy Markdown
Contributor Author

jurby commented May 31, 2026

Update: marketing/pitch pages converted — web sweep complete

Per request, also rewrote the V1 product positioning to V2 local-first on the marketing/pitch pages. 7 more files, astro build verified green (28 pages):

  • index.astro + en/ — "GitHub Projects sync" pitch → local-first; optional GitHub = PR-signal contribution-sync; EN evidence table corrected from a GitHub-issue schema to the local-git signal schema
  • journey.astro — V1 slides "Issue Types" / "GitHub Project" / "Custom Fields" → V2 "Lokální setup" / "Evidence-driven"; .claude/edpa.edpa/engine
  • presentation/index.astro + presentation/kashealth.astro (+ en/) — pitch decks → local-first: no GitHub Project / Issue Types / custom fields / "4h setup"; sync.py removed from the repo-tree slide; edpa-setup now "vendors engine into .edpa/engine/, seeds .edpa/config/, installs git hooks". Slide counts / JS / template-literal backticks preserved.

PR now covers 31 files (13 repo docs + 11 web doc pages + 7 web marketing/pitch). Full astro build green.

Remaining (out of scope here)

  • The presentation decks' slides 2–4 still lean on a "GitHub-owned dev stack / GitHub Team / 0 Jira" tooling-cost story (now reads "GitHub optional" alongside it). Reframing that pitch narrative is a larger marketing-content pass — left for a decision.
  • docs/org-lookup.md still documents the removed lookup_org.py (status banner added; delete vs restore?).
  • Shipping 2.1.8 still needs the web build+deploy + CHANGELOG + GitHub release per release-checklist.md.

jurby added 2 commits June 1, 2026 00:36
…GitHub optional

- presentation/index.astro + kashealth.astro (CZ+EN): slides 2-4 'GitHub-owned dev stack /
  central stack from day 1 / Teams+GitHub=complete stack' → 'local-first governance in git
  from day 1; tooling is the team's choice, GitHub optional'
- 'GitHub replaces: Jira→Issues+Projects, Roadmaps→Projects Roadmap, Automation→GitHub Actions'
  → 'git replaces: Jira→.edpa/backlog/, Roadmaps→/edpa:board, Automation→git hooks (+ optional --with-ci)'
- astro build green (28 pages); slide counts / backticks preserved
@jurby jurby merged commit 1c9798c into main May 31, 2026
1 check failed
@jurby jurby deleted the docs/v1-to-v2-sweep branch May 31, 2026 22:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant