Sync Boatstack from Intelligence Flow 1a67b309b53d

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.

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"
   }

docs/account-recovery-walkthrough.md

@@ -1,59 +1,61 @@
-<!-- Generated from operatorstack/intelligence-flow. Edit the upstream product-loop source, not this file. -->
+<!-- Generated from operatorstack/intelligence-flow. Edit the upstream public source, not this file. -->
 
-# 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).

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.