diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d11fecb..939b668 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/e2ba11f185aa370ec4302ffcd1f4f7e622f60105/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/06cd7f767374488a0ba95f92c9286c856be63649/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/UPSTREAM.json b/UPSTREAM.json index f4c62cc..b442121 100644 --- a/UPSTREAM.json +++ b/UPSTREAM.json @@ -12,7 +12,7 @@ }, "files": { ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957", - "CONTRIBUTING.md": "fe36d1fcccd0042e51ae8c590f21ec49d9fdb9a367ddfd31803a6fc1db1f0f24", + "CONTRIBUTING.md": "b032cbd59890e2095138d640b5ca56456c840487951896e5c47457dd53f65acf", "README.md": "3ce3e95e511089b44e946a44b8d5f4f81d019ece5336db65b2cab1f9dc4d4dad", "assets/boatstack-journey.svg": "e465befc50c8ce30f3e07e8fd97012931beeb053392c8fbf38ad645023b3cc63", "assets/boatstack-mark.svg": "be1f984da1bfa69fa5d1f986d8343d21f7e20921b71db888c928b4d2e54b09b5", @@ -160,8 +160,8 @@ "boatstack/runtime_cache.go": "e026ffc1906f7e1e98b768bae63e6658164d2826c07169c9121ce0f23c73faf8", "boatstack/runtime_cache_test.go": "b981467ddc9f0f562da6bff5de7a80a9fe5a433a0317541d1e48df268546ac85", "boatstack/runtime_provenance_test.go": "1d52f1e6b0691cf4667729cc9b9f3c55c128f0aa3321f3a2843a9aa6fd0e73dc", - "boatstack/safety.go": "b68ea12b2ee4c1f1782c1a6a8540fff908ef8ef6d80f0b391c2933a5f2fecb38", - "boatstack/safety_test.go": "02260654d0b93ad48585c40391b310810876a6abcafc3d6c074f1f4e4e633f76", + "boatstack/safety.go": "31dbeb58ff22359812fee8e4113d47ebb563733908d17eddb264fe9e92fe2ca7", + "boatstack/safety_test.go": "c5c5413e66266a5159e56e6f9681fc5fdce4c4e53174f207c1605b639bd9d686", "boatstack/safety_update_publisher_test.go": "ed3f8187036623694dfe7c395cdae00fdae14609bab6124d1fdfc6fe73fa2196", "boatstack/skill_frontmatter.go": "73364df463ce828c2d005aab55f72bb92f7a34d99cf3f53d4e0cd5a4da9dbd0e", "boatstack/skill_frontmatter_test.go": "a3ec52e7df357a72265c95dd66db15d9c0effc7e5f90f14ce69c27792ce394eb", @@ -187,10 +187,10 @@ "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6", "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79", "docs/configuration.md": "060775c73431f28bd16066bdf9e0f89034d2855c7ca0f5544f660d24b91211d0", - "docs/evidence-engineered-coding.md": "525a3fd0cc83ad45ce494a10a94432c534283bbd0be424d320f4351cb78faad5", + "docs/evidence-engineered-coding.md": "273f96676c8f11d00a3eb172d05c6fe551ea5bda343fa46d14c70c6f729910b6", "docs/generated-files.md": "437791765b0a4015032ae21d1a6618563cad92b7402819e4f963bf5ae16284a3", "docs/getting-started.md": "51c2823f21e35140d31e6d5083dc4b89fddd24721ac6acc474154a4da53ee9f8", - "docs/public-claims.json": "d1e8ae99275098ed44ac52322fc0fece3c8091a2a43e7bdf10de78a00a3649ba", + "docs/public-claims.json": "4f11f552a9c337fd40c4460a37878fc4f2f3d74cefae75149ebb784d3dfe4685", "docs/public-surface.md": "713f7a050b5f339cf948299103ef3800417dccfecf2cc1a4166397ea6f978907", "docs/research-and-design.md": "8d78678108f0a6c924e1ff9b32c0f81aae9d1f779e0082843b6f99ad993ae2b6", "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6", @@ -204,7 +204,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": "b404cd373f8b5c33cd6c3de992e2db9e94d34367a2e7681d08de5a1561263faa", + "labs/diagram-json/plan.lock.json": "fd56e5b7f054ecb78051703e42577820999f3527ab9242b0b63632173bf205c3", "labs/diagram-json/plan.md": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51", "labs/diagram-json/questions.md": "74733b015002c8a6777c558e7e997fa48c94850b9bd39054fe9366c97ecf728d", "labs/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed", @@ -319,12 +319,13 @@ "release-notes/2026-07-26-hidden-jflow-design-note.md": "f60ed9dbbfb46a172ac9d33dd758a3166f820007b1673029f29f0fbefa0e5c0a", "release-notes/2026-07-26-workspace-reap.md": "e691d6a1c232cf218157880655413005fcb2c4f3113ededffdb80899a5054bb8", "release-notes/2026-07-27-coreachable-recovery.md": "6ffc6b0e9a7d46c0f99a64112813c33d19571c73d02e98ac5573924f1663fd54", - "release-notes/2026-07-27-invalid-delivery-block-actionable.md": "8fac8e3921e2285291703efa46e624b72cb5bac1b8492beca4c4b633abb5ba16" + "release-notes/2026-07-27-invalid-delivery-block-actionable.md": "8fac8e3921e2285291703efa46e624b72cb5bac1b8492beca4c4b633abb5ba16", + "release-notes/2026-07-27-read-only-inspection-pipelines.md": "0963286371e9a12592915c23a958dd013bf2a35e9fca6921691bc8bb3c3d8dc8" }, "generator": "operatorstack/intelligence-flow:boatstack-distribution", "schema_version": 1, "source": { - "commit": "e2ba11f185aa370ec4302ffcd1f4f7e622f60105", + "commit": "06cd7f767374488a0ba95f92c9286c856be63649", "path": "labs/12-product-engineering-loop", "repository": "operatorstack/intelligence-flow" } diff --git a/boatstack/safety.go b/boatstack/safety.go index e7e991f..55ada0e 100644 --- a/boatstack/safety.go +++ b/boatstack/safety.go @@ -51,7 +51,14 @@ func malformedHookInput(code string) error { return hookDecodeError{code: code} } -var readOnlyStage = regexp.MustCompile(`(?i)^\s*(?:env\s+[^ ]+\s+)*(?:rg|grep|git\s+(?:grep|diff|status|show|log)|cat|sed|head|tail|less|find\s+[^\n]*-(?:print|ls)|psql\s+[^\n]*\s-c\s+["']?\s*select\b|(?:[^\s]*/)?boatstack-helper(?:[_.-][a-z0-9._-]+)?\s+(?:recovery-status|mutation-status|operation-status|delivery-status|next-status|workspace-status|repair-status|check-plan|check-source-plan|check-safety|diagnose-hook|doctor|version)\b)`) +// readOnlyStage recognizes one stage of a pipeline that is read-only by EFFECT: a +// reader (rg/grep/git-read/cat/…), a read-only Boatstack status helper, or a pure +// stdin→stdout inspection filter (wc/awk/sort/…). Effect-Typed Allowlist: a +// pipeline is admitted iff EVERY stage is effect-read-only, so ordinary inspection +// idioms — recovery-status | jq, git diff | wc -l, … | sort | uniq -c — compose +// freely. Effect-CHANGING syntax (redirection > <, command substitution $()) is +// still banned in isPureReadOnlyCommand, so no filter can be turned into a writer. +var readOnlyStage = regexp.MustCompile(`(?i)^\s*(?:env\s+[^ ]+\s+)*(?:rg|grep|git\s+(?:grep|diff|status|show|log)|cat|sed|head|tail|less|wc|awk|sort|uniq|cut|tr|jq|column|nl|comm|rev|fold|find\s+[^\n]*-(?:print|ls)|psql\s+[^\n]*\s-c\s+["']?\s*select\b|(?:[^\s]*/)?boatstack-helper(?:[_.-][a-z0-9._-]+)?\s+(?:recovery-status|mutation-status|operation-status|delivery-status|next-status|workspace-status|repair-status|check-plan|check-source-plan|check-safety|diagnose-hook|doctor|version)\b)`) // irreversiblePatterns classify destruction by text. Rules whose regex names its // own EXECUTOR (rm, git, terraform, supabase db reset, …) are self-executing: diff --git a/boatstack/safety_test.go b/boatstack/safety_test.go index 82904b1..eb3b833 100644 --- a/boatstack/safety_test.go +++ b/boatstack/safety_test.go @@ -166,6 +166,38 @@ func TestInvokedSymlinkFailsClosed(t *testing.T) { } } +// Effect-Typed Allowlist: an inspection pipeline whose every stage is read-only by +// effect is allowed (compose a reader/status helper with pure filters), while any +// effect-changing syntax — redirection, command substitution, an in-place writer — +// is still denied. Classify by effect type, not by metacharacter presence. +func TestReadOnlyInspectionPipelinesAllowed(t *testing.T) { + repo := safetyTestRepo(t) + allowed := []string{ + "boatstack-helper recovery-status --repo . | jq .next_operation", + "boatstack-helper mutation-status --repo . | grep active", + "git diff | wc -l", + "git log --oneline | head -20 | awk '{print $1}'", + "git status --short | sort | uniq -c", + "cat plan.md | cut -c1-80", + } + for _, command := range allowed { + if findings := ClassifyCommand(repo, command); len(findings) != 0 { + t.Errorf("read-only inspection pipeline wrongly blocked: %q -> %#v", command, findings) + } + } + denied := []string{ + "git log > out.txt", // redirection changes effect + "git diff | tee snapshot.txt", // tee writes + "echo $(git rev-parse HEAD)", // command substitution + "git status && rm -rf build", // command separator hides a mutator + } + for _, command := range denied { + if isPureReadOnlyCommand(command) { + t.Errorf("effect-changing command wrongly treated as read-only: %q", command) + } + } +} + func TestSafeDiagnosticsAndFixForwardCommandsRemainAllowed(t *testing.T) { repo := safetyTestRepo(t) safeScript := filepath.Join(repo, "scripts", "apply_schema.py") diff --git a/docs/evidence-engineered-coding.md b/docs/evidence-engineered-coding.md index 06f7a06..182dfec 100644 --- a/docs/evidence-engineered-coding.md +++ b/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 [`e2ba11f185aa370ec4302ffcd1f4f7e622f60105`](https://github.com/operatorstack/intelligence-flow/tree/e2ba11f185aa370ec4302ffcd1f4f7e622f60105/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 [`06cd7f767374488a0ba95f92c9286c856be63649`](https://github.com/operatorstack/intelligence-flow/tree/06cd7f767374488a0ba95f92c9286c856be63649/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/public-claims.json b/docs/public-claims.json index 6180ea9..2db4ad1 100644 --- a/docs/public-claims.json +++ b/docs/public-claims.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "source_commit": "e2ba11f185aa370ec4302ffcd1f4f7e622f60105", + "source_commit": "06cd7f767374488a0ba95f92c9286c856be63649", "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" }, { "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:e2ba11f185aa370ec4302ffcd1f4f7e622f60105" + "last_verified_version": "source:06cd7f767374488a0ba95f92c9286c856be63649" } ] } diff --git a/labs/diagram-json/plan.lock.json b/labs/diagram-json/plan.lock.json index 9f64d40..42c1836 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": "e2ba11f185aa370ec4302ffcd1f4f7e622f60105", + "source_commit": "06cd7f767374488a0ba95f92c9286c856be63649", "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-27-read-only-inspection-pipelines.md b/release-notes/2026-07-27-read-only-inspection-pipelines.md new file mode 100644 index 0000000..4feda70 --- /dev/null +++ b/release-notes/2026-07-27-read-only-inspection-pipelines.md @@ -0,0 +1,17 @@ +### Read-only inspection pipelines work during recovery + +While a workflow is blocked, an operator often wants to look before acting — pipe a status command into +a filter to read the part that matters. This was rejected. The guard treated any command with a pipe as +possibly changing state, so ordinary inspection such as `recovery-status | jq`, `git diff | wc -l`, or +`git status | sort | uniq -c` was denied, and falling off the read-only list re-entered the mutation +checks. Looking before acting was blocked at the moment it was most needed. + +The guard now judges a pipeline by the effect of each stage. A pipeline is allowed when every stage is +read-only by effect — a reader, a Boatstack status command, or a pure filter that reads its input and +writes only to the next stage (`wc`, `awk`, `sort`, `uniq`, `cut`, `tr`, `jq`, and similar). Any stage +that changes state is still denied. + +The dangerous forms stay denied, because they change effect, not because they contain a special +character: writing to a file with `>`, running a subcommand with `$(...)`, chaining a real command with +`;` or `&&`, or piping into a writer such as `tee`. So `recovery-status | jq .next_operation` is allowed +while `git status && rm -rf build` is not.