create-flowdular 0.2.4 → 0.2.5

package/agent-template/.ai/blueprints/add-migration/gates.yaml

@@ -0,0 +1,30 @@
+schemaVersion: 1
+# Ids equal GateId in packages/sandbox/src/server/gates.ts. The sandbox runs the
+# gates a role lists in its front matter after every turn that changed files;
+# from the repository root run the command column yourself. Nothing executes
+# this file; it documents the contract.
+gates:
+  - id: spec-schema
+    command: pnpm flowdular spec validate --all --json
+    sandbox: pnpm flowdular spec validate --all --json --root <session workspace>
+    required: true
+  - id: module-schema
+    command: pnpm flowdular module validate --json
+    sandbox: pnpm flowdular module validate --json --root <session workspace>
+    required: true
+  - id: dependencies
+    command: 'grep the imports under src/** and compare with package.json dependencies (no CLI command yet)'
+    sandbox: checkDeclaredDependencies(modulePath) in packages/sandbox/src/server/dependencies.ts, run after every turn that changed files, plus a pnpm install when a package.json changed
+    required: true
+  - id: typecheck
+    command: pnpm --filter @flowdular/module-{module} typecheck
+    sandbox: node_modules/.bin/tsrx-tsc --noEmit -p tsconfig.json (cwd module)
+    required: true
+  - id: tests
+    command: pnpm --filter @flowdular/module-{module} test
+    sandbox: node_modules/.bin/vitest run --passWithNoTests (cwd module; zero tests still pass)
+    required: true
+  - id: format
+    command: pnpm format:check
+    sandbox: prettier --check . (cwd module)
+    required: true

package/agent-template/.ai/blueprints/add-migration/input.schema.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["moduleId", "change", "name", "destructive"],
+	"properties": {
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"change": {
+			"type": "string",
+			"enum": ["table", "column", "index", "constraint"]
+		},
+		"name": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9_]*$"
+		},
+		"destructive": {
+			"const": false
+		}
+	}
+}

package/agent-template/.ai/blueprints/add-migration/plan.schema.json

