Skip to content

Sync Boatstack from Intelligence Flow 3cd11c293b39 #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bigboateng merged 1 commit into from
Jul 16, 2026
Merged

Sync Boatstack from Intelligence Flow 3cd11c293b39 #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/40ebae5dfb3d090812301a438aaac079426edcfc/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/3cd11c293b3903aeac9ff8d8eacd47840d63a02d/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.

Expand Down
68 changes: 41 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

**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 `40ebae5dfb3d090812301a438aaac079426edcfc`](https://github.com/operatorstack/intelligence-flow/tree/40ebae5dfb3d090812301a438aaac079426edcfc/examples/12-product-engineering-loop).
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 `3cd11c293b3903aeac9ff8d8eacd47840d63a02d`](https://github.com/operatorstack/intelligence-flow/tree/3cd11c293b3903aeac9ff8d8eacd47840d63a02d/examples/12-product-engineering-loop).

> **You are free in how you build. Only claims of completion require evidence.**

Expand Down Expand Up @@ -32,11 +32,13 @@ Q2 Stability? versioned schema | internal object dump
Q3 Run data? compact overlay | entire execution trace
```

The accepted answers become observable criteria and tasks—not hidden assumptions:
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."}
Expand Down Expand Up @@ -90,34 +92,46 @@ Ambiguous claims cannot pass unchanged:

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.

The compiler refuses a criterion with no task or verification. Then `/plan-gate` requires a named human and binds approval to content hashes:
The developer-facing transition stays inside the coding host:

```text
/plan-gate
Approve the displayed plan.
Choose the host's normal Build action.
```

`/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.

<details>
<summary>Internal deterministic boundary</summary>

The generated adapter invokes the repository-local helper; users do not need to learn these commands:

```bash
.product-loop/bin/boatstack-helper compile-plan \
--plan .product-loop/features/diagram-json/plan.json \
--out-dir .product-loop/features/diagram-json/compiled

.product-loop/bin/boatstack-helper approve-plan \
--source-plan .product-loop/features/diagram-json/source-plan.md \
--spec .product-loop/features/diagram-json/spec.md \
--plan .product-loop/features/diagram-json/plan.json \
--tasks .product-loop/features/diagram-json/compiled/tasks.json \
--approved-by "Boateng Opoku-Yeboah" \
.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
```

Build work checks that lock first:
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 approve-plan ... --check
PASS: approved plan lock matches the current artifacts
$ .product-loop/bin/boatstack-helper activate-plan ...
PASS: approved Markdown plan activated and locked

# after plan.json changes
$ .product-loop/bin/boatstack-helper approve-plan ... --check
BLOCKED: stale or invalid plan lock: plan
# 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.
</details>

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).

Expand Down Expand Up @@ -165,7 +179,7 @@ irm https://raw.githubusercontent.com/operatorstack/boatstack/main/install.ps1 |

Run the command from the product repository. The installer detects the repository and available coding hosts, previews every generated path, verifies the downloaded helper, and asks whether to add gstack, Spec Kit, both, or core only. Boatstack core requires no Python, Node, Go, or package manager.

After installation, open the chosen host's Plan mode, describe the change, save its plan, and run `/auto-plan`. Boatstack uses the host-exposed active path or discovers exactly one file under `.product-loop/intake/`; an explicit path is only needed to resolve ambiguity. The source plan remains required and hash-checked through `/build`; after build, test, review, and ship gates use the approved lock, actual diff, and evidence instead.
After installation, open the chosen host's Plan mode, describe the change, save its plan, and run `/auto-plan`. Boatstack uses the host-exposed active path or discovers exactly one file under `.product-loop/intake/`; an explicit path is only needed to resolve ambiguity. Auto-plan and plan-gate write Markdown only. After explicit approval, use the host's normal Build transition; `/build` activates and locks the plan before its first code edit. The source plan remains required and hash-checked through `/build`; later gates use the lock, actual diff, and evidence.

## Use Boatstack with gstack and GitHub Spec Kit

Expand All @@ -180,15 +194,15 @@ product intent + repository context
\ /
normalized spec + plan + decisions
|
approval lock -> open build -> evidence gates -> PR
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, deterministic compilation, approval/drift locks, evidence mapping, review/ship gates | The completion and shipping claim itself |
| 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

Expand All @@ -207,11 +221,11 @@ speckit.specify / clarify / plan / tasks / analyze / checklist
explicit /plan-gate
```

`speckit.implement` does not bypass Boatstack's plan lock or `/build` boundary. If Spec Kit changes accepted semantics, Boatstack invalidates the old lock and returns to approval. This preserves Spec Kit's artifact-generation value without allowing a generator to approve or validate its own output.
`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 planning, deterministic approval locking, validation/evidence mapping, test/review gates, and PR preparation. Integration failure is recorded as partial installation and does not roll back the working core.
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:

