feat(boatstack): supply source plans explicitly, remove ambient discovery - #134
Merged
Conversation
…very Boatstack retained context for work that was never shipped: auto-plan scanned .product-loop/intake, .cursor/plans, .claude/plans, and .codex/plans for source plans, so stale plan-mode files accumulated and could block next-status with an ambiguity stop or be silently selected. Remove all directory-based discovery and the intake staging concept. The plan produced in the host conversation is now supplied explicitly via --plan <path>; with no started feature, state is NOT_STARTED -> auto-plan regardless of any ambient plan files. Harden the source_plan_path invariant: reject an out-of-repo --plan up front, since the path is hashed into the plan fingerprint and re-checked through build and an out-of-repo file cannot stay committed and hash-current. The source_plan_path/source_plan_sha256 invariant is otherwise unchanged. Includes conformance tests (Go + Python) guarding against ambient discovery, intake staging, and out-of-repo plan paths ever returning.
bigboateng
force-pushed
the
boatstack/explicit-source-plan
branch
from
July 23, 2026 14:19
adfcbd8 to
dc7d340
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Boatstack retained context for work that was never shipped.
auto-planscanned four directories —.product-loop/intake,.cursor/plans,.claude/plans,.codex/plans— and treated any plan-shaped file it found as a source-plan candidate. Stale plan-mode saves accumulated there and eventually hard-stoppednext-statuswith anAMBIGUOUSresult, or got silently auto-selected. Principle: there should be no Boatstack context for things we did not ship. Unshipped plans are regular docs, not retained Boatstack artifacts.What changed
.product-loop/intake/staging concept. The plan produced in the host conversation is now supplied explicitly via--plan <path>(surfaced to users as/auto-plan <plan-file>), the only supported mechanism.next-statusstate machine: dropped theSOURCE_PLAN_READYstage and the source-planAMBIGUOUSbranch. With no started feature, state falls through cleanly toNOT_STARTED → auto-planregardless of any ambient plan files.DiscoverSourcePlannow rejects an out-of-repo--planup front with a clear error.source_plan_pathis hashed into the plan fingerprint and re-validated through build, and an out-of-repo file cannot stay committed and hash-current — this converts a late build-time drift failure into an immediate, actionable one.source_plan_path+source_plan_sha256invariant. The plan must still be a real, present, hash-current file fromauto-planthroughbuild; only the discovery mechanism is removed.init.go, helper flag help,SKILL.md,references/workflow.md, distribution docs) to require a durable in-repo--plan.Conformance tests (required deliverable)
TestSourcePlanRequiresExplicitPlanAndNeverScansDirectories— seeds all four historically scanned dirs; empty--planerrors, only an explicit path resolves.TestSourcePlanRejectsOutsideRepoPath— out-of-repo absolute and repo-escaping relative paths are rejected.TestNoIntakeStagingReferenceInProductionSource— no production.gofile references.product-loop/intake.TestResolveNextIgnoresAmbientPlanFiles(Go) andtest_linked_worktree_ignores_ambient_plan_files(Python) — ambient plan files yieldNOT_STARTED.export_test.go/test_export_and_drift_check— bundle omits intake scaffold; auto-plan body requires--planand mentions no intake/discovery.safety_test.go—.product-loop/intake/*.mdis no longer a permitted planning-write path.Verification
go build ./...,go vet ./..., fullgo test ./...— greenpython3 -m unittest tests.test_product_loop— 18/18 green2026-07-23-explicit-source-plan.md