@pushpalsdev/cli 1.0.32 → 1.0.34

package/runtime/sandbox/apps/workerpals/src/workerpals_main.ts

@@ -123,7 +123,8 @@ function buildWorkerLlmUsageEvent(
     return {
       service: "workerpals",
       sessionId,
-      backend: String(explicitUsage.backend ?? resolveExecutor(CONFIG)).trim() || resolveExecutor(CONFIG),
+      backend:
+        String(explicitUsage.backend ?? resolveExecutor(CONFIG)).trim() || resolveExecutor(CONFIG),
       modelId: String(explicitUsage.modelId ?? llmConfig.model).trim() || llmConfig.model,
       promptTokens,
       completionTokens,
@@ -214,6 +215,14 @@ function isNoisyProgressLine(line: string): boolean {
   return /^(📦 Installing \[\d+\/\d+\]|🔍 Resolving\.\.\.|🔒 Saving lockfile\.\.\.)$/.test(line);
 }
 
+export function shouldEmitDirectSessionJobEvent(options: {
+  ok: boolean;
+  statusPersistedToServer: boolean;
+}): boolean {
+  if (options.ok) return true;
+  return !options.statusPersistedToServer;
+}
+
 function shouldRecycleWorkerForCodexUnavailableFailure(
   summary: string,
   stderr?: string | null,
@@ -949,13 +958,15 @@ async function failActiveJobOnShutdown(
 
   const message = "Worker process shutting down during claimed job";
   const detail = `worker=${opts.workerId}; signal=${signalName}; action=fail-claimed-job-on-shutdown`;
+  let statusPersistedToServer = false;
 
   try {
-    await fetch(`${opts.server}/jobs/${activeJobId}/fail`, {
+    const response = await fetch(`${opts.server}/jobs/${activeJobId}/fail`, {
       method: "POST",
       headers,
       body: JSON.stringify({ message, detail }),
     });
+    statusPersistedToServer = response.ok;
   } catch (err) {
     console.error(
       `[WorkerPals] Failed to mark active job ${activeJobId} as failed during shutdown:`,
@@ -963,7 +974,10 @@ async function failActiveJobOnShutdown(
     );
   }
 
-  if (runtimeState.currentSessionId) {
+  if (
+    runtimeState.currentSessionId &&
+    shouldEmitDirectSessionJobEvent({ ok: false, statusPersistedToServer })
+  ) {
     await sendCommand(opts.server, runtimeState.currentSessionId, headers, {
       type: "job_failed",
       payload: {
@@ -1241,6 +1255,7 @@ async function workerLoop(
               }
             }
 
+            let statusPersistedToServer = false;
             if (result.ok) {
               const reviewAgent =
                 parsedParams.reviewAgent && typeof parsedParams.reviewAgent === "object"
@@ -1252,7 +1267,7 @@ async function workerLoop(
                 reviewAgent.prUrl.trim().length > 0
                   ? reviewAgent.prUrl.trim()
                   : null;
-              await fetch(`${opts.server}/jobs/${job.id}/complete`, {
+              const response = await fetch(`${opts.server}/jobs/${job.id}/complete`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify({
@@ -1265,11 +1280,12 @@ async function workerLoop(
                   ],
                 }),
               });
+              statusPersistedToServer = response.ok;
               console.log(
                 `[WorkerPals] Job ${job.id} completed in ${formatDurationMs(jobDurationMs)}: ${result.summary}`,
               );
             } else {
-              await fetch(`${opts.server}/jobs/${job.id}/fail`, {
+              const response = await fetch(`${opts.server}/jobs/${job.id}/fail`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify({
@@ -1278,6 +1294,7 @@ async function workerLoop(
                   durationMs: jobDurationMs,
                 }),
               });
+              statusPersistedToServer = response.ok;
               console.log(
                 `[WorkerPals] Job ${job.id} failed in ${formatDurationMs(jobDurationMs)}: ${result.summary}`,
               );
@@ -1318,29 +1335,31 @@ async function workerLoop(
                 }
               }
 
-              const eventCmd = result.ok
-                ? {
-                    type: "job_completed" as const,
-                    payload: {
-                      jobId: job.id,
-                      summary: result.summary,
-                      artifacts: result.stdout
-                        ? [{ kind: "log" as const, text: result.stdout }]
-                        : undefined,
-                    },
-                    from: `worker:${opts.workerId}`,
-                  }
-                : {
-                    type: "job_failed" as const,
-                    payload: {
-                      jobId: job.id,
-                      message: result.summary,
-                      detail: redactSensitiveText(result.stderr ?? ""),
-                    },
-                    from: `worker:${opts.workerId}`,
-                  };
+              if (shouldEmitDirectSessionJobEvent({ ok: result.ok, statusPersistedToServer })) {
+                const eventCmd = result.ok
+                  ? {
+                      type: "job_completed" as const,
+                      payload: {
+                        jobId: job.id,
+                        summary: result.summary,
+                        artifacts: result.stdout
+                          ? [{ kind: "log" as const, text: result.stdout }]
+                          : undefined,
+                      },
+                      from: `worker:${opts.workerId}`,
+                    }
+                  : {
+                      type: "job_failed" as const,
+                      payload: {
+                        jobId: job.id,
+                        message: result.summary,
+                        detail: redactSensitiveText(result.stderr ?? ""),
+                      },
+                      from: `worker:${opts.workerId}`,
+                    };
 
-              await sendCommand(opts.server, job.sessionId, headers, eventCmd);
+                await sendCommand(opts.server, job.sessionId, headers, eventCmd);
+              }
             }
           } finally {
             clearInterval(busyHeartbeat);

package/runtime/sandbox/packages/shared/src/autonomy_policy.ts

@@ -263,8 +263,9 @@ export function globBreadthScore(glob: string): number {
   const rootWide = /^[\*]/.test(glob) || glob.startsWith("**/") ? 1 : 0;
   const literalSegments = glob
     .split("/")
-    .filter((segment) => segment.length > 0 && !segment.includes("*") && !segment.includes("?"))
-    .length;
+    .filter(
+      (segment) => segment.length > 0 && !segment.includes("*") && !segment.includes("?"),
+    ).length;
   const shallowPenalty = Math.max(0, 2 - Math.min(literalSegments, 2));
   return 4 * hasGlobStar + 2 * rootWide + Math.min(4, wildcardCount) + shallowPenalty;
 }
@@ -343,7 +344,11 @@ export function validateScopeInvariants(
       errors.push(`write_glob outside component root: ${normalized}`);
       continue;
     }
-    if (!normalizedTargetPaths.some((targetPath) => targetPath === prefix || targetPath.startsWith(`${prefix}/`))) {
+    if (
+      !normalizedTargetPaths.some(
+        (targetPath) => targetPath === prefix || targetPath.startsWith(`${prefix}/`),
+      )
+    ) {
       errors.push(`write_glob prefix does not align with target_paths: ${normalized}`);
       continue;
     }

package/runtime/sandbox/packages/shared/src/communication.ts

@@ -21,7 +21,10 @@ function stripPresenceSourcePrefix(value: string): string {
 
 export function normalizePresenceClientId(value: unknown): string {
   const raw = stripPresenceSourcePrefix(String(value ?? "").trim());
-  return raw.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "").trim();
+  return raw
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .trim();
 }
 
 export function normalizePresenceClientLabel(value: unknown): string {
@@ -31,7 +34,9 @@ export function normalizePresenceClientLabel(value: unknown): string {
 }
 
 export function normalizePresenceLookupToken(value: unknown): string {
-  return normalizePresenceClientLabel(value).toLowerCase().replace(/[^a-z0-9]+/g, "");
+  return normalizePresenceClientLabel(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "");
 }
 
 type SessionTransportPresence = {
@@ -91,8 +96,9 @@ export class CommunicationManager {
         : `${normalizedFrom || "agent"}__${normalizedSessionId || "session"}`,
       kind: "agent",
       label: labelFrom || normalizedFrom || "Agent",
-      version: String(process.env.PUSHPALS_RUNTIME_TAG ?? process.env.npm_package_version ?? "")
-        .trim(),
+      version: String(
+        process.env.PUSHPALS_RUNTIME_TAG ?? process.env.npm_package_version ?? "",
+      ).trim(),
       platform: `${process.platform}/${process.arch}`,
       repoRoot,
     };
@@ -151,10 +157,15 @@ export class CommunicationManager {
     text: string,
     meta: EventMeta = {},
   ): Promise<boolean> {
-    return this.emitToSession(sessionId, "message", { text }, {
-      ...meta,
-      from: meta.from ?? "client",
-    });
+    return this.emitToSession(
+      sessionId,
+      "message",
+      { text },
+      {
+        ...meta,
+        from: meta.from ?? "client",
+      },
+    );
   }
 
   async userMessage(text: string, meta: EventMeta = {}): Promise<boolean> {

package/runtime/sandbox/packages/shared/src/config.ts

@@ -457,11 +457,7 @@ function normalizeWorkerImageRebuildMode(value: string): "auto" | "always" | "ne
 
 function normalizeStartupPortConflictPolicy(value: string): "fail" | "terminate_pushpals" {
   const text = value.trim().toLowerCase().replace(/-/g, "_");
-  if (
-    text === "terminate_pushpals" ||
-    text === "kill_pushpals" ||
-    text === "auto_kill_pushpals"
-  ) {
+  if (text === "terminate_pushpals" || text === "kill_pushpals" || text === "auto_kill_pushpals") {
     return "terminate_pushpals";
   }
   return "fail";
@@ -535,10 +531,7 @@ function resolveLlmConfig(
   );
   const codexTimeoutMs = Math.max(
     10_000,
-    asInt(
-      parseIntEnv(`${envPrefix}_LLM_CODEX_TIMEOUT_MS`) ?? llmNode.codex_timeout_ms,
-      120_000,
-    ),
+    asInt(parseIntEnv(`${envPrefix}_LLM_CODEX_TIMEOUT_MS`) ?? llmNode.codex_timeout_ms, 120_000),
   );
   return {
     backend,
@@ -916,7 +909,8 @@ export function loadPushPalsConfig(options: LoadOptions = {}): PushPalsConfig {
     Math.min(
       10,
       asInt(
-        parseIntEnv("WORKERPALS_QUALITY_MAX_AUTO_REVISIONS") ?? workerNode.quality_max_auto_revisions,
+        parseIntEnv("WORKERPALS_QUALITY_MAX_AUTO_REVISIONS") ??
+          workerNode.quality_max_auto_revisions,
         DEFAULT_WORKERPALS_QUALITY_MAX_AUTO_REVISIONS,
       ),
     ),
@@ -973,8 +967,7 @@ export function loadPushPalsConfig(options: LoadOptions = {}): PushPalsConfig {
   const workerQualityCriticTimeoutMs = Math.max(
     1_000,
     asInt(
-      parseIntEnv("WORKERPALS_QUALITY_CRITIC_TIMEOUT_MS") ??
-        workerNode.quality_critic_timeout_ms,
+      parseIntEnv("WORKERPALS_QUALITY_CRITIC_TIMEOUT_MS") ?? workerNode.quality_critic_timeout_ms,
       DEFAULT_WORKERPALS_QUALITY_CRITIC_TIMEOUT_MS,
     ),
   );
@@ -1431,8 +1424,7 @@ export function loadPushPalsConfig(options: LoadOptions = {}): PushPalsConfig {
     parseBoolEnv("PUSHPALS_ALLOW_EXTERNAL_CLEAN") ??
     asBoolean(startupNode.allow_external_clean, false);
   const startupPortPreflight =
-    parseBoolEnv("PUSHPALS_STARTUP_PORT_PREFLIGHT") ??
-    asBoolean(startupNode.port_preflight, true);
+    parseBoolEnv("PUSHPALS_STARTUP_PORT_PREFLIGHT") ?? asBoolean(startupNode.port_preflight, true);
   const startupPortConflictPolicy = normalizeStartupPortConflictPolicy(
     firstNonEmpty(
       process.env.PUSHPALS_STARTUP_PORT_CONFLICT_POLICY,
@@ -1508,10 +1500,7 @@ export function loadPushPalsConfig(options: LoadOptions = {}): PushPalsConfig {
         asBoolean(remoteNode.auto_spawn_workerpals, true),
       maxWorkerpals: Math.max(
         1,
-        asInt(
-          parseIntEnv("REMOTEBUDDY_MAX_WORKERPALS") ?? remoteNode.max_workerpals,
-          20,
-        ),
+        asInt(parseIntEnv("REMOTEBUDDY_MAX_WORKERPALS") ?? remoteNode.max_workerpals, 20),
       ),
       workerpalStartupTimeoutMs: Math.max(
         1_000,
@@ -1647,8 +1636,7 @@ export function loadPushPalsConfig(options: LoadOptions = {}): PushPalsConfig {
         llmTimeoutMs: Math.max(
           1_000,
           asInt(
-            parseIntEnv("REMOTEBUDDY_AUTONOMY_LLM_TIMEOUT_MS") ??
-              remoteAutonomyNode.llm_timeout_ms,
+            parseIntEnv("REMOTEBUDDY_AUTONOMY_LLM_TIMEOUT_MS") ?? remoteAutonomyNode.llm_timeout_ms,
             12_000,
           ),
         ),
@@ -2156,10 +2144,7 @@ function sanitizeConfigString(value: string): string {
   return out;
 }
 
-function sanitizeConfigValueForLogging(
-  value: unknown,
-  parentKey = "",
-): unknown {
+function sanitizeConfigValueForLogging(value: unknown, parentKey = ""): unknown {
   if (
     typeof value === "string" ||
     typeof value === "number" ||

package/runtime/sandbox/packages/shared/src/config_template_parity.ts

@@ -18,11 +18,7 @@ export function collectDotEnvKeys(raw: string): Set<string> {
   return keys;
 }
 
-function collectTomlLeafKeysFromNode(
-  node: unknown,
-  prefix: string,
-  out: Set<string>,
-): void {
+function collectTomlLeafKeysFromNode(node: unknown, prefix: string, out: Set<string>): void {
   if (!isObject(node)) return;
   for (const [rawKey, value] of Object.entries(node)) {
     const key = rawKey.trim();
@@ -43,7 +39,10 @@ export function collectTomlLeafKeys(raw: string): Set<string> {
   return keys;
 }
 
-export function missingTemplateKeys(templateKeys: Iterable<string>, localKeys: Set<string>): string[] {
+export function missingTemplateKeys(
+  templateKeys: Iterable<string>,
+  localKeys: Set<string>,
+): string[] {
   const templateSet = new Set(templateKeys);
   const missing: string[] = [];
   for (const key of templateSet) {

package/runtime/sandbox/packages/shared/src/git_backend.ts

@@ -42,10 +42,7 @@ export function sanitizeGitRemoteUrl(remoteUrl: string): string {
   return raw.replace(/^(https?:\/\/)[^@/]+@/i, "$1");
 }
 
-function firstNonEmpty(
-  env: Record<string, string | undefined>,
-  keys: readonly string[],
-): string {
+function firstNonEmpty(env: Record<string, string | undefined>, keys: readonly string[]): string {
   for (const key of keys) {
     const value = trimToken(env[key]);
     if (value) return value;
@@ -110,10 +107,7 @@ export function toGitHubRepoWebUrl(remoteUrl: string): string | null {
   return `https://github.com/${repo.owner}/${repo.repo}`;
 }
 
-async function defaultRunCommand(
-  command: string[],
-  cwd?: string,
-): Promise<CommandCaptureResult> {
+async function defaultRunCommand(command: string[], cwd?: string): Promise<CommandCaptureResult> {
   try {
     const proc = Bun.spawn(command, {
       cwd,
@@ -147,7 +141,9 @@ async function resolveGitHubCliToken(
   cwd?: string,
 ): Promise<string> {
   const useHostname = host && host !== "github.com";
-  const command = useHostname ? ["gh", "auth", "token", "--hostname", host] : ["gh", "auth", "token"];
+  const command = useHostname
+    ? ["gh", "auth", "token", "--hostname", host]
+    : ["gh", "auth", "token"];
   const result = await runCommand(command, cwd);
   return result.ok ? trimToken(result.stdout) : "";
 }

package/runtime/sandbox/packages/shared/src/local_network.ts

@@ -89,7 +89,9 @@ export function resolveLocalServerConnection(options: {
   serverWasNormalized: boolean;
   authTokenWasIgnored: boolean;
 } {
-  const rawServer = String(options.serverUrl ?? "").trim().replace(/\/+$/, "");
+  const rawServer = String(options.serverUrl ?? "")
+    .trim()
+    .replace(/\/+$/, "");
   const normalizedServer = normalizeLoopbackHttpUrl(rawServer, options.fallbackPort);
   const authToken = String(options.authToken ?? "").trim();
   return {

package/runtime/sandbox/packages/shared/src/localbuddy_runtime.ts

@@ -50,10 +50,7 @@ export function parseLocalBuddyRuntimeSnapshot(raw: string): LocalBuddyRuntimeSn
   return {
     localbuddy: {
       enabled,
-      port:
-        Number.isFinite(port) && port >= 1 && port <= 65_535
-          ? port
-          : DEFAULT_LOCALBUDDY_PORT,
+      port: Number.isFinite(port) && port >= 1 && port <= 65_535 ? port : DEFAULT_LOCALBUDDY_PORT,
     },
   };
 }
@@ -155,7 +152,9 @@ function resolveRuntimeConfigDir(workspaceRoot: string, configuredDir?: string):
 }
 
 function parseBoolEnv(value: string | undefined): boolean | undefined {
-  const text = String(value ?? "").trim().toLowerCase();
+  const text = String(value ?? "")
+    .trim()
+    .toLowerCase();
   if (!text) return undefined;
   if (TRUTHY.has(text)) return true;
   if (FALSY.has(text)) return false;

package/runtime/sandbox/packages/shared/src/vision.ts

@@ -40,7 +40,9 @@ export type VisionDocValidation = {
 const MAX_KEY_ITEMS_PER_BUCKET = 8;
 
 function toLines(markdown: string): string[] {
-  return String(markdown ?? "").replace(/\r\n/g, "\n").split("\n");
+  return String(markdown ?? "")
+    .replace(/\r\n/g, "\n")
+    .split("\n");
 }
 
 function extractOneSentence(lines: string[]): string {
@@ -75,7 +77,9 @@ function extractOneSentence(lines: string[]): string {
 }
 
 function normalizeItem(value: string): string {
-  return String(value ?? "").replace(/\s+/g, " ").trim();
+  return String(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
 }
 
 function dedupeAndClamp(values: string[]): string[] {

package/runtime/sandbox/prompts/workerpals/commit_message_prompt.md

@@ -10,6 +10,7 @@ Output only the raw commit message text — no markdown fences, no explanation,
 - <specific implementation detail>
 
 Tests:
+
 - <test runner command>
 
 ## Writing rules
@@ -25,12 +26,14 @@ Background context: "can you add one more unit test for localbuddy"
 
 Bad (copies instruction / uses planning language):
 {{type}}({{area}}): lets add one more unit test for localbuddy
+
 - At least one new unit test is added validating a meaningful LocalBuddy behavior.
 - All existing and new tests pass.
 - No unrelated files are modified.
 
 Good (reads the diff):
 {{type}}({{area}}): add unit test for LocalBuddy request routing and error response handling
+
 - add test case in localbuddy.test.ts asserting router returns 404 for unknown tool calls
 - add negative test for malformed request payload returning 400 with error message
 - extract shared test fixtures into testHelpers.ts to reduce duplication

package/runtime/sandbox/prompts/workerpals/miniswe_broker_system_prompt.md

@@ -5,18 +5,19 @@ Repository root: {{repo}}
 
 Output format (STRICT JSON, no markdown, no extra keys unless specified):
 {
-  "actions": [
-    {"type":"read_file","path":"README.md"},
-    {"type":"append_line","path":"README.md","line":"..."},
-    {"type":"replace_text_once","path":"x","old":"a","new":"b"},
-    {"type":"write_file","path":"x","content":"..."},
-    {"type":"run_shell","command":"git status --porcelain"}
-  ],
-  "done": false,
-  "note": "short explanation"
+"actions": [
+{"type":"read_file","path":"README.md"},
+{"type":"append_line","path":"README.md","line":"..."},
+{"type":"replace_text_once","path":"x","old":"a","new":"b"},
+{"type":"write_file","path":"x","content":"..."},
+{"type":"run_shell","command":"git status --porcelain"}
+],
+"done": false,
+"note": "short explanation"
 }
 
 Rules:
+
 - Keep actions minimal and directly relevant.
 - JSON syntax must be exact: use ":" between keys and values, never ",".
 - Use double quotes for all keys and string values.

package/runtime/sandbox/prompts/workerpals/miniswe_strict_tool_use_guidance.md

@@ -1,4 +1,5 @@
 CRITICAL: You must use tools to make progress.
+
 - Use the environment's tools (file read/list/search, and file edit/write/patch) to inspect and modify the repo.
 - Do NOT only describe what you would do; actually do it.
 - Avoid broad scans; choose one target file quickly.

package/runtime/sandbox/prompts/workerpals/openai_codex_runtime_policy_appendix.md

@@ -1,4 +1,5 @@
 Runtime policy guardrails (mandatory):
+
 - Codex CLI is required infrastructure in this environment.
 - Never bypass Codex usage by changing tests/code expectations.
 - If Codex CLI auth/execution is unavailable, hard-fail and stop.

package/runtime/sandbox/prompts/workerpals/openai_codex_task_execute_system_prompt.md

@@ -1,12 +1,14 @@
 You are PushPals WorkerPal running via the OpenAI Codex CLI backend.
 
 Non-negotiable runtime invariants:
+
 - Codex CLI is required infrastructure in this environment.
 - Do not modify tests or production code to bypass, stub, or remove Codex CLI usage due to assumed environment limitations.
 - Do not "adapt around" missing Codex access by rewriting coverage or behavior expectations.
 - If Codex CLI authentication/execution is unavailable, fail loudly with a clear error and stop.
 
 Execution rules:
+
 - Keep edits minimal, correct, and scoped to the requested task.
 - Read relevant files before editing, then run focused validation.
 - Report blockers explicitly; do not hide platform/runtime issues with workaround edits.

package/runtime/sandbox/prompts/workerpals/task_quality_critic_system_prompt.md

@@ -2,8 +2,9 @@ You are a strict code-review critic for worker-generated patches.
 Return exactly one JSON object with keys:
 {"score": <0-10 number>, "findings": [string], "must_fix": [string], "revision_guidance": string}
 Scoring rubric:
+
 - 10: complete, correct, and robust with strong validation coverage.
 - 8-9: good quality with minor non-blocking issues.
 - <=7: requires revision before commit.
-must_fix must list blocking issues only.
-Do not include markdown or prose outside JSON.
+  must_fix must list blocking issues only.
+  Do not include markdown or prose outside JSON.

package/runtime/vision.example.md

@@ -9,18 +9,21 @@
 ## 1) Who this is for
 
 ### Primary users
+
 - **User type A:** (e.g., app developers, SREs, analysts, end-users)
   - Jobs-to-be-done: …
   - Pain today: …
   - Success looks like: …
 
 ### Secondary users
+
 - **User type B:** …
   - Jobs-to-be-done: …
   - Pain today: …
   - Success looks like: …
 
-### Non-users (explicitly *not* optimizing for)
+### Non-users (explicitly _not_ optimizing for)
+
 - **Not for:** …
   - Why: …
 
@@ -31,13 +34,15 @@
 ## 2) The problem we solve
 
 ### Today’s reality
+
 - What is hard / slow / risky today?
 - What failures happen repeatedly? (bugs, incidents, misconfig, confusion)
 - What is expensive? (time, money, cognitive load, coordination)
 
 ### The change we want
-- In 6–12 months, what should feel *meaningfully easier*?
-- In 2–3 years, what should be *obviously different*?
+
+- In 6–12 months, what should feel _meaningfully easier_?
+- In 2–3 years, what should be _obviously different_?
 
 > **Optional:** Add a 3–5 line “story” of a user before vs after.
 
@@ -66,11 +71,13 @@ These are **tie-breakers** when tradeoffs happen. Put them in priority order.
 Pick a small set of metrics you can actually track.
 
 ### User-facing outcomes
+
 - **Time-to-success:** e.g., median time from install → first successful use
 - **Quality:** e.g., bug rate / support tickets per active user
 - **Trust:** e.g., SLO compliance, error rate, crash-free sessions
 
 ### Developer / maintainer outcomes
+
 - **Change velocity:** PR cycle time, lead time to release
 - **Operational burden:** pages/alerts per week, toil hours
 - **Maintainability:** test coverage for critical paths, build time, flake rate
@@ -81,17 +88,20 @@ Pick a small set of metrics you can actually track.
 
 ## 5) Scope and boundaries
 
-### In scope (what we *are*)
+### In scope (what we _are_)
+
 - Core capability A: …
 - Core capability B: …
 - Core capability C: …
 
-### Out of scope / non-goals (what we are *not*)
+### Out of scope / non-goals (what we are _not_)
+
 - Not a replacement for: …
 - Not trying to support: …
 - Not optimizing for: …
 
 ### Compatibility & support policy (optional)
+
 - Supported platforms / versions: …
 - Breaking changes policy: …
 - Deprecation timeline: …
@@ -120,6 +130,7 @@ Pick 3–5 items max. Each should be **outcome-oriented**.
 These are “bets” with explicit results.
 
 ### Objective A: <name>
+
 - **Problem:** …
 - **Approach:** …
 - **Deliverables:** …
@@ -127,6 +138,7 @@ These are “bets” with explicit results.
 - **Exit criteria:** How we’ll know it worked (measurable)
 
 ### Objective B: <name>
+
 - …
 
 ---
@@ -136,6 +148,7 @@ These are “bets” with explicit results.
 Describe where this repo is going, without over-promising.
 
 ### Strategic bets
+
 - **Bet 1:** …
   - Why it matters: …
   - What we’ll likely build: …
@@ -143,6 +156,7 @@ Describe where this repo is going, without over-promising.
 - **Bet 2:** …
 
 ### “If we’re right, then…”
+
 - Users will be able to: …
 - Maintainers will spend less time on: …
 - The ecosystem will have: …
@@ -152,6 +166,7 @@ Describe where this repo is going, without over-promising.
 ## 9) Guardrails and constraints
 
 ### Guardrails (how we avoid harm / churn)
+
 - Prefer changes that are **reversible** or behind flags.
 - Default to **secure / safe** settings.
 - Optimize for the **common path**; support escape hatches for experts.
@@ -159,6 +174,7 @@ Describe where this repo is going, without over-promising.
 - Pay down operational toil before adding big surface area.
 
 ### Constraints (reality checks)
+
 - Staffing level / maintainer bandwidth: …
 - Hard requirements (privacy, compliance, perf, cost): …
 - External dependencies: …
@@ -181,11 +197,14 @@ Describe where this repo is going, without over-promising.
 ## Appendix (optional but powerful)
 
 ### A) Glossary
+
 - Term: definition…
 
 ### B) Personas (one-page each)
+
 - Persona, environment, constraints, success criteria…
 
 ### C) Example “no” responses (template)
+
 - “Thanks — this is valuable, but it conflicts with our non-goal X…”
 - “We’d reconsider if metric Y becomes a problem…”