@@ -0,0 +1,54 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"blueprint",
+		"moduleId",
+		"constant",
+		"upFile",
+		"downFile",
+		"guarded",
+		"gates"
+	],
+	"properties": {
+		"blueprint": {
+			"const": "add-migration@1.0.0"
+		},
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"constant": {
+			"type": "string",
+			"pattern": "^[A-Z][A-Z0-9_]*_MIGRATION_[0-9]{3}[A-Z0-9_]*$"
+		},
+		"upFile": {
+			"type": "string",
+			"pattern": "^migrations/[0-9]{4}_[a-z0-9_]+\\.up\\.sql$"
+		},
+		"downFile": {
+			"type": "string",
+			"pattern": "^migrations/[0-9]{4}_[a-z0-9_]+\\.down\\.sql$"
+		},
+		"guarded": {
+			"type": "boolean"
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"spec-schema",
+					"module-schema",
+					"dependencies",
+					"typecheck",
+					"tests",
+					"format"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/agent-template/.ai/blueprints/add-migration/required-files.yaml

@@ -0,0 +1,18 @@
+schemaVersion: 1
+required:
+  - src/services/migration.ts (new byte-identical constant and ordered migrations entry appended; old constants untouched)
+  - src/services/database-repository.ts (row interface, fromRow, statement lists; migrations still run from the runtime migration lease)
+  - migrations/000N_{module}_{name}.up.sql
+  - migrations/000N_{module}_{name}.down.sql
+  - tests/migrations.test.ts (byte parity, fresh apply, pre-ledger adoption, second start)
+  - tests/module.test.ts (the createPgliteTestProvider() fixture proves the new data rule and tenant isolation)
+  - spec/module.yaml (invariant, specVersion)
+rules:
+  - PostgreSQL only; CREATE TABLE IF NOT EXISTS
+  - tenant_id TEXT NOT NULL on tenant-owned tables
+  - UNIQUE and indexes start with tenant_id, indexes end with id
+  - a new tenant table enables and forces row-level security and adds a <table>_tenant_policy on current_setting('coreloom.tenant_id', true)
+  - ALTER TABLE ADD COLUMN runs once through the ledger; inspectExisting detects an existing column
+  - applied migration bytes are immutable; a change always gets a new number
+  - inspectExisting returns complete only for every effect, absent only for none, partial for anything mixed
+  - numbering 0001, 0002, ... per module, append-only

package/agent-template/.ai/blueprints/add-migration/spec-requirements.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+status:
+  allowed:
+    - approved
+requiredKeys:
+  - dataOwnership
+  - invariants
+capabilities:
+  mustInclude:
+    - database
+onChange:
+  invariants: one sentence per new uniqueness, range or tenancy rule
+  specVersion: minor bump

package/agent-template/.ai/blueprints/add-migration/steps.yaml

@@ -0,0 +1,62 @@
+schemaVersion: 1
+steps:
+  - id: design
+    role: backend-engineer
+    action: Name the table or column, its type, CHECK, default and index; confirm the change is additive.
+    inputs:
+      - 'spec/module.yaml'
+    outputs:
+      - 'SQL draft'
+  - id: sql
+    role: backend-engineer
+    action: Write migrations/000N_{module}_{name}.up.sql first as one additive unit and .down.sql as documentation of the reverse; never edit an existing migration.
+    inputs:
+      - 'SQL draft'
+    outputs:
+      - 'migrations/000N_*.up.sql'
+      - 'migrations/000N_*.down.sql'
+  - id: mirror
+    role: backend-engineer
+    action: Append X_MIGRATION_00N to src/services/migration.ts with bytes identical to the .up.sql file and append its ordered { id, sql, inspectExisting } entry to databaseMigrations, with sql.postgresql set to the constant and inspectExisting built from postgresTenantTableState. Migrations run from the runtime migration lease, never from the repository.
+    inputs:
+      - 'migrations/000N_*.up.sql'
+    outputs:
+      - 'src/services/migration.ts'
+  - id: plumb
+    role: backend-engineer
+    action: Extend the row interface, fromRow, INSERT and SELECT lists, domain type, service validation and endpoint parsing.
+    inputs:
+      - 'SQL draft'
+    outputs:
+      - 'src/services/database-repository.ts'
+      - 'src/domain/types.ts'
+      - 'src/services/*-service.ts'
+      - 'src/api/endpoints.ts'
+    gates:
+      - 'typecheck'
+      - 'tests'
+      - 'format'
+  - id: prove
+    role: backend-engineer
+    action: Add migration tests proving SQL byte parity, fresh apply, safe adoption of a populated pre-ledger schema, and a clean second start. Add module tests for the new rule and tenant isolation; inspect migration status against a copy of the existing database before applying.
+    inputs:
+      - 'migrations/000N_*.up.sql'
+    outputs:
+      - 'tests/migrations.test.ts'
+      - 'tests/module.test.ts'
+    gates:
+      - 'tests'
+  - id: land
+    role: orchestrator
+    action: 'Sandbox: eject. Direct path: flowdular migration verify, pnpm verify, then a pull request stating that the schema applies on next boot.'
+    inputs:
+      - 'diff'
+    outputs:
+      - 'pull request'
+    gates:
+      - 'spec-schema'
+      - 'module-schema'
+      - 'dependencies'
+      - 'typecheck'
+      - 'tests'
+      - 'format'

package/agent-template/.ai/blueprints/author-spec/README.md

@@ -0,0 +1,5 @@
+# author-spec
+
+Turn an agreed business request into `modules/<dir>/spec/module.yaml`. In the sandbox this is the first turn of a `new-module` session, taken by `business-manager`; at the repository root it is `spec-author` following `.ai/agents/spec-author.md`. The blueprint creates or revises the specification only. It never creates implementation files and never sets `status: approved`; approval belongs to a human owner (the sandbox approve button, or an edit in the pull request).
+
+The result must validate against `packages/contracts/schemas/module-spec.schema.json` (`pnpm flowdular spec validate --all --json`) and be decision complete: permissions with one read and one manage id per entity, invariants for tenancy and uniqueness, data ownership, and acceptance scenarios that include a denial and a tenant isolation case. Unknown business decisions stay explicit questions in the handoff, never guesses. `templates/module.yaml` is a starting point with the keys the schema knows; `.ai/agents/sandbox/business-manager.md` carries a complete minimal example.

package/agent-template/.ai/blueprints/author-spec/allowed-paths.yaml

@@ -0,0 +1,7 @@
+schemaVersion: 1
+write:
+  - modules/{module}/spec/**
+deny:
+  - modules/{module}/src/**
+  - modules/{module}/migrations/**
+  - .ai/**

package/agent-template/.ai/blueprints/author-spec/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"id": "author-spec",
+	"version": "1.0.0",
+	"architecture": "0.2.0",
+	"risk": "workspace-write",
+	"owner": "platform-architecture",
+	"agentRoles": ["business-manager", "spec-author"],
+	"executorProfiles": ["sandbox-specialist", "repo-agent"],
+	"requiredReviewers": ["business-owner", "platform-owner"],
+	"requiresApprovedSpec": false,
+	"status": "approved"
+}

package/agent-template/.ai/blueprints/author-spec/examples/invalid/input-missing-outcome.json

@@ -0,0 +1,5 @@
+{
+	"moduleId": "sales.orders",
+	"businessOutcome": "Orders",
+	"actors": []
+}

package/agent-template/.ai/blueprints/author-spec/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"moduleId": "sales.orders",
+	"businessOutcome": "Let sales operators capture and confirm tenant-scoped customer orders.",
+	"actors": ["sales-operator", "sales-manager"],
+	"constraints": ["Every order belongs to exactly one tenant."]
+}

package/agent-template/.ai/blueprints/author-spec/gates.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+# Nothing executes this file; it documents the contract.
+gates:
+  - id: spec-schema
+    command: pnpm flowdular spec validate --all --json
+    sandbox: pnpm flowdular spec validate --all --json --root <session workspace>
+    required: true
+  - id: unresolved-decisions
+    assertion: the handoff lists zero open business questions
+    required: true
+  - id: human-approval
+    assertion: status is draft or in-review; an agent never wrote approved
+    required: true

package/agent-template/.ai/blueprints/author-spec/input.schema.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["moduleId", "businessOutcome", "actors"],
+	"properties": {
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"businessOutcome": { "type": "string", "minLength": 20 },
+		"actors": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "type": "string", "minLength": 1 },
+			"uniqueItems": true
+		},
+		"constraints": { "type": "array", "items": { "type": "string" } }
+	}
+}

package/agent-template/.ai/blueprints/author-spec/plan.schema.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["specPath", "openQuestions", "acceptanceScenarioCount"],
+	"properties": {
+		"specPath": {
+			"type": "string",
+			"pattern": "^modules/[a-z0-9-]+/spec/module\\.yaml$"
+		},
+		"openQuestions": { "type": "array", "items": { "type": "string" } },
+		"acceptanceScenarioCount": { "type": "integer", "minimum": 1 }
+	}
+}

package/agent-template/.ai/blueprints/author-spec/required-files.yaml

@@ -0,0 +1,6 @@
+schemaVersion: 1
+create:
+  - modules/{module}/spec/module.yaml
+forbid:
+  - modules/{module}/src/**
+  - modules/{module}/module.json

package/agent-template/.ai/blueprints/author-spec/spec-requirements.yaml

@@ -0,0 +1,35 @@
+schemaVersion: 1
+# Keys below exist in packages/contracts/schemas/module-spec.schema.json.
+status:
+  initial: draft
+  allowed:
+    - draft
+    - in-review
+  agentMayApprove: false
+requiredKeys:
+  - schemaVersion
+  - id
+  - specVersion
+  - status
+  - name
+  - description
+  - profile
+  - capabilities
+  - dependencies
+  - tenancy
+  - locales
+  - invariants
+  - permissions
+  - dataOwnership
+  - acceptanceScenarios
+identifiers:
+  id: ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$
+  permissions: <module>.<entity>.read and <module>.<entity>.manage
+  acceptanceScenarios: ^[A-Z][A-Z0-9-]+$
+acceptanceScenarios:
+  minimum: 3
+  mustInclude:
+    - denial
+    - tenant isolation
+openQuestions:
+  policy: stay in the handoff message; never guessed into the file

package/agent-template/.ai/blueprints/author-spec/steps.yaml

@@ -0,0 +1,28 @@
+schemaVersion: 1
+steps:
+  - id: collect
+    role: business-manager
+    action: Validate the brief against input.schema.json (module id, outcome, actors); list the business facts still missing.
+    inputs: [brief]
+    outputs: [open questions]
+  - id: ask
+    role: business-manager
+    action: Stop and ask for every unresolved business or security decision instead of guessing.
+    inputs: [open questions]
+    outputs: [answers]
+  - id: draft
+    role: business-manager
+    action: Write spec/module.yaml from templates/module.yaml with status draft; permissions, invariants, dataOwnership, acceptanceScenarios complete.
+    inputs: [answers]
+    outputs: [spec/module.yaml]
+    gates: [spec-schema]
+  - id: validate
+    role: orchestrator
+    action: pnpm flowdular spec validate --all --json (the sandbox spec-schema gate).
+    inputs: [spec/module.yaml]
+    outputs: [gate evidence]
+  - id: handoff
+    role: business-manager
+    action: Leave status as draft or in-review; end with HANDOFF to backend-engineer (or ux-designer for a ui profile) and let the operator approve.
+    inputs: [spec/module.yaml]
+    outputs: [handoff line]

package/agent-template/.ai/blueprints/author-spec/templates/module.yaml

@@ -0,0 +1,45 @@
+# Replace every {placeholder}. Keys are the ones module-spec.schema.json knows;
+# nothing else is accepted. Keep status: draft; a human approves.
+schemaVersion: 1
+id: '{moduleId}'
+specVersion: 0.1.0
+status: draft
+name: '{name}'
+description: '{businessOutcome}'
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: system.core
+    range: ^0.1.0
+  - id: auth.core
+    range: ^0.1.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Every {entity} is owned by exactly one tenant and every query uses the trusted tenant identifier.
+permissions:
+  - id: '{module}.{entities}.read'
+    description: Read {entities} in the active tenant.
+  - id: '{module}.{entities}.manage'
+    description: Create and update {entities} in the active tenant.
+dataOwnership:
+  - '{moduleId} owns {entity} identity and lifecycle status.'
+acceptanceScenarios:
+  - id: '{MODULE}-LIST'
+    given: Tenant-scoped {entities} exist.
+    when: An authorized principal lists {entities}.
+    then: Only {entities} owned by the active tenant are returned in deterministic order.
+  - id: '{MODULE}-CREATE'
+    given: An authorized principal supplies valid {entity} data.
+    when: The {entity} is created.
+    then: A tenant-owned active {entity} is persisted and returned with a generated identifier.
+  - id: '{MODULE}-DENY'
+    given: A principal is unauthenticated or lacks the required permission.
+    when: The principal reads or mutates {entities}.
+    then: The server denies the operation before repository access.

package/agent-template/.ai/blueprints/bug-fix/README.md

@@ -0,0 +1,5 @@
+# bug-fix
+
+Fix a defect at the owning layer with a regression test that fails before the fix. In the sandbox this is an `edit-module` session whose brief describes a symptom; at the repository root it is `.ai/skills/bug-hunt/SKILL.md` followed by a pull request. A defect in `packages/**` switches to `core-extend` for the paths and gates, and keeps this blueprint's steps.
+
+No behaviour beyond the fix travels in the change: no refactors, no renames, no reformatting of untouched code.

package/agent-template/.ai/blueprints/bug-fix/allowed-paths.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+write:
+  - modules/{module}/**
+deny:
+  - platform/**
+  - packages/**
+  - infra/**
+  - .github/**
+  - docs/**
+  - specs/**
+  - .ai/**
+  - flowdular.json
+  - pnpm-workspace.yaml
+  - modules/!({module})/**
+notes:
+  - a defect under packages/** follows core-extend allowed-paths.yaml
+# Written only by CLI commands, never by hand. The eject and the direct path
+# both run the commands; the files still travel in the same commit.
+cliOwned:
+  - path: flowdular.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/package.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/src/generated/modules.server.ts
+    command: pnpm flowdular module sync --apply
+  - path: platform/src/generated/modules.client.ts
+    command: pnpm flowdular module sync --apply
+  - path: pnpm-lock.yaml
+    command: pnpm install

package/agent-template/.ai/blueprints/bug-fix/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "bug-fix",
+	"version": "1.0.0",
+	"risk": "workspace-write",
+	"agentRoles": ["backend-engineer", "frontend-engineer", "module-executor"],
+	"executorProfiles": ["sandbox-specialist", "repo-agent"],
+	"requiredReviewers": ["reviewer"],
+	"requiresApprovedSpec": false
+}

package/agent-template/.ai/blueprints/bug-fix/examples/invalid/input-no-symptom.json

@@ -0,0 +1,4 @@
+{
+	"scope": "module",
+	"target": "catalog.core"
+}

package/agent-template/.ai/blueprints/bug-fix/examples/invalid/plan-no-test.json

@@ -0,0 +1,8 @@
+{
+	"blueprint": "bug-fix@1.0.0",
+	"rootCause": "A guess without reproduction.",
+	"owningLayer": "service",
+	"regressionTest": "",
+	"siblings": [],
+	"gates": ["typecheck"]
+}

package/agent-template/.ai/blueprints/bug-fix/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"scope": "module",
+	"target": "catalog.core",
+	"symptom": "POST /api/catalog/items returns 500 when sku is longer than 64 characters.",
+	"reproduction": "createCatalogItem with a 70 character sku through route.handler(createContext(...))."
+}

package/agent-template/.ai/blueprints/bug-fix/examples/valid/plan.json

@@ -0,0 +1,8 @@
+{
+	"blueprint": "bug-fix@1.0.0",
+	"rootCause": "requiredString max for sku is missing so the service throws a generic error after the HTTP layer accepted the value.",
+	"owningLayer": "http",
+	"regressionTest": "tests/module.test.ts: rejects a sku above 64 characters with INVALID_INPUT",
+	"siblings": ["modules/parties/src/api/endpoints.ts"],
+	"gates": ["typecheck", "tests", "format"]
+}

package/agent-template/.ai/blueprints/bug-fix/gates.yaml

@@ -0,0 +1,30 @@
+schemaVersion: 1
+# Ids equal GateId in packages/sandbox/src/server/gates.ts. The sandbox runs the
+# gates a role lists in its front matter after every turn that changed files;
+# from the repository root run the command column yourself. Nothing executes
+# this file; it documents the contract.
+gates:
+  - id: spec-schema
+    command: pnpm flowdular spec validate --all --json
+    sandbox: pnpm flowdular spec validate --all --json --root <session workspace>
+    required: true
+  - id: module-schema
+    command: pnpm flowdular module validate --json
+    sandbox: pnpm flowdular module validate --json --root <session workspace>
+    required: true
+  - id: dependencies
+    command: 'grep the imports under src/** and compare with package.json dependencies (no CLI command yet)'
+    sandbox: checkDeclaredDependencies(modulePath) in packages/sandbox/src/server/dependencies.ts, run after every turn that changed files, plus a pnpm install when a package.json changed
+    required: true
+  - id: typecheck
+    command: pnpm --filter @flowdular/module-{module} typecheck
+    sandbox: node_modules/.bin/tsrx-tsc --noEmit -p tsconfig.json (cwd module)
+    required: true
+  - id: tests
+    command: pnpm --filter @flowdular/module-{module} test
+    sandbox: node_modules/.bin/vitest run --passWithNoTests (cwd module; zero tests still pass)
+    required: true
+  - id: format
+    command: pnpm format:check
+    sandbox: prettier --check . (cwd module)
+    required: true

package/agent-template/.ai/blueprints/bug-fix/input.schema.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["scope", "target", "symptom"],
+	"properties": {
+		"scope": {
+			"type": "string",
+			"enum": ["module", "package"]
+		},
+		"target": {
+			"type": "string",
+			"minLength": 1
+		},
+		"symptom": {
+			"type": "string",
+			"minLength": 8,
+			"maxLength": 4000
+		},
+		"reproduction": {
+			"type": "string",
+			"maxLength": 4000
+		}
+	}
+}

package/agent-template/.ai/blueprints/bug-fix/plan.schema.json

@@ -0,0 +1,53 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"blueprint",
+		"rootCause",
+		"owningLayer",
+		"regressionTest",
+		"siblings",
+		"gates"
+	],
+	"properties": {
+		"blueprint": {
+			"const": "bug-fix@1.0.0"
+		},
+		"rootCause": {
+			"type": "string",
+			"minLength": 8
+		},
+		"owningLayer": {
+			"type": "string",
+			"enum": ["http", "service", "repository", "client", "composition", "core"]
+		},
+		"regressionTest": {
+			"type": "string",
+			"minLength": 1
+		},
+		"siblings": {
+			"type": "array",
+			"items": {
+				"type": "string"
+			},
+			"uniqueItems": true
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"spec-schema",
+					"module-schema",
+					"dependencies",
+					"typecheck",
+					"tests",
+					"format"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/agent-template/.ai/blueprints/bug-fix/required-files.yaml

@@ -0,0 +1,7 @@
+schemaVersion: 1
+required:
+  - tests/module.test.ts (or a new tests/*.test.ts) containing the regression test
+changed:
+  - exactly the files of the owning layer named in the plan
+forbidden:
+  - unrelated refactors, renames, reformatting of untouched code

package/agent-template/.ai/blueprints/bug-fix/spec-requirements.yaml

@@ -0,0 +1,7 @@
+schemaVersion: 1
+status:
+  allowed:
+    - approved
+onFix:
+  specVersion: patch bump when the fix changes observable behaviour named in a scenario
+  acceptanceScenarios: add one only when the bug shows a missing scenario; never rewrite existing ones