Expand Down Expand Up @@ -269,8 +283,8 @@ Read the [research and design record](docs/research-and-design.md) and [corpus a

## Context has a budget

The three canonical runtime references currently total approximately **4044 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.
The three canonical runtime references currently total approximately **4521 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.

## Status

Boatstack is an alpha research distribution. It can generate host adapters, compile traceable task/test artifacts, hash-lock explicit approval, detect stale plans, and preserve provenance. The next proof boundary is a paired feature-development evaluation against a plain host harness.
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.
44 changes: 23 additions & 21 deletions UPSTREAM.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"canonical_context": {
"characters": 16173,
"estimated_tokens": 4044,
"characters": 18081,
"estimated_tokens": 4521,
"estimator": "ceil(total characters / 4); compactness signal, not provider billing",
"files": [
"product-engineering-loop/references/workflow.md",
Expand All @@ -11,44 +11,46 @@
},
"files": {
".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957",
"CONTRIBUTING.md": "cf876c19c52a1758c7347c0a27f63c12ef3e49d67066988df638cd09889b88ca",
"README.md": "0aada7f928bd0f1d2dcfd703fe822759a178e0e6a49779370f0c85f3a9d098f7",
"boatstack/SKILL.md": "1c71535962a56c9f9c7841e55e0e44c2988af427929f95e12cd7fcf08ef26686",
"CONTRIBUTING.md": "baaa5828ac493da05a5cf517524175534c318728830e191deb510e492b7d9c0f",
"README.md": "de733eb7d8a15a218cd52d37f510acfca1c3bdccc5085dfce8d9e09ea89d3ba2",
"boatstack/SKILL.md": "56cc1da6dea4fb57bd16d37ec9635eb06676d5e8580511190cddc78cd9e37346",
"boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1",
"boatstack/assets/templates/adr.md": "c577a3c1c1319061f61deb053597e6e853657022185fe28b8f733327e2a78565",
"boatstack/assets/templates/approval.md": "74b0b816703a6dce3c96c8f95f981af910b020b6908e7f76cf5630778637e9f5",
"boatstack/assets/templates/evidence.md": "12dac552bc5373ab443367d5797f41988f14284bcf46d16dfd72015cfddf9ad1",
"boatstack/assets/templates/feature-spec.md": "c7e007cc4295ed4c599642c0587021ef978e729cf0946f6bf3a6c4f01d366ad4",
"boatstack/assets/templates/gaps.md": "911cc2f086104d35071b952950c2ec44258641419f10b2355c594f33eb492cbe",
"boatstack/assets/templates/move.md": "91bfd9a9b9426ac023eb88fd19f4f638190481c1855f1239acc73830528e50f0",
"boatstack/assets/templates/plan-lock.json": "3e44dea05419cf198ee8112e9b9fdff92287edc2480a03fca026560fe929d468",
"boatstack/assets/templates/plan.json": "ff530e27959495aa800a494ebb745cd3703c8bd1c2b6c800c373f5210e89c9af",
"boatstack/assets/templates/questions.md": "86c9bcf51172fe222b7b28bffccaf3da3b1ea0633c7a2348272fdbbd8eea6740",
"boatstack/assets/templates/plan-lock.json": "a51e17bb74aa7cd95daaa70fab646a20374ff4bc1d63468d61c5119da61e930f",
"boatstack/assets/templates/plan.md": "358216e38d41f930c23c526741b718f30100c0071c8373a0c8b765d0e59f3fdf",
"boatstack/assets/templates/questions.md": "5875bbfc32d5a1b326c2a48da7449bb90c87f462a4c3a862173247e5f7ea6415",
"boatstack/assets/templates/test-plan.md": "6db8a9f27dd171fb80222a501cae50eb051e7278c04703fa43b5ff86dd4d2df4",
"boatstack/cmd/boatstack-helper/main.go": "c9238e078fd85540073a284772f7360597e68aa0af86b7d3fc0dbc2c73a198ac",
"boatstack/export.go": "e1dc2d79126e98a8202d93a5fc13049b7186e105724daa93814c7133336e810a",
"boatstack/export_test.go": "f880bc99e78bbb3d8533153abaa63eee39c3d067df0eef2451e622083cce5676",
"boatstack/cmd/boatstack-helper/main.go": "853e60ba22766567afc3f7526260ab70b9056645c5c0500d97a9f3fc0f3a0bf0",
"boatstack/export.go": "7d70967d28032a76e58e083f07f27ad9609b0ab894dd208b1d2f3b726c8cd751",
"boatstack/export_test.go": "8f78c9bb50210161a19878d17775e73ffb591502d6ee11e6428ac436c128fe23",
"boatstack/go.mod": "daf262a00abfe961d8ca266d4b26eea09a6aee73e4c53baaa537a809eaef59f6",
"boatstack/init.go": "6a04d5482748bd3b6a9febdf1723b89f8460144bcd5315d5feda0f82de477f07",
"boatstack/init_test.go": "7ca705f014f6bb22f7ea61a1eb370b98d1bc722f77a73711749375fb7a08ea14",
"boatstack/integrations.go": "75b39ce2e662fccd66bf4b9bff0e097a4db558f23b3aa1d9bc83a5fc6373444c",
"boatstack/plan.go": "8787fb1204fc7a81a2c81e39e4469faab637fd180297dce220eab1e48bf7787d",
"boatstack/plan_test.go": "5afab86a9b7f749652cfd31675f5a9bd1ec3e03086300923dd7d47765cd80963",
"boatstack/references/artifacts.md": "3aa4b2abc4195656b011cbfdd61b8e05759a0b67b37590be3a028c21b8a453e6",
"boatstack/plan.go": "8250ee93f91b4dd60e3788636ab79f32c626ace6daef6677fdc6338858f89a52",
"boatstack/plan_test.go": "f95ce7a38276f957064ee83901566c84ebf3eec0683e81794f823dc446b2ac54",
"boatstack/references/artifacts.md": "22b6cc596b65c8c2a22b0f3a692ca16a808fa495dad0b4453d23ea734978a2b7",
"boatstack/references/failure-moves.md": "2d7d3988c70718e9cc02104f9899a00208173e2f654d1046edd22079f4d46f41",
"boatstack/references/portability.md": "fb683095991bb0cb06ec56fb8884c49038b283172a7d2f8b203483b7cacb4bae",
"boatstack/references/workflow.md": "b8262570751ea73cf40cf9de76fc2e6acf1303657d1956b6957ca9af7034fbb0",
"boatstack/references/workflow.md": "0b22fbe168aa31a3ac2832f2439367224aedd2b59468941ee45092b2c1ada1a9",
"boatstack/runtime.go": "66c02aa0b6e9c031c26799b86dfbcb26df74487cc26b32f7fb85e38707eeec31",
"docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6",
"docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79",
"docs/evidence-engineered-coding.md": "2c2b9cb428d3e75b8463d17099ec254afd204367cdc6f8a2214c9def97d8c2a9",
"docs/research-and-design.md": "fc9c517f2783489cbbc4de5ad020a4e4e5bb542c7092b13b317a1893a3415cb4",
"docs/evidence-engineered-coding.md": "453536fa767b98e4671ba885375a5f9af19cb95adb88444691e6e8905966fecf",
"docs/research-and-design.md": "67dc454f0d13e0e2809f49e910f7847457fa78f03c4cef6fb0138f6039a57c4f",
"docs/validation-and-evidence.md": "3b5ed588bd44c5568f0c313be0dfaa411e959dc184fe886dfd0a81aee9fd25cc",
"examples/diagram-json/README.md": "fbb4721434e6110bbef84813c244132bbe7ae0e9e0cd535b6871e3359bcd4559",
"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.json": "df1b205517cf7dbdf5c5db65a342622922bd959a5ba885326888f6dd2b9c50d3",
"examples/diagram-json/plan.lock.json": "c904d4873bf678198dc2d7aba4e90e278385d0266e8bf8bc54334d3f764f1a1a",
"examples/diagram-json/plan.lock.json": "81617b3d642c50734c4b7188d639a244f344da16b5e35c6d0e0af8bd354efe37",
"examples/diagram-json/plan.md": "3ad35cc3cbe48306e7ee401bd9e9047d25e46c8a6fe9679aa1b3f5e96ceea292",
"examples/diagram-json/questions.md": "1a0050041cac0a8d53e6ebfe04cbec4a298cdc8c50efeeb6fa15aeb663c5ec76",
"examples/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed",
"examples/diagram-json/source-plan.md": "e10593ddaa7522ab80cc991d0a09399257139799e37f737794cd49d68a39985b",
Expand All @@ -60,7 +62,7 @@
"generator": "operatorstack/intelligence-flow:boatstack-distribution",
"schema_version": 1,
"source": {
"commit": "40ebae5dfb3d090812301a438aaac079426edcfc",
"commit": "3cd11c293b3903aeac9ff8d8eacd47840d63a02d",
"path": "examples/12-product-engineering-loop",
"repository": "operatorstack/intelligence-flow"
}
Expand Down
Loading
Loading