@stdd/plugin 0.9.1 → 0.10.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "stdd",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Native STDD workflow skills and lifecycle context",
   "author": {
     "name": "Azamat Almazbek uulu"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "stdd",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Native STDD workflow skills and lifecycle context for Codex",
   "author": {
     "name": "Azamat Almazbek uulu"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stdd/plugin",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Universal STDD workflow skills and lifecycle integration for Codex, Claude Code, and Pi",
   "type": "module",
   "license": "MIT",

package/runtime/adapters/README.md

@@ -6,6 +6,15 @@ runs the adapters; re-run it after upgrading stdd to refresh the output.
 
 ## Common output
 
+Every host receives the same five-route always-on contract. Investigation
+answers current-state factual or diagnostic questions directly, Brainstorming
+explores opinions and future or hypothetical behavior directly, and only
+explicit intent to persist or modify the repository enters Start Change.
+Implement and Finish Change execute and close that action. Unknown current
+facts may cause Investigation → Brainstorming; ordinary docs or code reading
+inside Brainstorming does not. The renderer preserves host-native invocation
+syntax: Claude `/name`, Codex `$name`, and Pi `/skill:name`.
+
 Every init installs `.stdd/` into the target repo:
 
 ```
@@ -95,18 +104,7 @@ the extension queues one corrective follow-up model turn and then fails open;
 it never creates an unbounded continuation loop. A conflicting user-owned
 `.pi/extensions/stdd.js` is not overwritten.
 
-## CI
-
-CI adapters only transport provider state into portable CLI commands:
-
-- GitHub writes `.github/workflows/stdd.yml`;
-- GitLab writes `.gitlab/stdd.gitlab-ci.yml`; same-project MRs authenticate
-  with `CI_JOB_TOKEN`, while a fork source project must be on the target's
-  CI job-token allowlist. A trusted controlled fork may instead provide a
-  masked and hidden `STDD_GITLAB_READ_API_TOKEN` scoped to target-project
-  `read_api`; target secrets must never be exposed to untrusted fork code;
-- generic prints the `check` and `check-pr` command contract without writing
-  provider configuration.
+## Adapter composition and renderer tokens
 
 The public SDK exposes the built-in adapter registry and render functions so
 other packages can add a host without importing `cli/` internals.
@@ -128,6 +126,15 @@ capabilities (`subagents` on, `crossCli` off). Its planning skill names
 `--via subagent`; it never names a cross-CLI reviewer, emits a renderer token,
 or falls back to manual self-review.
 
+## CI
+
+Adapters compile playbooks for agents; they do not write CI. A provider
+workflow is infrastructure the repository owns, and stdd generates none of it.
+The contract a job composes is `stdd check .` over the checkout and the live
+review description piped to `stdd check-pr - --base <ref>`; see the `## CI`
+section of `method/reference-integration.md` for the three things a
+hand-written job has to get right.
+
 ## Plugin distribution
 
 `plugins/stdd/` is one generated distribution for Codex, Claude Code, and Pi.
@@ -148,6 +155,10 @@ fail-open and never forward arbitrary child output.
 
 ## Design rules for adapters
 
+- The five direct/action routes are mandatory and stay semantically identical
+  across hosts; only their invocation syntax changes.
+- Idle lifecycle output is neutral: discussion and read-only work do not need a
+  task, and generated hooks do not prime agents to create one.
 - One source of truth: adapters copy or point, never fork playbook content.
 - Always-on instructions contain invariants and routing only; detailed
   workflows live in lazy skills.

package/runtime/cli/check.mjs

@@ -529,7 +529,7 @@ export async function doctor(targetDir, readinessOnly = false) {
 				report(
 					false,
 					`.github/workflows/${file} validates the frozen event payload body — ` +
-						"body edits will not be re-checked; see stdd init --ci github",
+						"body edits will not be re-checked; fetch it live from the API instead",
 				);
 			}
 		}

package/runtime/cli/generated-files.mjs

@@ -5,7 +5,6 @@ import { fileURLToPath } from "node:url";
 import {
 	AGENT_ADAPTERS,
 	assertSemanticVersion,
-	CI_ADAPTERS,
 	getAgentAdapter,
 	renderAgentInstructions,
 } from "../sdk/adapters.mjs";
@@ -27,7 +26,6 @@ import { MANIFEST_HASH_PATTERN } from "./state-validation.mjs";
 export const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8")).version;
 export const KNOWN_TOOLS = Object.keys(AGENT_ADAPTERS);
-export const KNOWN_CI = Object.keys(CI_ADAPTERS);
 export const KNOWN_CAPABILITIES = Object.keys(DEFAULT_CONFIG.capabilities);
 export const CLEANUP_JOURNAL_REL = ".stdd/cleanup-transaction.json";
 const SHIPPED_PLAYBOOK_FILES = new Set(
@@ -79,14 +77,30 @@ export function validateAdapterSelection(field, values, known, { nonEmpty = fals
 	return [...values];
 }
 
+// `ci` is a retired key, not a required one: installs made before provider CI
+// adapters were removed still carry it, and rejecting their manifest would
+// turn an upgrade into a hard failure. It is accepted, never validated against
+// a registry, and never written back.
+const RETIRED_MANIFEST_TARGET_KEYS = ["ci"];
+const RETIRED_CI_PROVIDERS = ["github", "gitlab", "generic"];
+
+// The paths those adapters used to write. Nothing generates them any more, but
+// a pre-0.10.0 manifest still lists them, so they stay recognized outputs —
+// otherwise the upgrade fails validation before it can do anything. They are
+// released rather than retired, so the sweep never deletes an adopter's CI
+// gate — see finalizeGeneratedFilesWithCapabilities.
+const RETIRED_GENERATED_OUTPUTS = [".github/workflows/stdd.yml", ".gitlab/stdd.gitlab-ci.yml"];
+
 function validateManifestTargets(value) {
-	const required = ["tools", "ci", "hooks", "sessionHook", "stopHook"];
+	const required = ["tools", "hooks", "sessionHook", "stopHook"];
 	if (typeof value !== "object" || value === null || Array.isArray(value)) {
 		throw new TypeError("must be an object");
 	}
 	const keys = Object.keys(value);
 	const missing = required.filter((key) => !Object.hasOwn(value, key));
-	const unknown = keys.filter((key) => !required.includes(key));
+	const unknown = keys.filter(
+		(key) => !required.includes(key) && !RETIRED_MANIFEST_TARGET_KEYS.includes(key),
+	);
 	if (missing.length > 0 || unknown.length > 0) {
 		throw new TypeError(
 			`must contain exactly ${required.join(", ")}${
@@ -97,13 +111,17 @@ function validateManifestTargets(value) {
 	const tools = validateAdapterSelection("tools", value.tools, KNOWN_TOOLS, {
 		nonEmpty: true,
 	});
-	const ci = validateAdapterSelection("ci", value.ci, KNOWN_CI);
+	// A retired key is still graded before it is discarded: tolerating the
+	// upgrade is not the same as accepting a corrupt manifest, and `check`
+	// exists to notice one.
+	if (Object.hasOwn(value, "ci")) {
+		validateAdapterSelection("ci", value.ci, RETIRED_CI_PROVIDERS);
+	}
 	for (const field of ["hooks", "sessionHook", "stopHook"]) {
 		if (typeof value[field] !== "boolean") throw new TypeError(`${field} must be a boolean`);
 	}
 	return {
 		tools,
-		ci,
 		hooks: value.hooks,
 		sessionHook: value.sessionHook,
 		stopHook: value.stopHook,
@@ -188,9 +206,7 @@ function isRecognizedGeneratedOutput(file) {
 	const exact = new Set([
 		".stdd/method.md",
 		...Object.values(AGENT_ADAPTERS).map((adapter) => adapter.snippetFile),
-		...Object.values(CI_ADAPTERS)
-			.map((adapter) => adapter.outputFile)
-			.filter((output) => output !== null),
+		...RETIRED_GENERATED_OUTPUTS,
 		...[...KNOWN_MANAGED_PLAYBOOK_FILES].map((name) => `.stdd/playbooks/${name}`),
 	]);
 	if (exact.has(file)) return true;
@@ -1116,6 +1132,18 @@ export async function finalizeGeneratedFilesWithCapabilities(
 	try {
 		for (const [file, hash] of Object.entries(oldFiles)) {
 			if (Object.hasOwn(generated, file)) continue;
+			// Release, do not retire. A pre-0.10.0 install lists a generated
+			// provider workflow here; nothing generates one now, so the sweep
+			// below would delete it for being byte-identical and unclaimed — an
+			// upgrade that silently removes the repository's CI gate. Skipping it
+			// leaves the file on disk and out of the new manifest: the adopter
+			// owns it from here, edits and all.
+			if (RETIRED_GENERATED_OUTPUTS.includes(file)) {
+				console.log(
+					`Left ${file} in place — stdd no longer generates provider CI; it is yours to maintain`,
+				);
+				continue;
+			}
 			const inspected = await nativeInspectOutput(context, file);
 			if (inspected.kind === "missing") continue;
 			if (inspected.kind !== "ok") {
@@ -1356,7 +1384,6 @@ export async function finalizeGeneratedFilesWithCapabilities(
 			files: generated,
 			targets: {
 				tools: targets.tools,
-				ci: targets.ci,
 				hooks: targets.hooks,
 				sessionHook: targets.sessionHook,
 				stopHook: targets.stopHook,
@@ -1470,9 +1497,6 @@ function discoverGeneratedOutputs(targetDir) {
 		...loadLocalPlaybooks(targetDir).map((playbook) => playbook.meta.name),
 	]);
 	for (const playbook of shippedPlaybooks) addIfPresent(`.stdd/playbooks/${playbook.file}`);
-	for (const adapter of Object.values(CI_ADAPTERS)) {
-		if (adapter.outputFile) addIfPresent(adapter.outputFile);
-	}
 
 	for (const adapter of Object.values(AGENT_ADAPTERS)) {
 		// Shipped and validated local skill names reserve generated-output paths. Surface an

package/runtime/cli/init.mjs

@@ -3,13 +3,11 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import {
 	AGENT_ADAPTERS,
-	CI_ADAPTERS,
 	CROSS_CLI_REVIEW_VIA_TOKEN,
 	getAgentAdapter,
 	MANDATORY_ROUTING_SKILLS,
 	renderAgentInstructions,
 	renderAgentSkill,
-	renderCiTemplate,
 } from "../sdk/adapters.mjs";
 import { resolveWritableRepoPath } from "../sdk/path.mjs";
 import { hasLocalStddBinary, isStddSourceCheckout, prepareAgentHooks } from "./claude-hooks.mjs";
@@ -29,7 +27,6 @@ import {
 	renderInstalledMethod,
 	SOURCE_RUNNER,
 	STAMP,
-	VERSION,
 	validateAdapterSelection,
 } from "./generated-files.mjs";
 import {
@@ -233,9 +230,6 @@ export async function interview() {
 	// The first selected native host is the driver for the repository-level
 	// default. Generated skills still carry a per-host explicit override.
 	const reviewVia = await askReviewVia(ask, close, recommendedReviewVia(tools, capabilities));
-	const ci = (await yes("Install the GitHub Actions gate (stdd check + PR evidence)?", true))
-		? ["github"]
-		: [];
 	const hooks = await yes("Install the pre-push hook (stdd check — fast, offline)?", true);
 	const sessionHook =
 		tools.length > 0 ? await yes("Wire native agent session hooks (stdd status --local)?", true) : false;
@@ -261,7 +255,6 @@ export async function interview() {
 	}
 	return {
 		tools,
-		ci,
 		hooks,
 		sessionHook,
 		stopHook,
@@ -301,14 +294,12 @@ export async function configure(targetDir, opts) {
 	}
 	// installs made before targets were remembered: infer what the previous
 	// init actually GENERATED from manifest.files — live directories lie (a
-	// stray empty .claude/skills must not smuggle claude in) and an
-	// inferred blank would make the stale-file cleanup delete the CI
-	// workflow. The filesystem is the last resort with no usable manifest;
-	// hook files and settings entries are user-owned, never
-	// manifest-tracked, so they are always read from their files.
+	// stray empty .claude/skills must not smuggle claude in). The filesystem
+	// is the last resort with no usable manifest; hook files and settings
+	// entries are user-owned, never manifest-tracked, so they are always read
+	// from their files.
 	if (!targets) {
 		const tools = [];
-		const ci = [];
 		const skillRootCounts = new Map();
 		for (const adapter of Object.values(AGENT_ADAPTERS)) {
 			skillRootCounts.set(adapter.skillRoot, (skillRootCounts.get(adapter.skillRoot) ?? 0) + 1);
@@ -324,9 +315,6 @@ export async function configure(targetDir, opts) {
 					tools.push(adapter.id);
 				}
 			}
-			for (const adapter of Object.values(CI_ADAPTERS)) {
-				if (adapter.outputFile && manifestFiles.includes(adapter.outputFile)) ci.push(adapter.id);
-			}
 		} else {
 			for (const adapter of Object.values(AGENT_ADAPTERS)) {
 				const ownsDistinctSkillRoot = skillRootCounts.get(adapter.skillRoot) === 1;
@@ -337,11 +325,6 @@ export async function configure(targetDir, opts) {
 					tools.push(adapter.id);
 				}
 			}
-			for (const adapter of Object.values(CI_ADAPTERS)) {
-				if (adapter.outputFile && fs.existsSync(path.join(targetDir, adapter.outputFile))) {
-					ci.push(adapter.id);
-				}
-			}
 		}
 		let settingsText = "";
 		for (const relative of new Set(Object.values(AGENT_ADAPTERS).map((adapter) => adapter.hooksFile))) {
@@ -353,7 +336,6 @@ export async function configure(targetDir, opts) {
 		}
 		targets = {
 			tools: tools.length > 0 ? tools : ["claude"],
-			ci,
 			hooks: fs.existsSync(path.join(targetDir, ".stdd", "hooks", "pre-push")),
 			sessionHook:
 				settingsText.includes("stdd status") ||
@@ -414,14 +396,8 @@ export async function configure(targetDir, opts) {
 		);
 	}
 	const desiredStopHook = stopHook || targets.stopHook;
-	const existingCi = targets.ci.filter((provider) => {
-		const outputFile = CI_ADAPTERS[provider].outputFile;
-		return outputFile === null || fs.existsSync(path.join(targetDir, outputFile));
-	});
 	await init(targetDir, {
 		tools: targets.tools,
-		ci: existingCi,
-		rememberedCiTargets: targets.ci,
 		hooks: false,
 		sessionHook: false,
 		stopHook: desiredStopHook,
@@ -437,9 +413,8 @@ export async function configure(targetDir, opts) {
 }
 
 export async function init(targetDir, opts) {
-	const { tools, ci, hooks, sessionHook, capabilitiesList } = opts;
+	const { tools, hooks, sessionHook, capabilitiesList } = opts;
 	const stopHook = Boolean(opts.stopHook);
-	const rememberedCiTargets = opts.rememberedCiTargets ?? ci;
 	const rememberedHookTargets = opts.rememberedHookTargets ?? {
 		hooks: Boolean(hooks),
 		sessionHook: Boolean(sessionHook),
@@ -553,19 +528,6 @@ export async function init(targetDir, opts) {
 			}),
 		});
 	}
-	const ciPlans = new Map();
-	for (const provider of ci) {
-		const adapter = CI_ADAPTERS[provider];
-		if (adapter.outputFile !== null) {
-			ciPlans.set(
-				provider,
-				renderCiTemplate(
-					fs.readFileSync(path.join(PKG_ROOT, "templates", adapter.templateFile), "utf8"),
-					{ stamp: STAMP, version: VERSION },
-				),
-			);
-		}
-	}
 	const publicationPaths = new Set([".stdd/method.md", ".stdd/config.json", ".gitignore"]);
 	for (const pb of kitActive) publicationPaths.add(`.stdd/playbooks/${pb.file}`);
 	for (const { adapter, skills } of toolPlans.values()) {
@@ -578,7 +540,6 @@ export async function init(targetDir, opts) {
 	for (const adapter of Object.values(AGENT_ADAPTERS)) {
 		publicationPaths.add(adapter.instructionsFile);
 	}
-	for (const provider of ciPlans.keys()) publicationPaths.add(CI_ADAPTERS[provider].outputFile);
 	if (hooks) publicationPaths.add(".stdd/hooks/pre-push");
 	publicationPaths.add(".stdd/policy.md");
 	for (const relative of publicationPaths) {
@@ -755,20 +716,6 @@ export async function init(targetDir, opts) {
 			console.log(`Removed the managed STDD section from deselected ${adapter.instructionsFile}`);
 		}
 
-		for (const provider of ci) {
-			const adapter = CI_ADAPTERS[provider];
-			if (adapter.outputFile === null) {
-				console.log(
-					`Portable CI contract for ${adapter.id} (compose with your provider's checkout and live PR/MR body):\n` +
-						`  npx --yes @stdd/cli@${VERSION} check .\n` +
-						`  printf '%s' "$REVIEW_BODY" | npx --yes @stdd/cli@${VERSION} check-pr - --base "$BASE_REF"`,
-				);
-				continue;
-			}
-			await writeGenerated(adapter.outputFile, ciPlans.get(provider));
-			console.log(`Installed ${adapter.outputFile} (${provider} live review evidence)`);
-		}
-
 		// Repository-owned standing decisions. Seeded once and then hands-off:
 		// user-owned after generation like config.json, never manifested, so a
 		// recorded permission survives every later init.
@@ -865,7 +812,6 @@ export async function init(targetDir, opts) {
 			retainedCleanupJournals: [...previouslyRetainedCleanupJournals, ...recoveredCleanupJournals],
 			targets: {
 				tools,
-				ci: rememberedCiTargets,
 				hooks: rememberedHookTargets.hooks,
 				sessionHook: rememberedHookTargets.sessionHook,
 				stopHook: rememberedHookTargets.stopHook,

package/runtime/cli/status.mjs

@@ -89,12 +89,12 @@ export function status(cwd, asJson, localOnly = false) {
 			plan: { present: false },
 			review: null,
 			pr: { state: "unknown", reason: "idle task" },
-			next: 'start a task with `stdd task start "<short name>"`',
+			next: "no task is required for discussion or read-only work",
 		};
 		if (asJson) console.log(JSON.stringify(idle, null, "\t"));
 		else
 			console.log(
-				`task:   idle on ${branch}\nnext:   start a task with \`stdd task start "<short name>"\``,
+				`task:   idle on ${branch}\nnext:   no task is required for discussion or read-only work`,
 			);
 		return;
 	}
@@ -225,11 +225,21 @@ export function status(cwd, asJson, localOnly = false) {
 		: `enable a compatible review capability/route, then run ${reviewInvocation}${
 				reviewBudgetSpent ? " deliberately" : " again"
 			}`;
-	const planReviewSatisfied = Boolean(plan.present && plan.review?.present && plan.review.done);
+	// The closing review rides on coordination — a plan that ordered the work, or
+	// a slice handed to a worker whose code the orchestrator never watched being
+	// written. A single slice coordinates nothing, claims no review, and is owed
+	// none, so nothing is named. Expectation and completion are separate
+	// questions: reading a missing plan as an unfinished review is what made
+	// `status` ask after every verified loop, whatever the change's size.
+	const reviewExpected = Boolean(latestReview) || plan.present || Boolean(scopeEvent);
 	const recordedReviewSatisfied = latestReview?.verdict === "approved" && !reviewStale;
 	// Once a ledger verdict exists it is authoritative; a checked legacy
 	// heuristic item must never hide a newer failed or stale review.
-	const reviewSatisfied = latestReview ? recordedReviewSatisfied : planReviewSatisfied;
+	const reviewSatisfied = !reviewExpected
+		? true
+		: latestReview
+			? recordedReviewSatisfied
+			: Boolean(plan.review?.done);
 	const reviewNeedsAction = !reviewSatisfied;
 	const reviewFailureGuidance =
 		latestReview?.verdict === "changes-requested"

package/runtime/cli/stdd.mjs

@@ -8,7 +8,6 @@ import { loadConfig } from "./config.mjs";
 import { checkPr, evidence } from "./evidence.mjs";
 import {
 	KNOWN_CAPABILITIES,
-	KNOWN_CI,
 	KNOWN_TOOLS,
 	VERSION,
 	validateAdapterSelection,
@@ -300,7 +299,6 @@ async function main() {
 		}
 	}
 	let tools = null;
-	let ci = null;
 	let baseRefArg = null;
 	let prArg = null;
 	let readinessOnly = false;
@@ -400,19 +398,6 @@ async function main() {
 			i = parsedValueIndex;
 			prArg = parsedValue;
 			if (!prArg) fail("--pr requires a PR number, or . for the current branch's PR");
-		} else if (parsedArg === "--ci") {
-			if (command !== "init") fail(`--ci is only valid for "stdd init"`);
-			i = parsedValueIndex;
-			ci = parseGenericList(parsedValue, "--ci", {
-				noun: "ci provider(s)",
-				example: "github",
-				known: KNOWN_CI,
-			});
-			try {
-				ci = validateAdapterSelection("ci", ci, KNOWN_CI);
-			} catch (err) {
-				fail(`--ci ${err.message.replace(/^ci /, "")}`);
-			}
 		} else if (parsedArg === "--tools") {
 			if (command !== "init") fail(`--tools is only valid for "stdd init"`);
 			i = parsedValueIndex;
@@ -439,17 +424,13 @@ async function main() {
 
 	switch (command) {
 		case "init": {
-			if (
-				interviewFlag &&
-				(tools || ci || capabilitiesArg || hooksFlag || sessionHookFlag || stopHookFlag)
-			) {
+			if (interviewFlag && (tools || capabilitiesArg || hooksFlag || sessionHookFlag || stopHookFlag)) {
 				fail("--interview replaces the other init flags — drop them and answer the questions instead");
 			}
 			const opts = interviewFlag
 				? await interview()
 				: {
 						tools: tools ?? KNOWN_TOOLS,
-						ci: ci ?? [],
 						hooks: hooksFlag,
 						sessionHook: sessionHookFlag,
 						stopHook: stopHookFlag,
@@ -515,7 +496,7 @@ async function main() {
 			}
 			console.log(
 				"Usage: stdd <init|configure|check|check-pr|evidence|doctor|task|status|ci|docs|red|verify|note|defer|policy|slice|worker|scope|review|stop-hook> " +
-					"[dir|pr-body-file|pr] [--tools claude,codex,pi] [--ci github,gitlab,generic] [--hooks] " +
+					"[dir|pr-body-file|pr] [--tools claude,codex,pi] [--hooks] " +
 					"[--session-hook] [--interview] [--base <ref>] " +
 					"[--pr <n|.>] [--watch] [--readiness] [--json] [--gate] [--local] [--reason <why>] " +
 					"[--capabilities <list>] [--via subagent|codex|claude] [--review-via <route>] " +

package/runtime/method/README.md

@@ -94,6 +94,41 @@ classify → read docs → docs edit (the spec) → failing test → implement
    The base comes from `--base` or the `baseRef` key in `.stdd/config.json`;
    there is no built-in default.
 
+## Proportionality
+
+The default route for an agreed change is one slice: the docs decision, a
+failing test where one applies, the implementation, a fresh verify. A plan, a
+delegated worker, and an independent review are escalations from that route,
+each with a condition below. None of it touches proof — the docs decision, a
+genuine red where a test applies, and a fresh verify hold at every size.
+Proportionality cuts paperwork, never evidence.
+
+A change is one slice when, at the moment of deciding, it has one agreed
+observable outcome, one coherent implementation boundary, one acceptance check,
+and no known dependency on another independently verifiable change. Escalate as
+soon as any of four things appears: a second independent outcome, an ordering
+dependency between parts, a need to hand work to another session, or a design
+decision nobody has made yet. They are usually discovered mid-work. Escalating
+then is the normal case, not a failed classification — the criterion is re-read
+as the work goes, never declared once at the start.
+
+Two independent axes decide which escalation applies. **Coordination
+complexity** decides the plan and delegation: work that must be ordered, split,
+or handed over needs a durable plan, because those artifacts exist against
+memory that does not survive compaction or a handoff. **Consequence** is why a human may want an
+independent review that coordination did not already require: a two-line change
+to authorization or pricing can carry more of it than a two-hundred-line
+rename. `stdd status` names the review from coordination alone, because
+coordination is what it can observe; consequence is a judgement, and
+`stdd review` is callable for it at any moment. Which surfaces carry
+consequence is the adopting team's contract, not this kit's — see "What stdd
+does not cover". Diff size decides neither axis; it proxies both and measures
+neither.
+
+A PR, and the CI wait that follows it, ride on the delivery boundary the user
+asked for. A change requested as a local edit is complete when it is verified
+locally.
+
 ## The frontend exception: design-first
 
 Frontend **visual** work — layout, styling, markup structure, presentation
@@ -220,10 +255,17 @@ Agent adapters have two outputs with deliberately different context costs:
 - a short, always-on instruction block carrying only repository invariants;
 - native, lazily loaded skills carrying the task workflows.
 
-Three routing skills make the main path explicit instead of asking an agent
-to infer a workflow from a flat list: `stdd-start-change` classifies first,
-opens a task only for repository-changing work, and routes read-only questions
-without writing state; `stdd-implement` runs the docs/red/green/verify loop, and
+Five routing skills make the main path explicit instead of asking an agent
+to infer a workflow from a flat list. `stdd-investigation` directly answers
+current-state factual and diagnostic questions with evidence;
+`stdd-brainstorming` directly explores opinions, future behavior, and
+hypothetical implementation approaches. Both are read-only and create no task,
+ledger event, persisted artifact, or repository mutation. When unknown current
+facts materially affect a design, they may run in sequence as Investigation →
+Brainstorming; reading docs or code while brainstorming does not itself switch
+workflows. `stdd-start-change` begins only after explicit intent to persist a
+work artifact or modify the repository; a hypothetical plan shown in chat stays
+Brainstorming. `stdd-implement` runs the docs/red/green/verify loop, and
 `stdd-finish-change` closes review, evidence, PR checks, and any requested
 runtime verification. Specialized playbooks remain independently invocable.
 
@@ -249,7 +291,9 @@ half-written state — see
 `stdd status --json` has one stable top-level shape in every lifecycle
 state: `state`, `task`, `branch`, `loop`, `slice`, `plan`, `review`, `pr`,
 and `next` are always present. Idle state uses explicit empty/null values,
-so integrations never need a second response schema.
+so integrations never need a second response schema. Its string-valued `next`
+is neutral: no task is required for discussion or read-only work, and a task
+starts only when the user chooses persisted or repository-changing action.
 
 Readers consider only the current branch's active task. A plan that was
 already present when the task started stays invisible until rewritten for
@@ -315,11 +359,14 @@ snapshot. A passing verify becomes stale after any later checkout change;
 current proof. Older ledger events without snapshots remain readable but
 are explicitly reported as legacy evidence. Timing
 leaves the prose: run `stdd status` at session start and before opening a
-PR. Once the loop is verified and the plan is exhausted, the closing
-review is the named next step ahead of the evidence line — when the
-capability profile has a dispatch route on (`subagents` or `crossCli`),
-`status` says to dispatch the fresh reviewer explicitly; with both off
-the suggestion is omitted rather than degraded to self-review.
+PR. Once the loop is verified, `status` names the closing review only when
+something expects one: a plan is present, a slice was delegated (a recorded
+`scope` event), or a review verdict is already recorded. With none of the
+three it goes straight to the evidence line — a single slice makes no review
+claim and is not asked for one. Where a review is expected, it is named ahead
+of the evidence line when the capability profile has a dispatch route on
+(`subagents` or `crossCli`); with both off the suggestion is omitted rather
+than degraded to self-review.
 
 ## The durable plan and `stdd defer`
 
@@ -358,7 +405,10 @@ delegated work alike, and its reviewer is a fresh context (a read-only
 subagent or the other CLI, per the capability profile) that sees the plan
 and the diff, never the implementing session's history. With both dispatch
 capabilities off, capability compilation omits the review item and closing
-review guidance entirely; it never substitutes self-review.
+review guidance entirely; it never substitutes self-review. A change that
+needed no plan carries no such item, makes no review claim, and is not asked
+for one — the review rides on coordination, and `stdd review` stays callable
+at any moment for a change whose consequence warrants it.
 
 The review item carries a `[review:]` tag, and the tag follows the same
 claim-vs-proof rule as `[red:]`: the checkbox is a claim, the ledger is
@@ -402,8 +452,8 @@ authority.
 A permission's action comes from a closed set: `merge`, `deploy`, `publish`,
 `migrate`, `force-push`, and `external-mutation`. Any other action is rejected,
 which is also why policy cannot waive a method gate — the docs edit, a genuine
-red, verification, the closing review, and `stdd check` are not actions the
-file can name. Policy widens what an agent may do without asking; it never
+red, verification, a closing review the plan claims, and `stdd check` are not
+actions the file can name. Policy widens what an agent may do without asking; it never
 narrows what the loop must prove.
 
 The set is enforced when the document is read, not only when `stdd policy`

package/runtime/method/reference-commands.md

@@ -98,7 +98,13 @@ formatting characters are rejected before durable state is written.
 
 A managed worker sandbox created by `stdd worker create` requires an active
 task and an already recorded docs
-decision. Its destination must not exist. Managed create and collect use the
+decision. Its destination must not exist, must be outside the source checkout,
+and must be outside any Git repository — a sandbox carries no `.git` and must
+not be swept up by a surrounding one. That puts it beside the project rather
+than inside it, so the convention is one hidden container,
+`../.stdd-workers/<slice>`: a directory of projects then collects a single
+`.stdd-workers/` however many slices are delegated, instead of one visible
+sibling each. Managed create and collect use the
 native mutation helper and fail before mutation when the destination
 filesystem cannot provide the required capability guarantees. Creation copies
 the checkout's tracked and non-ignored untracked files at