From bc2a177d5fe5105b4d517a902cd2c0594bcf48b3 Mon Sep 17 00:00:00 2001 From: "operator-stack-publisher[bot]" Date: Sat, 25 Jul 2026 01:47:07 +0000 Subject: [PATCH] Sync Boatstack from Intelligence Flow Labs @ bf68921a54fd --- CONTRIBUTING.md | 2 +- README.md | 2 ++ UPSTREAM.json | 31 ++++++++++--------- boatstack/SKILL.md | 1 + boatstack/export.go | 8 ++++- boatstack/export_test.go | 5 +-- boatstack/references/failure-moves.md | 2 ++ boatstack/references/workflow.md | 3 ++ docs/evidence-engineered-coding.md | 4 +-- docs/getting-started.md | 2 ++ docs/public-claims.json | 24 +++++++------- labs/diagram-json/plan.lock.json | 2 +- .../2026-07-25-root-cause-operation.md | 24 ++++++++++++++ 13 files changed, 76 insertions(+), 34 deletions(-) create mode 100644 release-notes/2026-07-25-root-cause-operation.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe93a3b..84c2a5e 100644 --- a/CONTRIBUTING.md +++ b/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/e37b56904acfc2a70bcc91139521ced8dd3e6051/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/bf68921a54fdb3139401ce4a91241c799887e5b6/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. diff --git a/README.md b/README.md index c8f2387..4bcfc2a 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,8 @@ When coding agents or developers encounter a bug, they instinctively patch the l When you ask for a fix during `/auto-plan`, Boatstack actively scans your codebase to determine if the bug is a symptom of a missing systemic boundary. Instead of silently patching the symptom, it pauses and asks if you want to establish a programmatic lock (like a database trigger or strict validator). +For a bug you want diagnosed first, run `/root-cause ` (paste a stack trace, error, or failing signal). It is strictly read-only: it locates the failure below its surface symptom, names the failure *class*, traces a cited root-cause chain, maps the blast radius, and proposes the structural change that eliminates the whole class. It ends by producing a source plan you save and hand to `/auto-plan --plan ` — the diagnostic front door to the plan gate. + By turning one-off bug fixes into systemic constraints, your codebase gets safer with every agent run. Boatstack requires a negative test to prove the new lock is impenetrable. Upon publication, it extracts that verified boundary into the repository's global memory, ensuring all future agent runs are strictly bound by the new law of physics. ## Install with your coding agent diff --git a/UPSTREAM.json b/UPSTREAM.json index 577e892..2b352f5 100644 --- a/UPSTREAM.json +++ b/UPSTREAM.json @@ -1,7 +1,7 @@ { "canonical_context": { - "characters": 76916, - "estimated_tokens": 19229, + "characters": 77946, + "estimated_tokens": 19487, "estimator": "ceil(total characters / 4); compactness signal, not provider billing", "files": [ "product-engineering-loop/references/workflow.md", @@ -12,14 +12,14 @@ }, "files": { ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957", - "CONTRIBUTING.md": "3ff3ff4de9be3c70f7b447e971b6a5b1aaf6451dd14810f8b42a3ad9e7f79b6a", - "README.md": "125b47671a68556df382f19756fb61fa18925606cbbaf54d6bc9df8872b36870", + "CONTRIBUTING.md": "b5ed7bc801e78adc910b1467cd0be364fe39c44a4c6e4547200debc1d9f74517", + "README.md": "6b7402c5cef5b3b9b739281d3d4d576cdc995796ff127fc6aefb97c5743e0bac", "assets/boatstack-journey.svg": "e465befc50c8ce30f3e07e8fd97012931beeb053392c8fbf38ad645023b3cc63", "assets/boatstack-mark.svg": "be1f984da1bfa69fa5d1f986d8343d21f7e20921b71db888c928b4d2e54b09b5", "assets/boatstack-portability.svg": "66dfdfa85db857b3bd18b32047a6975f1fbbfc4dc091158e8277193f9969a346", "boatstack/AGENTS.md": "39574398c3c3f82c22077299b45fd46a587926e1c9a35b66998c65ab8a756554", "boatstack/BUG-worktree-delivery-state.md": "02469cf51c3849dad5743783e248e5c04583e4240507fbef0e3f890cd6a95724", - "boatstack/SKILL.md": "639264b06a3315e2d100783d9a55c8e6b489578d6d5fdedd8d7f36eaa7f499e7", + "boatstack/SKILL.md": "ae1b18b2b68b762a0b6b3d018fb9bbf8fb221f7e247f48321b9e16b04a6be334", "boatstack/agents/gemini.yaml": "cbf43b387399e456fa6178f86d83e6e35567e6142ff800f8de6ffca306fa963e", "boatstack/agents/openai.yaml": "68a30a60859556c5a26e16d184594ca243a6043d99c8cf7d66b5dd6d50a93cd1", "boatstack/assets/templates/adr.md": "c577a3c1c1319061f61deb053597e6e853657022185fe28b8f733327e2a78565", @@ -52,8 +52,8 @@ "boatstack/delivery_reactivation_test.go": "573a2dba0034bc4290478414e3bdd8670b06a326128eb0295d77e748ecc8689e", "boatstack/delivery_test.go": "45c48ff7581c911bcaf821c3e4241d4ae2a9bb4aa682485cc58b6ad8fe1c85bf", "boatstack/evidence.go": "497a31e6ff632cb1d7c3adfc9f269af3f6aa84e948dd5d417c162767542a27df", - "boatstack/export.go": "9d2b83b6075b3715599a3c19afb3a7ec8d2a006f8af624e3807f3b1fe7620065", - "boatstack/export_test.go": "67eb890728d20630925d6e4e90d2a97ec025195ba5c54994c1b098ab72721dca", + "boatstack/export.go": "9cb23234e6cd79441ff6f39f88ed66d6d47ef7c27901404439a3572b03fdf881", + "boatstack/export_test.go": "dce5aa3ab5499c82d05859cf86b46dfcee308482491366d83e10ca3fb8605bb6", "boatstack/go.mod": "6086ef1b2a83f5696190dca692c653925f27b61f652f659fd3fca43ed54a1641", "boatstack/go.sum": "26c315c867b11b886f3c9402fce7f341f6a9115a5d61f54afbb5e1b1fb5f6017", "boatstack/hooks.go": "0639eff2ec5ce50dcbe77ace0f7c25de1e9a68784a6ed70d6acc9984d049ef1a", @@ -96,11 +96,11 @@ "boatstack/reexec_windows.go": "f5335c8c28cb4e89048b058b1c4d12f78644f99acb4f6167ff60e622dfb9e742", "boatstack/references/artifacts.md": "5fa888ac519085d65cee1d04df5902761651bcf2d7af81711fa0f8ecd1fc0f59", "boatstack/references/config-schema.md": "0170b90f1d0a592f58e255ffeff642fa037676042443f74a0f1b6e39be5dbbb8", - "boatstack/references/failure-moves.md": "fe4c867b06b0913cec202631a0a8beced52394d356bfd37b5fa43a9c977ebae2", + "boatstack/references/failure-moves.md": "04cf53609c355f93df20ae7650bab49183d612b8b04ef425ea564b808039192b", "boatstack/references/host-hook-contracts.md": "d68ae1556e7b1e29e9ac7cb4db767809d510aabf0be52e60e44665ea7abb980e", "boatstack/references/irreversible-operation-boundary.md": "e0076f0fea3bf729b2e9bdf353eaeaaf7cdafabfaf26b8d9b27287e5414c2441", "boatstack/references/portability.md": "fb683095991bb0cb06ec56fb8884c49038b283172a7d2f8b203483b7cacb4bae", - "boatstack/references/workflow.md": "667ccba32f6c2710ad4fb41e34253dfe38477499d40f0dd51f8a3714b47a53c9", + "boatstack/references/workflow.md": "f4df30d30bf3d05a5b2fe09fd05ff46eec3fce4e7fe3f20b28dc5e758495ab27", "boatstack/release.go": "82dcb4ca59e8c79a68d5333d650f90e64abd448d04e0c6f504fdf07f42b5ed76", "boatstack/release_test.go": "5cf2d76fe9b836a91ca68eba53d5585e2c4be5b9421aaf939ea0723063a24690", "boatstack/repair_state_test.go": "f3779ac47c3db3927175a545728d3b2e020dbc85f41394d8235753b52afc3739", @@ -134,10 +134,10 @@ "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6", "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79", "docs/configuration.md": "df054f49d532c8b1b7d94184810d1b3b5bf18cdc30eb985b4b6d0639162e341a", - "docs/evidence-engineered-coding.md": "2a01fc2590c21b01548ac1376f6adaa8387451159f60e1c1a6500bc741f3be3d", + "docs/evidence-engineered-coding.md": "0eb1c59316939ebb951e28c9a508743be4d55a7ab49a15e80c237dbd1715232d", "docs/generated-files.md": "437791765b0a4015032ae21d1a6618563cad92b7402819e4f963bf5ae16284a3", - "docs/getting-started.md": "f314270c5ed1a55bbef5f3ddbcb5596693dbee9374e5f0d3df8838cefbd68052", - "docs/public-claims.json": "a33f473598df850c8ed1b0e2b7d2b766c3295b6f2aa699d5035fdf8753e7903d", + "docs/getting-started.md": "1dd4f4e2e636cc5adfc2f79939629701e171087c3d5e558cf919548b9224adfd", + "docs/public-claims.json": "8d9a5258882cdc22df696000a44fdb1d0185c9eae853a3b31f29d49d75fe9cb8", "docs/public-surface.md": "713f7a050b5f339cf948299103ef3800417dccfecf2cc1a4166397ea6f978907", "docs/research-and-design.md": "8d78678108f0a6c924e1ff9b32c0f81aae9d1f779e0082843b6f99ad993ae2b6", "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6", @@ -151,7 +151,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": "aa8119d00ee13aa06f50c1b3f9779ea6b1f67e88243096812b83d74ce4b6baf8", + "labs/diagram-json/plan.lock.json": "54138d8f25086643c31032262bfe9b6d2f7fec4eabd3fcbfd41c92923c283987", "labs/diagram-json/plan.md": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51", "labs/diagram-json/questions.md": "74733b015002c8a6777c558e7e997fa48c94850b9bd39054fe9366c97ecf728d", "labs/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed", @@ -232,12 +232,13 @@ "release-notes/2026-07-24-reactivation-preserves-published-progress.md": "77233df3d6955e8f7a076c301ce7cbff84ba138ab812f18ddd97785600fd3d22", "release-notes/2026-07-24-repair-state-recovery.md": "daaa12deb51a5f647178d6164ea5b4bcd29bf5482b77d90002429f69e0da5dd0", "release-notes/2026-07-24-transactional-mutation-boundary.md": "38819a4811edbc99a9d8a77983aedbd0589bdbbf849da4991d3e21a1b319a65c", - "release-notes/2026-07-25-boatstack-banner.md": "28e83f294de606211cfdc91b2586aa834e004dee76d5c4bee08859986ae86b5b" + "release-notes/2026-07-25-boatstack-banner.md": "28e83f294de606211cfdc91b2586aa834e004dee76d5c4bee08859986ae86b5b", + "release-notes/2026-07-25-root-cause-operation.md": "5bf1f082e9123c5a7bcc8bc01b12e97b24b5ae15958577b4ff2a358994fca891" }, "generator": "operatorstack/intelligence-flow:boatstack-distribution", "schema_version": 1, "source": { - "commit": "e37b56904acfc2a70bcc91139521ced8dd3e6051", + "commit": "bf68921a54fdb3139401ce4a91241c799887e5b6", "path": "labs/12-product-engineering-loop", "repository": "operatorstack/intelligence-flow" } diff --git a/boatstack/SKILL.md b/boatstack/SKILL.md index 07d4f34..66ebe96 100644 --- a/boatstack/SKILL.md +++ b/boatstack/SKILL.md @@ -14,6 +14,7 @@ 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. - `run`: drive the verified feature through every delivery slice and PR publication, pausing at approval, product-decision, and publication boundaries. +- `root-cause`: read-only failure-mode-elimination diagnosis of a bug — classify the failure class below its symptom, produce a cited root-cause chain, and hand a class-eliminating source plan to `auto-plan`; never edits code or advances a gate. - `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. diff --git a/boatstack/export.go b/boatstack/export.go index 9b7d52a..43f3c57 100644 --- a/boatstack/export.go +++ b/boatstack/export.go @@ -49,6 +49,11 @@ var claudeVisibleSkills = []claudeSkillSpec{ Name: "boatstack-run", Description: "Drive the verified Boatstack feature through every delivery slice and PR publication, pausing only at required human boundaries.", }, + { + Name: "root-cause", + Description: "Read-only failure-mode-elimination diagnosis of a bug — a cited root-cause chain, the named failure class, and a class-eliminating source plan to hand to auto-plan.", + ArgumentHint: "[symptom-or-log]", + }, { Name: "auto-plan", Description: "Refine one saved Plan-mode proposal into a reviewable Boatstack feature plan.", @@ -292,6 +297,7 @@ func BuildExportBundle(configPath string, config ProjectConfig, rawConfig []byte operations := map[string]string{ "boatstack-next": "Run the project-local helper next-status --repo . --json. This operation is strictly read-only: do not run the reported operation, edit artifacts, contact GitHub beyond the helper's bounded published-PR inspection, or advance a gate. Translate the structured result into the canonical response contract. Show the verified feature and active slice when present. Distinguish NOT_STARTED, whose next operation is auto-plan run with the plan path via --plan, from PUBLISHED, which responds PR published and makes reviewing its checks the one action, and FEATURE_COMPLETE, which is reserved for a verified merged PR and responds Feature complete with No action required. If verification_status is BLOCKED, name the ambiguity or invalid evidence and make its safe restoration the one action; never clear artifacts. Conversation, terminal, worktree, or process observations may be included as clearly labeled context only and must never override the repository-backed result. Otherwise make the returned next_operation the one next action.", "boatstack-run": "First run the read-only next-status --repo . --json and operation-status --repo . --json. If an operation is executing, wait and report it instead of launching it again; if reconciliation is required, verify its exact postcondition before retrying. If NOT_STARTED, respond Start a Boatstack feature and ask the user for the plan produced in the host conversation, then execute auto-plan with its path via --plan (Boatstack does not scan directories for plans) without Git preflight, pausing at its normal decision or approval boundary; do not fetch or require a feature branch. If PUBLISHED, report that the PR is awaiting or lacks verified completion and make reviewing its checks the one next action; do not claim completion. If FEATURE_COMPLETE, respond Feature complete with No action required. Stop on UNVERIFIED, BLOCKED, ambiguous, stale, or invalid state. Before executing the first delivery-stage next_operation (build, repair, test-gate, review-gate, or ship-gate), run the project-local helper run-preflight --repo . --json; planning and plan-gate do not require it. Stop on a blocked preflight; never merge, rebase, force-push, discard changes, switch branches, or create a constrained delivery branch to repair freshness. Then execute exactly the verified next_operation using the canonical operation semantics, verify the resulting repository state, and resolve again. Continue across every declared delivery slice. Pause for the exact plan approval reply a, any material product decision, and the exact PR publication reply o or u; after a valid reply in the current host session, automatically continue the run. A run request never supplies approval or publication authority. For a same-intent test or review failure, use repair, record the observation, and retry from the returned stage. The delivery state's durable repair_attempt is the budget; stop after three complete automated repair-and-gate cycles even across new turns, host restarts, or async notifications. Stop immediately on an amendment, ambiguity, unsafe or destructive capability, stale evidence, branch mismatch, unsupported recovery, or exhausted repair budget. If Cursor reports MainThreadShellExec not initialized, explain that Cursor failed before the Boatstack hook started and make Developer: Reload Window the one recovery action; do not recommend reinstall unless Boatstack reports a missing, drifted, unsafe, or checksum-invalid runtime. Do not use conversation as workflow evidence. Durable operation receipts store execution facts and retry budgets, never autonomous workflow intent. Report the feature, active slice, stages completed, completion or pause reason, durable repair-cycle count, and exactly one next action. Ship means publishing every declared slice PR for review; never merge or deploy.", + "root-cause": "Perform failure-mode elimination on a bug, not a patch. This operation is strictly read-only: do not edit product code, create or update artifacts, advance a gate, or contact GitHub; the user supplies the symptom, stack trace, error log, or failing signal as the argument. Locate the failure below its surface symptom and classify it against the failure classes in @.product-loop/failure-moves.md; name the failure CLASS, not the one instance, and if no class fits, name the new class in that vocabulary. Investigate with read-only tools and produce a numbered root-cause chain in which every step is cited to file:line and which distinguishes the crashing frame (the victim) from the true origin (the cause); label authoritative repository facts DISCOVERED and any inference PROPOSED. State the blast radius: every other call site or path exposed to the same class. Propose the minimal STRUCTURAL elimination that makes the whole class unreachable and covers every exposed site, reusing an existing repository pattern or utility where one exists, rather than a local guard on the single line in the trace. Present this as a material product decision with the same tiered paths auto-plan uses under boundary_analysis: [1a] Symptom Patch or [1b] Programmatic Enforcement (a boundary that eliminates the class), and recommend one. Require a regression that reproduces the failure mode before the fix plus the project's own gates as the proof the class is gone, and name related latent hazards left out of scope as non-goals. Then format the result as a host Plan-mode source plan (symptom, root-cause chain, failure mode, blast radius, elimination, non-goals, verification, delivery base branch) and respond Root cause found, making the one next action: save this plan to a durable in-repo path and run auto-plan with it via --plan. Do not implement the fix; hand off to the plan gate.", "auto-plan": "Take the plan produced in the host conversation, supplied explicitly via --plan (Boatstack never scans directories for plans), and refine it into a Markdown-only draft feature package whose canonical structured artifact is plan.md. Run check-plan read-only. If workflow.boundary_analysis is true, evaluate if the change is a symptom of a missing systemic boundary and perform a rapid codebase scan for other vulnerabilities. Present this as a material product decision with tiered paths: [1a] Symptom Patch or [1b] Programmatic Enforcement (Slice 1 for the boundary, Slice 2 for the feature). When workflow.pr_visual_evidence is suggest or require, record a structural pr_visual_evidence decision: relevant with one to three entry/state/viewport/expected scenarios, or not_relevant with a reason. Discover existing visual tooling but never require a frontend framework or add repository tooling during planning. When a scenario is relevant but no capability command resolves, surface a material provisioning decision with tiered paths: [1a] provision the capture capability now as its own ordered delivery slice, [1b] bundle the capture harness into the feature slice, or [1c] record the gap and defer; this is a surfaced choice, never an imposed framework. Record affected_paths and structured side_effects for external writes; use an immutable target identity, transactional or fix-forward recovery, and destructive=false. When workflow.maintain_changelog is true, include CHANGELOG.md in every delivery slice's affected paths. Keep internal phases as tasks in one delivery slice. Only when the accepted outcome explicitly needs multiple PRs, declare ordered delivery_slices and assign every task exactly once; plan approval never authorizes publication. Do not implement, create JSON or locks, or imply acceptance. If ready, respond with Plan ready and make Run /plan-gate the one next action. If decisions remain, respond with I need your input and ask only 1-3 material questions. If an earlier hand-authored draft was never registered and its plan cannot be verified, the guard denies every product mutation at INVALID_STATE with next operation repair-state; run repair-state to quarantine that unregistered malformed draft and return to auto-plan. It is reversible, refuses any feature carrying a plan lock, pr.md, delivery state, tracked files, or an active or published delivery, and never edits product code.", "plan-gate": "Run check-plan read-only and present its plan fingerprint, baseline product diff fingerprint, changed paths, exact baseline diff when non-empty, and all open decisions. If workflow.human_plan_approval is true, require explicit human approval. While plan approval is pending, the normal user action is the exact standalone reply a. Trim surrounding whitespace and match a case-insensitively; do not treat [a] or an a embedded in other text as approval. Continue accepting the full reply approve for compatibility, but do not advertise it in the user-facing response. Resolve approved_by from an explicit supplied identity, otherwise from the authenticated GitHub login when available; ask one short identity follow-up only when neither exists, and never infer it from a filesystem username, commit history, or agent identity. On approval invoke record-approval with the displayed baseline fingerprint, omitting it only when the baseline is clean, so it writes only approval.md. While pending respond Ready for your approval and render: Reply `a` to approve. After recording respond Approved — ready to build. If human_plan_approval is false, do not request approval or create approval.md; state that Build will create a fingerprinted policy-activation lock. In either mode Remain in Plan mode, do not compile, and make entering execution mode and running /build the next action once ready.", "build": "First confirm the host is in an execution-capable mode. If the mode transition is rejected or product-code writes remain unavailable, return READY_FOR_BUILD internally without activating the plan, compiling JSON, or writing a lock. Only then locate plan.md and, when workflow.human_plan_approval is true, approval.md; run activate-plan before the first product-code edit and omit --approval for policy activation. activate-plan promotes the compiled task graph, test matrix, evidence ledger, and the plan lock together through the transactional mutation boundary as one mutation, so all four land all-or-nothing with a reversible receipt and a failed or interrupted promote leaves the prior state unchanged rather than half-written. The boundary is closed under inversion: mutation-status lists the receipts and undo --mutation reverses a managed-artifact promotion (redo is undo of the undo receipt), with undo refusing to reverse an activation once a delivery gate would be stranded; this governs Boatstack-generated artifacts only, never source code. Stop if it reports BLOCKED. Read delivery-status and implement only the active delivery slice task_ids. When workflow.maintain_changelog is true, add a concise entry grounded in the active slice's actual changes under the current CHANGELOG.md Unreleased heading before recording test evidence. Use only the one allowed category needed by the entry and do not add empty category headings. If the file is absent, create the documented minimal skeleton with ## [Unreleased] - YYYY-MM-DD and the first categorized entry; if it exists, add to the current file without rewriting its history or layout. Run the internal repository safety check after operational or high-risk edits; a destructive capability blocks execution and gate progression but does not block reviewable source editing. Implementation tactics remain open inside the authorized boundary, but push and PR mutation are never build tactics and are denied while managed delivery is active. On success respond Build complete and make Run /test-gate the one next action. When a new product decision blocks work, respond Build needs a decision and ask only that question.", @@ -343,7 +349,7 @@ description: Use when the user asks what is next in Boatstack, asks Boatstack to # Boatstack adapter - Read .product-loop/project.json and .product-loop/workflow.md. The requested operation is supplied by the user; valid managed operations are next, boatstack-next, run, boatstack-run, auto-plan, plan-gate, build, repair, test-gate, review-gate/review, ship-gate/ship, boatstack-update, retro, workspace-cut, and workspace-cleanup. Route next and natural-language questions such as "what's next in Boatstack?" to the read-only boatstack-next operation. Route run and requests such as "run Boatstack through ship" to boatstack-run. Before any product edit, resolve complete Boatstack state. Once auto-plan creates a saved feature plan, draft, approved, policy-ready, ambiguous, stale, or invalid state denies product mutation until controlled activation creates a current lock; conversation and async completion never grant authority. For an active or current-branch published managed delivery, automatically use repair only for product behavior, implementation, test, review, or delivery-evidence failures and changes. Never instruct the user to manually repeat a push or PR mutation denied by the safety hook. + Read .product-loop/project.json and .product-loop/workflow.md. The requested operation is supplied by the user; valid managed operations are next, boatstack-next, run, boatstack-run, root-cause, auto-plan, plan-gate, build, repair, test-gate, review-gate/review, ship-gate/ship, boatstack-update, retro, workspace-cut, and workspace-cleanup. Route next and natural-language questions such as "what's next in Boatstack?" to the read-only boatstack-next operation. Route bug diagnosis such as a stack trace or "why did this crash" to the read-only root-cause operation, which classifies the failure and produces a source plan to hand to auto-plan; it never edits code or advances a gate. Route run and requests such as "run Boatstack through ship" to boatstack-run. Before any product edit, resolve complete Boatstack state. Once auto-plan creates a saved feature plan, draft, approved, policy-ready, ambiguous, stale, or invalid state denies product mutation until controlled activation creates a current lock; conversation and async completion never grant authority. For an active or current-branch published managed delivery, automatically use repair only for product behavior, implementation, test, review, or delivery-evidence failures and changes. Never instruct the user to manually repeat a push or PR mutation denied by the safety hook. %s diff --git a/boatstack/export_test.go b/boatstack/export_test.go index 78bf4af..f7f005a 100644 --- a/boatstack/export_test.go +++ b/boatstack/export_test.go @@ -215,6 +215,7 @@ func TestExportAndDriftCheck(t *testing.T) { build := string(bundle.Files[".cursor/commands/build.md"]) responseOutcomes := map[string][]string{ "boatstack-run": {"Start a Boatstack feature", "Feature complete"}, + "root-cause": {"Root cause found"}, "auto-plan": {"Plan ready", "I need your input"}, "plan-gate": {"Ready for your approval", "Approved — ready to build"}, "build": {"Build complete", "Build needs a decision"}, @@ -477,7 +478,7 @@ func TestPortableHostAdaptersShareWorkflowAndArtifactContract(t *testing.T) { workflow := string(bundle.Files[".product-loop/workflow.md"]) artifacts := string(bundle.Files[".product-loop/artifacts.md"]) - for _, expected := range []string{"boatstack-next", "boatstack-run", "auto-plan", "plan-gate", "build", "test-gate", "review-gate", "ship-gate", "boatstack-update", "retro"} { + for _, expected := range []string{"boatstack-next", "boatstack-run", "root-cause", "auto-plan", "plan-gate", "build", "test-gate", "review-gate", "ship-gate", "boatstack-update", "retro"} { if !strings.Contains(workflow, expected) { t.Fatalf("canonical portable workflow is missing %q", expected) } @@ -526,7 +527,7 @@ func TestPortableHostAdaptersShareWorkflowAndArtifactContract(t *testing.T) { t.Fatalf("%s adapter retains broad free-form repair capture", host) } } - for _, operation := range []string{"next", "boatstack-next", "run", "boatstack-run", "auto-plan", "plan-gate", "build", "test-gate", "review-gate", "ship-gate", "boatstack-update", "retro"} { + for _, operation := range []string{"next", "boatstack-next", "run", "boatstack-run", "root-cause", "auto-plan", "plan-gate", "build", "test-gate", "review-gate", "ship-gate", "boatstack-update", "retro"} { if !strings.Contains(hostSurfaces["codex"], operation) { t.Fatalf("Codex router does not declare portable operation %q", operation) } diff --git a/boatstack/references/failure-moves.md b/boatstack/references/failure-moves.md index dde81a5..d90b79d 100644 --- a/boatstack/references/failure-moves.md +++ b/boatstack/references/failure-moves.md @@ -2,6 +2,8 @@ Select a move only after locating the failure below its surface symptom. “Timed out,” “tests failed,” and “the agent got confused” are starting observations, not diagnoses. +The `root-cause` operation operationalizes this taxonomy for a single bug: it classifies the failure against the classes below, produces a cited root-cause chain, and proposes the structural change that eliminates the class rather than patching the instance, then hands the result to `auto-plan` as a source plan. + | Failure class | Evidence | Candidate moves | Main regression risk | |---|---|---|---| | Unknown requirement | Plausible implementations disagree on product behavior | Ask a targeted human question; record answer and expiry | Invented requirements or stalled delivery | diff --git a/boatstack/references/workflow.md b/boatstack/references/workflow.md index 395c9cf..c951d8e 100644 --- a/boatstack/references/workflow.md +++ b/boatstack/references/workflow.md @@ -117,6 +117,7 @@ Lead with a plain outcome, never a machine code such as `PASS`, `PLAN_APPROVED`, |---|---| | `next`, `/boatstack-next`, `$boatstack next` not started / active / complete / ambiguous | **Start a Boatstack feature** -> save a Plan-mode file or run `auto-plan`; **Next Boatstack stage** -> run the one repository-backed operation; **Feature complete** -> no action required; **Boatstack state needs attention** -> resolve the named ambiguity (address the invalid evidence, or, when the block names only past deliveries, ignore a named past delivery after explicit user confirmation) | | `run`, `/boatstack-run`, `$boatstack run` not started / complete / paused / blocked | **Start a Boatstack feature** -> save a Plan-mode file; **Feature ready for review** -> review the published PRs; **Boatstack run paused** -> provide the one required approval, confirmation, or product answer; **Boatstack run needs attention** -> resolve the named freshness, safety, state, or repair blocker | +| `root-cause`, `/root-cause`, `$boatstack root-cause` | **Root cause found** -> save the diagnosis as a source plan and run `auto-plan` with it via `--plan`; the operation is read-only and never edits code or advances a gate | | `auto-plan` ready / needs answers | **Plan ready** -> run `/plan-gate`; **I need your input** -> answer with the displayed choice keys or `r` for all recommendations | | `plan-gate` pending / approved | **Ready for your approval** -> reply `a` to approve; **Approved — ready to build** -> enter execution mode and run `/build` | | `build` success / paused | **Build complete** -> run `/test-gate`; **Build needs a decision** -> answer the blocking question | @@ -164,6 +165,8 @@ For plan approval, resolve `approved_by` from (1) an identity supplied with appr Begin in the active coding host's Plan mode. Explore the ordinary product intent without editing implementation files, then save that host-generated plan as a durable file. Invoke `auto-plan` with the plan's path. +For bug-shaped intent (a crash, stack trace, or failing signal), the read-only `root-cause` operation is the optional on-ramp to this state: it classifies the failure against [failure-moves.md](failure-moves.md), produces a cited root-cause chain, and proposes the structural change that eliminates the failure class rather than patching the instance, formatted as the source plan you then save and pass to `auto-plan --plan`. It never edits code, writes artifacts, or advances a gate. + Before repository inspection, run: ```bash diff --git a/docs/evidence-engineered-coding.md b/docs/evidence-engineered-coding.md index 94aa73d..ab7c5b7 100644 --- a/docs/evidence-engineered-coding.md +++ b/docs/evidence-engineered-coding.md @@ -96,7 +96,7 @@ subject to acceptance criteria pass approval is current ``` -That is why context trimming is not automatically an optimization. If removing state increases rework or false acceptance, total cost rises. The canonical runtime references are approximately **19229 estimated tokens**, while host adapters point to one operation at a time. +That is why context trimming is not automatically an optimization. If removing state increases rework or false acceptance, total cost rises. The canonical runtime references are approximately **19487 estimated tokens**, while host adapters point to one operation at a time. ## Control appears at transitions @@ -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 [`e37b56904acfc2a70bcc91139521ced8dd3e6051`](https://github.com/operatorstack/intelligence-flow/tree/e37b56904acfc2a70bcc91139521ced8dd3e6051/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 [`bf68921a54fdb3139401ce4a91241c799887e5b6`](https://github.com/operatorstack/intelligence-flow/tree/bf68921a54fdb3139401ce4a91241c799887e5b6/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. diff --git a/docs/getting-started.md b/docs/getting-started.md index 03f9d47..23ef3c9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -64,6 +64,8 @@ Add account recovery without removing the existing passwordless sign-in flow. Let the host inspect the relevant repository slice and save its plan as a durable file. Pass that path to `/auto-plan` via `--plan `; Boatstack does not scan directories for plans, so the path is always required. +For bug-shaped work, `/root-cause ` is an optional read-only on-ramp: it diagnoses the failure, names its class, and produces exactly this source plan for you to save and pass to `/auto-plan --plan `. + Start Boatstack with the entry point for your host: | Host | Start command | diff --git a/docs/public-claims.json b/docs/public-claims.json index 3035b3e..4d9ed5a 100644 --- a/docs/public-claims.json +++ b/docs/public-claims.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "source_commit": "e37b56904acfc2a70bcc91139521ced8dd3e6051", + "source_commit": "bf68921a54fdb3139401ce4a91241c799887e5b6", "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" }, { "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:e37b56904acfc2a70bcc91139521ced8dd3e6051" + "last_verified_version": "source:bf68921a54fdb3139401ce4a91241c799887e5b6" } ] } diff --git a/labs/diagram-json/plan.lock.json b/labs/diagram-json/plan.lock.json index ec0326e..f4c54c0 100644 --- a/labs/diagram-json/plan.lock.json +++ b/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": "e37b56904acfc2a70bcc91139521ced8dd3e6051", + "source_commit": "bf68921a54fdb3139401ce4a91241c799887e5b6", "source_plan_path": "labs/diagram-json/source-plan.md", "source_plan_sha256": "e10593ddaa7522ab80cc991d0a09399257139799e37f737794cd49d68a39985b", "spec_path": "labs/diagram-json/spec.md", diff --git a/release-notes/2026-07-25-root-cause-operation.md b/release-notes/2026-07-25-root-cause-operation.md new file mode 100644 index 0000000..c830710 --- /dev/null +++ b/release-notes/2026-07-25-root-cause-operation.md @@ -0,0 +1,24 @@ +### A read-only `root-cause` operation diagnoses a bug before you plan the fix + +Boatstack already carried the discipline of eliminating a failure *class* rather than +patching one instance — the failure taxonomy in `failure-moves.md` and the symptom-vs- +systemic-boundary decision `auto-plan` surfaces under `boundary_analysis` — but there was +no dedicated entry point for turning a raw bug into that kind of plan. Diagnosis and +planning were fused inside `auto-plan`, so a stack trace had no home of its own. + +The new `root-cause` operation is that home. Invoke it as `/root-cause ` +(`$boatstack root-cause` in Codex) with a stack trace, error, alert, or failing signal. +It is strictly read-only: it never edits product code, writes artifacts, contacts GitHub, +or advances a gate. It locates the failure below its surface symptom, classifies it +against the classes in `.product-loop/failure-moves.md`, and produces a numbered +root-cause chain in which every step is cited to `file:line` and the crashing frame (the +victim) is distinguished from the true origin (the cause). It then maps the blast radius — +every other call site exposed to the same class — and proposes the minimal *structural* +elimination that makes the whole class unreachable, using the same tiered +`[1a] Symptom Patch` / `[1b] Programmatic Enforcement` framing as `auto-plan`, plus a +regression that reproduces the failure mode as the proof the class is gone. + +Its output is formatted as a host Plan-mode source plan. `root-cause` ends by making the +one next action explicit: save that plan to a durable in-repo path and run +`auto-plan --plan `. It is the diagnostic front door to the existing plan gate and +changes nothing about how planning, approval, gates, or publication work.