diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d035f9..625c54d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,14 @@ # 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/593a10ce11eee415a06a6383cc9e4b91b58aace6/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/1a67b309b53d52011909a95b291151afaf575ce7/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. Repository-specific examples and outcome reports can be proposed upstream as new evidence. A failure becomes a durable move only after its mechanism and non-regression gate are documented. + +## Public-facing changes + +Any user-facing upgrade must state the user problem, supporting observation or requirement, current evidence status, and the README or guide it changes. If no public document changes, explain why the behavior is internal. Material public claims must appear in `docs/public-claims.json` and link to a readable explanation. + +Use Huashu Design for README and beginner-guide review when it is installed. The portable requirements remain in [the public-surface contract](docs/public-surface.md): plain outcomes first, one dominant product journey, progressive disclosure, accessible assets, no invented proof, and explicit separation between verified behavior and outcomes still being evaluated. diff --git a/README.md b/README.md index 742612c..ce32c57 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - +

Boatstack stacked-node B mark @@ -8,321 +8,108 @@

Build freely. Prove it. Ship.

-Boatstack is **evidence-engineered coding**: a model-neutral coding node that turns product intent and repository context into an explicitly approved, tested, reviewable change. It does not prescribe the model, implementation technique, tools, or document structure. It governs what may be claimed, approved, or shipped. Its behavior is generated from [Intelligence Flow at `593a10ce11eee415a06a6383cc9e4b91b58aace6`](https://github.com/operatorstack/intelligence-flow/tree/593a10ce11eee415a06a6383cc9e4b91b58aace6/examples/12-product-engineering-loop). +## Turn an idea into a change you can review and trust -> **You are free in how you build. Only claims of completion require evidence.** +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. -It is not a claim that a longer prompt writes better code. Here is what the node actually makes observable. +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. -## Install in a repository +## Why these steps? -Install Boatstack on a clean infrastructure branch and merge that PR before starting product work. This keeps the one-time host adapters and repository policy separate from every feature diff. +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. -### Install with your coding agent - -Copy and paste this into Cursor, Codex, or Claude Code: - -```text -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. -``` - -Active-host detection changes the guidance shown after installation; Boatstack keeps every thin host adapter so the repository remains portable across developers and coding environments. - -### Install manually - -macOS or Linux: - -```bash -git switch -c chore/install-boatstack -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/operatorstack/boatstack/main/install.sh)" -``` - -Windows PowerShell: - -```powershell -git switch -c chore/install-boatstack -irm https://raw.githubusercontent.com/operatorstack/boatstack/main/install.ps1 | iex -``` - -The installer previews the generated paths, verifies the platform helper, asks about optional gstack and Spec Kit integrations, runs a smoke check, and prints the exact infrastructure commit commands. Boatstack core requires no Python, Node, Go, or package manager. The helper is repository-local and ignored; the adapters and policy are committed. - -**New here?** [Install and ship your first feature](docs/getting-started.md) · [Safety boundary](docs/safety.md) · [Understand generated files](docs/generated-files.md) · [Troubleshoot](docs/troubleshooting.md) · [See the real account-recovery walkthrough](docs/account-recovery-walkthrough.md) - -**Go deeper:** [Validation and evidence](docs/validation-and-evidence.md) · [gstack and Spec Kit](#use-boatstack-with-gstack-and-github-spec-kit) · [Evidence-engineered coding](docs/evidence-engineered-coding.md) - -```text -idea -> Plan mode -> /auto-plan -> questions -> /plan-gate - -> approve -> Build -> /build -> /test-gate - -> /review-gate -> /ship-gate -> preview -> confirm -> PR -``` - -At ship, Boatstack compiles the approved intent, actual committed diff, evidence, decisions, gaps, rollout, and rollback into a reviewer-ready title and body. It shows the exact preview first; GitHub changes only after `open PR` or `update PR`. For an existing branch, simply ask **“Use Boatstack to improve this PR.”** There is no extra `/pr-brief` command, and missing workflow evidence is labeled `NOT_VERIFIED` rather than invented. - -## Irreversible operations stop before execution - -Boatstack installs fail-closed project hooks for Cursor, Codex, and Claude. High-confidence database resets and drops, broad recursive deletion, destructive Git history changes, cloud-resource destruction, and backup removal are always denied—across ordinary agent tool calls, not only Boatstack commands. There is no in-session bypass. After an external-write failure, the agent must preserve state, diagnose read-only, and use only a proven transactional retry or fix-forward repair. +| 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 | -The hooks are defense in depth, not a security sandbox. Keep least-privilege credentials, service-side destructive approval, and backups. See [Safety boundary](docs/safety.md) for the exact policy, host limitations, and evaluation status. +[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. -## Plan first, then auto-plan +## Install with your coding agent -Start with ordinary product intent **inside Cursor, Codex, or Claude Plan mode**: +Copy this into Cursor, Codex, or Claude Code while the repository is open: ```text -Add machine-readable JSON output to the diagram printer while preserving the current text output. +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. ``` -Save the host's plan. When the host exposes the active plan path, Boatstack reads it from conversation context; otherwise save it under `.product-loop/intake/`. Then run: +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. -```text -/auto-plan -``` +

+ Boatstack journey from idea through planning, approval, building, proof, review, and pull request, with failed checks returning to revision +

-`/auto-plan` must validate a real, non-empty source plan before it reads repository context. Its fallback searches only bounded Plan-mode locations and succeeds for exactly one file. When discovery finds none or several, it returns `BLOCKED` and asks for the intended path; it never guesses from recency or creates the missing plan itself. It then inspects the smallest relevant code boundary and makes contract choices visible: +## From idea to PR -```text -Q1 Public API? sibling serializeFlowGraph() | change printFlowGraph() -Q2 Stability? versioned schema | internal object dump -Q3 Run data? compact overlay | entire execution trace -``` +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. -The accepted answers become observable criteria and tasks—not hidden assumptions. They live in the single marked structured block inside human-readable `plan.md`: - -```json -{ - "source_plan_path": "source-plan.md", - "spec_path": "feature-spec.md", - "blocking_questions": [], - "acceptance_criteria": [ - {"id": "AC-1", "text": "Return parseable schema-versioned graph JSON."}, - {"id": "AC-4", "text": "Keep existing ASCII output byte-compatible."} - ], - "tasks": [{ - "id": "T-3", - "acceptance_criteria": ["AC-1", "AC-4"], - "validation": [ - { - "criteria": ["AC-1"], - "run": "pnpm exec tsx examples/05-diagram-printer/json-check.ts", - "origin": "AC-1 and the approved v1 JSON contract", - "oracle": "parser and schema assertions against the approved contract", - "independence": "contract-derived" - }, - { - "criteria": ["AC-4"], - "run": "diff -u expected-output.txt actual-output.txt", - "origin": "AC-4 and the repository's existing ASCII behavior", - "oracle": "pre-feature golden fixture", - "independence": "pre-existing" - } - ] - }] -} -``` +[Install and ship your first feature](docs/getting-started.md) -## Where validation comes from +## A small example -Boatstack does not choose a command after seeing the implementation and call that proof. Validation is derived before approval: +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. -```text -product intent or invariant - -> observable acceptance claim - -> oracle that could falsify the claim - -> executable or human procedure - -> recorded evidence -``` +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. -`criteria` limits which claims the check can support. The compiler rejects a criterion with no mapped validation and rejects a validation attached to a criterion its task does not serve. The `origin` identifies why the check is required: an acceptance criterion, existing repository invariant, explicit human decision, risk analysis, or external contract. The `oracle` identifies what makes the result meaningful: a pre-existing fixture, approved schema, independent system, measurable threshold, review rubric, or named human judgment. `independence` makes circular evidence visible; an implementation-authored test is useful evidence, but is not automatically an independent oracle. +[Follow the complete sanitized walkthrough](docs/account-recovery-walkthrough.md) -Ambiguous claims cannot pass unchanged: +## What Boatstack helps with -| Ambiguous claim | Required resolution before approval | +| Without Boatstack | With Boatstack | |---|---| -| “It should be fast” | Named workload, environment, metric, and threshold such as p95 under 200 ms | -| “The design should look good” | Approved reference states, review rubric, named reviewer, and captured evidence | -| “The migration should be safe” | Enumerated invariants, rehearsal/rollback procedure, and observable failure conditions | - -`/auto-plan` asks only the questions needed to establish that resolution. If no defensible oracle or authorized human judgment exists, the criterion remains `BLOCKED`; the model cannot validate its own interpretation by restating it. gstack and Spec Kit may help propose criteria and checks, but Boatstack still requires their provenance and evidence contract. +| 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 | -See [Validation and evidence](docs/validation-and-evidence.md) for validation forms, ambiguity handling, independence levels, gate outcomes, and the benchmark observations behind this contract. +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. -The developer-facing transition stays inside the coding host: +## Works with the tools you already use -```text -/plan-gate -Approve the displayed plan. -Choose the host's normal Build action. -``` +- **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. -`/plan-gate` presents a fingerprint over the complete source plan, spec, and `plan.md` and requires a named human. Explicit approval creates only `approval.md`, so the developer remains in Plan mode. The host's normal Build transition then validates and activates the exact approved plan before editing code. - -The source plan remains required and hash-checked through `/build`; later gates rely on the resulting lock, actual diff, and accumulated evidence. +These tools may propose content. They do not approve their own proposal or bypass Boatstack's evidence checks.
-Internal deterministic boundary +Install manually -The generated adapter invokes the repository-local helper; users do not need to learn these commands: +macOS or Linux: ```bash -.product-loop/bin/boatstack-helper check-plan \ - --plan .product-loop/features/diagram-json/plan.md - -.product-loop/bin/boatstack-helper activate-plan \ - --plan .product-loop/features/diagram-json/plan.md \ - --approval .product-loop/features/diagram-json/approval.md \ - --out-dir .product-loop/features/diagram-json/compiled \ - --output .product-loop/features/diagram-json/plan.lock.json -``` - -Activation compiles the machine task graph and writes the lock last. A changed planning input cannot reuse the receipt: - -```console -$ .product-loop/bin/boatstack-helper activate-plan ... -PASS: approved Markdown plan activated and locked - -# after plan.md prose, its structured block, the spec, or source plan changes -$ .product-loop/bin/boatstack-helper activate-plan ... -BLOCKED: stale approval receipt -``` - -
- -That is the approval boundary in code: conversation cannot silently turn a draft into permission to build, and Plan mode never needs to write JSON or executable state. - -See the complete, linked [worked example](examples/diagram-json/README.md). - -## Bring your own product context - -**Bring your context as it is.** Boatstack does not impose a documentation structure or maintain a second product memory. Keep feature briefs, vision, roadmaps, ADRs, gaps, and engineering rules wherever they already live in the repository. Cursor, Codex, or Claude discovers the relevant surrounding code and documents; Boatstack controls how that context becomes an approved change. - -Boatstack treats the repository as canonical and creates only temporary, reviewable, provenance-linked task projections. This matters because a deterministic translation `T` cannot add information about the desired outcome `Y` that was not present in the source context `C`: - -```text -I(Y; T(C)) <= I(Y; C) -``` - -This data-processing bound motivates source preservation; it does **not** prove that every transformation is harmful. A well-chosen projection can improve a finite-context model's effective performance by removing irrelevant material. The rule is therefore: **preserve the source; project only the relevant slice.** - -Point the host at an existing product document: - -```text -/auto-plan -Product brief: docs/features/team-notifications.md -Relevant decisions: docs/architecture/notifications.md -``` - -If no product document exists, the host Plan-mode file can begin with only the ordinary request. Boatstack then inspects the smallest relevant repository slice, separates discoverable facts from product questions, and produces the consistent handoff: - -```text -existing product docs + code -> questions -> feature spec -> approval -> engineering plan -``` - -Product documents define what and why. ADRs record durable technical decisions. Gaps record known incomplete work. Boatstack references these sources without replacing them. Any generated spec or plan must remain traceable to its sources and reviewable as a lossy task projection. No context map or documentation migration is required in V1; the project config may list useful starting paths when a repository wants stable defaults. - -## Use Boatstack with gstack and GitHub Spec Kit - -Boatstack is primarily a **control and evidence layer** over your coding host and optional planning/review tools. It does not need to reproduce everything those projects already do well: - -```text -product intent + repository context - | - [ BOATSTACK CONTRACT ] - / \ - gstack review lenses Spec Kit artifacts - \ / - normalized spec + plan + decisions - | - Markdown approval -> build activation -> evidence gates -> PR -``` - -| Layer | What it contributes | What remains Boatstack-owned | -|---|---|---| -| Coding host: Cursor, Codex, or Claude | Plan mode, repository exploration, implementation, tool execution | Cross-host artifact meanings and transition rules | -| [gstack](https://github.com/garrytan/gstack) | Product/CEO, design, engineering, and developer-experience review lenses; adversarial plan critique | Which findings change the approved plan, validation provenance, approval hashing, and gate outcomes | -| [GitHub Spec Kit](https://github.com/github/spec-kit) | Constitution, specify, clarify, plan, tasks, analyze, checklist, and related spec-driven artifacts | Normalization into Boatstack's criterion/validation contract and explicit human plan gate | -| Boatstack core | Source-plan discovery, provenance, question/gap boundaries, Markdown approval, deterministic build activation, drift locks, evidence mapping, review/ship gates | The completion and shipping claim itself | - -### With gstack - -When installed, Boatstack invokes gstack through namespaced `/gstack-*` review skills inside `auto-plan`, review, or retrospective work. gstack can challenge product premises, design states, architecture, failure modes, and developer experience. Its findings are proposals: Boatstack records accepted decisions, maps resulting claims to validation, and re-runs approval when semantics change. gstack never becomes an implicit approval signal. - -### With GitHub Spec Kit - -Spec Kit can generate or cross-check the constitution, specification, clarification answers, implementation plan, tasks, analysis, and checklists. Boatstack sits above those artifacts as the authority/evidence layer: - -```text -speckit.specify / clarify / plan / tasks / analyze / checklist - | - v - Boatstack criteria + oracle + validation normalization - | - explicit /plan-gate -``` - -`speckit.implement` does not bypass Boatstack's approval receipt, build activation, or `/build` boundary. If Spec Kit changes accepted semantics, Boatstack invalidates the receipt and returns to approval. This preserves Spec Kit's artifact-generation value without allowing a generator to approve or validate its own output. - -### Core only - -Both integrations are optional. Boatstack core still performs Plan-mode source discovery, question-led specification, structured Markdown planning, explicit approval receipts, deterministic build activation, validation/evidence mapping, test/review gates, and PR preparation. Integration failure is recorded as partial installation and does not roll back the working core. - -The installer creates one canonical `.product-loop/` runtime and thin adapters for: - -```text -.cursor/commands/{auto-plan,plan-gate,build,test-gate,review,ship,retro}.md -.cursor/rules/boatstack.mdc -.agents/skills/boatstack/SKILL.md -.claude/skills/boatstack/SKILL.md -.github/PULL_REQUEST_TEMPLATE/boatstack.md +git switch -c chore/install-boatstack +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/operatorstack/boatstack/main/install.sh)" ``` -It refuses to overwrite user-owned host files. The small platform helper lives under ignored `.product-loop/bin/`; users continue to operate Boatstack through their coding host. Re-run the installer to restore the helper on a fresh clone. - -## Freedom inside, evidence at the edges - -Boatstack is a mathematically modeled composite node inside an Intelligence Flow graph: +Windows PowerShell: -```text -product intent + repository state - | - v - [ BOATSTACK ] - | - v -diff + evidence + decisions + known gaps +```powershell +git switch -c chore/install-boatstack +irm https://raw.githubusercontent.com/operatorstack/boatstack/main/install.ps1 | iex ``` -Inside the node, a model, developer, team, or tool may use any suitable implementation method. At the edges, Boatstack makes authority, acceptance, evidence, and known gaps explicit. - -- A first implementation that passes is a **linear path**. -- Evidence that causes revision creates a **feedback path**. -- Multiple agents or approaches form a **branch/merge path**. - -Boatstack can participate in a loop, but it is not constrained to one. The graph topology follows the work. The invariant is evidence at transitions, not repeated ceremony. +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. -- **Optimization:** select the smallest context and ceremony that preserve required quality and evidence. -- **Control:** represent state explicitly and verify approval, acceptance, and shipping transitions. -- **Model neutrality:** route on ambiguity, risk, convergence, tool results, and evidence—not model brand, price, or a guessed capability tier. - -The full mapping from equations to files and checks is in [Evidence-engineered coding](docs/evidence-engineered-coding.md). + -## Evidence, with boundaries +## Find what you need -The rules were informed by a mechanically audited local corpus of **4,016 benchmark trial results** and **3,985 signal streams**, plus two real product-repository studies. For example: +**Start:** [Getting started](docs/getting-started.md) · [Generated files](docs/generated-files.md) · [Troubleshooting](docs/troubleshooting.md) -| Observed failure | Encoded move | -|---|---| -| Restarting discarded partial progress | Preserve known-good state; repair locally | -| Structured-output errors hid useful work | Validate and perform bounded same-step repair | -| Stronger verification wording regressed | Treat self-review as evidence, not the oracle | -| Blind context trimming lost accuracy | Select relevant context without deleting required state | -| A development-slice gain did not transfer | Require representative gates before promoting a move | +**Operate safely:** [Safety](docs/safety.md) · [Validation and evidence](docs/validation-and-evidence.md) · [Why these steps](docs/why-these-steps.md) -Read the [research and design record](docs/research-and-design.md) and [corpus audit](docs/benchmark-corpus-audit.md). This evidence motivates the loop; it does not prove that every future feature or model will improve. +**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) -## Context has a budget +**Contribute:** [Public-surface contract](docs/public-surface.md) · [Contributing](CONTRIBUTING.md) -The three canonical runtime references currently total approximately **7645 estimated tokens** using `ceil(characters / 4)`. That is a stable compactness signal, not provider billing. Host adapters stay thin and load the operation-specific slice on demand. +## Project status -## 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 alpha research distribution. It can generate host adapters, keep planning and approval Markdown-native, compile traceable task/test artifacts at Build, detect stale approvals, and preserve provenance. The next proof boundary is a paired feature-development evaluation against a plain host harness. +The exact Intelligence Flow source and generated file hashes for this checkout are recorded in [`UPSTREAM.json`](UPSTREAM.json). diff --git a/UPSTREAM.json b/UPSTREAM.json index 8b26854..65f8ccd 100644 --- a/UPSTREAM.json +++ b/UPSTREAM.json @@ -12,8 +12,9 @@ }, "files": { ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957", - "CONTRIBUTING.md": "bd9075f49658c0bdd4965cc1930ebbd31d97dfb8ebfc2edd79363acbef2c7600", - "README.md": "8fcc94a8c17d6d0588a15e21c2fbd59b09c8b7d4ae70f4e713cfcf4b0cda50f6", + "CONTRIBUTING.md": "40a302d838cf8de949bda1c3a6823725a64860d96cdaa5ab5a0020a09b91ec62", + "README.md": "1bc55b9c3cdd78c64b9d8cec11263397fb9a1a109973c7c3093465d247d3bfac", + "assets/boatstack-journey.svg": "b5f0ad554e0e1b56f0e1c4686a5341a6cc4e83c6ca2032442306f8175ff426a4", "assets/boatstack-mark.svg": "c46e935f06fcfde3b37abfd579c1963b765b2337a0fa993f9538c9b652297e39", "boatstack/SKILL.md": "4d80c39521763831655df0f98224769e0bf3caf535c0751ecf96c33bc33039e5", "boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1", @@ -55,22 +56,25 @@ "boatstack/testdata/reviewer-pr-body.md": "4c64e3788e5d61a377aeb0f797f7fc8d2316ab6e49572d15636eea7ba9e34ac4", "boatstack/testdata/safety/safe_apply.py.txt": "c9ec7fb932cf21b6aa8df597c4d4c54d6ec65e796240e49118d699f583383975", "boatstack/testdata/safety/unsafe_apply.py.txt": "42db1751865cc15c4dd69a03146b5deca8f21f916d258e433b27bbef5f884ab1", - "docs/account-recovery-walkthrough.md": "912edec85d930750c044bcd6117df9d03491a8c91f139af3ee82ab853452f1b7", + "docs/account-recovery-walkthrough.md": "acd3558a95f48004f18a0590670de496e1cc9f0cd1d187f924615497f57e1d6f", "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6", "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79", - "docs/evidence-engineered-coding.md": "d3816bbba4b1069e7043d94790728830b6259aaa495e21a6e0a3b96580cf0f88", - "docs/generated-files.md": "9df63782f3211d2cb3eea6011ab36abe7eeb30767e9b875c6f33f0c2e2763036", - "docs/getting-started.md": "0cc31c99c3b34f04bd6c8b0d5de24c0843da9a8ec0d7a27348d91274220b6f00", - "docs/research-and-design.md": "c9e6fffd3a094cda9f6534027f9e1cec41f14cbcff705fe621698f8094013690", + "docs/evidence-engineered-coding.md": "c4ad772f06ce5e304b838a48bcba7ea88fee1d235abe2d194203071b655e846f", + "docs/generated-files.md": "7f4d7cddff80d794361c26962b4c89b4e525eafb53776553be966258c6d867c6", + "docs/getting-started.md": "dccb5895bfbf6ac40309c6779f2a23dcdc27355e62a8a4858bb37c043e8de442", + "docs/public-claims.json": "49b7bc2bc0774e6cdb68c025edcf481f6b1298ac9c9878e8e48240d1caea3843", + "docs/public-surface.md": "53d741f04b2928a6ee8c006d647a6d675a215e863412e5862cd67d48433bff76", + "docs/research-and-design.md": "d65c66e323037bda5d45aacef5d48afa6bf93da55901378891d235aca3a5684f", "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6", - "docs/troubleshooting.md": "b9f0409bebb688fed5dddd61e6434c703b8ecc7dc3ded8c4ebb1986259d5ca30", + "docs/troubleshooting.md": "67ec380fc24226d6afd1d4fe250a123edd153f88bc1e318ee2ef7635e0ae1520", "docs/validation-and-evidence.md": "a9fe9274f3dc22b152094a307feda5d8c3ab099755100aef77bda13024cc3166", + "docs/why-these-steps.md": "7c6856c1cdff9946c771295184ce9fb552e0732f1f2ae8adf83aa72590bce9a7", "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": "b8da4986b20a36667ac57fb0d29b8334b43a12dc7031e737a711a62a5b2ccf2e", + "examples/diagram-json/plan.lock.json": "9b2e97f0bfbf6c0c412683f17079d41641978c6e3576971b8a839ed1b8aafae6", "examples/diagram-json/plan.md": "3ad35cc3cbe48306e7ee401bd9e9047d25e46c8a6fe9679aa1b3f5e96ceea292", "examples/diagram-json/questions.md": "1a0050041cac0a8d53e6ebfe04cbec4a298cdc8c50efeeb6fa15aeb663c5ec76", "examples/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed", @@ -83,7 +87,7 @@ "generator": "operatorstack/intelligence-flow:boatstack-distribution", "schema_version": 1, "source": { - "commit": "593a10ce11eee415a06a6383cc9e4b91b58aace6", + "commit": "1a67b309b53d52011909a95b291151afaf575ce7", "path": "examples/12-product-engineering-loop", "repository": "operatorstack/intelligence-flow" } diff --git a/assets/boatstack-journey.svg b/assets/boatstack-journey.svg new file mode 100644 index 0000000..5de1209 --- /dev/null +++ b/assets/boatstack-journey.svg @@ -0,0 +1,27 @@ + + Boatstack product journey + A continuous path from idea to plan, questions, approval, build, tests, review, and pull request. Failed tests return to build, and review changes return to the plan. + + + + + + + + 01Idea + 02Plan + 03Questions + 04Approve + Build05 + Tests06 + Review07 + PR08 + + a failed check returns to the change + + a changed decision returns to the plan + diff --git a/docs/account-recovery-walkthrough.md b/docs/account-recovery-walkthrough.md index 9e5aefb..fc17816 100644 --- a/docs/account-recovery-walkthrough.md +++ b/docs/account-recovery-walkthrough.md @@ -1,59 +1,61 @@ - + -# Walkthrough: account recovery in a passwordless product +# Example: account recovery in a passwordless product -This sanitized real-world sequence shows why Boatstack asks questions before it turns a request into code. +**For:** someone who wants to see why Boatstack asks questions before code. +**Outcome:** follow a real product conflict through decision, approval, repair, and PR preparation. -## Intent collides with repository reality +This is a sanitized product-repository sequence. It demonstrates observed behavior, not a benchmark claim about Boatstack's overall performance. -The product request was: +## The request conflicts with the product + +The request was: ```text Add a password reset button on the homepage. ``` -Minimal repository inspection found passwordless email-code authentication, no password reset route, and copy promising that users needed no password. A literal implementation would have produced a button for a capability that did not exist. +The repository used passwordless email-code authentication, had no password-reset route, and promised that users needed no password. A literal implementation would have created a button for a capability that did not exist. -`/auto-plan` therefore stopped and asked two product questions in plain text: +Boatstack therefore stopped and asked: ```text Q-1 Clarify email-code recovery, introduce passwords, or choose another behavior? Q-2 If passwords are introduced, do they replace email codes or sit alongside them? ``` -The human chose password authentication alongside the existing passwordless flow. Those responses became `ANSWERED`; the repository facts were `DISCOVERED`. Boatstack did not treat its own recommendation as an answer. - -## Approval turns the choice into a bounded change +The human chose password authentication alongside the existing passwordless flow. Repository facts were recorded as discovered; only the human responses became answered decisions. -The refined plan kept passwordless login, added password login and recovery routes, preserved passwordless signup, updated misleading copy, and required route and authentication tests. `/plan-gate` displayed the exact scope, non-goals, operational redirect gap, and fingerprint. An explicit `approve` created only `approval.md`. +## Approval defines the change -After the host entered its execution-capable mode, `/build` activated that exact plan and implemented the feature. The targeted suite initially passed. +The revised plan kept passwordless login, added password login and recovery routes, preserved passwordless signup, updated misleading copy, and required route and authentication tests. It also kept an operational redirect gap visible rather than implying it was solved. -## Review falsifies a completion claim +The plan gate displayed the outcome, exclusions, decisions, checks, gaps, and exact fingerprint. The human replied `approve`. No product code changed until the host entered its execution mode and build activated that approved plan. -`/review-gate` inspected the actual diff and found that the reset screen accepted any authenticated session as proof of password recovery. A normally signed-in user could reach a form intended only for a recovery event. +## Review finds what the tests missed -The gate returned `BLOCKED`. The implementation was repaired to unlock the form only for the recovery event, a regression test was added, and `/review-gate` then passed with the separate operator redirect gap still explicit. +The targeted suite initially passed. Review then found that the reset screen accepted any authenticated session as proof of password recovery. An ordinarily signed-in user could reach a form intended only for a recovery event. -## Shipping respects repository boundaries +Boatstack blocked progression. The implementation was repaired to unlock the form only for the recovery event, a regression test was added, and review passed with the separate operational gap still visible. -At `/ship-gate`, a pre-push type check failed in code unrelated to the approved feature. The correct response is to prove whether the failure exists on the base branch and then either: +## Shipping keeps unrelated work separate -1. repair it in a separate PR; or -2. use a repository-policy bypass only with explicit human authorization and recorded evidence. +At ship time, a pre-push type check failed in code unrelated to the feature. The correct choices were to prove it existed on the base branch and then either repair it separately or use a repository-policy bypass with explicit human authorization. -Changing unrelated code in the feature branch would silently widen the approved scope. +Silently editing unrelated code would have widened the approved feature and made the PR harder to review. -## What this demonstrates +## What the sequence shows ```text -vague intent - -> discover conflicting repository fact - -> ask the product owner - -> approve one observable slice - -> build freely inside that boundary - -> let evidence force a local repair - -> keep unrelated repository failures outside the feature +vague request + -> discover a product conflict + -> ask the person responsible + -> approve one clear change + -> build + -> let evidence force a repair + -> keep unrelated failures outside the feature ``` -The value did not come from a larger prompt. It came from preserving the original intent, separating discovered facts from human decisions, and requiring the implementation to survive an evidence boundary before shipping. +The safeguard behavior is covered by planning, approval, review, and PR-projection tests. Whether the complete Boatstack workflow improves product-delivery success remains a separate paired evaluation. + +Next: [install and ship a first feature](getting-started.md) or read [why these steps exist](why-these-steps.md). diff --git a/docs/evidence-engineered-coding.md b/docs/evidence-engineered-coding.md index 9139475..28fe9a0 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 [`593a10ce11eee415a06a6383cc9e4b91b58aace6`](https://github.com/operatorstack/intelligence-flow/tree/593a10ce11eee415a06a6383cc9e4b91b58aace6/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 [`1a67b309b53d52011909a95b291151afaf575ce7`](https://github.com/operatorstack/intelligence-flow/tree/1a67b309b53d52011909a95b291151afaf575ce7/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/generated-files.md b/docs/generated-files.md index 8c33a3e..2b58ba0 100644 --- a/docs/generated-files.md +++ b/docs/generated-files.md @@ -1,55 +1,58 @@ - + -# What Boatstack generates +# What Boatstack adds to a repository -Boatstack creates two different kinds of repository state. Keeping them separate is what makes feature diffs reviewable. +**For:** anyone reviewing an installation or feature PR. +**Outcome:** know what to commit, what can be edited, and what Boatstack regenerates. -## Installation state: commit in its own PR +Boatstack creates installation state once and feature evidence repeatedly. Keeping those two groups separate is what makes later product diffs understandable. -| Path | Ownership | What to do | +## Installation PR + +| Path | What it is | What you do | |---|---|---| -| `.boatstack-project.json` | Project-owned input | Review and edit repository facts, real commands, context starting points, and policy. | -| `.product-loop/project.json`, references, templates, and `generated.lock.json` | Boatstack-generated | Commit; regenerate through the installer instead of editing directly. | -| `.cursor/commands/` and `.cursor/rules/` | Boatstack-generated Cursor adapter | Commit so slash commands survive clones, branch changes, and cleanup. | -| `.agents/skills/boatstack/` | Boatstack-generated Codex/open-agent adapter | Commit. | -| `.claude/skills/boatstack/` | Boatstack-generated Claude adapter | Commit. | -| `.github/PULL_REQUEST_TEMPLATE/boatstack.md` | Boatstack-generated PR adapter | Commit. | -| `.product-loop/hooks/` | Boatstack-generated fail-closed Bash/PowerShell launchers and host fragments | Commit; do not weaken or edit directly. | -| `.cursor/hooks.json`, `.claude/settings.json`, `.codex/hooks.json` | Merged host configuration | Commit the Boatstack fragment alongside preserved unrelated settings. | -| `.product-loop/bin/` | Machine-local | Do not commit. It contains the verified platform helper and local install lock and is ignored. | +| `.boatstack-project.json` | Project-owned repository facts and commands | Review and edit | +| `.product-loop/` references, templates, hooks, and generated lock | Shared Boatstack runtime | Commit; regenerate rather than hand-edit | +| `.cursor/`, `.agents/`, and `.claude/` Boatstack adapters | Portable host commands and skills | Commit | +| `.github/PULL_REQUEST_TEMPLATE/boatstack.md` | Fallback PR structure | Commit | +| `.cursor/hooks.json`, `.claude/settings.json`, `.codex/hooks.json` | Boatstack fragments merged with existing host settings | Review and commit | +| `.product-loop/bin/` | Verified machine-local helper | Never commit; it is ignored | + +The installer prints the exact staging command and runs `doctor`. Put this state in `chore/install-boatstack`, review it once, and merge it before feature work. -The installation manifest `.product-loop/generated.lock.json` describes generated infrastructure. It is different from a feature's `plan.lock.json`, which proves that a specific approved plan activated without drift. +## Feature PR -## Feature state: commit with the feature PR +Boatstack stores feature artifacts under `.product-loop/features//`: -| Artifact | Meaning | +| Artifact | Why it exists | |---|---| -| `source-plan.md` | Preserved host Plan-mode interpretation of the original request. | -| `feature-spec.md` | Accepted outcome, boundaries, behavior, and criteria. | -| `questions.md` | Discovered facts, proposed choices, human answers, and open unknowns. | -| `gaps.md` | Known incomplete or deferred work with impact and revisit trigger. | -| `test-plan.md` | Criterion-to-oracle and validation design. | -| `plan.md` | Canonical human-readable and structured approved plan. | -| `approval.md` | Named human, timestamp, and exact plan fingerprint. | -| `compiled/` | Build-time task graph, test matrix, and evidence skeleton. | -| `plan.lock.json` | Content-addressed build activation record. | -| `evidence.md` | Commands, results, findings, runtime checks, and gate status. | -| `pr.md` | Exact reviewer-ready title/body preview, bound to the committed product diff and current evidence. | +| `source-plan.md` | Preserves the host's first interpretation of the request | +| `feature-spec.md` | Defines the accepted outcome and exclusions | +| `questions.md` | Separates repository facts, proposals, human answers, and unknowns | +| `gaps.md` | Keeps deferred or incomplete work visible | +| `test-plan.md` | Connects promised outcomes to checks | +| `plan.md` | Holds the human-readable approved plan | +| `approval.md` | Records who approved which exact plan | +| `compiled/` and `plan.lock.json` | Prove that build activated the approved inputs without drift | +| `evidence.md` | Records commands, results, review findings, and gate status | +| `pr.md` | Contains the exact reviewer-ready title and body preview | -These files travel with the product diff because they explain what was approved and why completion is defensible. Changes to the source plan, spec, or `plan.md` invalidate approval until the plan gate runs again. +These artifacts travel with the feature because they explain what was agreed and what supports completion. Changing the source plan, spec, or plan invalidates approval until the plan gate runs again. -For an existing or ad-hoc branch, Boatstack stores the same exact preview under `.product-loop/pr-briefs//pr.md`. It is committed with that branch but does not create approval, lock, or gate provenance. Missing evidence stays visibly `NOT_VERIFIED`. +## Existing branches -The `pr.md` frontmatter is non-rendered publication metadata; the remaining Markdown is the exact GitHub body. Edit the reviewer narrative through Boatstack, preview it, then explicitly reply `open PR` or `update PR`. Any product diff or evidence change makes the preview stale. The preview artifact itself is excluded from the product-diff fingerprint so committing it does not invalidate itself. +When Boatstack improves a branch that did not use the full workflow, it stores the preview under `.product-loop/pr-briefs//pr.md`. It summarizes the actual commits, diff, and observed checks without creating approval or gate history. Missing evidence remains `NOT_VERIFIED`. -## Fresh clones and updates +The preview's frontmatter is publication metadata; the remaining Markdown is the exact GitHub body. The preview is excluded from its own product-diff fingerprint, but any other diff or evidence change makes it stale. -Committed adapters remain available after cloning. Restore only the ignored helper by rerunning the installer from the repository root. For an update, create a new `chore/update-boatstack` branch, rerun the installer, inspect the generated diff and version provenance, and merge it as a separate infrastructure PR. +## Fresh clones and updates -Never delete untracked adapters merely to make a feature diff smaller. If Boatstack was installed without committing its infrastructure, stop and create the installation PR first. Run this read-only check whenever commands disappear or generated state looks suspicious: +Committed adapters survive a clone; the ignored helper does not. Rerun the installer to restore it. For an update, use a separate `chore/update-boatstack` branch, inspect the generated diff and version provenance, and merge it before unrelated product work. -`doctor` also verifies that each configured host contains exactly one current Boatstack fragment and that malformed events are denied. Some hosts do not expose whether a repository is trusted or hooks are enabled; confirm that host state separately. The hooks complement, rather than replace, least-privilege external credentials. +If generated state looks wrong, run: ```bash .product-loop/bin/boatstack-helper doctor --repo . ``` + +Do not delete adapters merely to make a feature diff smaller. If the original installation was never committed, stop and create its infrastructure PR first. diff --git a/docs/getting-started.md b/docs/getting-started.md index 21706d5..65c390b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,55 +1,47 @@ - + # Install Boatstack and ship a first feature -Boatstack is repository-local. Install it once in an infrastructure PR, then create ordinary feature branches from the merged base. +**For:** a product builder or engineer using Cursor, Codex, or Claude Code. +**Outcome:** install Boatstack in one infrastructure PR, then take one ordinary request through approval, build, evidence, review, and PR preparation. -## 1. Install on a clean branch +Boatstack is repository-local. Install it once and commit the shared workflow before starting product work. -macOS or Linux: +## 1. Install it separately + +The easiest path is to paste the [agent installation prompt](../README.md#install-with-your-coding-agent) into your coding host. It asks the agent to create `chore/install-boatstack`, run the official installer, explain the generated files, run `doctor`, and prepare the installation PR without merging it. + +For a manual install: ```bash git switch -c chore/install-boatstack /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/operatorstack/boatstack/main/install.sh)" ``` -Windows PowerShell: +On Windows PowerShell: ```powershell git switch -c chore/install-boatstack irm https://raw.githubusercontent.com/operatorstack/boatstack/main/install.ps1 | iex ``` -Choose `core` unless you already want gstack review lenses, Spec Kit artifact generation, or both. Confirm the real test command when asked. The installer previews every path before writing it, verifies the helper checksum, and runs `doctor` after installation. - -The install also merges Boatstack's fail-closed safety fragments into all portable host configurations. Review those fragments in the infrastructure PR. They deny high-confidence irreversible operations on every supported agent call; no approval phrase bypasses them. - -Review the printed paths and repository facts: +Choose `core` unless you already want gstack, GitHub Spec Kit, or both. Confirm the real repository test command when asked. The installer previews paths, verifies the helper, installs portable host adapters, and runs: ```bash -git status --short -git diff -- .boatstack-project.json .product-loop .cursor .agents .claude .github/PULL_REQUEST_TEMPLATE .product-loop/bin/boatstack-helper doctor --repo . ``` -Use the exact `git add` command printed by the installer, then commit and push: +Review and commit the paths printed by the installer. Merge this infrastructure PR before creating a feature branch. Later feature PRs then contain the product change and its evidence rather than one-time setup noise. -```bash -git commit -m "chore: install Boatstack" -git push -u origin chore/install-boatstack -``` - -Open and merge that infrastructure PR before starting a feature. The first PR is intentionally larger because it establishes the shared workflow; later feature PRs contain only the product change and its feature evidence. A fresh clone reruns the installer to restore the ignored platform helper without changing committed adapters. +## 2. Start with the idea -## 2. Start one feature in Plan mode - -Create a feature branch from the base containing the merged Boatstack installation. Open Cursor, Codex, or Claude in its planning surface and describe ordinary product intent: +Create a feature branch from the base containing Boatstack. Enter your host's Plan mode and describe the outcome in normal product language: ```text Add account recovery without removing the existing passwordless sign-in flow. ``` -Let the host explore the smallest relevant repository slice and save its plan. Boatstack uses a host-exposed plan path when available; otherwise save one plan under `.product-loop/intake/`. +Let the host inspect the relevant repository slice and save its plan. Boatstack uses a host-exposed path when available; otherwise save exactly one non-empty plan under `.product-loop/intake/`. Run: @@ -57,23 +49,9 @@ Run: /auto-plan ``` -`/auto-plan` may answer discoverable repository facts, but it cannot answer product decisions for you. If it asks questions, answer them in plain text. Material agent suggestions stay `PROPOSED`; only your responses become `ANSWERED`. Re-run `/auto-plan` until the draft is ready. - -## 3. Review and approve the exact plan - -Run: - -```text -/plan-gate -``` - -Boatstack presents the intended outcome, non-goals, decisions, known gaps, and validation plan. Request changes or explicitly reply `approve`. When available, Boatstack uses your authenticated GitHub username for the internal approval record; it asks for a name or handle only when no trustworthy identity is available. Approval does not build code. - -### What Boatstack responses look like - -Boatstack leads with the outcome and one action. Internal status codes, helper operations, fingerprints, and artifact paths remain available under **Technical details** instead of dominating the response. +Boatstack can discover repository facts. It cannot choose product behavior for you. When different answers would materially change the feature, it asks in plain language and waits for your answer. -After a successful `/auto-plan`: +### What a ready plan looks like ```markdown ## Plan ready @@ -90,12 +68,28 @@ Plan paths, validation output, and fingerprint. ``` -When `/plan-gate` needs approval: +## 3. Review and approve + +Run: + +```text +/plan-gate +``` + +Read the intended outcome, exclusions, decisions, gaps, and planned checks. Request corrections when anything is wrong. When it matches what you want, reply: + +```text +approve +``` + +Boatstack uses an explicit identity or your authenticated GitHub username for the approval record. Approval does not edit product code. + +### While approval is waiting ```markdown ## Ready for your approval -This plan builds the agreed slice and keeps the listed non-goals and gaps outside it. +This plan builds the agreed slice and keeps the listed non-goals outside it. ### Next step @@ -107,7 +101,7 @@ Machine status, fingerprint, and artifact paths. ``` -After approval: +### After approval ```markdown ## Approved — ready to build @@ -124,27 +118,21 @@ Approver, timestamp, fingerprint, and approval-record path. ``` -## 4. Enter the host's execution surface and build +## 4. Build the approved change -Use the host's normal transition out of planning, then run: +Use Cursor, Codex, or Claude's normal transition out of Plan mode, then run `/build`. Boatstack verifies the approval, creates the machine task/evidence state, and locks it to the reviewed inputs before the first product edit. -```text -/build -``` +| Host | Planning surface | Build transition | +|---|---|---| +| Cursor | Plan mode | Accept Cursor's normal switch to Agent or Build mode | +| Codex | Plan mode in the app or supported client | Enter its normal execution-capable mode | +| Claude Code | Plan permission mode | Exit plan mode before `/build` | -Boatstack first activates the approved plan into compiled tasks, a requirement-to-test matrix, evidence skeleton, and content-addressed lock. Only then may the host edit product code. If the host rejects the mode transition, Boatstack returns `READY_FOR_BUILD` and creates no machine state. +If the host is still read-only, Boatstack reports that it is ready for build without creating compiled state. Switch modes and rerun `/build`. -Host notes: +## 5. Prove, review, and prepare the PR -| Host | Planning | Build transition | Boatstack adapter | -|---|---|---|---| -| Cursor | Plan mode; plain-text questions work when structured questions are unavailable | Accept Cursor's normal switch to Agent/Build mode | `.cursor/commands/*.md` | -| Codex | Plan mode in the app or supported client | Move to its normal execution-capable mode | `.agents/skills/boatstack/SKILL.md` | -| Claude Code | Start or switch to plan permission mode | Exit plan mode before `/build` | `.claude/skills/boatstack/SKILL.md` | - -## 5. Prove, review, and ship - -Run the gates in order: +Run the remaining gates: ```text /test-gate @@ -152,22 +140,26 @@ Run the gates in order: /ship-gate ``` -- `test-gate` maps every acceptance criterion to current evidence. -- `review-gate` reviews the actual diff and may send the feature back for a local repair. -- `ship-gate` generates a reviewer-ready title and body from the approved intent, actual committed diff, evidence, decisions, and gaps. +- **Test gate:** connects every promised outcome to current evidence. +- **Review gate:** checks the actual diff against the approved intent, risks, invariants, and gaps. +- **Ship gate:** creates a reviewer-first title and body from the committed change and recorded evidence. -For external writes, the gates also require immutable target identity, transactional or fix-forward failure behavior, an independent safety oracle, and an operational diff with no executable destructive recovery. Operator-only recovery remains outside the feature branch. +Boatstack shows the exact PR preview before changing GitHub. Reply `open PR` for a new PR. Reply `update PR` for an existing one. Any changed commit or evidence makes the preview stale and forces regeneration. Merge and deploy remain separate human decisions. -Boatstack shows the exact title and rendered body before changing GitHub. Reply `open PR` when the branch has no PR. Reply `update PR` when one already exists. It then rechecks the diff and evidence before publication. If anything changed after the preview, Boatstack regenerates it instead of publishing stale claims. Merge and deploy remain separate decisions. - -You do not need another slash command for existing work. Ask naturally: +For an existing branch, ask naturally: ```text Use Boatstack to improve this PR. ``` -Without a managed feature package, Boatstack uses an evidence-limited brief: it summarizes the committed branch and observed checks, while marking unavailable approval or gate evidence `NOT_VERIFIED`. It never pretends the ad-hoc branch passed the full Boatstack workflow. +Boatstack summarizes what it can observe and labels unavailable approval or gate evidence `NOT_VERIFIED`; it does not invent a history the branch never had. + +## When something blocks -`PASS_WITH_GAPS` is honest success with explicitly owned, non-critical gaps. `BLOCKED` means the claim cannot progress. After fixing a review finding, rerun the affected gates. A check that already fails on the base branch belongs in a separate repair PR or an explicitly authorized repository-policy bypass—not an unrelated edit hidden in the feature branch. +- A product decision returns to you rather than being guessed. +- A changed plan returns to approval. +- Failed evidence returns to a bounded repair. +- A destructive recovery path remains denied. +- A pre-existing unrelated repository failure stays outside the feature unless separately authorized. -See the [sanitized account-recovery walkthrough](account-recovery-walkthrough.md) for a complete realistic path, or the [diagram JSON example](../examples/diagram-json/README.md) for exact artifacts. +Continue with the [account-recovery walkthrough](account-recovery-walkthrough.md), inspect [what Boatstack generates](generated-files.md), or use [troubleshooting](troubleshooting.md). diff --git a/docs/public-claims.json b/docs/public-claims.json new file mode 100644 index 0000000..3388abb --- /dev/null +++ b/docs/public-claims.json @@ -0,0 +1,52 @@ +{ + "schema_version": 1, + "source_commit": "1a67b309b53d52011909a95b291151afaf575ce7", + "statuses": ["verified", "observed", "still_being_evaluated"], + "claims": [ + { + "id": "human-decisions", + "public_claim": "Boatstack asks for material product decisions, records the human answer, and requires approval before build.", + "status": "verified", + "originating_observation": "A password-reset request conflicted with a passwordless product model and required a human product choice.", + "safeguard": "Question states, explicit Markdown approval, approval fingerprints, and stale-plan rejection.", + "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:1a67b309b53d52011909a95b291151afaf575ce7" + }, + { + "id": "validation-provenance", + "public_claim": "Boatstack links every planned acceptance criterion to a validation procedure and records why that check can support the claim.", + "status": "verified", + "originating_observation": "Stronger verification wording and same-model checks did not reliably distinguish correct completion from unsupported claims.", + "safeguard": "Criterion coverage, validation origin, named falsifier, and independence level.", + "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:1a67b309b53d52011909a95b291151afaf575ce7" + }, + { + "id": "irreversible-operations", + "public_claim": "Boatstack denies high-confidence destructive recovery operations before supported hosts execute them.", + "status": "verified", + "evaluation_status": "still_being_evaluated", + "originating_observation": "A failed external schema apply led to an invented reset path before human review removed it.", + "safeguard": "Fail-closed host hooks, immutable destructive classes, and read-only diagnosis after failure.", + "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:1a67b309b53d52011909a95b291151afaf575ce7" + }, + { + "id": "reviewer-ready-pr", + "public_claim": "Boatstack previews a reviewer-first PR body derived from the committed diff and available evidence before changing GitHub.", + "status": "verified", + "originating_observation": "A generated PR summary omitted product decisions, accepted gaps, review findings, rollout, and rollback context.", + "safeguard": "Managed and evidence-limited PR projection, stale-preview checks, and explicit open or update confirmation.", + "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:1a67b309b53d52011909a95b291151afaf575ce7" + } + ] +} diff --git a/docs/public-surface.md b/docs/public-surface.md new file mode 100644 index 0000000..2d11809 --- /dev/null +++ b/docs/public-surface.md @@ -0,0 +1,49 @@ + + +# Boatstack public-surface contract + +Boatstack's README is a product-builder homepage, not the complete manual. Public presentation may change freely inside this contract while the runtime remains deterministic. + +## Reading order + +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? +4. What will using it feel like? +5. 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. + +## Evidence language + +Every material capability claim must have a `boatstack-claim:` marker that resolves to `public-claims.json`. Distinguish: + +- an observed problem; +- behavior verified in Boatstack tests; +- a product outcome that is still being evaluated. + +Do not use “proven,” “optimal,” performance uplift, cost reduction, or safety-improvement language without a matching evaluation. A fixture can verify enforcement behavior; it cannot by itself prove improved product delivery. + +## Design review + +When Huashu Design is installed, use it to review a public-surface change. The review must still satisfy this portable fallback: + +- 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; +- 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. + +## Upgrade checklist + +Any user-facing upgrade must declare: + +- the user problem it addresses; +- the observation or requirement behind it; +- its claim-record status and supporting test/evaluation; +- the README or guide that changes, or why no public change is needed. + +Internal refactors may declare no public impact. A new public claim without a record, readable explanation, and current status is incomplete. diff --git a/docs/research-and-design.md b/docs/research-and-design.md index 3e90f5e..aeba50a 100644 --- a/docs/research-and-design.md +++ b/docs/research-and-design.md @@ -11,7 +11,7 @@ The proposed product is not a large prompt and not a Codex-, Cursor-, Claude-, o The initial implementation is in [`product-engineering-loop/`](product-engineering-loop/). Its exporter generates Cursor rules/commands, Claude Code and Codex skills, and a GitHub PR template from one source. -The public [Boatstack](https://github.com/operatorstack/boatstack) repository is a compiled distribution, not a second source of product/runtime truth. `scripts/build_boatstack.py` projects this package into a branded README, evidence-engineered-coding explanation, worked example, tests, and installable skill; `UPSTREAM.json` binds every projected file to its Intelligence Flow commit. A Boatstack-owned scheduled workflow polls this public source and proposes content changes by PR. Boatstack's `.github/workflows` directory is a deliberately separate control-plane slice: it originates and changes in Boatstack through ordinary, manually reviewed PRs and is never emitted, owned, or removed by the Intelligence Flow projector. +The public [Boatstack](https://github.com/operatorstack/boatstack) repository is a compiled distribution, not a second source of product/runtime truth. `scripts/build_boatstack.py` projects this package into a branded README, evidence-engineered-coding explanation, worked example, tests, and installable skill; `UPSTREAM.json` binds every projected file to its Intelligence Flow commit. The README and beginner guides remain ordinary human-authored Markdown copied byte-for-byte, while the Go helper embeds only install-time workflow references and templates. A machine-readable public claim record keeps homepage wording tied to observations, safeguards, tests, and explicit evaluation status. A Boatstack-owned scheduled workflow polls this public source and proposes content changes by PR. Boatstack's `.github/workflows` directory is a deliberately separate control-plane slice: it originates and changes in Boatstack through ordinary, manually reviewed PRs and is never emitted, owned, or removed by the Intelligence Flow projector. ## Outcome sizing and where value emerges diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d94e0d0..e333229 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,64 +1,73 @@ - + # Troubleshooting Boatstack -## An operation is denied as irreversible +**For:** someone blocked during installation or a feature. +**Outcome:** identify the smallest safe action that restores the intended workflow. -Boatstack has no in-session override. Preserve the current external state and use read-only diagnosis. Remove the destructive capability, replace it with transactional or fix-forward behavior, or move intentional recovery into a separately controlled operator runbook. Do not rename or wrap the command to evade classification. +Start with: -If a safe diagnostic is denied, retain the denial evidence and report the smallest reproducible command as a false-positive candidate. The Move remains proposed until its false-denial evaluation passes. +```bash +.product-loop/bin/boatstack-helper doctor --repo . +``` + +## A command is denied as destructive -## The safety helper or hook is missing or drifted +Boatstack has no in-session bypass. Preserve the current external state and diagnose with read-only commands. Replace the destructive capability with transactional or fix-forward behavior, or move intentional recovery into a separately controlled operator runbook. -The hook fails closed. Rerun the official installer from the repository root, run `.product-loop/bin/boatstack-helper doctor --repo .`, reload the host, and inspect its trust/hook enablement. Do not delete the hook to unblock work. +If a safe diagnostic was denied, keep the denial output and report the smallest reproducible command. Do not rename or wrap it to evade the check. -## Cursor does not recognize a slash command +## The safety helper or hook is missing -Cursor discovers project commands from `.cursor/commands/*.md`. Check the installation: +The hook fails closed. Rerun the official installer, run `doctor`, reload the coding host, and confirm the repository is trusted and hooks are enabled. Keep least-privilege external credentials; hooks are defense in depth, not a complete sandbox. + +## Cursor cannot find a slash command + +Cursor reads project commands from `.cursor/commands/*.md`: ```bash -.product-loop/bin/boatstack-helper doctor --repo . ls .cursor/commands +.product-loop/bin/boatstack-helper doctor --repo . ``` -If commands are missing, rerun the installer and reload the Cursor window. Commit the restored installation state in a dedicated PR; otherwise a cleanup, branch change, or fresh clone can remove untracked commands again. +Rerun the installer and reload Cursor when files are missing. Commit the restored adapter in a dedicated infrastructure PR. -## `/auto-plan` says no source plan exists +## `/auto-plan` cannot find a source plan -Boatstack will not invent a source plan. Finish the host's Plan-mode exploration and save it. If the host does not expose the active plan path, place exactly one non-empty plan under `.product-loop/intake/`, then rerun `/auto-plan`. Pass an explicit path only when discovery reports multiple candidates. +Finish the host's Plan-mode exploration and save it. If the host does not expose the path, put exactly one non-empty plan under `.product-loop/intake/`, then rerun `/auto-plan`. Supply an explicit path only when Boatstack reports multiple candidates. -## Plan mode blocks the normal Write tool +## Plan mode cannot write an artifact -Boatstack planning remains Markdown-only. The adapter may use the bounded `planning-write` helper for known feature documents; it must not use arbitrary redirection to bypass the host or write product code. If the host cannot support even that bounded operation, return `WAITING_FOR_HOST_WRITE_PERMISSION` instead of leaving planning early. +Planning is Markdown-only. The adapter may use Boatstack's bounded planning writer for known feature documents; it must not use arbitrary shell redirection or edit product code. If the host cannot support the bounded write, keep the plan and report the missing permission rather than leaving Plan mode early. -## `/build` says `READY_FOR_BUILD` +## `/build` says it is ready but cannot start -The plan is approved, but the host is still read-only. Accept the host's normal transition into its execution-capable surface and rerun `/build`. Boatstack does not compile tasks or create a lock until product-code writes are available. +The plan is approved, but the host remains read-only. Enter the host's normal execution-capable mode and rerun `/build`. Boatstack deliberately creates no compiled state or lock before that transition. ## Approval is stale -The source plan, feature spec, or complete `plan.md` changed after approval. Return to `/auto-plan`, review the new fingerprint at `/plan-gate`, and approve the revised plan. Never edit the fingerprint in `approval.md` manually. +The source plan, feature spec, or complete plan changed after approval. Return to `/auto-plan`, review the new plan at `/plan-gate`, and approve it again. Never edit approval metadata manually. -## A gate reports `PASS_WITH_GAPS` +## A gate passes with gaps -The proven criteria passed, while named non-critical gaps remain. The evidence must identify their impact, owner, reason, affected criteria, and revisit trigger. Any critical safety, correctness, or product-acceptance gap is `BLOCKED`, not `PASS_WITH_GAPS`. +The proven criteria passed while named non-critical gaps remain. Each gap needs an impact, owner, reason, affected criteria, and revisit trigger. A critical correctness, safety, or acceptance gap blocks instead. -## A pre-push hook fails on unrelated base-branch code +## An unrelated base-branch check fails -Reproduce the failure against the target branch. If it is pre-existing, keep the repair in a separate PR. A bypass is allowed only when repository policy permits it and the human explicitly authorizes it; record that evidence. Do not quietly add unrelated repairs to the approved feature branch. +Reproduce the failure against the target branch. Keep its repair in a separate PR. Use a bypass only when repository policy permits it and a human explicitly authorizes it; do not hide unrelated edits in the approved feature. -## Non-interactive installation cannot detect tests +## Non-interactive installation cannot find the tests -Boatstack recognizes common package-manager tests, `scripts/check.sh`, Go, Rust, Make, and Python/pytest projects. If the repository uses a custom command, run the installer interactively or create `.boatstack-project.json` with the real test command. Boatstack will not invent a command merely to complete installation. +Boatstack detects common package-manager tests, `scripts/check.sh`, Go, Rust, Make, and Python/pytest projects. For a custom command, install interactively or define the real test command in `.boatstack-project.json`. Boatstack will not invent one merely to complete setup. -## A fresh clone has adapters but no helper +## A fresh clone has no helper -This is expected: `.product-loop/bin/` is machine-local and ignored. Rerun the installer from the repository root; the generated diff should remain clean when the committed configuration and installed Boatstack version match. +This is expected: `.product-loop/bin/` is machine-local and ignored. Rerun the installer from the repository root. A matching version and configuration should restore the helper without changing committed adapters. -## The PR preview became stale +## The PR preview is stale -Boatstack binds `pr.md` to the current committed product diff and evidence. A new commit, amended evidence, changed approval artifact, or base-branch change invalidates that preview. Ask Boatstack to regenerate the PR; do not copy the old body forward. +A new commit, changed evidence, changed approval artifact, or base-branch update invalidated the preview. Ask Boatstack to regenerate it. Do not copy the old body forward. -## GitHub CLI is missing or signed out +## GitHub CLI is unavailable -Boatstack keeps the validated `pr.md` instead of discarding the work. Install or authenticate GitHub CLI and rerun the open/update confirmation, or copy the title and rendered body from the preview into GitHub manually. The manual path still does not authorize merge. +Boatstack retains the validated `pr.md`. Authenticate or install GitHub CLI and repeat the open/update confirmation, or copy the exact preview into GitHub manually. Neither path authorizes merge. diff --git a/docs/why-these-steps.md b/docs/why-these-steps.md new file mode 100644 index 0000000..2177799 --- /dev/null +++ b/docs/why-these-steps.md @@ -0,0 +1,62 @@ + + +# Why Boatstack has these steps + +**For:** anyone who wants to see the work behind Boatstack's safeguards. +**Outcome:** understand what was observed, what Boatstack now does, and what has—or has not—been proven. + +Boatstack was not designed by writing a long list of ideal engineering practices. Its safeguards were traced from benchmark trajectories and two product repositories, then turned into behavior that can be inspected and tested. This page keeps three different kinds of evidence separate: + +- **Observed:** the problem appeared in recorded work. +- **Verified:** Boatstack's implementation behaves as stated in automated tests. +- **Still being evaluated:** the safeguard exists, but its effect on overall product-delivery outcomes has not yet been established. + +Those labels prevent an implementation test from being presented as proof that the whole product improves engineering performance. + +## 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. + +**What Boatstack does.** Material product choices remain open until a human answers them. The reviewed plan is fingerprinted, explicit approval is recorded, and any subsequent planning change makes that approval stale. + +**How we check it.** Planning, approval, and stale-plan tests verify that unanswered decisions block progress, approval cannot be inferred from silence, and changed inputs cannot reuse an old approval. + +**Status:** observed in a sanitized product workflow; enforcement verified in automated tests. This does not yet quantify a change in feature success rate. + +## Validation provenance + +**What happened.** Terminal-Bench experiments showed that stronger self-verification wording and same-model repair did not reliably create truth. In another experiment, model-authored tests helped a development slice while the frozen evaluator had low fidelity, and the apparent gain did not transfer to the full board. + +**What Boatstack does.** Every acceptance criterion must name a validation procedure and explain what makes that procedure meaningful. A test written with the implementation remains useful evidence, but it is not silently promoted into an independent source of truth. + +**How we check it.** The plan compiler rejects uncovered criteria, incomplete validation records, and checks attached to work that does not serve the claimed outcome. + +**Status:** experimental problem observed; compiler behavior verified. The best validation mix for different product risks remains an open evaluation question. + +## Irreversible operations + +**What happened.** After a partial database-schema apply failed, an agent introduced a reset path that could drop the public schema. The human stopped execution and the capability was removed in favor of target checks and transactional or fix-forward behavior. + +**What Boatstack does.** Project hooks deny high-confidence destructive operations before execution and require read-only diagnosis after an external-write failure. There is no in-session bypass. + +**How we check it.** Host-event fixtures cover direct and indirect destructive commands, malformed events, missing helpers, and safe controls. A blocked command must not create its sentinel side effect. + +**Status:** incident observed and enforcement verified in fixtures. The net benefit, false-denial rate, and host coverage are **still being evaluated**; the safety documentation keeps that limitation visible. + +## Reviewer-ready PR + +**What happened.** Ordinary generated PR summaries described edited files and test commands but omitted important product decisions, accepted gaps, review findings, rollout, and rollback context accumulated during the feature. + +**What Boatstack does.** At ship time, Boatstack projects the approved intent, committed diff, recorded evidence, decisions, gaps, rollout, and rollback into a reviewer-first preview. The human sees the exact title and body before GitHub is changed. + +**How we check it.** Tests cover managed and ad-hoc branches, evidence-limited wording, stale previews, conditional risk sections, and explicit open/update confirmation. + +**Status:** product-workflow problem observed; projection behavior verified. Reviewer speed and acceptance quality still need blinded product-delivery evaluation. + +## What the experiments do and do not support + +The current research covers thousands of locally available benchmark result records, preregistered comparisons, product-repository studies, and targeted trajectory inspection. It supports the mechanisms that Boatstack is designed to address. It does **not** yet support a claim that Boatstack improves feature success, cost, or delivery speed. + +The next product evaluation compares the same model, task, budget, and coding host with and without Boatstack on a feature-building benchmark. Until that result exists, the homepage describes implemented behavior and evidence lineage—not performance uplift. + +Technical readers can inspect the [research and design record](research-and-design.md), [validation model](validation-and-evidence.md), [safety evaluation status](safety.md), and [benchmark corpus audit](benchmark-corpus-audit.md). diff --git a/examples/diagram-json/plan.lock.json b/examples/diagram-json/plan.lock.json index 32642db..bd9c793 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": "593a10ce11eee415a06a6383cc9e4b91b58aace6", + "source_commit": "1a67b309b53d52011909a95b291151afaf575ce7", "source_plan_path": "examples/diagram-json/source-plan.md", "source_plan_sha256": "e10593ddaa7522ab80cc991d0a09399257139799e37f737794cd49d68a39985b", "spec_path": "examples/diagram-json/spec.md",