Sync Boatstack from Intelligence Flow Labs @ 569709dad427

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/bbed9588e74016250e3cf8968e70bdd375afb863/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/569709dad427c28f7e866a1bd72ca0312d7b2f1b/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.
 

README.md

@@ -50,6 +50,8 @@ Install Boatstack in its own infrastructure PR and merge it before starting a fe
 
 That is all you need to learn up front. Boatstack shows one next action at a time through approval, building, tests, review, and PR preparation.
 
+When you return after an interruption, run `/boatstack-next` in Claude Code or Cursor, or `$boatstack next` in Codex. Boatstack reports the repository-verified stage and one next action without changing state; if nothing remains active, it reports **Feature complete**.
+
 In Claude Code and Cursor, that guidance moves through `/plan-gate` → `/build` → `/test-gate` → `/review-gate` → `/ship-gate`. In Codex, use the same operation names after `$boatstack`.
 
 > The diagram shows what Boatstack guides—not a checklist you need to memorize.
@@ -72,6 +74,7 @@ Receipts remain as history; published corrections become linked deliveries.
 ## Features
 
 - **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.
+- **Instant orientation after a break.** `boatstack next` reconstructs the verified stage without treating chat or a running process as workflow evidence.
 - **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.

UPSTREAM.json

@@ -1,7 +1,7 @@
 {
   "canonical_context": {
-    "characters": 39803,
-    "estimated_tokens": 9951,
+    "characters": 40064,
+    "estimated_tokens": 10016,
     "estimator": "ceil(total characters / 4); compactness signal, not provider billing",
     "files": [
       "product-engineering-loop/references/workflow.md",
@@ -12,12 +12,12 @@
   },
   "files": {
     ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957",
-    "CONTRIBUTING.md": "6c29c112507af7f6661d7d3485da1f7974462b85f54b1075a014fdb5b9a4e546",
-    "README.md": "7d1473b75566901899b49a9f98cd5446ac40d2fceee3f168c5e6869c742e0b4a",
+    "CONTRIBUTING.md": "4512dadf5f809ce83323766bd62b8b85498718273d21a498635bfc0aca1afbc0",
+    "README.md": "b624739fd939fe1e94c2c75bc5e30f9517214fdd4c518b8830975257cd22f072",
     "assets/boatstack-journey.svg": "c1f7fe2741f5e9ca66bb3fe9b103e6364ba5acbca8b7a8054768ffd85cf325ea",
     "assets/boatstack-mark.svg": "ec96165583b15cfd446c27049d49217973f3e9b1defa5771cc08eec0c9542ce4",
     "assets/boatstack-portability.svg": "ce648f5581d16586d25824d3a8132ef1b3d88b73329179173120129d4f74fd24",
-    "boatstack/SKILL.md": "9443685e255a59de2f5e58928051b4f7385f7401831300b78376d48e41024ba1",
+    "boatstack/SKILL.md": "a6dc11f9010d2029d7ed1ee3f8f1555988c8ec7e603b6eb83b48ed6c7748af5d",
     "boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1",
     "boatstack/assets/templates/adr.md": "c577a3c1c1319061f61deb053597e6e853657022185fe28b8f733327e2a78565",
     "boatstack/assets/templates/approval.md": "74b0b816703a6dce3c96c8f95f981af910b020b6908e7f76cf5630778637e9f5",
@@ -31,18 +31,20 @@
     "boatstack/assets/templates/test-plan.md": "6db8a9f27dd171fb80222a501cae50eb051e7278c04703fa43b5ff86dd4d2df4",
     "boatstack/atomic_unix.go": "89f2723361591de2bb8bd22ce7e34ec529d3278509f0df78fd5c4a7d4140fbe9",
     "boatstack/atomic_windows.go": "cefd775cbe7e7c3bd8a3f5673b11cdd784c6d3ebd6de7dcb8f39406b0bee511f",
-    "boatstack/cmd/boatstack-helper/main.go": "fc979a21007107f6a2f52a2c1eb82c35be5dbe97a775a908e0d1ebc25864f040",
+    "boatstack/cmd/boatstack-helper/main.go": "dc30a087003f5a1e432d69052178a7594d544b91a75cb0b99881a6f67c451260",
     "boatstack/delivery.go": "907a0ff8dc3e6120387eef3c7d97cdadb0b9dd8f788cb39e149aa7a6c4a6260a",
     "boatstack/delivery_test.go": "744d166757deafe5b9fc4f66b79b324de43dcc36a26a317572eaec73a8b21044",
-    "boatstack/export.go": "72ed801fcf52fc93e8446dd3b7d205d7ef8a0530b33f4e02891f7290bc243343",
-    "boatstack/export_test.go": "8f04947a5e1723df21f068b14ba295b0281a04b5037d251be0315100bdce65e8",
+    "boatstack/export.go": "c78647482118b80eb6e8283a3939234d400f324f9f576d069317dfb7d2046ed3",
+    "boatstack/export_test.go": "fb6d85a984e5e03e21dcb0878fc89dc6ec9ea5e12467a21495287784bf31bf6e",
     "boatstack/go.mod": "57c377eccea51372d6664de4169e2ca45806b046f7e8a98a1e35a9eb454b4b8d",
     "boatstack/hooks.go": "1d5d8c4bf7e6e867c8bf07e391d86158347269f856647a5d256f345bbb8d3c96",
     "boatstack/hooks_test.go": "c3f359416ea53f258d8747d0247381e8946efd4d4a5bcf072c4147f885475ad3",
-    "boatstack/init.go": "3bc5b94f662c855f32ccf7db021d4783bad75e3c8c2ed7b384e3a9c60ccd4096",
-    "boatstack/init_test.go": "090cdde8541459330774e6b7ba17f6a0fa2c44e3a4dc7151dccb5d53b535a482",
+    "boatstack/init.go": "fb863a68a6cced5bd2dcf9cd8ca53f0dab7ef0309830269efd985ad8b8a92059",
+    "boatstack/init_test.go": "46ef98d955224d7744a5d67798bbc001f2d4c2c6aa2ac8a802c56e91a3ad8fb8",
     "boatstack/init_transaction.go": "112456c4e1c4db54c4137bcf4f7a9a9e63399a6f5971e9b3dc952d0c4b2aa4b6",
     "boatstack/integrations.go": "75b39ce2e662fccd66bf4b9bff0e097a4db558f23b3aa1d9bc83a5fc6373444c",
+    "boatstack/next.go": "3d3bad7aecc94f2507432393a0bee0e71d4e85a6017f858aafe684c5ec4bc84b",
+    "boatstack/next_test.go": "79ea79666065d8e100a86577bec00b427208cbf05fd6493cd2e0816bb54da38f",
     "boatstack/plan.go": "6a8a6bf3352749516b65748c413c5d14d3499897570902aff707ba3de05bfc42",
     "boatstack/plan_test.go": "006cdc6681f77e579c5a0f709e30ede759c337132d4f2f5193b7b79b29bd7149",
     "boatstack/planning.go": "3a26417a295e5dfc2b6dcac702287c04b6053e7b74215858a4ea11cf9f9dadfe",
@@ -53,7 +55,7 @@
     "boatstack/references/failure-moves.md": "1d35126348d0b681976e8819665e16fd745fd65eca271492603cb80aab75bf49",
     "boatstack/references/irreversible-operation-boundary.md": "2a695f2d7de95cfc8750f107bef9c86581712aa1f02e7233b69b850d8c2af42e",
     "boatstack/references/portability.md": "fb683095991bb0cb06ec56fb8884c49038b283172a7d2f8b203483b7cacb4bae",
-    "boatstack/references/workflow.md": "6794ef2899e3cde7f8cdf182b65def8e371ae3ec3d38cc3cbe2009adb4321512",
+    "boatstack/references/workflow.md": "c604f5e6372a1f32adf4e49360395bfba6869a249db2e077cf678792c0241eac",
     "boatstack/release.go": "fa2ac926df89c90c5844e938a2e02d4b8dbbaefbf85bb7a1a89fc51690bea520",
     "boatstack/release_test.go": "5cf2d76fe9b836a91ca68eba53d5585e2c4be5b9421aaf939ea0723063a24690",
     "boatstack/runtime.go": "f393745950e8ba2da7e25d5539ad536a6239a10c17109224bad20cf48445c380",
@@ -69,10 +71,10 @@
     "docs/account-recovery-walkthrough.md": "676034974594a7d1a559b24dbed31d7ccc429eb81404b203ca07bbdaa19ec3d3",
     "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6",
     "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79",
-    "docs/evidence-engineered-coding.md": "d9397b0ddb7ede2080a1a4d703b3272dcf31080cfc0f7b1cc732c847145386ee",
+    "docs/evidence-engineered-coding.md": "9a6e1770ed903a22ade4be804a35e5fc0a557d369b438b449cce967b761f6943",
     "docs/generated-files.md": "136422baf0c7fc2bd5100cfe0ebdb3d9d0705dfd7e7d54bf745dd1037e63492c",
-    "docs/getting-started.md": "4ef77719a01a2dbe98c5154d58fc03f51797ae0ef39a09d8804fe0708b8cc920",
-    "docs/public-claims.json": "67f2b7c4a288ba11338b11e5db2cb7efa7e498c42dcc3264da641ecbadd59f2a",
+    "docs/getting-started.md": "2a642a8ef072502f1a099e211cb599a0179023d1b48b41b4d6b407881494e594",
+    "docs/public-claims.json": "e68306b85634d7868ca9697da1e7491fd72abe0ba3eb0706a958b35b06930afb",
     "docs/public-surface.md": "713f7a050b5f339cf948299103ef3800417dccfecf2cc1a4166397ea6f978907",
     "docs/research-and-design.md": "d65c66e323037bda5d45aacef5d48afa6bf93da55901378891d235aca3a5684f",
     "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6",
@@ -86,7 +88,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": "4fc2cba6a3a4bbe37d6e3591b583c023dccc8fff778ec00fd2c8ef789d6a6b0e",
+    "labs/diagram-json/plan.lock.json": "50e07d4290abd9c122a300f7f5aa443d8e829ea5010abbf8ddf0711d2497b576",
     "labs/diagram-json/plan.md": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51",
     "labs/diagram-json/questions.md": "74733b015002c8a6777c558e7e997fa48c94850b9bd39054fe9366c97ecf728d",
     "labs/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed",
@@ -105,13 +107,14 @@
     "release-notes/2026-07-18-harbor-lab-namespace.md": "6419c049e5a3024c5a8604e4d9fb241c27ceb80bf1d4cc62f66d1a0eaf09ea21",
     "release-notes/2026-07-18-host-hook-migrations.md": "1c9f81d9318854214f72802045e8e39c9ca45435af0f9d2c28fcf4ff4c1e0071",
     "release-notes/2026-07-18-intelligence-flow-labs.md": "b236dddcf22dab718698b05c5dcf162ffddf9f5b53ea98468fd49b342d75edb9",
+    "release-notes/2026-07-18-next-stage.md": "42ac8e9e45303fe5609cdd3fde10ca69ed349b2d4948445ed91d0e49d5c769b0",
     "release-notes/2026-07-18-safety-sql-boundaries.md": "32011ca3d02a371e8f3f2899ffb34df3af0843d18d25e7db95fbca32c2dcf18c",
     "release-notes/2026-07-18-stacked-bar-mark.md": "c4d5bd5fb89c280d7fba015384fd795fcb8c31ffe501078aa55a90cbcf66ba7b"
   },
   "generator": "operatorstack/intelligence-flow:boatstack-distribution",
   "schema_version": 1,
   "source": {
-    "commit": "bbed9588e74016250e3cf8968e70bdd375afb863",
+    "commit": "569709dad427c28f7e866a1bd72ca0312d7b2f1b",
     "path": "labs/12-product-engineering-loop",
     "repository": "operatorstack/intelligence-flow"
   }

boatstack/SKILL.md

@@ -12,6 +12,7 @@ Build the smallest complete product slice that can be independently verified. Im
 Map the request to one operation:
 
 - `init`: inspect a repository and create or update `.product-loop/project.json`.
+- `next`: report the verified current stage and exactly one next action without changing workflow or repository state.
 - `auto-plan`: refine a saved host Plan-mode file into a reviewable draft feature package; refuse when that file is absent.
 - `plan-gate`: validate the Markdown draft, present it for explicit human acceptance, and record that acceptance in Markdown.
 - `build`: activate the approved Markdown plan, then implement only the active delivery slice's tasks.
@@ -25,6 +26,10 @@ Map the request to one operation:
 
 For the full state machine, read [workflow.md](references/workflow.md). For artifact meanings and templates, read [artifacts.md](references/artifacts.md).
 
+## Report what is next
+
+Run the project-local helper's read-only `next-status --repo . --json` inspection. Repository artifacts, managed delivery state, and gate receipts are evidence; conversation, terminal, worktree, and process observations are context only. Never run the returned operation automatically. If nothing remains active in an initialized repository, report **Feature complete** with **No action required**. If state is ambiguous or stale, name the blocker instead of choosing by recency.
+
 ## Enforce the irreversible-operation boundary
 
 Read [irreversible-operation-boundary.md](references/irreversible-operation-boundary.md). Project hooks hard-deny high-confidence destructive shell and MCP operations on every supported agent call. Never request or invent an in-session bypass. After an external-write failure, preserve state, use read-only diagnosis, retain the immutable target boundary, and choose only proven transactional retry or fix-forward recovery. Source edits may be reviewed, but an executable destructive capability blocks activation and every later gate.

boatstack/cmd/boatstack-helper/main.go

@@ -302,6 +302,29 @@ func deliveryStatusCommand(arguments []string) int {
 	return 0
 }
 
+func nextStatusCommand(arguments []string) int {
+	flags := flag.NewFlagSet("next-status", flag.ContinueOnError)
+	repo := flags.String("repo", ".", "repository whose Boatstack stage should be inspected")
+	jsonOutput := flags.Bool("json", false, "print the versioned structured status")
+	if err := flags.Parse(arguments); err != nil {
+		return 2
+	}
+	status, err := boatstack.ResolveNext(*repo)
+	if err != nil {
+		return fail(err)
+	}
+	if *jsonOutput {
+		value, marshalErr := boatstack.MarshalJSON(status)
+		if marshalErr != nil {
+			return fail(marshalErr)
+		}
+		fmt.Print(string(value))
+	} else {
+		fmt.Print(boatstack.FormatNextStatus(status))
+	}
+	return 0
+}
+
 func recordChangeCommand(arguments []string) int {
 	flags := flag.NewFlagSet("record-change", flag.ContinueOnError)
 	options := boatstack.ChangeObservationOptions{}
@@ -489,7 +512,7 @@ func publishPRCommand(arguments []string) int {
 
 func run() int {
 	if len(os.Args) < 2 {
-		fmt.Fprintln(os.Stderr, "usage: boatstack-helper <init|update|check-update|release-classify|next-patch|export|check-source-plan|planning-write|check-plan|record-approval|activate-plan|delivery-status|record-change|record-delivery-gate|check-safety|safety-hook|pr-context|check-pr|publish-pr|doctor|version>")
+		fmt.Fprintln(os.Stderr, "usage: boatstack-helper <init|update|check-update|release-classify|next-patch|export|check-source-plan|planning-write|check-plan|record-approval|activate-plan|delivery-status|next-status|record-change|record-delivery-gate|check-safety|safety-hook|pr-context|check-pr|publish-pr|doctor|version>")
 		return 2
 	}
 	switch os.Args[1] {
@@ -517,6 +540,8 @@ func run() int {
 		return activatePlanCommand(os.Args[2:])
 	case "delivery-status":
 		return deliveryStatusCommand(os.Args[2:])
+	case "next-status":
+		return nextStatusCommand(os.Args[2:])
 	case "record-change":
 		return recordChangeCommand(os.Args[2:])
 	case "record-delivery-gate":