diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f3bcb6..60b504d 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/b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10/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/ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8/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 2984d01..be9b8b9 100644 --- a/README.md +++ b/README.md @@ -133,19 +133,9 @@ Receipts remain as history; published corrections become linked deliveries. -### Optional changelog +## Configure repository policy -It is disabled by default. Enable it in `.boatstack-project.json`: - -```json -{ - "workflow": { - "maintain_changelog": true - } -} -``` - -Enabled repositories require a categorized `CHANGELOG.md` → `Unreleased` entry for every managed slice and Boatstack-prepared ad-hoc PR. The file stays user-owned; install and update never overwrite it. [See the format and first-entry example](docs/getting-started.md#keep-a-repository-changelog). +`.boatstack-project.json` controls the project commands and context Boatstack uses, which coding hosts it supports, and opt-in policies for changelogs, boundary analysis, high-risk review, and feature workspaces. [Choose the outcomes you want and see every configuration field](docs/configuration.md). ## How Boatstack fits into your AI stack diff --git a/UPSTREAM.json b/UPSTREAM.json index fecc099..6b9e2cd 100644 --- a/UPSTREAM.json +++ b/UPSTREAM.json @@ -12,8 +12,8 @@ }, "files": { ".gitignore": "a7079e923a776f14f1bb3a6aa0a11a133a8e1dfb35af020f327623357b7e3957", - "CONTRIBUTING.md": "927f0a25406086d3d014e024b6754f9a64fc792edcaced2fbf58e2671a034bbf", - "README.md": "2a8ed9e1b3305d68d6a6aba68b78a6301daa29acc15a53f805ac94551326cce8", + "CONTRIBUTING.md": "b55062527a81d79fa92d792f4ae6a50783066159533375305bb4d23866555bff", + "README.md": "1b8b3dea6186faa18f01afa096117c57e2bd0b1c4765f35ef87518018e3839e0", "assets/boatstack-journey.svg": "e465befc50c8ce30f3e07e8fd97012931beeb053392c8fbf38ad645023b3cc63", "assets/boatstack-mark.svg": "be1f984da1bfa69fa5d1f986d8343d21f7e20921b71db888c928b4d2e54b09b5", "assets/boatstack-portability.svg": "66dfdfa85db857b3bd18b32047a6975f1fbbfc4dc091158e8277193f9969a346", @@ -36,6 +36,7 @@ "boatstack/changelog_test.go": "ce792f23a7fe1e09fb3096cd1314130a6ab69321d4877b12a8e994027541baf7", "boatstack/cmd/boatstack-helper/main.go": "91f869e9dd8b9b19a07c161e170f720ef4d51bc7fba67606d66cf973fcf0422f", "boatstack/cmd/boatstack-helper/main_test.go": "ff73003b6a5157202fa09ddf1129fb13c3d79702b2e05a8721ce5a11bf5ab779", + "boatstack/config_documentation_test.go": "d5ada5aa02ef4ba90ca917a5005a03c95197dc58dcb4f4d95d782c6faab4984a", "boatstack/decision.go": "257ca328da6ae19ab252f10ee5d06bd7daf49dd8141d083ab1b32f106ea7a94c", "boatstack/decision_test.go": "1a92ff832610f9559bd47ccac7fc1755a8b4f8261c35bc72a092830dff05f7c0", "boatstack/delivery.go": "6ff71b6f4ae4f85a184edaf453b5933a79366e36137802fda056e58f83fe319c", @@ -64,7 +65,7 @@ "boatstack/pr.go": "b076ac9e05978b90bf6063209f6ab75bbe2bcd8b9bf38c62ad3ba7b1e2d59e83", "boatstack/pr_test.go": "ae23130d9d96cf214cf272227aa572dd09e2fe3adac22921949f541ba99ecb23", "boatstack/references/artifacts.md": "8f2e79b8af4bd3ad2e32aa3e8c07f10812555d0a3247e4991db75cc1cda395c3", - "boatstack/references/config-schema.md": "894c001601246ad87411756902aa7b2962314e4395e2075f94d5c7c93c99e013", + "boatstack/references/config-schema.md": "9ece0ac49290e5d213e573ca68290996eb81b2b25e68bcfc93a77130cea2ab6e", "boatstack/references/failure-moves.md": "1d35126348d0b681976e8819665e16fd745fd65eca271492603cb80aab75bf49", "boatstack/references/host-hook-contracts.md": "1382213ad004389de6da5a03af43ec28ace6329c9e7a3f07148566cf2ea12727", "boatstack/references/irreversible-operation-boundary.md": "631743991ace65977586e4537f8dd50f8ae88f8e16f27cf7baad93b2791a73df", @@ -91,10 +92,11 @@ "docs/account-recovery-walkthrough.md": "676034974594a7d1a559b24dbed31d7ccc429eb81404b203ca07bbdaa19ec3d3", "docs/benchmark-corpus-audit.md": "f2d206fe8579a514f9da82b2c96c19b343ac004be67617e1bd34f0f8e0e5e6c6", "docs/benchmark-submission-audit.md": "9518abdd17690729c6423f87cab20418ed47b0915b5faa44b9ef975e9e9c3b79", - "docs/evidence-engineered-coding.md": "d785365deb036d5e4ec783abd4b0ce04488faa17ff5de279b0293e0b7325da70", + "docs/configuration.md": "010863ef7a772c0a2f813651ce8ca4c605c91474b7ebd42cc76902e6737021b6", + "docs/evidence-engineered-coding.md": "2208d42d9c3c973ceb27ec818fa29f2c455764209696c5db332a1e2819a3335c", "docs/generated-files.md": "136422baf0c7fc2bd5100cfe0ebdb3d9d0705dfd7e7d54bf745dd1037e63492c", "docs/getting-started.md": "eacc814fdffdfa3c7d8052b7cd99a79c04da5c75d88d8b44f3fb68d9afec0316", - "docs/public-claims.json": "2528752e111bf8c626435356fdc62535c23e3f1c8512639ef23f74b0cc87fe1a", + "docs/public-claims.json": "ca55f32105da4d67b05d773357042c2c2c87fde49f2e025dbad86991dfaa1dbc", "docs/public-surface.md": "713f7a050b5f339cf948299103ef3800417dccfecf2cc1a4166397ea6f978907", "docs/research-and-design.md": "d65c66e323037bda5d45aacef5d48afa6bf93da55901378891d235aca3a5684f", "docs/safety.md": "7b9b5c515d36e683767ec8d3d9d6d119ac93650b2f629d351deadd4c600ed6a6", @@ -108,7 +110,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": "7c07e8bd6c6c69bc1955e0621895e23274af54d483e650964ab93e3aa39ca9d6", + "labs/diagram-json/plan.lock.json": "b19cc1ae2a5fef75d9a673017c063e927ac07e1d154fae269bbd06f64fa83304", "labs/diagram-json/plan.md": "3cc4f533b8d69386deff16b3a594a3ba09d4c0c3db636cccd8c4380084ce6a51", "labs/diagram-json/questions.md": "74733b015002c8a6777c558e7e997fa48c94850b9bd39054fe9366c97ecf728d", "labs/diagram-json/request.md": "0808fc41c36779c404f4a3a121167da6e76cac56df526e70f9ed6d3e0d4c02ed", @@ -158,12 +160,13 @@ "release-notes/2026-07-21-value-translation-readme.md": "8dd16fd08c1591667a1074fc6825dcbf58beda0faa18ede1526647267418c8ea", "release-notes/2026-07-22-boundary-analysis-dx.md": "60d727ab3b109fff95a82eb36ee4c6c5833760535b14f386fda349a21b4fe588", "release-notes/2026-07-22-boundary-oracle-loop.md": "698c2ed7dd0a000e6e210f521989992b8fa476376987819ba92c12feb3528f7c", + "release-notes/2026-07-22-product-configuration-guide.md": "45e96862336bd53a2628ce3fe718c829ea20315555f53187eb7f04ba749f3a97", "release-notes/2026-07-22-value-translation-boundary.md": "9cf168ff7caaf3906b78533935bdfb2c86e753984ed1e5ec8204cb373d083390" }, "generator": "operatorstack/intelligence-flow:boatstack-distribution", "schema_version": 1, "source": { - "commit": "b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10", + "commit": "ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8", "path": "labs/12-product-engineering-loop", "repository": "operatorstack/intelligence-flow" } diff --git a/boatstack/config_documentation_test.go b/boatstack/config_documentation_test.go new file mode 100644 index 0000000..6db1a77 --- /dev/null +++ b/boatstack/config_documentation_test.go @@ -0,0 +1,89 @@ +package boatstack + +import ( + "os" + "reflect" + "sort" + "strings" + "testing" +) + +const configFieldMarkerPrefix = "boatstack-config-field:" + +func configSurface(value reflect.Type, prefix string) []string { + if value.Kind() == reflect.Pointer { + value = value.Elem() + } + var fields []string + for index := 0; index < value.NumField(); index++ { + field := value.Field(index) + name := strings.Split(field.Tag.Get("json"), ",")[0] + if name == "" || name == "-" { + continue + } + path := name + if prefix != "" { + path = prefix + "." + name + } + fields = append(fields, path) + + nested := field.Type + if nested.Kind() == reflect.Pointer { + nested = nested.Elem() + } + switch nested.Kind() { + case reflect.Struct: + fields = append(fields, configSurface(nested, path)...) + case reflect.Map: + item := nested.Elem() + if item.Kind() == reflect.Struct { + fields = append(fields, configSurface(item, path+".*")...) + } + } + } + return fields +} + +func configFieldMarkers(content string) []string { + var fields []string + for _, line := range strings.Split(content, "\n") { + line = strings.TrimSpace(line) + if strings.HasPrefix(line, configFieldMarkerPrefix) { + fields = append(fields, strings.TrimPrefix(line, configFieldMarkerPrefix)) + } + } + sort.Strings(fields) + return fields +} + +func documentedConfigSurface(t *testing.T, path string) []string { + t.Helper() + content, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read configuration documentation %s: %v", path, err) + } + return configFieldMarkers(string(content)) +} + +func TestConfigFieldMarkersAcceptWindowsLineEndings(t *testing.T) { + content := "\r\n" + want := []string{"project.name", "workflow"} + if got := configFieldMarkers(content); !reflect.DeepEqual(got, want) { + t.Fatalf("CRLF configuration markers were not parsed: got %v, want %v", got, want) + } +} + +func TestPublicConfigurationSurfaceIsDocumented(t *testing.T) { + want := configSurface(reflect.TypeOf(ProjectConfig{}), "") + sort.Strings(want) + + for _, document := range []string{ + "references/config-schema.md", + "../boatstack-distribution/CONFIGURATION.md", + } { + got := documentedConfigSurface(t, document) + if !reflect.DeepEqual(got, want) { + t.Errorf("configuration documentation drift in %s\nimplementation: %v\ndocumented: %v", document, want, got) + } + } +} diff --git a/boatstack/references/config-schema.md b/boatstack/references/config-schema.md index 5607693..bf392c8 100644 --- a/boatstack/references/config-schema.md +++ b/boatstack/references/config-schema.md @@ -1,5 +1,32 @@ # Boatstack Configuration Schema + + This reference document defines the schema and version history of `.boatstack-project.json`. ## Current Schema Version @@ -13,6 +40,7 @@ This reference document defines the schema and version history of `.boatstack-pr - `schema_version` (integer, required): Must be exactly `1`. - `project` (object, required): General project definition. - `workflow` (object, required): Flags controlling state machine transitions and safety gates. +- `workspace` (object, optional): Opt-in per-feature branch or worktree management. - `adapters` (array of strings, optional): Enabled host environment adapters. If empty, defaults to enabling all. - `integrations` (object, optional): Explicit configurations for individual third-party integrations. @@ -23,6 +51,7 @@ This reference document defines the schema and version history of `.boatstack-pr - `context` (array of strings, optional): Paths to persistent project directories or contextual documents. - `commands` (object, required): Custom development commands: - `test` (string, required): The exact command to execute project-local tests. + - Other command names (string, optional): Additional repository-owned commands such as `build`, `lint`, or `typecheck`. - `high_risk_paths` (array of strings, optional): Glob patterns of files requiring independent reviewer sign-off before shipping. ### workflow Fields @@ -30,10 +59,31 @@ This reference document defines the schema and version history of `.boatstack-pr - `human_plan_approval` (boolean, optional): Whether a parent plan requires explicit human approval before building. - `independent_review_for_high_risk` (boolean, optional): Whether modifications to high-risk files require a distinct peer review gate. - `allow_pass_with_gaps` (boolean, optional): Whether the delivery verification allows outstanding questions or gaps. -- `maintain_changelog` (boolean, optional): Whether a release-notes fragment is required for each delivery slice. +- `maintain_changelog` (boolean, optional): Whether a reader-visible `CHANGELOG.md` entry is required for each delivery slice. +- `boundary_analysis` (boolean, optional): Whether planning checks for a missing systemic boundary and presents local repair versus programmatic enforcement as a material product decision. + +### workspace Fields + +- `enabled` (boolean, optional): Enables managed per-feature workspaces. Defaults to `false`. +- `mode` (string, optional): `worktree` or `branch`. Defaults to `worktree` when workspace management is enabled. +- `cleanup` (string, optional): `confirm`, `auto`, or `off`. Defaults to `confirm`. +- `cleanup_after` (string, optional): `merge` or `ship`. Defaults to `merge`. + +### adapters Values + +Supported values are `cursor`, `claude`, `codex`, `gemini`, and `github`. An empty or omitted array enables all supported adapters. + +### integrations Fields + +Supported integration keys are `gstack` and `spec-kit`. Each integration state can contain: + +- `requested` (boolean, required when the integration is present): Whether installation was requested. +- `status` (string, optional): Installer-maintained installation status. +- `version` (string, optional): Installer-maintained pinned version or revision. +- `detail` (string, optional): Installer-maintained diagnostic detail. ## Version Changelog ### Version 1 -- Initial schema with `project`, `workflow`, `adapters`, and `integrations`. +- Initial schema with `project`, `workflow`, `workspace`, `adapters`, and `integrations`. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..413589e --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,227 @@ +# Configure Boatstack + + + +Boatstack keeps delivery policy in `.boatstack-project.json` so the same project rules apply when the coding agent, model, session, or worktree changes. Start with the outcome you want, then set only the policies your repository needs. + +## Choose the outcome + +| If you want to… | Configure… | What changes | +|---|---|---| +| Run the right project checks | `project.commands` | Boatstack uses repository-owned commands instead of inventing validation. `test` is required. | +| Give planning durable project context | `project.context` | Planning can find the named documents and directories without scanning the whole repository. | +| Treat selected files as higher risk | `project.high_risk_paths` and `workflow.independent_review_for_high_risk` | Changes matching those globs require the configured independent review boundary. | +| Require a person to approve plans | `workflow.human_plan_approval` | Build waits for an explicit approval receipt. | +| Allow a gate to pass with recorded gaps | `workflow.allow_pass_with_gaps` | A gate may report a pass with visible, retained gaps instead of requiring a gap-free result. | +| Keep reader-facing release history | `workflow.maintain_changelog` | Every managed delivery slice and Boatstack-prepared ad-hoc PR must update `CHANGELOG.md`. | +| Look for a missing systemic boundary | `workflow.boundary_analysis` | Planning checks whether the request is a local symptom and asks before expanding it into boundary work. | +| Start features in fresh Git workspaces | `workspace` | Boatstack can create a branch or linked worktree and manage local cleanup under the selected policy. | +| Limit generated host adapters | `adapters` | Only the named Cursor, Claude Code, Codex, Gemini CLI, or GitHub surfaces are exported. | +| Add supported specialist workflows | `integrations` | The installer records whether gstack or Spec Kit was requested and its installed state. | + +Changing configuration is an infrastructure change. Regenerate the Boatstack export and review the resulting diff through the repository's normal change process. + +## Complete example + +JSON does not support comments, so the explanations follow the example. + +```json +{ + "schema_version": 1, + "project": { + "name": "example-product", + "default_branch": "main", + "context": [ + "README.md", + "AGENTS.md", + "docs/architecture/", + "docs/decisions/" + ], + "commands": { + "build": "npm run build", + "lint": "npm run lint", + "test": "npm test", + "typecheck": "npm run typecheck" + }, + "high_risk_paths": [ + "migrations/**", + "auth/**", + "billing/**" + ] + }, + "workflow": { + "human_plan_approval": true, + "independent_review_for_high_risk": true, + "allow_pass_with_gaps": true, + "maintain_changelog": false, + "boundary_analysis": false + }, + "workspace": { + "enabled": true, + "mode": "worktree", + "cleanup": "confirm", + "cleanup_after": "merge" + }, + "adapters": ["cursor", "claude", "codex", "gemini", "github"], + "integrations": { + "gstack": { + "requested": false, + "version": "" + }, + "spec-kit": { + "requested": false, + "version": "" + } + } +} +``` + +Use the versions written by the installer; the placeholders above describe ownership and are not literal version values to copy. + +## Field reference + +### Root fields + +| Field | Required | Values and default | Effect | +|---|---:|---|---| +| `schema_version` | Yes | Integer; currently `1` | Selects the configuration contract. A newer value requires a newer Boatstack; an older supported value is migrated during update. | +| `project` | Yes | Object | Names the project and supplies repository context and commands. | +| `workflow` | Yes | Object; booleans use `false` when omitted | Controls approval, review, gap, changelog, and boundary-analysis behavior. | +| `workspace` | No | Object; disabled when absent | Controls optional per-feature branch or worktree management. | +| `adapters` | No | Array of supported adapter names; empty or absent enables all supported adapters | Selects generated host surfaces. Duplicate and blank entries are removed during export. | +| `integrations` | No | Object keyed by supported integration name | Records requested specialist integrations and installer-maintained state. | + +### `project` + +| Field | Required | Values and default | Effect | +|---|---:|---|---| +| `name` | Yes | Non-empty string | Human-readable project name used in generated configuration. | +| `default_branch` | No | Branch name; PR operations fall back to `origin/HEAD`, then `main` | Sets the canonical base branch for freshness checks, PRs, updates, and managed workspace cuts. Boatstack updates require it to be explicit. | +| `context` | No | Array of repository-relative file or directory paths; empty by default | Identifies durable context that planning should consult when relevant. | +| `commands` | Yes | Object of command-name to shell-command strings | Declares repository-owned validation commands. | +| `commands.test` | Yes | Non-empty command string | Supplies the minimum test boundary; configuration validation fails if it is absent or blank. | +| Other `commands.*` entries | No | Command strings such as `build`, `lint`, or `typecheck` | Make additional project checks available under their chosen names. Only `test` has a required name. | +| `high_risk_paths` | No | Array of Git-style glob patterns; empty by default | Marks paths for safety scanning and, when enabled, independent high-risk review. | + +Context paths guide bounded discovery; they are not a request to load every listed file for every feature. Commands run from the repository and should be deterministic enough to act as evidence. + +### `workflow` + +The defaults below describe an omitted JSON field. A fresh installer-generated configuration writes its recommended policies explicitly, including human approval, independent high-risk review, and pass-with-gaps behavior, so review the actual file rather than assuming omission. + +| Field | Default | Effect | +|---|---:|---| +| `human_plan_approval` | `false` | When `true`, requires explicit human plan approval before Build can activate the plan. | +| `independent_review_for_high_risk` | `false` | When `true`, changes matching `project.high_risk_paths` require the independent review boundary before shipping. Configure both fields for this policy to have a target. | +| `allow_pass_with_gaps` | `false` | When `true`, verification may pass with explicitly recorded outstanding gaps. It does not hide or discard them. | +| `maintain_changelog` | `false` | When `true`, requires a reader-visible `CHANGELOG.md` entry for every managed delivery slice and Boatstack-prepared ad-hoc PR. | +| `boundary_analysis` | `false` | When `true`, planning checks whether a request indicates a missing systemic boundary. Scope expansion remains a material human decision; choosing programmatic enforcement produces a boundary slice followed by the feature slice. | + +### `workspace` + +Workspace management is off unless `workspace.enabled` is `true`. Empty policy fields receive defaults only after it is enabled. + +| Field | Values and default | Effect | +|---|---|---| +| `enabled` | Boolean; `false` | Master switch. When `false`, Boatstack does not create or remove branches or worktrees. | +| `mode` | `worktree` (default) or `branch` | Creates a linked worktree or switches to a fresh in-place feature branch. | +| `cleanup` | `confirm` (default), `auto`, or `off` | Asks before eligible cleanup, performs it automatically, or disables managed cleanup. | +| `cleanup_after` | `merge` (default) or `ship` | Makes cleanup eligible after the PR is confirmed merged or after the feature is published. Safety checks still prevent discarding uncommitted or unmerged local work without an explicit operator override. | + +Managed workspaces are cut from the current remote default branch. Boatstack does not rewrite history, reuse an existing branch, delete remote branches, merge pull requests, or silently discard local work. + +### `adapters` + +Supported values are `cursor`, `claude`, `codex`, `gemini`, and `github`. An empty or omitted array enables all five. Use a subset only when the repository intentionally does not support the other host surfaces. + +### `integrations` + +Supported keys are `gstack` and `spec-kit`. Installation normally owns this object; prefer selecting integrations through the installer instead of hand-editing its result. + +| Field | Ownership | Effect | +|---|---|---| +| `requested` | User choice recorded by installer | Whether the integration was requested. | +| `status` | Installer-maintained, optional | Current installation result, such as installed or partial. | +| `version` | Installer-maintained, optional | Pinned integration version or revision. | +| `detail` | Installer-maintained, optional | Human-readable installation or diagnostic detail. | + +## Common policies + +### Require a repository changelog + +```json +{ + "workflow": { + "maintain_changelog": true + } +} +``` + +Add a categorized entry under `CHANGELOG.md`'s current `Unreleased` heading. See [the format and first-entry example](getting-started.md#keep-a-repository-changelog). + +### Analyze systemic boundaries during planning + +```json +{ + "workflow": { + "boundary_analysis": true + } +} +``` + +This adds a product decision when repository evidence suggests that a local request is a symptom of a broader missing boundary. It does not silently turn every feature into a refactor. + +### Require independent review for high-risk paths + +```json +{ + "project": { + "high_risk_paths": ["migrations/**", "auth/**", "billing/**"] + }, + "workflow": { + "independent_review_for_high_risk": true + } +} +``` + +Choose paths where a distinct reviewer is meaningful. Broad patterns increase review cost and should reflect actual repository risk boundaries. + +### Manage a fresh worktree for each feature + +```json +{ + "workspace": { + "enabled": true, + "mode": "worktree", + "cleanup": "confirm", + "cleanup_after": "merge" + } +} +``` + +This is the conservative managed-workspace policy: start from a fresh remote base, use a linked worktree, and ask before reclaiming local state after merge. diff --git a/docs/evidence-engineered-coding.md b/docs/evidence-engineered-coding.md index eb76eec..6b9029c 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 [`b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10`](https://github.com/operatorstack/intelligence-flow/tree/b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10/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 [`ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8`](https://github.com/operatorstack/intelligence-flow/tree/ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8/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 fe5806c..5841e6a 100644 --- a/docs/public-claims.json +++ b/docs/public-claims.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "source_commit": "b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10", + "source_commit": "ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8", "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" }, { "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:b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10" + "last_verified_version": "source:ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8" } ] } diff --git a/labs/diagram-json/plan.lock.json b/labs/diagram-json/plan.lock.json index 09d7abc..7a1c139 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": "b0d1c2855e04be6f85e16b8e8d5bdd3cbd74fd10", + "source_commit": "ba2a8848e08caf35dc09a05c00d8dd76a9d2e7b8", "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-22-product-configuration-guide.md b/release-notes/2026-07-22-product-configuration-guide.md new file mode 100644 index 0000000..2059933 --- /dev/null +++ b/release-notes/2026-07-22-product-configuration-guide.md @@ -0,0 +1,5 @@ +### Make repository policy discoverable without lengthening the README + +Boatstack now links from its public README to a complete, value-first configuration guide. Maintainers can start from the delivery outcome they want, then see every supported `.boatstack-project.json` field, accepted value, default, interaction, and focused example without reverse-engineering the generated project file. The canonical internal schema now also covers managed workspaces, boundary analysis, supported adapters, integration metadata, and optional project commands. + +A supervisory contract now derives the public configuration surface from the implementation's JSON tags and compares it with both documentation slices. Adding, removing, or renaming a configuration field without updating the guide and canonical schema fails the Go test suite instead of silently creating documentation drift.