Sync Boatstack from Intelligence Flow Labs @ b8bde5fa0b4d (#53)

Co-authored-by: operator-stack-publisher[bot] <operator-stack-publisher[bot]@users.noreply.github.com>

Author: operator-stack-publisher[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/aefd94091a7e1e52b2bb6bd8da177905dde07cd7/labs/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/b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d/labs/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.
 

UPSTREAM.json

@@ -12,7 +12,7 @@
   },
   "files": {
     ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957",
-    "CONTRIBUTING.md": "640e496e306313eb79700c7c99d11bca233b75f771779d44280f5c2e638bcc6f",
+    "CONTRIBUTING.md": "e8d62a646c3c1ef92351af39c9fafc0f6a672ff70b89680cce90a82f0d71f7ee",
     "README.md": "590821a4cf3c4b196d3cfb39c972ccbebef7d4d558df817c1f1e88b4fd7ceb07",
     "assets/boatstack-journey.svg": "9f016fbfd2881675551a44dafa282cbc7510a7091131005be490c2dbe5e4e051",
     "assets/boatstack-mark.svg": "ec96165583b15cfd446c27049d49217973f3e9b1defa5771cc08eec0c9542ce4",
@@ -38,8 +38,8 @@
     "boatstack/cmd/boatstack-helper/main_test.go": "ff73003b6a5157202fa09ddf1129fb13c3d79702b2e05a8721ce5a11bf5ab779",
     "boatstack/delivery.go": "565bc8465252a798124a29874e1aeffff16e9027d1a86715e11b3e4bc0743bd2",
     "boatstack/delivery_test.go": "2545c26389d330a92c11e7b09fb2342101db5d09a825a2a9e81b4ea9eea9407b",
-    "boatstack/export.go": "52124d6d813588ff743ce3352c7392b2ef10f9c51c86ae1422e3053c7e0a697c",
-    "boatstack/export_test.go": "b38875e004c1a0003f8e377b25ac14e9f4898cf949e91f3d9bfd9531a2867d76",
+    "boatstack/export.go": "bbed04156778686599f8c4d07b06a01d217660240e0652f651350b705703e243",
+    "boatstack/export_test.go": "27f9895f39d0958b5b4824193865a8a30333db709e5b91788aff3d49304457ed",
     "boatstack/go.mod": "6086ef1b2a83f5696190dca692c653925f27b61f652f659fd3fca43ed54a1641",
     "boatstack/go.sum": "26c315c867b11b886f3c9402fce7f341f6a9115a5d61f54afbb5e1b1fb5f6017",
     "boatstack/hooks.go": "2b7d899f92efef8a68a160c423a46bcd6fd37daa0eba2ac8ad44ffa3dc5f88c9",
@@ -86,10 +86,10 @@
     "docs/account-recovery-walkthrough.md": "676034974594a7d1a559b24dbed31d7ccc429eb81404b203ca07bbdaa19ec3d3",
     "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6",
     "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79",
-    "docs/evidence-engineered-coding.md": "12f3116604c0fe2a60e79463a063161a8f57fa1da0c0f8d0baffb2e915397f6a",
+    "docs/evidence-engineered-coding.md": "f389b30ca57c1df60475574684166ddfedf21e9bb96516ed10ed262590044bd6",
     "docs/generated-files.md": "136422baf0c7fc2bd5100cfe0ebdb3d9d0705dfd7e7d54bf745dd1037e63492c",
     "docs/getting-started.md": "eacc814fdffdfa3c7d8052b7cd99a79c04da5c75d88d8b44f3fb68d9afec0316",
-    "docs/public-claims.json": "c16189d867ffbb18bbee414e2325c15a93d8b0f48b4fa7d8b57f44188f97724d",
+    "docs/public-claims.json": "2b788ae7cd3f9bd330ec7366ae8dad77ff95faf97cfc650c3699a7ba2efbfb4d",
     "docs/public-surface.md": "713f7a050b5f339cf948299103ef3800417dccfecf2cc1a4166397ea6f978907",
     "docs/research-and-design.md": "d65c66e323037bda5d45aacef5d48afa6bf93da55901378891d235aca3a5684f",
     "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6",
@@ -103,7 +103,7 @@
     "labs/diagram-json/compiled/evidence.md": "1ba1c989ade070a8ef9a508fbd788d100d7292f2dbacbb2bce895468019f619d",
     "labs/diagram-json/compiled/tasks.json": "88f60851abf79d851e9fccc754ff3040034ae595306bc87d64784c19eb403e71",
     "labs/diagram-json/compiled/test-matrix.json": "424657ff505768e50fa113801fd8363364a18269d5297480907a993d44063a39",
-    "labs/diagram-json/plan.lock.json": "38a8a7dcb9d432f21f790f5f3c29c09a5209fd799380ae4cf3d3073851481b65",
+    "labs/diagram-json/plan.lock.json": "c4aaf275ed936ee8a38f7ead4b9c62971b6d4536e2ffa963c963ede5d125304a",
     "labs/diagram-json/plan.md": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51",
     "labs/diagram-json/questions.md": "74733b015002c8a6777c558e7e997fa48c94850b9bd39054fe9366c97ecf728d",
     "labs/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed",
@@ -137,14 +137,15 @@
     "release-notes/2026-07-19-valid-skill-frontmatter.md": "a0a002f7891474d7d1eea49e3234cae5ddbd941158726b83555dc48474181a92",
     "release-notes/2026-07-20-config-schema-migration.md": "99be8fcc408689f559c78bdf39f7161fa7d948846bfc136e3fceed5015841be0",
     "release-notes/2026-07-20-gemini-cli-integration.md": "d829b4fafb3a02dd766e018558b20bf1bc948dd5e337911d6a7c8b54c83c9942",
+    "release-notes/2026-07-20-generic-execution-mode-dx.md": "e16aa73c4ef8da4acb9f8e24706c7dbaf7d416d27e51d147abee1d0219b6d8e0",
     "release-notes/2026-07-20-managed-workspace-lifecycle.md": "e84e9c5a393ca88f9fc14d1f2a99ee9a2a1c525a16d141e9f9981bc9354d8f73",
     "release-notes/2026-07-20-portability-diagram-dark-theme.md": "b06bebec1361b21ef6deb8c8f43168d189803a32588aeb803ea4b441525a77e2",
     "release-notes/2026-07-20-speak-software-standards.md": "a8890ed7eb38868bdf3035572d71785ca89abd3ffc3a314a5dc5315150afe397"
   },
   "generator": "operatorstack/intelligence-flow:boatstack-distribution",
   "schema_version": 1,
   "source": {
-    "commit": "aefd94091a7e1e52b2bb6bd8da177905dde07cd7",
+    "commit": "b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d",
     "path": "labs/12-product-engineering-loop",
     "repository": "operatorstack/intelligence-flow"
   }

boatstack/export.go

@@ -20,6 +20,8 @@ var allowedAdapters = map[string]bool{
 	"github": true,
 }
 
+const executionModeDX = "\n\n**Execution Mode Notice:** Boatstack requires active tool use (such as shell execution) to run its commands and inspect the workspace. If you are currently operating in a Plan Mode, Read-Only Mode, or a state with restricted tool access, you MUST immediately inform the user that Boatstack requires full execution capabilities and ask them to approve exiting that mode or grant execution permissions before you can proceed. Do not attempt to mock or bypass the operation."
+
 var (
 	readCanonical    = ReadCanonical
 	readCanonicalDir = ReadCanonicalDir
@@ -173,7 +175,7 @@ Read @.product-loop/project.json, @.product-loop/artifacts.md, and only the mini
 Use the gate semantics in the canonical workflow. Do not redefine them in this adapter. Auto-plan and plan-gate may create or update Markdown only. Classify authoritative repository facts as DISCOVERED, agent suggestions as PROPOSED, and only explicit human responses as ANSWERED. Every material proposal remains in blocking_questions; never label an agent default as answered. For 1-3 finite questions, use compact keys such as 1a/1b and 2a/2b, suffix exactly one choice per question with (Recommended), and offer r to accept all displayed recommendations. Treat r as explicit human acceptance only when every displayed question has exactly one recommendation; echo the selected mapping before recording the answers. Use the same format with structured question tools or plain text and return WAITING_FOR_INPUT internally. Never silently choose a default. Boatstack leaves implementation tactics open, but completion, approval, and shipping claims require current evidence. During managed delivery, read the active delivery slice, never push or mutate a PR directly, and require slice-scoped test and review receipts before ship-gate. A successful publication activates the next declared slice; parent-plan approval never skips its gates.
 
 Follow the User-facing response contract in @.product-loop/workflow.md. Lead with its mapped plain-language outcome, show only decision-relevant content, end with exactly one `+"`### Next step`"+`, and put machine status, helper output, fingerprints, artifact paths, receipts, and locks inside collapsed `+"`Technical details`"+`. Treat helper names in this command as internal control machinery; do not expose them in the primary response.
-`, operation, operation, preflight, extra)
+`, operation, operation, preflight, extra) + executionModeDX
 }
 
 func claudeOperationSkill(spec claudeSkillSpec, operationBody string) string {
@@ -296,7 +298,7 @@ When the user asks to update Boatstack itself, use /boatstack-update. Release di
 Do not branch behavior on model name, provider, or price; branch on observed work state and evidence.
 Boatstack's repository hooks deny high-confidence irreversible operations across every agent call. There is no in-session bypass. Preserve failed external state, use read-only diagnosis and fix-forward recovery, and leave intentional destructive recovery to an operator-owned surface outside Boatstack.
 `
-		files[fmt.Sprintf(".cursor/rules/%s.mdc", adapterName)], err = GeneratedFrontmatter(rule)
+		files[fmt.Sprintf(".cursor/rules/%s.mdc", adapterName)], err = GeneratedFrontmatter(rule + executionModeDX)
 		if err != nil {
 			return ExportBundle{}, err
 		}
@@ -337,7 +339,7 @@ When the user asks to update Boatstack, run the boatstack-update operation. Neve
 For a managed ship, use the internal pr-context operation with --feature to project the feature spec, accepted decisions, actual committed diff, evidence ledger, review findings, gaps, rollout, and rollback into the required pr.md artifact. Inspect the returned changed files, diff stat, high-risk matches, and the actual diff before writing claims; commits alone are not authoritative. Always include why, what changed, review order, evidence, gaps/risks, rollout/rollback, and collapsed provenance. Add UI evidence, security/privacy, migration, or operations sections only when relevant. For a natural-language request to improve an existing or ad-hoc PR, run pr-context without --feature and use the same reviewer-first format from observed branch facts, but mark unavailable approval or gate evidence as NOT_VERIFIED. Never create or advertise a /pr-brief command. Validate with check-pr and always show the exact title and rendered body before publication. Ask for state-scoped o to open or u to update the PR. Only after the matching shortcut or compatible full reply, commit only pr.md, revalidate the unchanged preview fingerprint, and invoke the internal publish-pr operation with the selected action. It may perform a normal push but never force-push. Any intervening product diff or evidence change invalidates the preview. Keep model attribution inside collapsed provenance. Internal helper names and hashes stay out of the primary response.
 
 If gstack is enabled, use only its namespaced /gstack-* specialist lenses inside Boatstack operations. If Spec Kit is enabled, use it to generate or cross-check artifacts; never invoke speckit.implement to bypass Boatstack's plan approval and build gate.
-	`, adapterName)
+	`, adapterName) + executionModeDX
 	if contains(adapters, "claude") {
 		claudeAdapterSkill := strings.Replace(
 			adapterSkill,

boatstack/export_test.go

@@ -506,6 +506,23 @@ func TestPortableHostAdaptersShareWorkflowAndArtifactContract(t *testing.T) {
 			t.Fatalf("Gemini natural-language router does not declare portable operation %q", operation)
 		}
 	}
+
+	for host, surface := range hostSurfaces {
+		if !strings.Contains(surface, "Execution Mode Notice:") {
+			t.Fatalf("%s router surface is missing the Execution Mode Notice", host)
+		}
+	}
+
+	for _, path := range []string{
+		".cursor/commands/auto-plan.md",
+		".claude/skills/auto-plan/SKILL.md",
+		".gemini/skills/auto-plan/SKILL.md",
+	} {
+		content := string(bundle.Files[path])
+		if !strings.Contains(content, "Execution Mode Notice:") {
+			t.Fatalf("%s is missing the Execution Mode Notice", path)
+		}
+	}
 }
 
 func TestExportRefusesUserOwnedCollision(t *testing.T) {

docs/evidence-engineered-coding.md

@@ -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 [`aefd94091a7e1e52b2bb6bd8da177905dde07cd7`](https://github.com/operatorstack/intelligence-flow/tree/aefd94091a7e1e52b2bb6bd8da177905dde07cd7/labs/12-product-engineering-loop).
+The current moves were derived from the Intelligence Flow benchmark corpus and product-repository studies. The generated source commit is [`b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d`](https://github.com/operatorstack/intelligence-flow/tree/b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d/labs/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/public-claims.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "source_commit": "aefd94091a7e1e52b2bb6bd8da177905dde07cd7",
+  "source_commit": "b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d",
   "statuses": ["verified", "observed", "still_being_evaluated"],
   "claims": [
     {
@@ -12,7 +12,7 @@
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     },
     {
       "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:aefd94091a7e1e52b2bb6bd8da177905dde07cd7"
+      "last_verified_version": "source:b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d"
     }
   ]
 }

labs/diagram-json/plan.lock.json

@@ -6,7 +6,7 @@
   "plan_path": "labs/diagram-json/plan.md",
   "plan_sha256": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51",
   "schema_version": 1,
-  "source_commit": "aefd94091a7e1e52b2bb6bd8da177905dde07cd7",
+  "source_commit": "b8bde5fa0b4d3c44a0f78fb9cdb9775361d1bd5d",
   "source_plan_path": "labs/diagram-json/source-plan.md",
   "source_plan_sha256": "e10593ddaa7522ab80cc991d0a09399257139799e37f737794cd49d68a39985b",
   "spec_path": "labs/diagram-json/spec.md",

release-notes/2026-07-20-generic-execution-mode-dx.md

@@ -0,0 +1,3 @@
+### Append generic execution-mode notice to all agent templates
+
+Boatstack now generates a clear, vendor-agnostic execution mode notice at the end of all exported routers, rules, and commands. This notice guides agents (Gemini, Claude, Cursor, and Codex) when operating in restricted modes (like Plan Mode or Read-Only Mode) to immediately halt and request the user to exit that mode or grant full tool/shell execution permissions, significantly improving Developer Experience (DX) and preventing opaque failures.