diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f0095c..86aca3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ # Contributing -Boatstack is a generated content distribution. Propose changes to workflow semantics, templates, evidence rules, or generated presentation in [Intelligence Flow](https://github.com/operatorstack/intelligence-flow/tree/09388a6c92ece15283a8d0dc2b7edef3d2cc3aba/examples/12-product-engineering-loop). +Boatstack is a generated content distribution. Propose changes to workflow semantics, templates, evidence rules, or generated presentation in [Intelligence Flow](https://github.com/operatorstack/intelligence-flow/tree/f761e7e73e982b0bf5562197519d0b5bc7b937f0/examples/12-product-engineering-loop). The Boatstack repository receives product/runtime changes through a generated pull request. Review the PR's `UPSTREAM.json`, tests, adapter diff, and context-size change; do not hand-edit generated output on `main`. `.github/workflows` is the exception: it is Boatstack's executable control plane, excluded from scheduled projection and changed only through a separate manually reviewed Boatstack PR. diff --git a/README.md b/README.md index 1c48f04..3ef1213 100644 --- a/README.md +++ b/README.md @@ -8,25 +8,22 @@

Build freely. Prove it. Ship.

-## Turn an idea into a change you can review and trust +## Your product development flow—not your coding agent's -Boatstack keeps your plan, decisions, tests, review findings, and known gaps attached to the work from idea to PR. Its safeguards come from failures observed in benchmark and product-repository experiments, with what is verified and what is still being evaluated clearly labeled. +Boatstack gives your repository one path from idea to PR. Use that path from Cursor, Codex, or Claude Code, with the model and specialist skills that fit the work. Plans, decisions, gaps, evidence, and review findings stay with the project. -It works inside Cursor, Codex, and Claude Code. You keep your model, repository, product documents, and way of building. Boatstack makes the important decisions and evidence visible before anyone claims the change is ready. +Change the tool without rebuilding how you ship or redefining what “done” means. Boatstack carries the workflow and saved project state—not an agent's private chat history or a command already in progress. -## Why these steps? - -They come from real coding failures we observed—not guesses. For every safeguard, Boatstack shows what went wrong, what now prevents it, and whether that safeguard has actually been tested. - -| What happened | What Boatstack does | How we check it | -|---|---|---| -| The agent guessed a product decision | It asks, records your answer, and requires approval before code | Approval and drift tests | -| “Tests passed” was used to support claims the tests did not cover | It links each promised outcome to the check that can disprove it | Plan compiler and coverage tests | -| A failed external write led to an invented reset path | It denies high-confidence destructive recovery before execution | Host-hook fixtures; overall benefit still being evaluated | -| A PR lost the decisions and gaps behind the change | It builds a review brief from the approved scope, actual diff, and recorded evidence | PR projection and stale-preview tests | -| A new worktree had the safety hook but not its ignored helper | It restores the verified local runtime from the clone before judging the first command | Real linked-worktree and tamper tests | +

+ Coding agents, models, and specialist skills feed one repository-owned Boatstack flow that produces a reviewed pull request and useful context for the next feature +

-[Read what happened, what is tested, and what remains open](docs/why-these-steps.md). The machine-readable [claim record](docs/public-claims.json) keeps the public wording tied to its sources. +| You change | Boatstack keeps | +|---|---| +| Cursor, Codex, or Claude Code | The same path from planning through PR preparation | +| Lower-cost, general, or frontier model | The same approval, testing, and review requirements | +| React guidance, gstack, Spec Kit, or another skill | Human approval and evidence remain authoritative | +| Session, worktree, or feature | Durable decisions, gaps, evidence, and code state in the repository | ## Install with your coding agent @@ -36,88 +33,74 @@ Copy this into Cursor, Codex, or Claude Code while the repository is open: Install Boatstack in this repository from https://github.com/operatorstack/boatstack. Detect whether you are running in Cursor, Codex, or Claude Code; create or use a chore/install-boatstack branch; run the official installer for this operating system; default to core unless I request gstack or Spec Kit; keep all portable host adapters; run Boatstack doctor; show me the generated files and installation diff; and prepare the installation PR without merging it or starting product work. ``` -Install Boatstack in its own infrastructure PR and merge that PR before starting a feature. This keeps one-time repository setup out of later product diffs. - -Install once per Git clone. Linked Git worktrees reuse the verified runtime and restore their ignored local helper automatically on first use. +Install Boatstack in its own infrastructure PR and merge it before starting a feature. Install once per Git clone; linked worktrees reuse the verified runtime and restore their ignored local helper automatically. ## Start with two moves 1. Create and save a plan in your coding tool's Plan mode. 2. Run `/auto-plan`. -That is all you need to learn up front. Boatstack shows you one next action at a time through approval, building, tests, review, and PR preparation. +That is all you need to learn up front. Boatstack shows one next action at a time through approval, building, tests, review, and PR preparation. -> The diagram below shows what Boatstack guides—not a checklist you need to memorize. +When you are ready, that guidance moves through `/plan-gate` → `/build` → `/test-gate` → `/review-gate` → `/ship-gate`. -

