OpenProgram Docs

Repository structure implementation ledger#

This ledger records implementation evidence for repository-structure.html. The HTML page is the current design contract; this file is operational history.

Scope#

  • Move the existing top-level CLI parser out of openprogram/cli.py without changing the public openprogram.cli.build_parser import or command grammar.
  • Keep docs/superpowers/ in Git but remove it from the public documentation build. Preserve linked reference/design/plans/ pages in a separate design section.
  • Group the existing UI design pages in navigation without moving their source files.
  • Record, but do not perform, Desktop and Web bridge splits while those areas have active product changes.

Workstreams#

Workstream Branch / commit Status Integration note
Earlier repository inventory codex/file-structure-20260816 / 373af35c superseded Useful inventory and repository contract remain review input; do not merge the old branch wholesale.
CLI parser split codex/code-doc-structure-20260817 / e54bd425 implemented Move-only split; openprogram.cli.build_parser remains the public import.
Documentation information architecture codex/code-doc-structure-20260817 / d37d9bab implemented Adds the HTML design, implementation ledger, shared navigation rules, and five UI design groups.
Review repairs 1be7295f, df3df11d implemented Preserve the Design landing and make build/language checks share the public-source exclusion.
Main-branch synchronization 2e3cda14 integrated Merges committed main at acf13f8c; no structural-file conflict.
Test and top-level structure maintenance codex/test-structure-20260817 / dbe752eb implemented Declares tracked top-level directories, relocates two root scripts, refreshes generated package READMEs, and removes obsolete active-guide paths.
Post-merge suite repair codex/test-structure-20260817 / d04aa050 implemented Moves two real workflow execution tests to component, updates their package schema, and repairs merged documentation, distribution, and optional-dependency regressions.

Verification record#

5 passed — focused CLI parser and documentation navigation contracts
207 passed — post-main-merge CLI component/unit tests plus focused structure contracts
158 passed, 2 skipped — independent quality selection of CLI-named and docs IA tests
497 pages — python -m tools.docs_site.build
0 broken links — python -m tools.docs_site.checklinks docs/_site
ok — python -m tools.docs_site.check_landing
0 Chinese lines — python -m tools.docs_site.checklang
pass — Ruff and git diff --check
pass — desktop render at 1280 × 720, no horizontal overflow
pass — narrow render at 390 × 844, no page overflow; wide tables scroll locally
pass — independent specification review at df3df11d
pass — independent quality review at df3df11d, including wheel-content and isolated-import probes
442 passed, 1 skipped — current repository contracts
5699 passed, 16 skipped, 1 xfailed — fixed -n 4 required selection, repeated three times with 0 worker crash
2560 passed, 3 skipped; 42.402765% — Python 3.12.13 serial unit branch coverage, repeated twice
503 pages; 0 broken links; landing and language checks pass — current documentation build
pass — Desktop full npm run check after adding update-service.js to build.files
0 new, 0 refreshed — second package README generator run
pending — independent specification and quality review for dbe752eb..d04aa050

Deferred boundaries#

  • desktop/main.js: extract existing window lifecycle, native WebView, tab transfer, and menu responsibilities after the current Desktop work lands.
  • web/lib/desktop-bridge.ts: establish executable state/transfer tests before moving types, view state, and transfer coordination.
  • Long cohesive Python state machines remain intact until a separately tested responsibility is identified; line count alone is not an implementation task.
Last updated · 2026-08-17
PreviousRepository structureNextSite discoverability and performance design