Sync Boatstack from Intelligence Flow c6770c227ed9 (#23)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 # Contributing
 
-Boatstack is a generated content distribution. Propose changes to workflow semantics, templates, evidence rules, or generated presentation in [Intelligence Flow](https://github.com/operatorstack/intelligence-flow/tree/16e771775417be997b7fc17e1b1b28d700780899/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/c6770c227ed9c7b4e3063663c014447c3b3c081e/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.
 

README.md

@@ -8,11 +8,13 @@
 
 <p align="center"><strong>Build freely. Prove it. Ship.</strong></p>
 
-## Your product development flow—not your coding agent's
+## A delivery harness for AI coding agents
 
-<!-- boatstack-claim:portable-product-flow -->Boatstack gives your repository one path from idea to PR. Use that path from Cursor, Codex, or Claude Code, with the model and specialist skills that fit the work. Plans, decisions, gaps, evidence, and review findings stay with the project.
+<!-- boatstack-claim:portable-product-flow -->Boatstack connects the work from an idea to a reviewed PR. Keep using Cursor, Codex, or Claude Code, with the models and specialist skills that fit the work. Boatstack keeps the plan, decisions, gaps, tests, review findings, and project context connected along the way.
 
-Change the tool without rebuilding how you ship or redefining what “done” means. Boatstack carries the workflow and saved project state—not an agent's private chat history or a command already in progress.
+The agent remains free to build. Before it says the work is done, Boatstack asks for the approval, tests, review, and recorded evidence appropriate to the change.
+
+**Your product development flow stays with the repository—not the coding agent.** Change tools without rebuilding how you ship or redefining what “done” means. Boatstack carries the workflow and saved project state—not an agent's private chat history or a command already in progress.
 
 <p align="center">
   <img src="assets/boatstack-portability.svg" width="900" alt="Coding agents, models, and specialist skills feed one repository-owned Boatstack flow that produces a reviewed pull request and useful context for the next feature">
@@ -50,25 +52,29 @@ When you are ready, that guidance moves through `/plan-gate` → `/build` → `/
   <img src="assets/boatstack-journey.svg" width="960" alt="One feature moves from idea through planning, approval, building, tests, review, and pull request; its retained plans, decisions, gaps, evidence, and code state combine with the next idea to create the next plan">
 </p>
 
-## What Boatstack guides
+## Features
 
-| Without Boatstack | With Boatstack |
-|---|---|
-| The agent guesses an important product decision | It asks, records your answer, and waits for approval |
-| “Tests passed” is treated as proof of everything | Each promised outcome names the check that can disprove it |
-| A failed external operation leads to a risky reset | High-confidence destructive recovery is stopped before execution |
-| The PR loses the reasoning behind the work | Decisions, evidence, gaps, rollout, and rollback stay attached |
-| Every feature starts from an empty conversation | Useful state from the previous feature informs the next plan |
+- **A guided path from idea to PR.** Start with `/auto-plan`; Boatstack presents one next action at a time through planning, approval, build, validation, review, and PR preparation.
+- **Human decisions stay human.** Material product questions remain open until a person answers them, and implementation waits for explicit approval.
+- **Evidence tied to the promise.** Tests and checks map to the outcomes the change claims to deliver instead of treating one green command as proof of everything.
+- **Context that survives the feature.** Plans, decisions, accepted gaps, evidence, review findings, and code state can inform the next feature rather than disappearing with the chat.
+- **Safer agent execution.** High-confidence destructive recovery is stopped before execution; phased work is gated and published one approved delivery slice at a time.
+- **Reviewer-ready pull requests.** Boatstack carries the reason, actual changes, validation, risks, gaps, rollout, and rollback into a focused PR brief.
+- **Portable across your AI stack.** Cursor, Codex, Claude Code, different model tiers, and specialist skills use the same repository-owned delivery contract.
+- **Repository-friendly maintenance.** Linked worktrees restore their verified runtime automatically, while Boatstack updates stay isolated in reviewable infrastructure PRs.
 
 You remain free to build however the work requires. Boatstack governs claims of approval, completion, review, and shipping—not the implementation technique.
 
-## Use the tools that fit the work
+## How Boatstack fits into your AI stack
 
-- **Cursor, Codex, and Claude Code:** portable repository adapters expose the same workflow.
-- **Models:** choose a lower-cost, general, or frontier model without silently changing the completion standard.
-- **Skills:** add specialist guidance such as React best practices. Boatstack can also use optional gstack and GitHub Spec Kit outputs.
+| Part | Its job |
+|---|---|
+| **Coding agent** — Cursor, Codex, or Claude Code | Executes the work in your repository |
+| **Model** — lower-cost, general, or frontier | Reasons, writes, and evaluates within the agent |
+| **Skill** — React guidance, gstack, Spec Kit, or another specialty | Adds expertise for a particular kind of work |
+| **Boatstack** | Carries the delivery path, saved context, and proof of completion across them |
 
-In technical terms, Boatstack is a repository-local software-delivery harness for AI coding agents. Skills contribute expertise; models perform work; Boatstack keeps the product-development path and evidence contract consistent.
+Boatstack does not replace the agent, model, or skills. It is the repository-local delivery harness that keeps their work connected to the product decision and the standard for calling it complete.
 
 > **Designed for model flexibility · Quality uplift evaluation in progress**
 

UPSTREAM.json

@@ -12,11 +12,11 @@
   },
   "files": {
     ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957",
-    "CONTRIBUTING.md": "e1f50278dcd1aa38b8d8ea162b760dafc1283b325f3769049c9b350abf93bafb",
-    "README.md": "ebd2c064401feeb2a7381775f9155285997d196a30ad5f4c59c2f3bbe6e14419",
+    "CONTRIBUTING.md": "71bf34b51561d2e1af39cf8bbeaabb86dd9b20646b90858b68b2ef9e1a324542",
+    "README.md": "a7a74bbf280912043c93e1e59f47866c10275520a256c59747c68d678fef0af5",
     "assets/boatstack-journey.svg": "c1f7fe2741f5e9ca66bb3fe9b103e6364ba5acbca8b7a8054768ffd85cf325ea",
     "assets/boatstack-mark.svg": "c46e935f06fcfde3b37abfd579c1963b765b2337a0fa993f9538c9b652297e39",
-    "assets/boatstack-portability.svg": "38c61b51959ebf5378b1857cdaacfae843a5ffc35350685fc6d1d2b8b9e165a3",
+    "assets/boatstack-portability.svg": "888b51cda1a72af0323a744dee89cc62f5d3f412f2a86f893db7c147f96b2f53",
     "boatstack/SKILL.md": "2c4547c504ebac01b14fe6cbed97b5ea114b685cb9b43b68ffa053ebe0aeb0c4",
     "boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1",
     "boatstack/assets/templates/adr.md": "c577a3c1c1319061f61deb053597e6e853657022185fe28b8f733327e2a78565",
@@ -66,11 +66,11 @@
     "docs/account-recovery-walkthrough.md": "acd3558a95f48004f18a0590670de496e1cc9f0cd1d187f924615497f57e1d6f",
     "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6",
     "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79",
-    "docs/evidence-engineered-coding.md": "d12239081a9e6486cf7e8354321afa197fe94c194d29469b614e905440788869",
+    "docs/evidence-engineered-coding.md": "2dfc75cc85b5250e2810bdeeffd03404e5545ab221365115c539202dbc9e8981",
     "docs/generated-files.md": "7b2e8c10a35aa351fb87753492ed3cadb05011002d2fd6ffeb1951c356f6b286",
     "docs/getting-started.md": "9ecd9e543862e4bcf139be52de113c548708a2a5707c3c09233fd1605eda86d0",
-    "docs/public-claims.json": "cf2c6fdc04e25d72a59fa87d5549ca02bc4c01bd3bb971bb5eed3ad4c61a36df",
-    "docs/public-surface.md": "422696611bdd52fbac2baf6723a277fa8c451601a9f66774bde1529efdc2abab",
+    "docs/public-claims.json": "f51061537b76bb7f76219dd5b63b6ad88cadf84092f742ba5fec290f444f1ee9",
+    "docs/public-surface.md": "43232ab36e8d62a31b2bb37b6800df77d8b4e2e22ef4779f0c7f836fb9125f14",
     "docs/research-and-design.md": "d65c66e323037bda5d45aacef5d48afa6bf93da55901378891d235aca3a5684f",
     "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6",
     "docs/troubleshooting.md": "a3314d0eb97643534415f3c19f1763fd80ff6bb5e98c53b646e447e0b31c4829",
@@ -81,7 +81,7 @@
     "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": "663ae19ea715dbd04e3d553c5af615241e3f0ab98d8ba1ffd7a83dcd11c96471",
+    "examples/diagram-json/plan.lock.json": "4bf3b716db39d0503fca784ea2c0eabd873d26d71e4569cf2ff5c175c88459db",
     "examples/diagram-json/plan.md": "3ad35cc3cbe48306e7ee401bd9e9047d25e46c8a6fe9679aa1b3f5e96ceea292",
     "examples/diagram-json/questions.md": "1a0050041cac0a8d53e6ebfe04cbec4a298cdc8c50efeeb6fa15aeb663c5ec76",
     "examples/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed",
@@ -90,13 +90,14 @@
     "install.ps1": "960b2b20b406bb2878a560e9ace53fe7226bc510be6ee8466ce4e608beb5625a",
     "install.sh": "939e604aa153b454e7fa1cbbe50a88be17782ea9df35d1bbb5615c737ed6f86e",
     "project.example.json": "d1f7aa3cff0b55ede79500bd2ca710bb99cb2ae579f0a058dc00934accf03d33",
+    "release-notes/2026-07-17-delivery-harness-framing.md": "6fccbe7efdb288f5eca7e824ee5e44ad6b30a34f312eb997dca6aa44c55b26cb",
     "release-notes/2026-07-17-phase-scoped-delivery.md": "bfc8edd30a67daf5940ad4ceceebf81d01d62914ebeabb7073985c53f13df2ff",
     "release-notes/2026-07-17-visible-release-messages.md": "c93e8c812528a983502263e35d66c86a265d6ccba8203f393788c069b3fa6606"
   },
   "generator": "operatorstack/intelligence-flow:boatstack-distribution",
   "schema_version": 1,
   "source": {
-    "commit": "16e771775417be997b7fc17e1b1b28d700780899",
+    "commit": "c6770c227ed9c7b4e3063663c014447c3b3c081e",
     "path": "examples/12-product-engineering-loop",
     "repository": "operatorstack/intelligence-flow"
   }

assets/boatstack-portability.svg

@@ -146,6 +146,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 [`16e771775417be997b7fc17e1b1b28d700780899`](https://github.com/operatorstack/intelligence-flow/tree/16e771775417be997b7fc17e1b1b28d700780899/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 [`c6770c227ed9c7b4e3063663c014447c3b3c081e`](https://github.com/operatorstack/intelligence-flow/tree/c6770c227ed9c7b4e3063663c014447c3b3c081e/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.

docs/evidence-engineered-coding.md

@@ -1,18 +1,18 @@
 {
   "schema_version": 1,
-  "source_commit": "16e771775417be997b7fc17e1b1b28d700780899",
+  "source_commit": "c6770c227ed9c7b4e3063663c014447c3b3c081e",
   "statuses": ["verified", "observed", "still_being_evaluated"],
   "claims": [
     {
       "id": "portable-product-flow",
-      "public_claim": "Boatstack exposes one product-development workflow across Cursor, Codex, and Claude Code while keeping its durable planning, decision, gap, evidence, and review state in the repository.",
+      "public_claim": "Boatstack is a repository-local delivery harness that exposes one product-development workflow across Cursor, Codex, and Claude Code while keeping its durable planning, decision, gap, evidence, and review state in the repository.",
       "status": "verified",
       "originating_observation": "Coding-host configuration, model choice, and specialist skills otherwise become separate places where a product-development process and its working state can fragment.",
       "safeguard": "Portable host adapters project one workflow contract while canonical feature artifacts remain repository-owned and model-neutral.",
       "readable_evidence": "why-these-steps.md#portable-workflow-and-state",
       "implementation": ["../boatstack/export.go", "../boatstack/references/artifacts.md", "../boatstack/references/workflow.md"],
       "verification": ["../boatstack/export_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "human-decisions",
@@ -23,7 +23,7 @@
       "readable_evidence": "why-these-steps.md#human-decisions",
       "implementation": ["../boatstack/references/workflow.md", "../boatstack/plan.go"],
       "verification": ["../boatstack/plan_test.go", "../boatstack/planning_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "validation-provenance",
@@ -34,7 +34,7 @@
       "readable_evidence": "why-these-steps.md#validation-provenance",
       "implementation": ["validation-and-evidence.md", "../boatstack/plan.go"],
       "verification": ["../boatstack/plan_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "irreversible-operations",
@@ -46,7 +46,7 @@
       "readable_evidence": "why-these-steps.md#irreversible-operations",
       "implementation": ["safety.md", "../boatstack/safety.go", "../boatstack/hooks.go"],
       "verification": ["../boatstack/safety_test.go", "../boatstack/hooks_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "reviewer-ready-pr",
@@ -57,7 +57,7 @@
       "readable_evidence": "why-these-steps.md#reviewer-ready-pr",
       "implementation": ["../boatstack/pr.go", "getting-started.md"],
       "verification": ["../boatstack/pr_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "phase-scoped-delivery",
@@ -68,7 +68,7 @@
       "readable_evidence": "why-these-steps.md#phase-scoped-delivery",
       "implementation": ["../boatstack/delivery.go", "../boatstack/safety.go", "../boatstack/hooks.go", "../boatstack/references/workflow.md"],
       "verification": ["../boatstack/delivery_test.go", "../boatstack/pr_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "model-neutral-contract",
@@ -79,7 +79,7 @@
       "readable_evidence": "why-these-steps.md#model-choice-and-budget",
       "implementation": ["research-and-design.md", "../boatstack/references/workflow.md"],
       "verification": ["../boatstack/export_test.go", "../boatstack/planning_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "cross-model-failures",
@@ -90,7 +90,7 @@
       "readable_evidence": "why-these-steps.md#model-choice-and-budget",
       "implementation": ["research-and-design.md"],
       "verification": ["benchmark-corpus-audit.md", "benchmark-submission-audit.md"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "lower-cost-outcomes",
@@ -101,7 +101,7 @@
       "readable_evidence": "why-these-steps.md#model-choice-and-budget",
       "implementation": ["research-and-design.md"],
       "verification": ["benchmark-corpus-audit.md", "benchmark-submission-audit.md"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "git-worktree-activation",
@@ -112,7 +112,7 @@
       "readable_evidence": "why-these-steps.md#git-worktree-activation",
       "implementation": ["../boatstack/runtime_cache.go", "../boatstack/hooks.go"],
       "verification": ["../boatstack/runtime_cache_test.go", "../boatstack/hooks_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     },
     {
       "id": "visible-updates",
@@ -123,7 +123,7 @@
       "readable_evidence": "why-these-steps.md#visible-updates",
       "implementation": ["../boatstack/update.go", "../boatstack/init.go"],
       "verification": ["../boatstack/update_test.go", "../boatstack/init_test.go", "../boatstack/export_test.go"],
-      "last_verified_version": "source:16e771775417be997b7fc17e1b1b28d700780899"
+      "last_verified_version": "source:c6770c227ed9c7b4e3063663c014447c3b3c081e"
     }
   ]
 }

docs/public-claims.json

@@ -8,7 +8,7 @@ Boatstack's README is a product-builder homepage, not the complete manual. Publi
 
 The homepage must answer, in order:
 
-1. What will Boatstack help me achieve?
+1. What is Boatstack, and what will it help me achieve?
 2. What remains portable when I change tools, models, or skills?
 3. How do I install and start it?
 4. What will using it feel like?
@@ -32,6 +32,7 @@ Do not use “proven,” “optimal,” performance uplift, cost reduction, or s
 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`;
+- name the delivery-harness category before asking readers to adopt its philosophy;
 - design from real Boatstack content rather than a generic AI landing-page pattern;
 - use one dominant product journey and progressive disclosure;
 - keep portability diagrams subordinate to the product journey and focused on real hosts, models, skills, and repository state;