substrate-ai 0.20.52 → 0.20.54

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import { createLogger } from "../logger-KeHncl-f.js";
 import { createEventBus } from "../helpers-CElYrONe.js";
 import { AdapterRegistry, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, ConfigError, CostTrackerConfigSchema, DEFAULT_CONFIG, DoltClient, DoltNotInstalled, GlobalSettingsSchema, InMemoryDatabaseAdapter, IngestionServer, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProvidersSchema, RoutingRecommender, STORY_METRICS, TelemetryConfigSchema, addTokenUsage, aggregateTokenUsageForRun, checkDoltInstalled, compareRunMetrics, createAmendmentRun, createConfigSystem, createDecision, createDoltClient, createPipelineRun, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initializeDolt, listRunMetrics, loadParentRunDecisions, supersedeDecision, tagRunAsBaseline, updatePipelineRun } from "../dist-VcMmfo2w.js";
 import "../adapter-registry-DXLMTmfD.js";
-import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runSolutioningPhase, validateStopAfterFromConflict } from "../run-BxDi30CG.js";
+import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runSolutioningPhase, validateStopAfterFromConflict } from "../run-DgmoC6HT.js";
 import "../errors-CogpxBUg.js";
 import "../routing-CcBOCuC9.js";
 import "../decisions-C0pz9Clx.js";
@@ -5204,7 +5204,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-7s_WEIAe.js"
+									"../run-B-SRlzdi.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

package/dist/{run-7s_WEIAe.js → run-B-SRlzdi.js}

@@ -2,7 +2,7 @@ import "./health-sQ1X_5_6.js";
 import "./logger-KeHncl-f.js";
 import "./helpers-CElYrONe.js";
 import "./dist-VcMmfo2w.js";
-import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, runRunAction, wireNdjsonEmitter } from "./run-BxDi30CG.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-DgmoC6HT.js";
 import "./routing-CcBOCuC9.js";
 import "./decisions-C0pz9Clx.js";
 

package/dist/{run-BxDi30CG.js → run-DgmoC6HT.js}