- One feature moves from idea through planning, approval, building, tests, review, and pull request; its retained plans, decisions, gaps, evidence, and code state combine with the next idea to create the next plan -

- -## Use the model that fits your budget - -Boatstack applies the same planning, approval, testing, review, and shipping requirements whichever coding model you choose. Lower-cost models remain an option without lowering the standard required to call the work complete. +> The diagram shows what Boatstack guides—not a checklist you need to memorize.

- Lower-cost, general, and frontier models enter the same Boatstack completion standard and produce a reviewed change with evidence + One feature moves from idea through planning, approval, building, tests, review, and pull request; its retained plans, decisions, gaps, evidence, and code state combine with the next idea to create the next plan

-> This does not mean every model performs equally. Boatstack makes the process less dependent on the model catching every mistake by itself. - -> **Designed for model flexibility · Quality uplift evaluation in progress** +## What Boatstack guides | Without Boatstack | With Boatstack | |---|---| -| Quality depends heavily on the model catching every mistake itself | Planning, approval, tests, and review provide additional checks | -| Switching to a lower-cost model may also change the development process | The completion standard stays consistent across models | -| Important context disappears between features | Decisions, gaps, evidence, and code state inform the next feature | - -- **Verified:** Boatstack uses the same completion requirements regardless of model, provider, or price. -- **Observed:** benchmark runs exposed failures in protocol handling, context, verification, and recovery—not only model capability. -- **Being evaluated:** whether this measurably improves product quality or cost when using lower-cost models. +| The agent guesses an important product decision | It asks, records your answer, and waits for approval | +| “Tests passed” is treated as proof of everything | Each promised outcome names the check that can disprove it | +| A failed external operation leads to a risky reset | High-confidence destructive recovery is stopped before execution | +| The PR loses the reasoning behind the work | Decisions, evidence, gaps, rollout, and rollback stay attached | +| Every feature starts from an empty conversation | Useful state from the previous feature informs the next plan | -[See the evidence and paired evaluation design](docs/why-these-steps.md#model-choice-and-budget). +You remain free to build however the work requires. Boatstack governs claims of approval, completion, review, and shipping—not the implementation technique. -## From idea to PR +## Use the tools that fit the work -1. **Explore the idea in your host's Plan mode.** Save the plan, then run `/auto-plan`. Boatstack finds relevant repository facts and asks only for decisions the code cannot answer. -2. **Review what will be built.** Run `/plan-gate`. Correct the scope or reply `approve`; approval alone does not change product code. -3. **Build in the way that suits the work.** Enter the host's execution mode and run `/build`. Boatstack activates the exact approved plan before the first product edit. -4. **Prove, review, and prepare the PR.** Run `/test-gate`, `/review-gate`, and `/ship-gate`. Failed evidence returns to revision. Opening or updating the PR still requires your confirmation. +- **Cursor, Codex, and Claude Code:** portable repository adapters expose the same workflow. +- **Models:** choose a lower-cost, general, or frontier model without silently changing the completion standard. +- **Skills:** add specialist guidance such as React best practices. Boatstack can also use optional gstack and GitHub Spec Kit outputs. -[Install and ship your first feature](docs/getting-started.md) +In technical terms, Boatstack is a repository-local software-delivery harness for AI coding agents. Skills contribute expertise; models perform work; Boatstack keeps the product-development path and evidence contract consistent. -## A small example +> **Designed for model flexibility · Quality uplift evaluation in progress** -A request said, “Add a password reset button.” The repository used passwordless sign-in and had no password-reset route. Building the request literally would have created a button for a feature that did not exist. +- **Verified:** the same completion requirements apply regardless of model, provider, or price. +- **Observed:** benchmark runs exposed failures in protocol handling, context, verification, and recovery—not only model capability. +- **Being evaluated:** whether this improves product quality, cost, or delivery time with lower-cost models. -Boatstack surfaced the conflict and asked whether to add passwords, clarify email-code recovery, or choose another behavior. The human selected dual authentication. Later, review caught a recovery screen that trusted any signed-in session instead of a real recovery event. The change returned for a local repair before the PR was prepared. +This does not mean every model performs equally. [See the evidence and paired evaluation design](docs/why-these-steps.md#model-choice-and-budget). -[Follow the complete sanitized walkthrough](docs/account-recovery-walkthrough.md) +## Why these steps? -## What Boatstack helps with +They come from coding failures observed in benchmark and product-repository work—not guesses. Every safeguard links what happened, what Boatstack now does, and whether that behavior has actually been tested. -| Without Boatstack | With Boatstack | -|---|---| -| The agent guesses an important product decision | It asks and records your answer before building | -| “Tests passed” is treated as proof of everything | Each promised outcome shows how it was checked | -| A failed operation leads to a risky reset | Destructive recovery is stopped before execution | -| The PR loses the reasoning behind the work | Decisions, evidence, gaps, rollout, and rollback stay attached | +| What happened | What Boatstack does | Current evidence | +|---|---|---| +| The agent guessed a product decision | Records a human answer and approval before code | Approval and drift tests | +| A passing test was used to support a broader claim | Links each promised outcome to its validation | Coverage and plan-compiler tests | +| A failed write led to an invented reset path | Denies high-confidence destructive recovery | Hook behavior verified; outcome benefit still being evaluated | +| A PR lost decisions and accepted gaps | Builds a review brief from scope, diff, and evidence | Projection and stale-preview tests | +| A worktree had the hook but not its ignored helper | Restores the verified local runtime before judging the command | Linked-worktree and tamper tests | -Boatstack does not replace your product context or force a new documentation system. Existing briefs, roadmaps, ADRs, gaps, code, and repository rules remain the source. It creates a reviewable working slice and keeps links back to that source. +[Read what happened, what is tested, and what remains open](docs/why-these-steps.md). The [claim record](docs/public-claims.json) keeps every material statement tied to its sources. -## Works with the tools you already use +## A small example -- **Cursor, Codex, and Claude Code:** thin repository-local adapters expose the same workflow. -- **gstack:** optional product, design, engineering, and review lenses can challenge the plan. -- **GitHub Spec Kit:** optional specification artifacts can feed the plan and validation contract. +A request said, “Add a password reset button,” but the product used passwordless sign-in and had no reset route. Boatstack surfaced the conflict instead of building the button literally. The human chose dual authentication; later, review caught an unsafe recovery-session assumption and returned the change for repair before PR preparation. -These tools may propose content. They do not approve their own proposal or bypass Boatstack's evidence checks. +[Follow the sanitized walkthrough](docs/account-recovery-walkthrough.md) or [ship your first feature](docs/getting-started.md). ## Updates stay out of product work -After a PR is published, Boatstack can quietly report that a new stable release exists. It does not change the feature branch. From a clean default branch, `/boatstack-update` prepares a versioned infrastructure branch, shows the exact diff, and waits for `open update PR` before changing GitHub. It never merges the update. - -[See how updates remain visible and separate](docs/getting-started.md#keeping-boatstack-current). +After a PR is published, Boatstack may report a new stable release without changing the feature branch. `/boatstack-update` prepares a separate infrastructure branch, shows the diff, and waits for `open update PR`. It never merges the update.
Install manually @@ -136,7 +119,7 @@ git switch -c chore/install-boatstack irm https://raw.githubusercontent.com/operatorstack/boatstack/main/install.ps1 | iex ``` -The installer previews generated paths, verifies the platform helper, offers optional integrations, runs a smoke check, and prints the exact files to commit. Boatstack core requires no Python, Node, Go, or package manager. +The installer previews generated paths, verifies the platform helper, offers optional integrations, runs a smoke check, and prints the files to commit. Boatstack core requires no Python, Node, Go, or package manager.
@@ -144,14 +127,12 @@ The installer previews generated paths, verifies the platform helper, offers opt **Start:** [Getting started](docs/getting-started.md) · [Generated files](docs/generated-files.md) · [Troubleshooting](docs/troubleshooting.md) -**Operate safely:** [Safety](docs/safety.md) · [Validation and evidence](docs/validation-and-evidence.md) · [Why these steps](docs/why-these-steps.md) - -**Understand the research:** [Evidence-engineered coding](docs/evidence-engineered-coding.md) · [Research and design](docs/research-and-design.md) · [Benchmark corpus audit](docs/benchmark-corpus-audit.md) +**Inspect:** [Why these steps](docs/why-these-steps.md) · [Validation and evidence](docs/validation-and-evidence.md) · [Safety](docs/safety.md) -**Contribute:** [Public-surface contract](docs/public-surface.md) · [Contributing](CONTRIBUTING.md) +**Go deeper:** [Evidence-engineered coding](docs/evidence-engineered-coding.md) · [Research and design](docs/research-and-design.md) · [Contributing](CONTRIBUTING.md) ## Project status -Boatstack is an open-source research prototype. Its workflow and enforcement behavior are covered by automated tests. The experimental record explains why the safeguards exist, but it does not yet prove that Boatstack improves product-delivery success. A paired feature-building benchmark—same model, task, and budget with and without Boatstack—is the next evaluation. +Boatstack is an open-source research prototype. Its workflow and enforcement behavior are tested, but the current record does not prove improved product-delivery success. A paired feature-building benchmark—same model, task, and budget with and without Boatstack—is the next evaluation. -The exact Intelligence Flow source and generated file hashes for this checkout are recorded in [`UPSTREAM.json`](UPSTREAM.json). +Exact Intelligence Flow provenance and generated file hashes are recorded in [`UPSTREAM.json`](UPSTREAM.json). diff --git a/UPSTREAM.json b/UPSTREAM.json index cb5084f..858caa0 100644 --- a/UPSTREAM.json +++ b/UPSTREAM.json @@ -12,11 +12,11 @@ }, "files": { ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957", - "CONTRIBUTING.md": "fbc9acf97597aaad553fc0a1b78af6ba70b92eb4174c61d46718595f765765bd", - "README.md": "9e82e07dd95021ea9cb307e0e13a14747852be051d8a9b1261db15b24b919879", + "CONTRIBUTING.md": "845be08f967dc10b776ffd24ab05cabbd8c4945dc331f9fca5c8047b94ce08ce", + "README.md": "fe52800af55f9867f3a7dfeafd17e2ebc3cca6c19a8f787c7eaf6d27f25028fc", "assets/boatstack-journey.svg": "c1f7fe2741f5e9ca66bb3fe9b103e6364ba5acbca8b7a8054768ffd85cf325ea", "assets/boatstack-mark.svg": "c46e935f06fcfde3b37abfd579c1963b765b2337a0fa993f9538c9b652297e39", - "assets/boatstack-model-choice.svg": "979952c2fc6220d41426f9072186fca000fb3f388a4e775cc09cc1e830ebdde4", + "assets/boatstack-portability.svg": "38c61b51959ebf5378b1857cdaacfae843a5ffc35350685fc6d1d2b8b9e165a3", "boatstack/SKILL.md": "5c37ec90eb8c3eae60f435f5d62afd1dc826f8bca6916726588379bcb99f3f58", "boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1", "boatstack/assets/templates/adr.md": "c577a3c1c1319061f61deb053597e6e853657022185fe28b8f733327e2a78565", @@ -33,7 +33,7 @@ "boatstack/atomic_windows.go": "cefd775cbe7e7c3bd8a3f5673b11cdd784c6d3ebd6de7dcb8f39406b0bee511f", "boatstack/cmd/boatstack-helper/main.go": "32d73f6ac8e87cbe7ebd8ee74e63dfe6f0b8b35da1d3200e23dcf011be9c19ea", "boatstack/export.go": "c53c5ec83dcea392d2e360c6819202b5f7cf9b3ae64510087bd627c4aaee82e3", - "boatstack/export_test.go": "f95be9c458645e9b150f25921a0452c9e10e6a94809567ee5ddbc8e833e4f040", + "boatstack/export_test.go": "da9b04e3e03c10f4095ac339d303c1699df3a0b3d68158b09746769c04031f5b", "boatstack/go.mod": "57c377eccea51372d6664de4169e2ca45806b046f7e8a98a1e35a9eb454b4b8d", "boatstack/hooks.go": "aed9cee6d3e3fb42e5e98288eade420793a07a4b071e78a613fc888c74521406", "boatstack/hooks_test.go": "a5298b7f46709bce617913085fe3b597a4bb4f730a5b5b51f459be85adbefcbb", @@ -64,22 +64,22 @@ "docs/account-recovery-walkthrough.md": "acd3558a95f48004f18a0590670de496e1cc9f0cd1d187f924615497f57e1d6f", "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6", "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79", - "docs/evidence-engineered-coding.md": "7240e06a5f1ee2fc6cecf2777f6438a5b7ebdaae96fe8f7ef626886dcab6f666", + "docs/evidence-engineered-coding.md": "4642e600fc527d1583dc13b21f8b132d6222b6fc0bc0f1c2cab8f283f3aab766", "docs/generated-files.md": "33ea0799eb01af6e035fb1322c6a58c39ecc5dcc95169ce0adbd7933a0bfbee1", "docs/getting-started.md": "9741947c4b072c0838d0ee3a578215d5fac1d72cf5e73075136d0a9c95db2bbb", - "docs/public-claims.json": "a011f7fc31dc656428f3544b61e34ebef2806f376635151cb44571b31e5422f7", - "docs/public-surface.md": "53d741f04b2928a6ee8c006d647a6d675a215e863412e5862cd67d48433bff76", + "docs/public-claims.json": "b67aad3c4aa25bc31caad7d7a910e0632a79d1968dbb07841850f6e92c51610c", + "docs/public-surface.md": "422696611bdd52fbac2baf6723a277fa8c451601a9f66774bde1529efdc2abab", "docs/research-and-design.md": "d65c66e323037bda5d45aacef5d48afa6bf93da55901378891d235aca3a5684f", "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6", "docs/troubleshooting.md": "27e73986a30df5d011b33c3d4701ce30610359e32c496c50d1b783ef5adf5c69", "docs/validation-and-evidence.md": "a9fe9274f3dc22b152094a307feda5d8c3ab099755100aef77bda13024cc3166", - "docs/why-these-steps.md": "e8f8918ad42b74314cf84974f6f4a7b4e79af4fc4571b6df7554e3c95f9e0da7", + "docs/why-these-steps.md": "afacdcd78b546c50a0b2a268233f8f86548024298196dcfc7b573773fd5f23e7", "examples/diagram-json/README.md": "061b583180e43bbd26618bbd9d3d79af4b75d7c8f37c66475640745a97328fbc", "examples/diagram-json/approval.md": "bc421a825349923512d5cb0ce489310d3a4d7cbac35e661a693b4a32eec263d1", "examples/diagram-json/compiled/evidence.md": "1ba1c989ade070a8ef9a508fbd788d100d7292f2dbacbb2bce895468019f619d", "examples/diagram-json/compiled/tasks.json": "f040696f1f8bcedc4a8ed9816a61a49edbda970ec0cc3b28175ba37b73bbc896", "examples/diagram-json/compiled/test-matrix.json": "6c6895c509271e4337f3c91d9f62ee3a2b34e768e78513784cb012506a328ecf", - "examples/diagram-json/plan.lock.json": "fe627c500ffccf639c113ec7eda6e1d20b39aaf643672ca7721e518b5d8f6ebe", + "examples/diagram-json/plan.lock.json": "9dc2698c705f33f4806a0e2b8dca748d0b2eed18b062b10243bff087ae97672a", "examples/diagram-json/plan.md": "3ad35cc3cbe48306e7ee401bd9e9047d25e46c8a6fe9679aa1b3f5e96ceea292", "examples/diagram-json/questions.md": "1a0050041cac0a8d53e6ebfe04cbec4a298cdc8c50efeeb6fa15aeb663c5ec76", "examples/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed", @@ -92,7 +92,7 @@ "generator": "operatorstack/intelligence-flow:boatstack-distribution", "schema_version": 1, "source": { - "commit": "09388a6c92ece15283a8d0dc2b7edef3d2cc3aba", + "commit": "f761e7e73e982b0bf5562197519d0b5bc7b937f0", "path": "examples/12-product-engineering-loop", "repository": "operatorstack/intelligence-flow" } diff --git a/assets/boatstack-model-choice.svg b/assets/boatstack-model-choice.svg deleted file mode 100644 index b5f91f3..0000000 --- a/assets/boatstack-model-choice.svg +++ /dev/null @@ -1,36 +0,0 @@ - - One Boatstack completion standard across model choices - Lower-cost, general, and frontier coding models converge on Boatstack's shared approval, testing, review, and evidence requirements before producing a reviewed change with evidence. - - - - - - CHOOSE THE MODEL THAT FITS THE WORK - Lower-cost model - General model - Frontier model - - - - - - - - - BOATSTACK - one completion standard - approval · tests · review · shipping - - - - - Reviewed change - with decisions, gaps, and evidence - - Same standard does not mean every model performs equally. - diff --git a/assets/boatstack-portability.svg b/assets/boatstack-portability.svg new file mode 100644 index 0000000..14d56f9 --- /dev/null +++ b/assets/boatstack-portability.svg @@ -0,0 +1,63 @@ + + Your product development flow stays with the repository + Cursor, Codex, Claude Code, different model tiers, and specialist skills feed one repository-owned Boatstack flow. The flow retains plans, decisions, gaps, evidence, and review findings, producing a reviewed pull request and useful context for the next feature. + + + + + + Change the tools. Keep the flow. + The repository owns the working state and the standard for “done.” + + + + CODING AGENT + Cursor · Codex · Claude Code + + + + MODEL + Lower-cost · General · Frontier + + + + SPECIALIST SKILLS + React · gstack · Spec Kit + and other repository skills + + + + + + + + + + + + YOUR REPOSITORY + BOATSTACK + one product-development flow + + + plan · decisions · gaps + evidence · review + + The saved state stays with the project. + + + + + + WHAT LEAVES THE FLOW + Reviewed PR + + plus useful context + for the next feature + + + diff --git a/boatstack/export_test.go b/boatstack/export_test.go index 211636c..99389a0 100644 --- a/boatstack/export_test.go +++ b/boatstack/export_test.go @@ -178,6 +178,54 @@ func TestExportAndDriftCheck(t *testing.T) { } } +func TestPortableHostAdaptersShareWorkflowAndArtifactContract(t *testing.T) { + config := testConfig() + raw, err := MarshalJSON(config) + if err != nil { + t.Fatal(err) + } + bundle, err := BuildExportBundle(".boatstack-project.json", config, raw, "boatstack") + if err != nil { + t.Fatal(err) + } + + workflow := string(bundle.Files[".product-loop/workflow.md"]) + artifacts := string(bundle.Files[".product-loop/artifacts.md"]) + for _, expected := range []string{"auto-plan", "plan-gate", "build", "test-gate", "review-gate", "ship-gate", "retro"} { + if !strings.Contains(workflow, expected) { + t.Fatalf("canonical portable workflow is missing %q", expected) + } + if _, exists := bundle.Files[".cursor/commands/"+expected+".md"]; !exists { + t.Fatalf("Cursor does not expose portable operation %q", expected) + } + } + for _, expected := range []string{"source plan", "plan.md", "approval.md", "evidence", "gaps", "review", "pr.md"} { + if !strings.Contains(strings.ToLower(artifacts), strings.ToLower(expected)) { + t.Fatalf("repository artifact contract is missing %q", expected) + } + } + + hostSurfaces := map[string]string{ + "cursor": string(bundle.Files[".cursor/rules/boatstack.mdc"]), + "claude": string(bundle.Files[".claude/skills/boatstack/SKILL.md"]), + "codex": string(bundle.Files[".agents/skills/boatstack/SKILL.md"]), + } + for host, surface := range hostSurfaces { + for _, expected := range []string{".product-loop/project.json", ".product-loop/workflow.md"} { + if !strings.Contains(surface, expected) { + t.Fatalf("%s adapter does not reference shared repository contract %q", host, expected) + } + } + } + for _, host := range []string{"claude", "codex"} { + for _, operation := range []string{"auto-plan", "plan-gate", "build", "test-gate", "review-gate", "ship-gate", "boatstack-update", "retro"} { + if !strings.Contains(hostSurfaces[host], operation) { + t.Fatalf("%s adapter does not expose portable operation %q", host, operation) + } + } + } +} + func TestExportRefusesUserOwnedCollision(t *testing.T) { repo := t.TempDir() path := filepath.Join(repo, ".cursor", "rules", "boatstack.mdc") diff --git a/docs/evidence-engineered-coding.md b/docs/evidence-engineered-coding.md index ee2f9e4..8d6c2ec 100644 --- a/docs/evidence-engineered-coding.md +++ b/docs/evidence-engineered-coding.md @@ -140,6 +140,6 @@ Delivery and system improvement also remain separate. A failed task may suggest ## What is evidence-backed -The current moves were derived from the Intelligence Flow benchmark corpus and product-repository studies. The generated source commit is [`09388a6c92ece15283a8d0dc2b7edef3d2cc3aba`](https://github.com/operatorstack/intelligence-flow/tree/09388a6c92ece15283a8d0dc2b7edef3d2cc3aba/examples/12-product-engineering-loop). +The current moves were derived from the Intelligence Flow benchmark corpus and product-repository studies. The generated source commit is [`f761e7e73e982b0bf5562197519d0b5bc7b937f0`](https://github.com/operatorstack/intelligence-flow/tree/f761e7e73e982b0bf5562197519d0b5bc7b937f0/examples/12-product-engineering-loop). The evidence supports specific failure mechanisms and guardrails. It does not establish that Boatstack is optimal, that control-theory notation proves software quality, or that one workflow dominates every team. Those are evaluation questions, so the distribution preserves measurements, provenance, gaps, and negative results. diff --git a/docs/public-claims.json b/docs/public-claims.json index 80ba968..b01a8ea 100644 --- a/docs/public-claims.json +++ b/docs/public-claims.json @@ -1,8 +1,19 @@ { "schema_version": 1, - "source_commit": "09388a6c92ece15283a8d0dc2b7edef3d2cc3aba", + "source_commit": "f761e7e73e982b0bf5562197519d0b5bc7b937f0", "statuses": ["verified", "observed", "still_being_evaluated"], "claims": [ + { + "id": "portable-product-flow", + "public_claim": "Boatstack exposes one product-development workflow across Cursor, Codex, and Claude Code while keeping its durable planning, decision, gap, evidence, and review state in the repository.", + "status": "verified", + "originating_observation": "Coding-host configuration, model choice, and specialist skills otherwise become separate places where a product-development process and its working state can fragment.", + "safeguard": "Portable host adapters project one workflow contract while canonical feature artifacts remain repository-owned and model-neutral.", + "readable_evidence": "why-these-steps.md#portable-workflow-and-state", + "implementation": ["../boatstack/export.go", "../boatstack/references/artifacts.md", "../boatstack/references/workflow.md"], + "verification": ["../boatstack/export_test.go"], + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" + }, { "id": "human-decisions", "public_claim": "Boatstack asks for material product decisions, records the human answer, and requires approval before build.", @@ -12,7 +23,7 @@ "readable_evidence": "why-these-steps.md#human-decisions", "implementation": ["../boatstack/references/workflow.md", "../boatstack/plan.go"], "verification": ["../boatstack/plan_test.go", "../boatstack/planning_test.go"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "validation-provenance", @@ -23,7 +34,7 @@ "readable_evidence": "why-these-steps.md#validation-provenance", "implementation": ["validation-and-evidence.md", "../boatstack/plan.go"], "verification": ["../boatstack/plan_test.go"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "irreversible-operations", @@ -35,7 +46,7 @@ "readable_evidence": "why-these-steps.md#irreversible-operations", "implementation": ["safety.md", "../boatstack/safety.go", "../boatstack/hooks.go"], "verification": ["../boatstack/safety_test.go", "../boatstack/hooks_test.go"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "reviewer-ready-pr", @@ -46,7 +57,7 @@ "readable_evidence": "why-these-steps.md#reviewer-ready-pr", "implementation": ["../boatstack/pr.go", "getting-started.md"], "verification": ["../boatstack/pr_test.go"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "model-neutral-contract", @@ -57,7 +68,7 @@ "readable_evidence": "why-these-steps.md#model-choice-and-budget", "implementation": ["research-and-design.md", "../boatstack/references/workflow.md"], "verification": ["../boatstack/export_test.go", "../boatstack/planning_test.go"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "cross-model-failures", @@ -68,7 +79,7 @@ "readable_evidence": "why-these-steps.md#model-choice-and-budget", "implementation": ["research-and-design.md"], "verification": ["benchmark-corpus-audit.md", "benchmark-submission-audit.md"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "lower-cost-outcomes", @@ -79,7 +90,7 @@ "readable_evidence": "why-these-steps.md#model-choice-and-budget", "implementation": ["research-and-design.md"], "verification": ["benchmark-corpus-audit.md", "benchmark-submission-audit.md"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "git-worktree-activation", @@ -90,7 +101,7 @@ "readable_evidence": "why-these-steps.md#git-worktree-activation", "implementation": ["../boatstack/runtime_cache.go", "../boatstack/hooks.go"], "verification": ["../boatstack/runtime_cache_test.go", "../boatstack/hooks_test.go"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" }, { "id": "visible-updates", @@ -101,7 +112,7 @@ "readable_evidence": "why-these-steps.md#visible-updates", "implementation": ["../boatstack/update.go", "../boatstack/init.go"], "verification": ["../boatstack/update_test.go", "../boatstack/init_test.go", "../boatstack/export_test.go"], - "last_verified_version": "source:09388a6c92ece15283a8d0dc2b7edef3d2cc3aba" + "last_verified_version": "source:f761e7e73e982b0bf5562197519d0b5bc7b937f0" } ] } diff --git a/docs/public-surface.md b/docs/public-surface.md index 2d11809..206d6cb 100644 --- a/docs/public-surface.md +++ b/docs/public-surface.md @@ -9,10 +9,11 @@ Boatstack's README is a product-builder homepage, not the complete manual. Publi The homepage must answer, in order: 1. What will Boatstack help me achieve? -2. Why do these steps exist? -3. How do I install it? +2. What remains portable when I change tools, models, or skills? +3. How do I install and start it? 4. What will using it feel like? -5. Where can I inspect the details? +5. Why do these steps exist? +6. Where can I inspect the details? Keep the README under 1,500 words. Put equations, schemas, internal helper commands, long artifact examples, and benchmark methodology in linked technical documents. @@ -33,6 +34,7 @@ When Huashu Design is installed, use it to review a public-surface change. The r - preserve the stacked-node mark, ink `#0F172A`, and electric blue `#2563EB`; - design from real Boatstack content rather than a generic AI landing-page pattern; - use one dominant product journey and progressive disclosure; +- keep portability diagrams subordinate to the product journey and focused on real hosts, models, skills, and repository state; - add no invented statistics, testimonials, decorative icons, or unsupported badges; - keep diagrams accessible, readable in light and dark themes, and useful without decoration; - render and inspect changed SVGs or public pages before approval. diff --git a/docs/why-these-steps.md b/docs/why-these-steps.md index 1d29ee4..f74afda 100644 --- a/docs/why-these-steps.md +++ b/docs/why-these-steps.md @@ -13,6 +13,18 @@ Boatstack was not designed by writing a long list of ideal engineering practices Those labels prevent an implementation test from being presented as proof that the whole product improves engineering performance. +## Portable workflow and state + +**What happened.** Coding hosts, model choices, and specialist skills can each become a separate place where the development process fragments. Plans and decisions that exist only in one agent conversation are difficult for another supported host—or the next feature—to inspect and continue. + +**What Boatstack does.** Cursor, Codex, and Claude Code receive adapters for the same path from planning through PR preparation. The durable state behind that path—source plan, specification, human answers, accepted gaps, approval, evidence, and review findings—lives in the repository instead of belonging to one model or chat session. Models and skills may contribute work without changing the completion requirements. + +**How we check it.** Export tests verify that all supported host adapters expose the same lifecycle and reference the same canonical repository artifact contract. Projection tests verify that the public workflow, adapters, and artifact definitions are generated from one upstream source. + +**What it does not mean.** Boatstack does not copy private chat history or move a command already in progress between agents. Portability covers the workflow and saved repository state available at the next transition. + +**Status:** cross-host workflow and artifact portability verified in automated tests. The effect on product-delivery outcomes remains part of the planned paired evaluation. + ## Human decisions **What happened.** A product request asked for a password-reset button in a passwordless product. A literal implementation would have created an interface for a capability that did not exist. Repository inspection could discover the conflict, but only a human could choose whether to introduce passwords or preserve the existing model. diff --git a/examples/diagram-json/plan.lock.json b/examples/diagram-json/plan.lock.json index 26a8953..a28473c 100644 --- a/examples/diagram-json/plan.lock.json +++ b/examples/diagram-json/plan.lock.json @@ -6,7 +6,7 @@ "plan_path": "examples/diagram-json/plan.md", "plan_sha256": "3ad35cc3cbe48306e7ee401bd9e9047d25e46c8a6fe9679aa1b3f5e96ceea292", "schema_version": 1, - "source_commit": "09388a6c92ece15283a8d0dc2b7edef3d2cc3aba", + "source_commit": "f761e7e73e982b0bf5562197519d0b5bc7b937f0", "source_plan_path": "examples/diagram-json/source-plan.md", "source_plan_sha256": "e10593ddaa7522ab80cc991d0a09399257139799e37f737794cd49d68a39985b", "spec_path": "examples/diagram-json/spec.md",