Skip to content

feat(boatstack): supply source plans explicitly, remove ambient discovery - #134

Merged
bigboateng merged 1 commit into
mainfrom
boatstack/explicit-source-plan
Jul 23, 2026
Merged

feat(boatstack): supply source plans explicitly, remove ambient discovery#134
bigboateng merged 1 commit into
mainfrom
boatstack/explicit-source-plan

Conversation

@bigboateng

Copy link
Copy Markdown
Contributor

Why

Boatstack retained context for work that was never shipped. auto-plan scanned 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-stopped next-status with an AMBIGUOUS result, 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

  • Removed all directory-based source-plan discovery and the .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-status state machine: dropped the SOURCE_PLAN_READY stage and the source-plan AMBIGUOUS branch. With no started feature, state falls through cleanly to NOT_STARTED → auto-plan regardless of any ambient plan files.
  • Hardened the durability invariant: DiscoverSourcePlan now rejects an out-of-repo --plan up front with a clear error. source_plan_path is 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.
  • Kept intact: the source_plan_path + source_plan_sha256 invariant. The plan must still be a real, present, hash-current file from auto-plan through build; only the discovery mechanism is removed.
  • Updated all guidance/docs surfaces (export preflight & adapter bodies, 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 --plan errors, only an explicit path resolves.
  • TestSourcePlanRejectsOutsideRepoPath — out-of-repo absolute and repo-escaping relative paths are rejected.
  • TestNoIntakeStagingReferenceInProductionSource — no production .go file references .product-loop/intake.
  • TestResolveNextIgnoresAmbientPlanFiles (Go) and test_linked_worktree_ignores_ambient_plan_files (Python) — ambient plan files yield NOT_STARTED.
  • export_test.go / test_export_and_drift_check — bundle omits intake scaffold; auto-plan body requires --plan and mentions no intake/discovery.
  • safety_test.go.product-loop/intake/*.md is no longer a permitted planning-write path.

Verification

  • go build ./..., go vet ./..., full go test ./... — green
  • python3 -m unittest tests.test_product_loop — 18/18 green
  • Added append-only release note: 2026-07-23-explicit-source-plan.md

…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
bigboateng force-pushed the boatstack/explicit-source-plan branch from adfcbd8 to dc7d340 Compare July 23, 2026 14:19
@bigboateng
bigboateng merged commit e4dd098 into main Jul 23, 2026
5 checks passed
@bigboateng
bigboateng deleted the boatstack/explicit-source-plan branch July 23, 2026 14:37
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