@@ -8448,12 +8448,13 @@ const TIMEOUT_RETRY_MULTIPLIER = 1.5;
 */
 async function runProbeAuthor(deps, params) {
 	const start = Date.now();
-	const { storyKey, storyFilePath, pipelineRunId, sourceAcContent, epicContent, emitEvent, bypassGates } = params;
+	const { storyKey, storyFilePath, pipelineRunId, sourceAcContent, epicContent, emitEvent, bypassGates, stateIntegratingEnabled } = params;
 	const tokenUsage = {
 		input: 0,
 		output: 0
 	};
-	if (bypassGates !== true && !detectsEventDrivenAC(epicContent) && !detectsStateIntegratingAC(epicContent)) {
+	const stateIntegratingActive = stateIntegratingEnabled !== false;
+	if (bypassGates !== true && !detectsEventDrivenAC(epicContent) && !(stateIntegratingActive && detectsStateIntegratingAC(epicContent))) {
 		logger$14.debug({ storyKey }, "probe-author: source AC neither event-driven nor state-integrating — skipping");
 		emitEvent?.("probe-author:skipped", {
 			storyKey,
@@ -13467,7 +13468,8 @@ function createImplementationOrchestrator(deps) {
 				const section = extractStorySection(epicFull, storyKey);
 				probeAuthorEpicContent = section ?? epicFull;
 			} catch {}
-			if (detectsEventDrivenAC(probeAuthorEpicContent) || detectsStateIntegratingAC(probeAuthorEpicContent)) {
+			const stateIntegratingEnabled = config.probeAuthorStateIntegrating !== false;
+			if (detectsEventDrivenAC(probeAuthorEpicContent) || stateIntegratingEnabled && detectsStateIntegratingAC(probeAuthorEpicContent)) {
 				let artifactHasProbes = false;
 				try {
 					const artifactContent = readFileSync(storyFilePath, "utf-8");
@@ -13489,6 +13491,7 @@ function createImplementationOrchestrator(deps) {
 						pipelineRunId: config.pipelineRunId ?? "",
 						sourceAcContent: probeAuthorEpicContent,
 						epicContent: probeAuthorEpicContent,
+						stateIntegratingEnabled,
 						emitEvent: (name, payload) => {
 							eventBus.emit("orchestrator:story-warn", {
 								storyKey,
@@ -44004,8 +44007,23 @@ function wireNdjsonEmitter(eventBus, ndjsonEmitter) {
 		});
 	});
 }
+/**
+* Resolve the `probeAuthorStateIntegrating` boolean from CLI flag and env var.
+*
+* Precedence: CLI flag (`on`/`off`) > env var `SUBSTRATE_PROBE_AUTHOR_STATE_INTEGRATING`
+* (`on`/`off`) > default `true`.
+*
+* @param cliFlag - The value of `--probe-author-state-integrating` CLI flag, or undefined
+* @returns `true` when state-integrating dispatch is enabled, `false` when disabled
+*/
+function resolveProbeAuthorStateIntegrating(cliFlag) {
+	if (cliFlag !== void 0) return cliFlag === "on";
+	const envVal = process.env["SUBSTRATE_PROBE_AUTHOR_STATE_INTEGRATING"];
+	if (envVal !== void 0) return envVal === "on";
+	return true;
+}
 async function runRunAction(options) {
-	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, skipVerification, epic: epicNumber, dryRun, maxReviewCycles = 2, engine, agent: agentId, registry: injectedRegistry, haltOn, costCeiling, probeAuthor } = options;
+	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, skipVerification, epic: epicNumber, dryRun, maxReviewCycles = 2, engine, agent: agentId, registry: injectedRegistry, haltOn, costCeiling, probeAuthor, probeAuthorStateIntegrating: probeAuthorStateIntegratingFlag } = options;
 	const VALID_PROBE_AUTHOR_MODES = [
 		"enabled",
 		"disabled",
@@ -44017,6 +44035,14 @@ async function runRunAction(options) {
 		else process.stderr.write(`Error: ${errorMsg}\n`);
 		return 1;
 	}
+	const VALID_PROBE_AUTHOR_STATE_INTEGRATING = ["on", "off"];
+	if (probeAuthorStateIntegratingFlag !== void 0 && !VALID_PROBE_AUTHOR_STATE_INTEGRATING.includes(probeAuthorStateIntegratingFlag)) {
+		const errorMsg = `Invalid --probe-author-state-integrating value '${probeAuthorStateIntegratingFlag}'. Valid values: on | off`;
+		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
+		else process.stderr.write(`Error: ${errorMsg}\n`);
+		return 1;
+	}
+	const resolvedProbeAuthorStateIntegrating = resolveProbeAuthorStateIntegrating(probeAuthorStateIntegratingFlag);
 	const VALID_HALT_ON = [
 		"all",
 		"critical",
@@ -44212,6 +44238,7 @@ async function runRunAction(options) {
 			meshProjectId
 		} : {},
 		...probeAuthor !== void 0 ? { probeAuthor } : {},
+		probeAuthorStateIntegrating: resolvedProbeAuthorStateIntegrating,
 		engineType: resolvedEngine,
 		maxReviewCycles: effectiveMaxReviewCycles,
 		retryBudget: configRetryBudget ?? 2,
@@ -44750,7 +44777,8 @@ async function runRunAction(options) {
 					enableHeartbeat: eventsFlag === true,
 					skipPreflight: skipPreflight === true,
 					...skipVerification === true ? { skipVerification: true } : {},
-					...probeAuthor !== void 0 ? { probeAuthorMode: probeAuthor } : {}
+					...probeAuthor !== void 0 ? { probeAuthorMode: probeAuthor } : {},
+					probeAuthorStateIntegrating: resolvedProbeAuthorStateIntegrating
 				},
 				projectRoot,
 				tokenCeilings,
@@ -44881,7 +44909,7 @@ async function runRunAction(options) {
 	}
 }
 async function runFullPipeline(options) {
-	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, skipVerification, maxReviewCycles = 2, retryBudget, registry: injectedRegistry, tokenCeilings, stories: explicitStories, telemetryEnabled: fullTelemetryEnabled, telemetryPort: fullTelemetryPort, agentId, meshUrl: fpMeshUrl, meshProjectId: fpMeshProjectId, engineType: fpEngineType, probeAuthor } = options;
+	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, skipVerification, maxReviewCycles = 2, retryBudget, registry: injectedRegistry, tokenCeilings, stories: explicitStories, telemetryEnabled: fullTelemetryEnabled, telemetryPort: fullTelemetryPort, agentId, meshUrl: fpMeshUrl, meshProjectId: fpMeshProjectId, engineType: fpEngineType, probeAuthor, probeAuthorStateIntegrating: fpProbeAuthorStateIntegrating } = options;
 	if (!existsSync$1(dbDir)) mkdirSync$1(dbDir, { recursive: true });
 	let doltServerFull = null;
 	try {
@@ -45183,7 +45211,8 @@ async function runFullPipeline(options) {
 						pipelineRunId: runId,
 						skipPreflight: skipPreflight === true,
 						...skipVerification === true ? { skipVerification: true } : {},
-						...probeAuthor !== void 0 ? { probeAuthorMode: probeAuthor } : {}
+						...probeAuthor !== void 0 ? { probeAuthorMode: probeAuthor } : {},
+						...fpProbeAuthorStateIntegrating !== void 0 ? { probeAuthorStateIntegrating: fpProbeAuthorStateIntegrating } : {}
 					},
 					projectRoot,
 					tokenCeilings,
@@ -45339,7 +45368,7 @@ async function runFullPipeline(options) {
 	}
 }
 function registerRunCommand(program, _version = "0.0.0", projectRoot = process.cwd(), registry) {
-	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--epic <n>", "Scope story discovery to a single epic number (e.g., 27)", (v) => parseInt(v, 10)).option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").option("--research", "Enable the research phase even if not set in the pack manifest").option("--skip-research", "Skip the research phase even if enabled in the pack manifest").option("--skip-preflight", "Skip the pre-flight build check (escape hatch for known-broken projects)").option("--skip-verification", "Skip the post-dispatch verification pipeline (Story 51-5)").option("--max-review-cycles <n>", "Maximum review cycles per story (default: 2)", (v) => parseInt(v, 10), 2).option("--dry-run", "Preview routing and repo-map injection without dispatching (Story 28-9)").option("--engine <type>", "Execution engine: linear (default) or graph").option("--agent <id>", "Agent backend: claude-code (default), codex, or gemini").option("--halt-on <severity>", "Halt pipeline on escalation severity: all | critical | none (default: none)", "none").option("--cost-ceiling <amount>", "Maximum cost ceiling in USD (positive number); halts pipeline when exceeded", parseFloat).option("--probe-author <mode>", "probe-author phase mode: enabled | disabled | auto (default: auto = SUBSTRATE_PROBE_AUTHOR_ENABLED env, default true) (Story 60-14)", "auto").action(async (opts) => {
+	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--epic <n>", "Scope story discovery to a single epic number (e.g., 27)", (v) => parseInt(v, 10)).option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").option("--research", "Enable the research phase even if not set in the pack manifest").option("--skip-research", "Skip the research phase even if enabled in the pack manifest").option("--skip-preflight", "Skip the pre-flight build check (escape hatch for known-broken projects)").option("--skip-verification", "Skip the post-dispatch verification pipeline (Story 51-5)").option("--max-review-cycles <n>", "Maximum review cycles per story (default: 2)", (v) => parseInt(v, 10), 2).option("--dry-run", "Preview routing and repo-map injection without dispatching (Story 28-9)").option("--engine <type>", "Execution engine: linear (default) or graph").option("--agent <id>", "Agent backend: claude-code (default), codex, or gemini").option("--halt-on <severity>", "Halt pipeline on escalation severity: all | critical | none (default: none)", "none").option("--cost-ceiling <amount>", "Maximum cost ceiling in USD (positive number); halts pipeline when exceeded", parseFloat).option("--probe-author <mode>", "probe-author phase mode: enabled | disabled | auto (default: auto = SUBSTRATE_PROBE_AUTHOR_ENABLED env, default true) (Story 60-14)", "auto").option("--probe-author-state-integrating <value>", "Disable probe-author dispatch for state-integrating ACs (Phase 3). Use to ramp DOWN if catch rate drops below the GREEN threshold. Values: on | off (default: on)").action(async (opts) => {
 		if (opts.helpAgent) {
 			process.exitCode = await runHelpAgent();
 			return;
@@ -45382,12 +45411,13 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 			registry,
 			haltOn: opts.haltOn,
 			costCeiling: opts.costCeiling,
-			probeAuthor: opts.probeAuthor
+			probeAuthor: opts.probeAuthor,
+			probeAuthorStateIntegrating: opts.probeAuthorStateIntegrating
 		});
 		process.exitCode = exitCode;
 	});
 }
 
 //#endregion
-export { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, normalizeGraphSummaryToStatus, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveMaxReviewCycles, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runRunAction, runSolutioningPhase, validateStopAfterFromConflict, wireNdjsonEmitter };
-//# sourceMappingURL=run-BxDi30CG.js.map
+export { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, normalizeGraphSummaryToStatus, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runRunAction, runSolutioningPhase, validateStopAfterFromConflict, wireNdjsonEmitter };
+//# sourceMappingURL=run-DgmoC6HT.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.20.52",
+  "version": "0.20.54",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",

package/packs/bmad/prompts/probe-author.md

@@ -162,6 +162,156 @@ Strata Story 2-4 ("morning briefing generator", v0.20.41) shipped two architectu
 
 A one-repo variant of this probe would pass against the (broken) v0.20.41 implementation; the two-repo variant catches the wrong-cwd defect because the parent-cwd `git log --all` returns BOTH commits but substring-match attribution mis-routes them.
 
+## State-integration probe shapes
+
+State-integration probes exercise code that reads from or writes to external state: the filesystem, subprocesses, git repositories, databases, network endpoints, and registries. Four principles govern probe design in this category:
+
+1. **Real-state context, not synthesized**: populate a tmpdir with a structure matching the production layout (e.g., for fleet-scanning logic, N subdirs each containing a `.git` directory). Do not pass artificial in-memory structures or bypass the I/O layer.
+2. **Sandbox choice leans `twin` more often**: any probe that touches the user's home directory, writes to the filesystem outside the project, or exercises a running service MUST use `sandbox: twin`. Reserve `sandbox: host` exclusively for read-only registry / config-shape probes that cannot mutate host state.
+3. **Multi-resource fixtures MUST contain ≥2 distinct, non-overlapping resources**: a single-resource fixture silently passes when the defect only surfaces under multiplicity. Create two or more distinct instances and assert each one independently.
+4. **External-binary availability assertions**: if the probe invokes `git`, `dolt`, `podman`, or any other binary that may not be installed, either add a sibling availability probe or put an inline `command -v <binary> || { echo "NOT_FOUND"; exit 1; }` check at the top of the `command:` block.
+
+### Filesystem shape
+
+Populate a tmpdir with a production-layout directory structure and assert file contents or directory invariants. Use `sandbox: twin` — the probe writes to the filesystem.
+
+```yaml
+- name: fleet-config-files-written-per-project
+  sandbox: twin
+  command: |
+    set -e
+    FLEET=$(mktemp -d)
+    mkdir -p "$FLEET/alpha" "$FLEET/beta"
+    node <REPO_ROOT>/dist/cli.mjs scan-fleet --root "$FLEET"
+    test -f "$FLEET/alpha/config.json" && echo "ALPHA_CONFIG_FOUND"
+    test -f "$FLEET/beta/config.json" && echo "BETA_CONFIG_FOUND"
+  expect_stdout_regex:
+    - ALPHA_CONFIG_FOUND
+    - BETA_CONFIG_FOUND
+  description: fleet scanner writes per-project config files to production-layout tmpdir with ≥2 dirs
+```
+
+### Subprocess shape
+
+Assert binary availability first via `command -v`, then exercise the subprocess via its production invocation path. Use `sandbox: twin` — the probe may mutate host state.
+
+```yaml
+- name: git-binary-available
+  sandbox: host
+  command: |
+    command -v git && echo "GIT_FOUND" || { echo "GIT_NOT_FOUND"; exit 1; }
+  expect_stdout_regex:
+    - GIT_FOUND
+  description: git binary must be on PATH before subprocess probes run
+- name: subprocess-production-path-invoked
+  sandbox: twin
+  command: |
+    set -e
+    TMPOUT=$(mktemp)
+    node <REPO_ROOT>/dist/cli.mjs run-task --output "$TMPOUT"
+    grep -q '"status":"ok"' "$TMPOUT" && echo "TASK_COMPLETED"
+  expect_stdout_regex:
+    - TASK_COMPLETED
+  description: subprocess invocation via production CLI path produces expected output shape
+```
+
+### Git shape (canonical obs_017 pattern)
+
+Create a ≥2-repo fleet in a tmpdir with non-overlapping commit messages, set `cwd` per-repo (NOT fleet root), and assert each repo's commits are attributed correctly. This is the canonical obs_017 pattern: the cwd-as-parent defect produces plausible output against a one-repo fleet but fails with two repos because `git log` at fleet root aggregates all repos' commits into one undifferentiated blob, making per-project attribution impossible.
+
+```yaml
+- name: git-per-repo-commit-attribution
+  sandbox: twin
+  command: |
+    set -e
+    FLEET=$(mktemp -d)
+    for proj in alpha beta; do
+      mkdir -p "$FLEET/$proj"
+      git -C "$FLEET/$proj" init -q
+      git -C "$FLEET/$proj" config user.email t@example.com
+      git -C "$FLEET/$proj" config user.name test
+      echo "$proj content" > "$FLEET/$proj/a.md"
+      git -C "$FLEET/$proj" add .
+      git -C "$FLEET/$proj" commit -qm "$proj-only commit"
+    done
+    ALPHA_LOG=$(git -C "$FLEET/alpha" log --oneline)
+    BETA_LOG=$(git -C "$FLEET/beta" log --oneline)
+    echo "alpha: $ALPHA_LOG"
+    echo "beta: $BETA_LOG"
+  expect_stdout_regex:
+    - 'alpha:.*alpha-only commit'
+    - 'beta:.*beta-only commit'
+  expect_stdout_no_regex:
+    - 'alpha:.*beta-only commit'
+    - 'beta:.*alpha-only commit'
+  description: >-
+    per-repo cwd correctly isolates each project's commits — catches the cwd-as-parent
+    defect (obs_017) where git log at fleet root aggregates all repos into one blob
+```
+
+### Database shape
+
+Exercise a Dolt or SQLite database in a twin sandbox, seeding ≥2 rows and asserting per-row behavior. Use `sandbox: twin`.
+
+```yaml
+- name: database-per-row-attribution
+  sandbox: twin
+  command: |
+    set -e
+    DBDIR=$(mktemp -d)
+    sqlite3 "$DBDIR/test.db" "CREATE TABLE items (id INTEGER, name TEXT);"
+    sqlite3 "$DBDIR/test.db" "INSERT INTO items VALUES (1, 'alpha-item');"
+    sqlite3 "$DBDIR/test.db" "INSERT INTO items VALUES (2, 'beta-item');"
+    node <REPO_ROOT>/dist/cli.mjs query-items --db "$DBDIR/test.db"
+  expect_stdout_regex:
+    - alpha-item
+    - beta-item
+  description: database probe seeds ≥2 rows and asserts per-row output is correctly attributed
+```
+
+### Network shape
+
+Exercise an HTTP endpoint with `expect_stdout_no_regex` error-envelope guards. Use `sandbox: twin` for endpoints that mutate state; `sandbox: host` for strictly read-only checks that cannot affect the host.
+
+```yaml
+- name: api-endpoint-returns-success-shape
+  sandbox: twin
+  command: |
+    set -e
+    curl -sf http://localhost:3000/health
+  expect_stdout_no_regex:
+    - '"isError"\s*:\s*true'
+    - '"status"\s*:\s*"error"'
+    - '"error"\s*:'
+  expect_stdout_regex:
+    - '"status"\s*:\s*"ok"'
+  description: health endpoint returns success-shaped JSON without error envelope
+```
+
+### Registry shape
+
+Read from an npm/package registry or fleet-config source. Precede the registry probe with a binary-availability sibling probe. Use `sandbox: host` — registry reads are strictly read-only and cannot mutate host state.
+
+```yaml
+- name: npm-binary-available
+  sandbox: host
+  command: |
+    command -v npm && echo "NPM_FOUND" || { echo "NPM_NOT_FOUND"; exit 1; }
+  expect_stdout_regex:
+    - NPM_FOUND
+  description: npm binary must be on PATH before registry probe runs
+- name: package-registry-version-resolves
+  sandbox: host
+  command: |
+    npm view @substrate-ai/sdlc version 2>&1
+  expect_stdout_no_regex:
+    - 'Not found'
+    - 'npm ERR!'
+  expect_stdout_regex:
+    - '\d+\.\d+\.\d+'
+  description: npm registry resolves @substrate-ai/sdlc and returns a semver version string
+```
+
 ## Mission
 
 Author runtime probes for the story described above. Use the AC sections provided: