From eb91a23ec80f4ea9ce24521d9d1932c5b0b868b4 Mon Sep 17 00:00:00 2001 From: Adrian Cosentino Date: Fri, 17 Jul 2026 18:38:06 -0400 Subject: [PATCH 1/2] docs: reconcile roadmap with implemented workspace --- CHANGELOG.md | 20 +++++++++++++----- README.md | 20 ++++++++++++------ docs/architecture.md | 40 +++++++++++++++++++++++++++--------- docs/mvp-phases.md | 48 +++++++++++++++++++++++++++++++++++++++++--- docs/repo-layout.md | 34 ++++++++++++++++++++++++------- 5 files changed, 131 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dfa99d1..73d026e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,13 +26,23 @@ semantic versioning once releases begin. rebase workflows with dirty-tree guardrails and confirmation plans. - Added Phase 9 operation planning, typed execution, queued operation preview and confirmation, and repo-aware audit visibility. -- Added Phase 10 deterministic prompt parsing for typed Git operation requests - as part of [#12](https://github.com/cosentinode/bitbygit/issues/12), with - golden parser tests, manual planner parity, and safe non-provider multi-step - prompts; `open pr` prompt execution remains Phase 11 GitHub integration work - in [#13](https://github.com/cosentinode/bitbygit/issues/13). +- Added Phase 10 deterministic prompt parsing for typed Git and GitHub operation + requests, with golden parser tests, manual planner parity, safe multi-step + prompts, and rejection of unsupported or shell-like input. +- Added a typed `gh` CLI boundary and guarded pull request planning and execution + for GitHub.com and GitHub Enterprise, including `open pr` in prompt sequences. +- Added merge/rebase operation-state detection and typed continue, abort, and + rebase-skip Git commands. Recovery planning and TUI actions remain open in + [#55](https://github.com/cosentinode/bitbygit/issues/55) and + [#56](https://github.com/cosentinode/bitbygit/issues/56). - Added strict typed TOML configuration loading with complete safe-default fallback and redacted path-aware diagnostics. +- Added effective policy enforcement for protected branches, confirmation + levels, disabled operations, and prompt availability. - Applied configured pull request base defaults after explicit prompt targets and before provider defaults, with provider validation and visible safe config diagnostics in the TUI. +- Added CI and tagged-release workflows that build, smoke-test, package, and + checksum supported Linux, macOS, and Windows artifacts, plus validated binary + and source installation documentation. The first real release is still open + in [#81](https://github.com/cosentinode/bitbygit/issues/81). diff --git a/README.md b/README.md index 4e2eab9..62c3786 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,20 @@ keeping risky operations visible, typed, previewed, and confirmed. ## Current Status -The repository has merged through Phase 10 deterministic prompt parser work as -part of [#12](https://github.com/cosentinode/bitbygit/issues/12), including -golden parser tests, manual planner parity, and safe non-provider multi-step -prompts. Pull request creation from `open pr` remains Phase 11 work in -[#13](https://github.com/cosentinode/bitbygit/issues/13). See -[`docs/mvp-phases.md`](docs/mvp-phases.md) for the implementation roadmap. +Phases 0 through 11 are merged. The workspace includes the TUI and `gh` CLI +boundaries, deterministic prompt parsing, a shared planner/executor path with +queue preview and audit history, and guarded single- and multi-step pull request +workflows. Phase 12 is in progress: repository operation-state detection and +typed merge/rebase recovery commands are merged, while recovery policy and TUI +actions remain open in [#55](https://github.com/cosentinode/bitbygit/issues/55) +and [#56](https://github.com/cosentinode/bitbygit/issues/56). + +Phase 13 configuration and policy slices and Phase 14 release automation and +installation documentation are implemented. Their umbrella issues remain open, +and no release has been published; cutting and validating the first release is +tracked in [#81](https://github.com/cosentinode/bitbygit/issues/81). Phase 15 +documentation work is also in progress. See +[`docs/mvp-phases.md`](docs/mvp-phases.md) for the issue-linked roadmap. ## Configuration diff --git a/docs/architecture.md b/docs/architecture.md index 09efc52..2ae853e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,7 +12,7 @@ before anything runs. ## Product Model -The core model should stay small and explicit: +The core model is small and explicit: - Repository: a registered working tree path plus derived Git identity such as root, current branch, upstream, remotes, and provider hints. @@ -73,15 +73,17 @@ The executor may run processes, but only from validated operation plans. 9. Record an audit entry with sanitized metadata. 10. Refresh repository state. -## Initial Workspace +## Workspace - `crates/bitbygit`: CLI binary entry point. -- `crates/bitbygit-core`: shared domain model and constants. +- `crates/bitbygit-core`: operation model, prompt parser, configuration, policy, + and shared constants. +- `crates/bitbygit-gh`: typed `gh` CLI boundary for repository and pull request + operations. - `crates/bitbygit-git`: typed system Git command boundary. - `crates/bitbygit-store`: local registry, app state, and audit storage. - -Future phases should add crates only when the boundary is useful in practice. -Likely future crates include `bitbygit-tui` and `bitbygit-gh`. +- `crates/bitbygit-tui`: responsive terminal UI, operation planner, pending + queue, confirmation flow, and typed executor. The initial store is a single-writer file-backed store. The TUI should route mutations through one runtime owner; multi-process locking is a later concern @@ -99,11 +101,29 @@ Prompt text and other user input must never be interpolated into shell commands. ## GitHub Boundary -The MVP should use the `gh` CLI for GitHub-specific workflows such as pull -request creation. `bitbygit` should not store GitHub tokens. +The MVP uses the `gh` CLI for GitHub-specific workflows such as pull request +creation on GitHub.com and GitHub Enterprise. `bitbygit` does not store GitHub +tokens. + +GitHub behavior stays behind a typed boundary so direct GitHub API calls or +other providers can be added later without changing the planner contract. + +## Configuration and Policy Boundary + +`bitbygit-core` parses strict typed TOML configuration and derives an effective +policy. Invalid startup configuration fails closed, and runtime reload failures +retain the last valid policy. Protected branches, confirmation levels, disabled +operations, prompt availability, and the default pull request base are applied +to typed plans rather than raw commands. + +## Automation Boundary -GitHub behavior should stay behind an interface that can later support direct -GitHub API calls or other providers without changing the planner contract. +`.github/workflows/ci.yml` checks the workspace and supported source-build +targets. `.github/workflows/release.yml` validates version tags, builds and +smoke-tests supported platform archives, creates checksums, and publishes an +immutable GitHub release. The automation is implemented, but the first real +tagged release remains open in +[#81](https://github.com/cosentinode/bitbygit/issues/81). ## Guardrail Boundary diff --git a/docs/mvp-phases.md b/docs/mvp-phases.md index 2c91752..f265045 100644 --- a/docs/mvp-phases.md +++ b/docs/mvp-phases.md @@ -113,7 +113,7 @@ Success condition: Status: -- completed +- merged Must have: @@ -205,6 +205,10 @@ Success condition: ## Phase 11: GitHub integration and pull request creation +Status: + +- merged as part of [#13](https://github.com/cosentinode/bitbygit/issues/13) + Must have: - detect `gh` availability and auth state @@ -212,8 +216,7 @@ Must have: - confirm base branch - surface PR URL - add `open pr`, `open pull request`, and `commit and push and open pr` prompt - execution after the GitHub provider integration in - [#13](https://github.com/cosentinode/bitbygit/issues/13) + execution Success condition: @@ -221,6 +224,16 @@ Success condition: ## Phase 12: Conflict detection and recovery UX +Status: + +- in progress under [#14](https://github.com/cosentinode/bitbygit/issues/14) +- operation-state detection and typed recovery commands merged in + [#53](https://github.com/cosentinode/bitbygit/issues/53) and + [#54](https://github.com/cosentinode/bitbygit/issues/54) +- recovery policy and TUI actions remain open in + [#55](https://github.com/cosentinode/bitbygit/issues/55) and + [#56](https://github.com/cosentinode/bitbygit/issues/56) + Must have: - merge and rebase in-progress detection @@ -234,6 +247,16 @@ Success condition: ## Phase 13: Config and policy controls +Status: + +- implementation slices merged in + [#59](https://github.com/cosentinode/bitbygit/issues/59), + [#62](https://github.com/cosentinode/bitbygit/issues/62), + [#65](https://github.com/cosentinode/bitbygit/issues/65), + [#67](https://github.com/cosentinode/bitbygit/issues/67), and + [#69](https://github.com/cosentinode/bitbygit/issues/69); umbrella + [#15](https://github.com/cosentinode/bitbygit/issues/15) remains open + Must have: - config file format and location @@ -248,6 +271,16 @@ Success condition: ## Phase 14: Packaging, installation, and release automation +Status: + +- release automation and installation docs merged in + [#57](https://github.com/cosentinode/bitbygit/issues/57), + [#61](https://github.com/cosentinode/bitbygit/issues/61), and + [#64](https://github.com/cosentinode/bitbygit/issues/64) +- the first real release remains open in + [#81](https://github.com/cosentinode/bitbygit/issues/81), and umbrella + [#16](https://github.com/cosentinode/bitbygit/issues/16) remains open + Must have: - release build workflow @@ -261,6 +294,15 @@ Success condition: ## Phase 15: Docs, onboarding, and contributor workflow +Status: + +- in progress under [#17](https://github.com/cosentinode/bitbygit/issues/17); + remaining documentation slices are tracked in + [#60](https://github.com/cosentinode/bitbygit/issues/60), + [#63](https://github.com/cosentinode/bitbygit/issues/63), + [#66](https://github.com/cosentinode/bitbygit/issues/66), and + [#68](https://github.com/cosentinode/bitbygit/issues/68) + Must have: - expanded usage docs diff --git a/docs/repo-layout.md b/docs/repo-layout.md index bca50ec..67e56bb 100644 --- a/docs/repo-layout.md +++ b/docs/repo-layout.md @@ -2,26 +2,46 @@ ```txt bitbygit/ - Cargo.toml - README.md - CONTRIBUTING.md + .github/ + workflows/ + ci.yml + release.yml + + .gitignore CHANGELOG.md + CONTRIBUTING.md + Cargo.lock + Cargo.toml LICENSE + README.md crates/ bitbygit/ + Cargo.toml src/main.rs bitbygit-core/ + Cargo.toml + src/ + config.rs + lib.rs + policy.rs + prompt_parser.rs + + bitbygit-gh/ + Cargo.toml src/lib.rs bitbygit-git/ + Cargo.toml src/lib.rs bitbygit-store/ + Cargo.toml src/lib.rs bitbygit-tui/ + Cargo.toml src/lib.rs docs/ @@ -31,16 +51,16 @@ bitbygit/ command-planner.md configuration.md guardrails.md + installation.md mvp-phases.md repo-layout.md tui-smoke-test.md scripts/ setup-dev.sh - - .github/ - workflows/ - ci.yml + test-installation-docs.ps1 + test-installation-docs.sh + test-release-workflow.sh ``` ## Notes From f9cbd626a176fa19077149727fd3201008223000 Mon Sep 17 00:00:00 2001 From: Adrian Cosentino Date: Fri, 17 Jul 2026 18:56:29 -0400 Subject: [PATCH 2/2] docs: correct phase and planner status --- README.md | 7 ++++--- docs/command-planner.md | 16 ++++++++-------- docs/mvp-phases.md | 3 ++- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 62c3786..c0eb347 100644 --- a/README.md +++ b/README.md @@ -37,9 +37,10 @@ typed merge/rebase recovery commands are merged, while recovery policy and TUI actions remain open in [#55](https://github.com/cosentinode/bitbygit/issues/55) and [#56](https://github.com/cosentinode/bitbygit/issues/56). -Phase 13 configuration and policy slices and Phase 14 release automation and -installation documentation are implemented. Their umbrella issues remain open, -and no release has been published; cutting and validating the first release is +Phase 13 configuration and policy controls are complete. Phase 14 release +automation and installation documentation are implemented, but its umbrella +issue [#16](https://github.com/cosentinode/bitbygit/issues/16) remains open and +no release has been published; cutting and validating the first release is tracked in [#81](https://github.com/cosentinode/bitbygit/issues/81). Phase 15 documentation work is also in progress. See [`docs/mvp-phases.md`](docs/mvp-phases.md) for the issue-linked roadmap. diff --git a/docs/command-planner.md b/docs/command-planner.md index 00392eb..0589021 100644 --- a/docs/command-planner.md +++ b/docs/command-planner.md @@ -42,11 +42,11 @@ Completed Phase 10 parser support includes deterministic, typed plans for: The parser also accepts `pull rebase` as an alias when the meaning is unambiguous. -`open pr`, `open pull request`, and `commit and push and open pr` are Phase 11 -GitHub integration work, not completed Phase 10 behavior. They depend on -[#13](https://github.com/cosentinode/bitbygit/issues/13). When implemented, -those prompts must produce plans that preview provider, remote, head branch, -base branch, title, and target URL before calling a GitHub operation. +Completed Phase 11 GitHub integration in +[#13](https://github.com/cosentinode/bitbygit/issues/13) adds `open pr`, +`open pull request`, and guarded sequences ending in `push and open pr`. These +prompts produce plans that preview provider, remote, head branch, base branch, +title, and target URL before calling a GitHub operation. ## Quoted Strings @@ -80,9 +80,9 @@ Multi-step prompts produce ordered plans. For example, 1. commit staged changes with message `sync docs` 2. push the current branch -If step 1 fails, step 2 must not run. Provider-backed sequences such as -`commit and push and open pr` must wait for the Phase 11 GitHub integration in -[#13](https://github.com/cosentinode/bitbygit/issues/13). +If step 1 fails, step 2 must not run. Phase 11 provider-backed sequences such as +`commit -m "message" and push and open pr` also stop before PR creation when an +earlier step fails. ## Agent Compatibility diff --git a/docs/mvp-phases.md b/docs/mvp-phases.md index f265045..0446061 100644 --- a/docs/mvp-phases.md +++ b/docs/mvp-phases.md @@ -255,7 +255,8 @@ Status: [#65](https://github.com/cosentinode/bitbygit/issues/65), [#67](https://github.com/cosentinode/bitbygit/issues/67), and [#69](https://github.com/cosentinode/bitbygit/issues/69); umbrella - [#15](https://github.com/cosentinode/bitbygit/issues/15) remains open + [#15](https://github.com/cosentinode/bitbygit/issues/15) is closed and Phase + 13 is complete Must have: