@michaelrwalker/stagehand 0.5.3 → 0.6.1

package/skills/compensation-safety/conditional-steps/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: 'conditional-steps'
+description: >
+  Covers `when` on `addStep` and `addPhase` for skipping work, the `"skipped"` StepStatus,
+  and how a skip interacts with `clean`, `rollback`, and a mounted routine's own resolved
+  input. Load this for "run this step only in production," "skip a whole phase based on
+  input," or when a rollback isn't firing and the step turns out to have been skipped.
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/phases-and-steps.md'
+  - 'miaklwalker/stagehand:docs/guides/reusable-scripts.md'
+  - 'miaklwalker/stagehand:src/script.ts'
+---
+
+# Stagehand — Conditional Steps and Phases
+
+`when` on `addStep` or `addPhase` is a function of `{ input, ctx }` (may be async) that gates whether the step, or every step in the phase, runs at all. A falsy result marks the step `"skipped"` — it never runs its handler and never runs its `rollback`.
+
+## Setup
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+interface Input {
+  environment: "development" | "production";
+}
+
+const script = new Script<Input>({ name: "deploy" })
+  .addPhase("Release")
+  .addStep({
+    name: "notify slack",
+    when: ({ input }) => input.environment === "production",
+    handler: async () => {
+      // only runs when input.environment === "production"
+    },
+  });
+
+await script.run({ environment: "production" });
+```
+
+## Core Patterns
+
+### Gate a single step on input or ctx
+
+```ts
+new Script<{ environment: "development" | "production" }>({ name: "deploy" })
+  .addPhase("Release")
+  .addStep({ name: "resolve commit", handler: async () => ({ sha: "abc123" }) })
+  .addStep({
+    name: "notify slack",
+    when: ({ input, ctx }) => input.environment === "production" && ctx.sha.length > 0,
+    handler: async () => {
+      /* notify */
+    },
+  });
+```
+
+`when` sees the same `{ input, ctx }` shape a handler does, so it can read anything an earlier step already put in context.
+
+### Gate an entire phase
+
+```ts
+new Script<{ environment: "development" | "production" }>({ name: "deploy" })
+  .addPhase("Validation")
+  .addStep({ name: "check permissions", handler: async () => ({}) })
+  .addPhase("Release", {
+    when: ({ input }) => input.environment === "production",
+  })
+  .addStep({ name: "notify slack", handler: async () => {} })
+  .addStep({ name: "publish", handler: async () => {} });
+```
+
+A falsy phase-level `when` marks every step in `"Release"` `"skipped"` in one shot, before any of those steps' own `when` (if they had one) is ever evaluated.
+
+### Async `when`
+
+```ts
+.addStep({
+  name: "run migration",
+  when: async ({ ctx }) => await isMigrationPending(ctx.dbUrl),
+  handler: async () => runMigration(),
+})
+```
+
+`when` may return a promise; the script awaits it before deciding whether to run or skip the step (or, at phase level, the whole phase).
+
+## Common Mistakes
+
+### MEDIUM Skipped step's `clean` still runs
+
+Wrong:
+```ts
+// developer expects `secret` to survive because "optional" never ran
+new Script<{ secret: string }>({ name: "t" })
+  .addStep({ name: "seed", handler: ({ input }) => ({ secret: input.secret }) })
+  .addStep({ name: "optional", when: () => false, handler: () => ({}), clean: ["secret"] })
+  .addStep({ name: "later", handler: ({ ctx }) => {
+    ctx.secret; // compile error — gone
+    return {};
+  } });
+```
+
+Correct:
+```ts
+// if "secret" should only be dropped when "optional" actually ran, clean elsewhere
+new Script<{ secret: string }>({ name: "t" })
+  .addStep({ name: "seed", handler: ({ input }) => ({ secret: input.secret }) })
+  .addStep({ name: "optional", when: () => false, handler: () => ({}) })
+  .addStep({ name: "use it then drop it", handler: ({ ctx }) => ({}), clean: ["secret"] });
+```
+
+`clean` is part of a step's declared shape, not of the work it performs, so `drop(ctx, item.def.clean)` runs in the skip branch exactly as it does after a normal run — runtime and types never disagree about what a skipped step removed.
+
+Source: docs/guides/cleaning-context.md; src/script.ts phaseLoop skip branch (`drop(ctx, item.def.clean)`)
+
+### LOW Expecting a skipped step's rollback to fire
+
+Wrong:
+```ts
+.addStep({
+  name: "notify slack",
+  when: ({ input }) => input.environment === "production",
+  handler: async () => notify(),
+  rollback: async () => undoNotify(), // assumed to fire if a later step fails and this was "run"
+})
+```
+
+Correct:
+```ts
+// rely on `when` purely as a gate; don't design a rollback around a skip firing it
+.addStep({
+  name: "notify slack",
+  when: ({ input }) => input.environment === "production",
+  handler: async () => notify(),
+  rollback: async () => undoNotify(), // correct: only fires if this step actually ran and succeeded
+})
+```
+
+A step marked `"skipped"` never enters the `completed` list the unwind walks, so its `rollback` never runs — there is nothing to compensate for.
+
+Source: docs/guides/phases-and-steps.md
+
+### HIGH Step-level `when` can't re-enable a step inside a skipped phase
+
+Wrong:
+```ts
+new Script<{ environment: string }>({ name: "t" })
+  .addPhase("Release", { when: ({ input }) => input.environment === "production" })
+  .addStep({ name: "always run this", when: () => true, handler: async () => ({}) });
+  // still skipped — the phase gate short-circuits before step.when is ever checked
+```
+
+Correct:
+```ts
+// move a step that must always run outside the conditional phase
+new Script<{ environment: string }>({ name: "t" })
+  .addPhase("Always")
+  .addStep({ name: "always run this", handler: async () => ({}) })
+  .addPhase("Release", { when: ({ input }) => input.environment === "production" })
+  .addStep({ name: "notify slack", handler: async () => ({}) });
+```
+
+Phase-level `when` is evaluated once per phase; when it resolves falsy, every step in that phase is marked skipped in a loop that never touches `item.def.when` at all.
+
+Source: src/script.ts run() phaseLoop (`phase.options.when` checked before any `step.when`)
+
+### MEDIUM `when` inside a mounted routine sees the mount's input, not the host's
+
+Wrong:
+```ts
+// inside routines/channel.ts, built with routineFor<{ channel: string }>()
+.addStep({ name: "gate", when: ({ input }) => input.hostOnlyFlag, handler: async () => ({}) })
+// TypeScript already prevents referencing hostOnlyFlag if routineFor's In doesn't include it —
+// but this is exactly the trap when In is loosely typed or the mapper over-forwards fields
+```
+
+Correct:
+```ts
+import { routineFor } from "@michaelrwalker/stagehand";
+
+export const pullChannel = routineFor<{ channel: string; since: string }>()(
+  "pull channel",
+  (script) =>
+    script.addStep({
+      name: "gate",
+      when: ({ input }) => input.channel === "amazon",
+      handler: async () => ({}),
+    }),
+);
+```
+
+A mount's input is resolved once, from a fixed value or an `{ input, ctx } => SubIn` mapper passed to `use()`, and every `when` inside that fragment — phase- or step-level — is evaluated against that resolved input, never the host script's own `input`.
+
+Source: docs/guides/reusable-scripts.md ("Giving a mount its own input"); src/script.ts `use()`/`run()` mount input resolution
+
+See also: skills/reuse/reusable-routines-and-mounts/SKILL.md — `when` inside a mounted fragment evaluates against the mount's resolved input, not the host's — easy to miss without reading both.

package/skills/errors-results/handling-results-and-errors/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: 'handling-results-and-errors'
+description: >
+  Covers the RunResult discriminated union returned by run(), every exported error class
+  (StepFailedError, StepTimeoutError, ScriptAbortedError, RollbackFailedError, CacheShapeError,
+  SchemaValidationError), the isAbort(error) helper, and the throwOnError script option. Load this
+  for "branch correctly on a failed run," "tell a Ctrl-C cancellation apart from a real failure,"
+  or "get the phase/step name a failure happened at."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/rollbacks.md'
+  - 'miaklwalker/stagehand:docs/guides/script-options-and-result.md'
+  - 'miaklwalker/stagehand:docs/reference/errors.md'
+  - 'miaklwalker/stagehand:src/errors.ts'
+  - 'miaklwalker/stagehand:src/script.ts'
+---
+
+# Stagehand — Handling Results and Errors
+
+`run()` never throws for an ordinary step failure — it resolves to a discriminated union on `ok`. A handful of exported error classes exist for callers building their own reporting, but most of them never propagate through `run()` itself; knowing which ones do (and which don't) is the whole game.
+
+## Setup
+
+```ts
+import { Script, isAbort } from "@michaelrwalker/stagehand";
+
+const deploy = new Script<{ env: string }>({ name: "deploy" })
+  .addStep({
+    name: "build",
+    handler: async ({ ctx }) => ({ releaseId: "r-123" }),
+  })
+  .addStep({
+    name: "publish",
+    handler: async ({ ctx }) => {
+      if (ctx.releaseId === undefined) throw new Error("no release to publish");
+      return { published: true };
+    },
+  });
+
+const result = await deploy.run({ env: "production" });
+
+if (result.ok) {
+  console.log("deployed", result.ctx.releaseId);
+} else if (isAbort(result.error) && result.status === "aborted") {
+  console.log("cancelled");
+} else {
+  console.error(`failed at ${result.failedAt?.phase} › ${result.failedAt?.step}`, result.error);
+  process.exitCode = 1;
+}
+```
+
+## Core Patterns
+
+### Branch on the full RunResult shape
+
+```ts
+const result = await deploy.run(input);
+
+if (result.ok) {
+  // result.status === "success"; result.ctx is fully typed
+  result.ctx.releaseId;
+} else {
+  // result.status is "failed" | "aborted"
+  console.error(`failed at ${result.failedAt?.phase} › ${result.failedAt?.step}`);
+  console.error(result.error);           // the original thrown value, unwrapped
+  console.error(result.ctx);              // Partial<Ctx> — whatever was produced before failure
+  for (const r of result.rollbacks) {
+    console.error(`rollback for "${r.step}": ${r.ok ? "ok" : "failed"}`);
+  }
+}
+```
+
+`result.ctx` on failure is not reverted by compensation — a rollback undoes external side effects, it does not erase what was already recorded in `ctx`.
+
+### Tell cancellation apart from an ordinary failure
+
+```ts
+const result = await deploy.run(input, { signal: controller.signal });
+
+if (!result.ok) {
+  if (isAbort(result.error) && result.status === "aborted") {
+    console.log("canceled from outside (Ctrl-C or an external signal)");
+  } else {
+    console.error("handler failure:", result.error);
+  }
+}
+```
+
+`isAbort(error)` returns `true` for a `ScriptAbortedError` or any `Error` named `"AbortError"` — checking `result.status === "aborted"` alongside it confirms the abort was the script's own, not an unrelated `AbortError` a handler happened to throw.
+
+### Use `throwOnError` when the script is one stage of a larger flow
+
+```ts
+import { SchemaValidationError } from "@michaelrwalker/stagehand";
+
+const stage = new Script<{ env: string }>({ name: "stage", throwOnError: true })
+  .addStep({ name: "one", handler: () => ({ done: true }) });
+
+try {
+  const result = await stage.run({ env: "production" });
+  console.log(result.ctx.done); // reached only on success — a failure rejects instead
+} catch (error) {
+  if (error instanceof SchemaValidationError) console.error(error.issues);
+  else throw error; // the original error a step threw, or a ScriptAbortedError
+}
+```
+
+Compensation still runs to completion before the rejection; `throwOnError` only changes how the outcome is reported.
+
+## Common Mistakes
+
+### CRITICAL wrapping run() in try/catch expecting it to throw
+
+Wrong:
+```ts
+try {
+  const result = await deploy.run(input);
+  console.log("deployed", result.ctx.releaseId);
+} catch (e) {
+  console.error(e);
+}
+```
+
+Correct:
+```ts
+const result = await deploy.run(input);
+if (!result.ok) {
+  console.error(result.error);
+  process.exitCode = 1;
+  return;
+}
+console.log("deployed", result.ctx.releaseId);
+```
+
+`run()` resolves to `{ ok: false, ... }` by default; nothing throws unless `throwOnError` is set, so the `catch` block never fires and a failed run is silently treated as if nothing happened.
+
+Source: docs/guides/script-options-and-result.md; src/script.ts `run()`
+
+### HIGH assuming a bad `defineInput` schema shows up as `{ ok: false }`
+
+Wrong:
+```ts
+const result = await deploy.run(rawInput);
+if (!result.ok) { /* never reached on bad input — it throws instead */ }
+```
+
+Correct:
+```ts
+try {
+  const result = await deploy.run(rawInput);
+} catch (error) {
+  if (error instanceof SchemaValidationError) console.error(error.issues);
+  else throw error;
+}
+```
+
+`SchemaValidationError` is always thrown directly by `run()`, before any phase executes, and is unaffected by `throwOnError` — there is no partial result to produce since nothing ran yet.
+
+Source: docs/guides/typed-context.md; docs/reference/errors.md
+
+### MEDIUM assuming a failing rollback replaces `result.error`
+
+Wrong:
+```ts
+const result = await script.run(input);
+if (!result.ok) console.error(result.error); // assumed to be the rollback's error if one failed
+```
+
+Correct:
+```ts
+const result = await script.run(input);
+if (!result.ok) {
+  console.error("run failed:", result.error);
+  for (const r of result.rollbacks) if (!r.ok) console.error("rollback failed:", r.step, r.error);
+}
+```
+
+A failing rollback is recorded as `{ ok: false, error }` inside `result.rollbacks`; `result.error` always stays the original failure that triggered the unwind, and the remaining rollbacks still run.
+
+Source: docs/guides/rollbacks.md; docs/reference/errors.md (`RollbackFailedError`)
+
+### MEDIUM trusting `AbortError`'s name to mean the script itself was cancelled
+
+Wrong (inside a handler, defeats retry):
+```ts
+handler: async ({ signal }) => {
+  const localController = new AbortController();
+  setTimeout(() => localController.abort(), 200);       // unrelated to `signal`
+  return fetch(url, { signal: localController.signal }); // throws AbortError → retry silently skipped
+},
+retry: { attempts: 3 },
+```
+
+```ts
+handler: async ({ signal }) => fetch(url, { signal }),  // forward the step's own signal
+retry: { attempts: 3, retryIf: (error) => !isAbort(error) },
+```
+
+Wrong (after `run()`, misreads an unrelated AbortError as user cancellation):
+```ts
+if (!result.ok && isAbort(result.error)) {
+  console.log("user pressed Ctrl-C");  // could actually be an unrelated internal AbortError
+}
+```
+
+Correct:
+```ts
+if (!result.ok && isAbort(result.error) && result.status === "aborted") {
+  console.log("cancelled");
+}
+```
+
+`isAbort()` returns `true` for a `ScriptAbortedError` *or* any `Error` whose `name` is exactly `"AbortError"` — not just ones tied to the script's own signal. Inside `executeStep`'s retry loop, that check runs before the retry-budget check, so a handler's own unrelated `AbortController` (e.g. a hand-rolled per-call timeout) silently skips `retry`/`retryIf` entirely; after `run()` returns, the same permissiveness means `isAbort(result.error)` alone doesn't prove the script itself was aborted — pair it with `result.status === "aborted"`.
+
+Source: src/errors.ts `isAbort()`; src/script.ts `executeStep()` (isAbort check precedes the retry-budget check); docs/guides/rollbacks.md ("Signals and cancellation")
+
+### HIGH checking `result.error instanceof StepFailedError`
+
+Wrong:
+```ts
+if (!result.ok && result.error instanceof StepFailedError) {
+  console.error(result.error.step, result.error.attempts); // never true — error is the raw throw
+}
+```
+
+Correct:
+```ts
+if (!result.ok) {
+  console.error(result.failedAt?.phase, result.failedAt?.step, result.error);
+}
+```
+
+`result.error` on a failed run is the original value the handler threw, not automatically wrapped in `StepFailedError` — that class exists for callers building their own reporting elsewhere; the phase/step is available on `result.failedAt` instead.
+
+Source: docs/reference/errors.md ("result.error on a failed run is the original thrown value, not automatically wrapped in this type")
+
+### MEDIUM assuming `throwOnError` skips compensation and fails fast
+
+Wrong:
+```ts
+// assumed: throwOnError means "don't bother rolling back, just blow up immediately"
+new Script({ name: "t", throwOnError: true })
+```
+
+Correct:
+```ts
+// rollbacks still run to completion; throwOnError only affects how the caller is told about the outcome
+new Script({ name: "t", throwOnError: true }) // reach for this when the script is one stage inside a larger error-handling flow
+```
+
+`throwOnError` only changes how the outcome is reported — a failing run rejects with the original error instead of resolving `{ ok: false }`, but compensation still runs first, in full, before the rejection.
+
+Source: docs/guides/script-options-and-result.md ("Compensation still runs before the rejection")
+
+### MEDIUM catching `RollbackFailedError` from `run()` or its result
+
+Wrong:
+```ts
+try {
+  await script.run(input);
+} catch (e) {
+  if (e instanceof RollbackFailedError) { /* never matches */ }
+}
+```
+
+Correct:
+```ts
+const result = await script.run(input);
+if (!result.ok) {
+  const failedRollbacks = result.rollbacks.filter((r) => !r.ok);
+}
+```
+
+`RollbackFailedError` is exported for a caller's own reporting, but the library itself never throws it or puts it in `RunResult` — a failing rollback is instead recorded as `{ ok: false, error }` inside `result.rollbacks`.
+
+Source: docs/reference/errors.md ("a failing rollback does not propagate as this error type through RunResult")
+
+See also: skills/compensation-safety/adding-rollbacks/SKILL.md — isAbort and the retry loop's abort check directly govern whether — and how fast — a rollback's unwind gets triggered.

package/skills/observability/log-placement-and-rendering/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: 'log-placement-and-rendering'
+description: >
+  logPlacement modes (scrollback/step/bottom) and how the live TTY frame differs from the plain/CI renderer, including which behaviors exist only in one of the two. Load this for "nest a rollback's log under the step it's undoing," "force plain output for CI," or "match my own console output to the script's styling."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/handler-surface.md'
+  - 'miaklwalker/stagehand:docs/guides/terminal-rendering.md'
+  - 'miaklwalker/stagehand:test/log-placement.test.ts'
+  - 'miaklwalker/stagehand:test/note.test.ts'
+---
+
+# Stagehand — Log Placement and Terminal Rendering
+
+`log`/`info`/`warn`/`error`/`success` all write a line; `logPlacement` (a `ScriptOptions` field) controls where that line lands in the live TTY frame. Which renderer is even active — live, in-place frame vs. plain sequential output — is chosen automatically per run, and only the live one honors `logPlacement` at all.
+
+## Setup
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+const script = new Script({ name: "checkout", logPlacement: "step" }).addStep({
+  name: "reserve inventory",
+  handler: async ({ log }) => {
+    log("checked warehouse A");
+    return { reservationId: "res_1" };
+  },
+});
+
+await script.run();
+```
+
+## Core Patterns
+
+### Nest a rollback's log under the step it's undoing
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+await new Script({ name: "checkout", logPlacement: "step" })
+  .addStep({
+    name: "reserve inventory",
+    handler: () => ({ reservationId: "res_1" }),
+    rollback: ({ log }) => {
+      log("released reservation res_1");
+    },
+  })
+  .addStep({
+    name: "boom",
+    handler: () => {
+      throw new Error("boom");
+    },
+  })
+  .run();
+```
+
+With `logPlacement: "step"`, a rollback's `log()` calls render nested under the step being undone instead of scrolling past at the top of the frame, keeping compensation output next to the failure that caused it.
+
+### Force plain, deterministic output for CI
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+new Script({ name: "deploy", plain: process.env.CI === "true" });
+```
+
+`plain: true` forces the sequential, non-repainting renderer even on a real TTY; `plain: false` forces the live one even when piped. Leaving `plain` unset (the default) auto-detects: live only when `process.stdout.isTTY` is true and color is enabled (color is off under `NO_COLOR` or `TERM=dumb`, on under `FORCE_COLOR`, otherwise on exactly when stdout is a TTY).
+
+### Roll a live tail of recent lines instead of nesting per step
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+new Script({ name: "sync", logPlacement: "bottom" }).addStep({
+  name: "sync records",
+  handler: async ({ log }) => {
+    log("synced batch 1");
+    log("synced batch 2");
+    return { batches: 2 };
+  },
+});
+```
+
+`"bottom"` renders a single rolling tail of the most recent lines below the whole phase tree (not per step), which is cheaper to scan when many steps are logging concurrently. Like `"step"`, it keeps only the most recent handful of entries.
+
+### Match custom console output to the script's own styling
+
+```ts
+import { formatDuration, isColorEnabled, palette, setColorEnabled, symbols } from "@michaelrwalker/stagehand";
+
+console.log(`${symbols.success} deploy finished in ${formatDuration(4084)}`);
+console.log(palette.warning("cache stale, rebuilding"));
+
+setColorEnabled(false); // override auto-detection directly, rather than via NO_COLOR/FORCE_COLOR
+isColorEnabled(); // false
+```
+
+`symbols` degrades automatically on terminals without solid Unicode support (`✔` becomes `√`, and so on) and `palette` exposes the same 256-color stylers (`accent`, `success`, `warning`, `error`, `info`, `muted`, `faint`, `bold`, `dim`) the built-in renderer uses.
+
+## Common Mistakes
+
+### MEDIUM Treating step/bottom placement as a complete run record
+
+Wrong:
+```ts
+new Script({ name: "audit", logPlacement: "bottom" });
+// assumed every log() call is retrievable after the run for compliance review
+```
+
+Correct:
+```ts
+new Script({ name: "audit", logPlacement: "scrollback" });
+```
+
+Both `"step"` and `"bottom"` keep only the most recent handful of lines per step or per run — only `"scrollback"` (the default) is guaranteed to retain every line, in order, for the whole run.
+
+Source: docs/guides/handler-surface.md; docs/guides/terminal-rendering.md
+
+### LOW Assuming logPlacement behaves the same in CI as it did locally
+
+Wrong:
+```ts
+// developer tunes `logPlacement: "step"` by eye in a local terminal,
+// then is confused that CI logs show every line in plain top-level order instead
+```
+
+Correct:
+```ts
+// treat logPlacement as a live-TTY-only concern; CI output is always flat and complete
+```
+
+Only the live renderer honors `logPlacement` — the plain/CI renderer (chosen automatically off a TTY, under `NO_COLOR`, or `TERM=dumb`) is already sequential and prints every line immediately in order regardless of the setting.
+
+Source: docs/guides/terminal-rendering.md; docs/guides/handler-surface.md
+
+### LOW Hardcoding Stagehand's glyphs into a script's own console output
+
+Wrong:
+```ts
+console.log(`✔ done`); // renders as mojibake on the same terminals Stagehand degrades for
+```
+
+Correct:
+```ts
+import { symbols, palette } from "@michaelrwalker/stagehand";
+
+console.log(`${symbols.success} done`);
+```
+
+Stagehand degrades its own symbols automatically on terminals without solid Unicode support, but that degradation is internal to the renderer and does not apply to anything a script prints itself unless it goes through the exported `symbols`/`palette` helpers.
+
+Source: docs/guides/terminal-rendering.md
+
+### HIGH Tension: Rich live observability vs. complete log record
+
+`logPlacement: "step"`/`"bottom"` produce the most pleasant live-TTY experience by capping what they retain, while `"scrollback"` is the only placement that is both complete and the default, and one choice applies to the whole script. Agents optimizing for this skill's goal tend to pick a locally-nice-looking placement like `"step"` as a script-wide default because they don't account for the need — covered by progress reporting — for a guaranteed-complete CI/audit trail from the same run.
+
+See also: skills/observability/reporting-progress/SKILL.md § Common Mistakes
+
+### HIGH Tension: Routine authoring instincts vs. host-controlled ScriptOptions
+
+A routine is built as an ordinary `Script`, which makes it natural to set `rollback`/`logPlacement`/`silent` on it as if authoring a standalone safety policy, but every one of those is discarded the moment it is mounted since only the host's own `ScriptOptions` ever apply. Agents optimizing for this skill's goal tend to bake `logPlacement` choices into a reusable sub-script and assume they travel with it because they don't account for mounting's constraint that a routine's own `ScriptOptions` are overridden entirely by the host script.
+
+See also: skills/reuse/reusable-routines-and-mounts/SKILL.md § Common Mistakes, skills/compensation-safety/adding-rollbacks/SKILL.md § Common Mistakes