@yagni-app/code-staging 0.1.0-staging.997.1 → 0.2.0-staging.1025.1

package/dist/extension/boostCommand.js

@@ -0,0 +1,263 @@
+/**
+ * `/boost` — the sanctioned session-scoped escalation to Peak (spec §7).
+ *
+ * The session default is the `balanced` tier. `/boost` flips the
+ * DRIVER session's live model to `peak` until `/boost off` or the process
+ * exits; `peak` stays directly pickable through pi's own model picker too,
+ * this just adds a one-word lever plus an attribution flag.
+ *
+ * Two halves, same split as `advisor.ts` / `permission.ts`:
+ *
+ *   - `boostOn` / `boostOff` are PURE. They own every transition and the exact
+ *     notice copy; no pi, no I/O, no env. That is what needs exhaustive tests.
+ *   - `registerBoostCommand` is the wiring: it applies the pure result's
+ *     `targetModelId` through pi's real model-switch API, toggles
+ *     `process.env.YAGNI_BOOST`, and paints the notice + a status-bar chip.
+ *
+ * The model-switch API (verified against pi 0.83.0's typings, not guessed):
+ * `ctx.modelRegistry.find(provider, modelId)` resolves a tier id to a
+ * `Model`, and `pi.setModel(model)` (the top-level `ExtensionAPI` method, NOT
+ * `ctx.setModel` — `ExtensionCommandContext` does not expose a setter) applies
+ * it to the live session, resolving `false` when no API key is configured.
+ * The `yagni` provider's catalog entries key `id` on the tier id itself (see
+ * `provider.ts`), so `peak` is the pi model id for the peak tier.
+ *
+ * State lives in the registration closure — module/session-scoped, mirroring
+ * `costHud.ts`'s accumulator — because a session's process exit is the only
+ * "end" there is; nothing needs to persist across it. `registerBoostCommand`
+ * returns a small `{ isBoosted() }` handle onto that same closure so other
+ * registrations (currently just `/cost`, see below) can read the live flag
+ * without a second source of truth.
+ *
+ * Picker-drift guard (spec review item 3): pi's OWN model picker (Ctrl+P,
+ * `/model`) can change the live model independently of `/boost` in either
+ * direction, so `state.active` can go stale relative to `ctx.model.id`. Both
+ * halves read the live model and reconcile rather than trusting `state.active`
+ * blindly:
+ *
+ *   - `boostOn` while already active but the live model has drifted OFF peak
+ *     (the user cycled models mid-boost without `/boost off`): re-applies
+ *     peak instead of a silent "Already boosted." that would leave the
+ *     driver quietly running a cheaper tier under an attribution header that
+ *     claims otherwise. The remembered `priorModelId` is left untouched — the
+ *     tier to restore is still whatever was active before the ORIGINAL boost,
+ *     not the tier the user happened to drift to.
+ *   - `boostOff` while active but the live model is no longer peak (same
+ *     drift, encountered from the other command): the user already left
+ *     boost manually, so forcing a switch back to the remembered prior tier
+ *     would clobber a choice they just made on purpose. Instead this clears
+ *     `/boost`'s own bookkeeping (state, env, chip) without touching the
+ *     model, and names where they actually landed.
+ *
+ * KNOWN asymmetry, documented rather than worked around: `YAGNI_BOOST=1`
+ * while boosted makes every CHILD process spawned during the boost (a /go
+ * run, a subagent, an advisor consult) inherit it, and those children's
+ * completions carry `x-yagni-boost` because their provider is registered
+ * fresh per child. The DRIVER's own completions do not gain that header
+ * retroactively — `buildYagniProvider`'s headers are baked into the
+ * `registerProvider` call once, at session start, from the env snapshot at
+ * that moment (see `provider.ts` / `attributionHeaders`). Re-registering the
+ * provider mid-session to pick up a new header is explicitly NOT the fix
+ * here: it would race the in-flight request the switch itself triggers and
+ * has no test coverage as a live-swap path.
+ *
+ * This is exactly why `/cost` cannot rely on server rows alone: the server's
+ * per-tier "Boosted (tier) spend" subtotal (`formatServerCostLines`, Task 7)
+ * only ever sees rows carrying `x-yagni-boost` — i.e. `/go` children, never
+ * the driver's own turns. A session that only chats while boosted would
+ * otherwise show no boost line at all. `registerCostCommand`'s `isBoosted`
+ * dep (threaded from THIS module's return handle, the same way
+ * `advisorSubtotal` is threaded from `advisor.ts`) closes that gap: `/cost`
+ * appends a fixed "Boost is on. Driver turns bill at the peak tier." line
+ * whenever the live toggle is on, on BOTH the server-authoritative and the
+ * local-fallback branch, independent of what server rows happen to show.
+ */
+/** The pi provider name the YAGNI catalog registers under (see `provider.ts`). */
+const YAGNI_PROVIDER = "yagni";
+/** The tier `/boost` escalates to. */
+const BOOST_TIER = "peak";
+/** The session default tier, restored when no prior tier is known. */
+const DEFAULT_TIER = "balanced";
+/** Tier ids are lowercase; every known tier's display name is just Title Case of the id. */
+function displayTierName(id) {
+    return id.length === 0 ? id : id.charAt(0).toUpperCase() + id.slice(1);
+}
+/**
+ * Turn boost on. PURE.
+ *
+ * - Already active AND the live model is still `peak`: genuine no-op,
+ *   "Already boosted." (no switch — nothing about the prior tier changes).
+ * - Already active but the live model has drifted off `peak` (picker-drift
+ *   guard 3b, see module docblock): re-applies `peak`, keeping the ORIGINAL
+ *   `priorModelId` rather than adopting the drifted-to tier.
+ * - Not active, current model IS already `peak`: activates anyway (so
+ *   attribution and `/boost off` behave correctly) with a distinct notice,
+ *   remembering `peak` itself as the tier to restore.
+ * - Not active, otherwise: remembers the current tier, targets `peak`.
+ */
+export function boostOn(state, currentModelId) {
+    if (state.active) {
+        if (currentModelId === BOOST_TIER) {
+            return { state, notice: "Already boosted." };
+        }
+        return {
+            state,
+            notice: `Re-boosted to Peak. /boost off to return to ${displayTierName(state.priorModelId ?? DEFAULT_TIER)}.`,
+            targetModelId: BOOST_TIER,
+        };
+    }
+    if (currentModelId === BOOST_TIER) {
+        return {
+            state: { active: true, priorModelId: BOOST_TIER },
+            notice: "Already on Peak. /boost off returns to Peak.",
+            targetModelId: BOOST_TIER,
+        };
+    }
+    return {
+        state: { active: true, priorModelId: currentModelId },
+        notice: `Boosted to Peak. /boost off to return to ${displayTierName(currentModelId ?? DEFAULT_TIER)}.`,
+        targetModelId: BOOST_TIER,
+    };
+}
+/**
+ * Turn boost off. PURE.
+ *
+ * - Not active: no-op, "Boost is not on."
+ * - Active but the live model is no longer `peak` (picker-drift guard 3a,
+ *   see module docblock): the user already left boost manually. Clears
+ *   `/boost`'s own bookkeeping WITHOUT a switch — forcing one back to the
+ *   remembered prior tier would clobber a choice just made on purpose — and
+ *   names the model they actually landed on.
+ * - Active and still on `peak`: restores the remembered prior tier (falling
+ *   back to the session default when none was recorded, which should not
+ *   normally happen). When the prior tier is itself `peak` (the
+ *   already-on-Peak activation path), the resulting switch is a no-op in
+ *   effect — still applied, harmlessly.
+ */
+export function boostOff(state, currentModelId) {
+    if (!state.active) {
+        return { state, notice: "Boost is not on." };
+    }
+    if (currentModelId !== BOOST_TIER) {
+        return {
+            state: { active: false, priorModelId: undefined },
+            notice: `Boost off. Leaving the model on ${displayTierName(currentModelId ?? DEFAULT_TIER)}.`,
+        };
+    }
+    const priorId = state.priorModelId ?? DEFAULT_TIER;
+    return {
+        state: { active: false, priorModelId: undefined },
+        notice: `Back to ${displayTierName(priorId)}.`,
+        targetModelId: priorId,
+    };
+}
+/**
+ * Resolve `tierId` to a live `Model` and apply it via `pi.setModel`.
+ *
+ * On a registry lookup miss, `allowFallback` (true only on the OFF path —
+ * MINOR 5) retries once against the session default tier rather than
+ * stranding the user on Peak over one missing catalog entry. Returns the
+ * tier id that was ACTUALLY applied, so the caller can tell whether the
+ * fallback fired and adjust the notice to name it honestly.
+ *
+ * @throws when neither the requested tier nor (if allowed) the fallback
+ * resolves, or when `pi.setModel` itself throws or resolves `false`.
+ */
+async function applyTier(pi, ctx, tierId, allowFallback) {
+    let model = ctx.modelRegistry?.find(YAGNI_PROVIDER, tierId);
+    let applied = tierId;
+    if (!model && allowFallback && tierId !== DEFAULT_TIER) {
+        model = ctx.modelRegistry?.find(YAGNI_PROVIDER, DEFAULT_TIER);
+        applied = DEFAULT_TIER;
+    }
+    if (!model) {
+        throw new Error(`Unknown YAGNI tier "${tierId}".`);
+    }
+    const ok = await pi.setModel(model);
+    if (!ok) {
+        throw new Error("setModel reported no API key configured.");
+    }
+    return applied;
+}
+/**
+ * Register the `/boost` command.
+ *
+ * `/boost` (no args) turns boost on; `/boost off` turns it off; any other
+ * argument shows a usage notice and changes nothing. Every transition that
+ * requires a model switch runs it through pi's real API and is guarded end to
+ * end: state and `YAGNI_BOOST` are only ever committed together, AFTER the
+ * switch succeeds (or is deliberately skipped — the picker-drift guards), so
+ * a half-applied boost (env set but model unchanged, or vice versa) can never
+ * happen. A failed ON reports "Boost failed."; a failed OFF reports a
+ * DISTINCT message, because the failure mode is materially worse — the
+ * driver is left still running (and billing) on Peak, not merely unchanged.
+ */
+export function registerBoostCommand(pi, deps = {}) {
+    const env = deps.env ?? process.env;
+    let state = { active: false };
+    const paintStatus = (ctx, active) => {
+        try {
+            if (ctx.hasUI)
+                ctx.ui.setStatus?.("yagni-boost", active ? "⚡ Peak" : undefined);
+        }
+        catch {
+            // The chip is chrome; never let it break /boost.
+        }
+    };
+    pi.registerCommand("boost", {
+        description: "Escalate this session's model to Peak until /boost off or the session ends. /boost off returns to the prior tier.",
+        handler: async (args, ctx) => {
+            const notify = (message, type) => {
+                if (ctx.hasUI)
+                    ctx.ui.notify(message, type);
+            };
+            // MINOR 4: case-insensitive "off" match, mirroring /mode's arg handling.
+            const arg = args.trim().toLowerCase();
+            if (arg !== "" && arg !== "off") {
+                notify("Usage: /boost (turn on) or /boost off.", "warning");
+                return;
+            }
+            const isOff = arg === "off";
+            const wasActive = state.active;
+            const result = isOff ? boostOff(state, ctx.model?.id) : boostOn(state, ctx.model?.id);
+            try {
+                let notice = result.notice;
+                if (result.targetModelId) {
+                    const applied = await applyTier(pi, ctx, result.targetModelId, isOff);
+                    if (applied !== result.targetModelId) {
+                        // MINOR 5: the remembered/target tier no longer resolves in the
+                        // catalog; we landed on the session default instead of
+                        // stranding the user on Peak. Name the fallback so the notice
+                        // stays honest about what actually happened.
+                        notice = `Back to ${displayTierName(applied)} (could not restore ${displayTierName(result.targetModelId)}).`;
+                    }
+                }
+                state = result.state;
+                // MINOR 6: only touch the env on a real active/inactive flip. Both
+                // pure no-op paths ("Already boosted.", "Boost is not on.") return
+                // `state` unchanged, so this never fires for them — an inherited
+                // YAGNI_BOOST from outside this session is left exactly as found.
+                if (state.active !== wasActive) {
+                    if (state.active) {
+                        env.YAGNI_BOOST = "1";
+                    }
+                    else {
+                        delete env.YAGNI_BOOST;
+                    }
+                }
+                notify(notice, "info");
+                paintStatus(ctx, state.active);
+            }
+            catch {
+                // IMPORTANT 1: a failed OFF is materially worse than a failed ON —
+                // the driver is STILL on Peak, still billing at Peak rates, which a
+                // generic "Boost failed." does not convey. Neither `state` nor
+                // `YAGNI_BOOST` was touched above (the throw lands before both), so
+                // the chip is also left exactly as it was: still lit.
+                notify(isOff ? "Could not leave boost. Still on Peak; try /boost off again." : "Boost failed.", "error");
+            }
+        },
+    });
+    return { isBoosted: () => state.active };
+}
+//# sourceMappingURL=boostCommand.js.map

package/dist/extension/branding.d.ts

@@ -14,9 +14,40 @@ export declare const BRAND_NAME = "YAGNI Code";
  * "You are an expert coding assistant operating inside pi..." opener. It states
  * the differentiator (connected to the YAGNI app) and the working contract
  * (consult ask_yagni before guessing) so the agent behaves more autonomously.
+ *
+ * This is the BASE identity, used for every non-driver caller (a `/go` stage
+ * child, a subagent, an advisor consult) as well as the driver, since the
+ * extension loads identically in every one of those pi processes. It carries
+ * no delegation directive: see {@link YAGNI_IDENTITY_DRIVER}.
  */
 export declare const YAGNI_IDENTITY: string;
+/**
+ * The delegation-first directive: fan mechanical/wide work out to subagents
+ * (which run on cheaper tiers) and keep judgment, synthesis, and the user
+ * conversation in this session. DRIVER-ONLY (see {@link YAGNI_IDENTITY_DRIVER}):
+ * a `/go` stage child has no `subagent` tool, so this instruction would be
+ * pure prompt noise there, or worse, an attempt to call a tool that doesn't
+ * exist.
+ */
+export declare const DRIVER_DELEGATION_PARAGRAPH: string;
+/**
+ * The identity used for the interactive DRIVER session ONLY: {@link
+ * YAGNI_IDENTITY} plus {@link DRIVER_DELEGATION_PARAGRAPH}. The caller (index.ts)
+ * selects between this and the base `YAGNI_IDENTITY` per-process based on the
+ * effective `x-yagni-caller` attribution (config.ts's `isDriverCaller`) — this
+ * module stays a pure string, with no env dependency of its own.
+ */
+export declare const YAGNI_IDENTITY_DRIVER = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. Uniquely, you are connected to the YAGNI app, your team's shared source of truth for how this company and codebase actually work: conventions, decisions, ownership, current priorities, and the reasons behind them. Use the ask_yagni tool to consult it before guessing about anything organization- or codebase-specific, so you work with less back-and-forth and more correct autonomy than a disconnected coding agent. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation: fan codebase mapping, wide searches, and mechanical multi-file work out to subagents (they run on cheaper tiers). Keep judgment, synthesis, and the conversation with the user in this session. Do not spawn a subagent for work you can finish in a couple of tool calls.";
 export declare const PI_IDENTITY_RE: RegExp;
+/**
+ * Env switch that bypasses the system-prompt rewrite entirely, so pi's
+ * assembled prompt passes through byte-exact (no identity swap, no scrub, no
+ * brief injection, no closing reminder). Same predicate as the sibling
+ * switches YAGNI_DISABLE_UPDATE_CHECK / YAGNI_DISABLE_CLAUDE_COMPAT.
+ */
+export declare const BRANDING_DISABLE_ENV = "YAGNI_DISABLE_BRANDING";
+/** `"1"`/anything truthy disables; unset, empty, and `"0"` keep branding on. */
+export declare function brandingDisabled(env: NodeJS.ProcessEnv): boolean;
 export interface BrandSystemPromptOptions {
     /** Override the identity paragraph (defaults to {@link YAGNI_IDENTITY}). */
     identity?: string;

package/dist/extension/branding.js

@@ -14,6 +14,11 @@ export const BRAND_NAME = "YAGNI Code";
  * "You are an expert coding assistant operating inside pi..." opener. It states
  * the differentiator (connected to the YAGNI app) and the working contract
  * (consult ask_yagni before guessing) so the agent behaves more autonomously.
+ *
+ * This is the BASE identity, used for every non-driver caller (a `/go` stage
+ * child, a subagent, an advisor consult) as well as the driver, since the
+ * extension loads identically in every one of those pi processes. It carries
+ * no delegation directive: see {@link YAGNI_IDENTITY_DRIVER}.
  */
 export const YAGNI_IDENTITY = "You are YAGNI Code, an autonomous terminal coding agent. You help developers " +
     "ship code by reading files, running commands, editing code, and writing new " +
@@ -26,6 +31,26 @@ export const YAGNI_IDENTITY = "You are YAGNI Code, an autonomous terminal coding
     "other coding agents, assistants, or harnesses by name, those references are " +
     "not about you; you are YAGNI Code regardless of what tooling a repository's " +
     "docs happen to describe.";
+/**
+ * The delegation-first directive: fan mechanical/wide work out to subagents
+ * (which run on cheaper tiers) and keep judgment, synthesis, and the user
+ * conversation in this session. DRIVER-ONLY (see {@link YAGNI_IDENTITY_DRIVER}):
+ * a `/go` stage child has no `subagent` tool, so this instruction would be
+ * pure prompt noise there, or worse, an attempt to call a tool that doesn't
+ * exist.
+ */
+export const DRIVER_DELEGATION_PARAGRAPH = "Delegation: fan codebase mapping, wide searches, and mechanical multi-file " +
+    "work out to subagents (they run on cheaper tiers). Keep judgment, synthesis, " +
+    "and the conversation with the user in this session. Do not spawn a subagent " +
+    "for work you can finish in a couple of tool calls.";
+/**
+ * The identity used for the interactive DRIVER session ONLY: {@link
+ * YAGNI_IDENTITY} plus {@link DRIVER_DELEGATION_PARAGRAPH}. The caller (index.ts)
+ * selects between this and the base `YAGNI_IDENTITY` per-process based on the
+ * effective `x-yagni-caller` attribution (config.ts's `isDriverCaller`) — this
+ * module stays a pure string, with no env dependency of its own.
+ */
+export const YAGNI_IDENTITY_DRIVER = `${YAGNI_IDENTITY}\n\n${DRIVER_DELEGATION_PARAGRAPH}`;
 // pi 0.83.0's exact identity sentence (dist/core/system-prompt.js). Exported as
 // the identity anchor the CLI's pi-contract tripwire test reads back from pi's
 // built system prompt, so a pi bump that reworded the opener (silently defeating
@@ -56,6 +81,18 @@ function scrubOutsideProjectContext(s) {
         .map((p) => (p.startsWith("<project_context>") ? p : scrubPiHarness(p)))
         .join("");
 }
+/**
+ * Env switch that bypasses the system-prompt rewrite entirely, so pi's
+ * assembled prompt passes through byte-exact (no identity swap, no scrub, no
+ * brief injection, no closing reminder). Same predicate as the sibling
+ * switches YAGNI_DISABLE_UPDATE_CHECK / YAGNI_DISABLE_CLAUDE_COMPAT.
+ */
+export const BRANDING_DISABLE_ENV = "YAGNI_DISABLE_BRANDING";
+/** `"1"`/anything truthy disables; unset, empty, and `"0"` keep branding on. */
+export function brandingDisabled(env) {
+    const value = env[BRANDING_DISABLE_ENV];
+    return value !== undefined && value !== "" && value !== "0";
+}
 /**
  * Rebrand pi's assembled system prompt as YAGNI Code's, and optionally inject a
  * live company brief.

package/dist/extension/chipEditor.js

@@ -26,7 +26,7 @@ import { matchesKey } from "@earendil-works/pi-tui";
 import { spawnSync } from "node:child_process";
 import { readFileSync, unlinkSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, basename } from "node:path";
+import { join, basename, isAbsolute } from "node:path";
 import { randomUUID } from "node:crypto";
 import { logImagePaste } from "./diagnostics.js";
 /** Matches the `[Image #N]` chip token in the editor text. */
@@ -81,10 +81,14 @@ export function readPastedImagePath(pastedText) {
     // must confirm the un-escaped form is a well-formed tmp image path before any
     // unescaping or path resolution. cmux tmp paths contain no escapable chars
     // (no spaces/metacharacters), so a legitimate paste has NO backslashes at all.
-    if (trimmed.includes("\\"))
+    // On Windows the backslash IS the path separator (and cmd/PowerShell do no
+    // backslash-escaping), so the escape-smuggling rejection applies only where
+    // a backslash could be an escape: POSIX shells.
+    const isWindows = process.platform === "win32";
+    if (!isWindows && trimmed.includes("\\"))
         return null; // escapes => not a plain cmux tmp path
     const path = trimmed;
-    if (!path.startsWith("/"))
+    if (isWindows ? !isAbsolute(path) : !path.startsWith("/"))
         return null;
     const name = basename(path);
     if (!name.startsWith("clipboard-"))

package/dist/extension/claudeRules.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Claude Code `.claude/rules/*.md` compat: fold rule files into the system
+ * prompt the extension already owns.
+ *
+ * Claude Code loads a rule without `paths` frontmatter at launch (same weight
+ * as CLAUDE.md) and injects a `paths`-scoped rule when the agent reads a
+ * matching file. pi has no read-triggered injection, so the faithful bounded
+ * mapping (see docs/superpowers/specs/2026-08-08-claude-plugins-design.md) is:
+ *
+ * - unscoped rules: content inlined verbatim into one system-prompt section
+ *   (per-file and total character caps, truncation markers) — exactly the
+ *   load-at-launch behavior;
+ * - path-scoped rules: a pointer line — "when working with files matching
+ *   these patterns, read and follow <file>" — so the prompt stays bounded on
+ *   rule-heavy repos and scoping stays honest.
+ *
+ * The launcher decides WHICH dirs load (user `~/.claude/rules` freely, repo
+ * `.claude/rules` only once the folder is trusted) and passes them via
+ * `YAGNI_CLAUDE_RULES_DIRS`, user dir first so project rules land last and
+ * win. Everything here is fail-soft and honors the compat kill switch.
+ */
+export declare const CLAUDE_RULES_DIRS_ENV = "YAGNI_CLAUDE_RULES_DIRS";
+export declare const CLAUDE_RULES_HEADER = "## Repository rules (.claude/rules)";
+export interface ClaudeRule {
+    /** Absolute file path — the pointer target for scoped rules. */
+    path: string;
+    /** Glob patterns from `paths` frontmatter; empty means always-on. */
+    paths: string[];
+    /** Markdown body (frontmatter stripped). */
+    body: string;
+}
+export interface CollectRulesOptions {
+    /** Total file cap across all dirs (default 40). */
+    maxFiles?: number;
+    /** Recursion depth cap per dir (default 5). */
+    maxDepth?: number;
+    /** Skip files larger than this (default 64 KiB). */
+    maxFileBytes?: number;
+}
+/** Enumerate + parse rule files from `dirs`, in dir order. Never throws. */
+export declare function collectClaudeRules(dirs: string[], opts?: CollectRulesOptions): ClaudeRule[];
+export interface BuildSectionOptions {
+    /** Per-file inline cap in characters (default 8000). */
+    maxInlineChars?: number;
+    /** Total inline budget across unscoped rules (default 32000). */
+    maxTotalChars?: number;
+}
+/** The system-prompt section for `rules`, or null when there is nothing to say. */
+export declare function buildClaudeRulesSection(rules: ClaudeRule[], opts?: BuildSectionOptions): string | null;
+/** Env-driven entry: dirs from YAGNI_CLAUDE_RULES_DIRS, null when off/empty. */
+export declare function claudeRulesSection(env: NodeJS.ProcessEnv, opts?: CollectRulesOptions & BuildSectionOptions): string | null;
+/** Append `section` to a system prompt exactly once; no-op without a section. */
+export declare function appendClaudeRules(systemPrompt: string, section: string | null): string;
+//# sourceMappingURL=claudeRules.d.ts.map

package/dist/extension/claudeRules.js

@@ -0,0 +1,180 @@
+/**
+ * Claude Code `.claude/rules/*.md` compat: fold rule files into the system
+ * prompt the extension already owns.
+ *
+ * Claude Code loads a rule without `paths` frontmatter at launch (same weight
+ * as CLAUDE.md) and injects a `paths`-scoped rule when the agent reads a
+ * matching file. pi has no read-triggered injection, so the faithful bounded
+ * mapping (see docs/superpowers/specs/2026-08-08-claude-plugins-design.md) is:
+ *
+ * - unscoped rules: content inlined verbatim into one system-prompt section
+ *   (per-file and total character caps, truncation markers) — exactly the
+ *   load-at-launch behavior;
+ * - path-scoped rules: a pointer line — "when working with files matching
+ *   these patterns, read and follow <file>" — so the prompt stays bounded on
+ *   rule-heavy repos and scoping stays honest.
+ *
+ * The launcher decides WHICH dirs load (user `~/.claude/rules` freely, repo
+ * `.claude/rules` only once the folder is trusted) and passes them via
+ * `YAGNI_CLAUDE_RULES_DIRS`, user dir first so project rules land last and
+ * win. Everything here is fail-soft and honors the compat kill switch.
+ */
+import * as fs from "node:fs";
+import { delimiter, join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+export const CLAUDE_RULES_DIRS_ENV = "YAGNI_CLAUDE_RULES_DIRS";
+const CLAUDE_COMPAT_DISABLE_ENV = "YAGNI_DISABLE_CLAUDE_COMPAT";
+export const CLAUDE_RULES_HEADER = "## Repository rules (.claude/rules)";
+function asPathList(value) {
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string" && v.trim().length > 0);
+    }
+    return [];
+}
+function walkRuleFiles(dir, depth, maxDepth, out, cap) {
+    if (depth > maxDepth || out.length >= cap)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        if (out.length >= cap)
+            return;
+        const full = join(dir, entry.name);
+        let isDir = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                const stat = fs.statSync(full);
+                isDir = stat.isDirectory();
+                isFile = stat.isFile();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (isDir) {
+            walkRuleFiles(full, depth + 1, maxDepth, out, cap);
+        }
+        else if (isFile && entry.name.endsWith(".md")) {
+            out.push(full);
+        }
+    }
+}
+/** Enumerate + parse rule files from `dirs`, in dir order. Never throws. */
+export function collectClaudeRules(dirs, opts = {}) {
+    const maxFiles = opts.maxFiles ?? 40;
+    const maxDepth = opts.maxDepth ?? 5;
+    const maxFileBytes = opts.maxFileBytes ?? 64 * 1024;
+    const rules = [];
+    try {
+        for (const dir of dirs) {
+            const files = [];
+            walkRuleFiles(dir, 0, maxDepth, files, Math.max(0, maxFiles - rules.length));
+            for (const file of files) {
+                try {
+                    if (fs.statSync(file).size > maxFileBytes)
+                        continue;
+                    const content = fs.readFileSync(file, "utf8");
+                    let paths = [];
+                    let body = content;
+                    try {
+                        const parsed = parseFrontmatter(content);
+                        paths = asPathList(parsed.frontmatter.paths);
+                        body = parsed.body;
+                    }
+                    catch {
+                        // Malformed YAML: treat as an unscoped rule with the raw content.
+                    }
+                    rules.push({ path: file, paths, body: body.trim() });
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+    catch {
+        return rules;
+    }
+    return rules;
+}
+/** The system-prompt section for `rules`, or null when there is nothing to say. */
+export function buildClaudeRulesSection(rules, opts = {}) {
+    if (rules.length === 0)
+        return null;
+    const maxInlineChars = opts.maxInlineChars ?? 8_000;
+    const maxTotalChars = opts.maxTotalChars ?? 32_000;
+    const inlined = [];
+    const overflow = [];
+    const scoped = [];
+    let spent = 0;
+    for (const r of rules) {
+        if (r.paths.length > 0) {
+            scoped.push(`- Files matching ${r.paths.map((p) => `\`${p}\``).join(", ")} → read and follow ${r.path}`);
+            continue;
+        }
+        if (!r.body)
+            continue;
+        if (spent >= maxTotalChars) {
+            overflow.push(`- ${r.path}`);
+            continue;
+        }
+        let body = r.body;
+        const room = Math.min(maxInlineChars, maxTotalChars - spent);
+        if (body.length > room)
+            body = `${body.slice(0, room)}\n[truncated — full rule: ${r.path}]`;
+        spent += body.length;
+        inlined.push(`<rule file="${r.path}">\n${body}\n</rule>`);
+    }
+    if (inlined.length === 0 && overflow.length === 0 && scoped.length === 0)
+        return null;
+    const parts = [
+        CLAUDE_RULES_HEADER,
+        "This project/user carries Claude Code rules files. They are house rules for this codebase; follow them.",
+    ];
+    if (inlined.length > 0)
+        parts.push(inlined.join("\n\n"));
+    if (scoped.length > 0) {
+        parts.push("Path-scoped rules — BEFORE creating or editing files matching a pattern below, read that rule file and follow it:\n" +
+            scoped.join("\n"));
+    }
+    if (overflow.length > 0) {
+        parts.push(`Additional rules files (read as needed):\n${overflow.join("\n")}`);
+    }
+    return parts.join("\n\n");
+}
+/** Env-driven entry: dirs from YAGNI_CLAUDE_RULES_DIRS, null when off/empty. */
+export function claudeRulesSection(env, opts = {}) {
+    try {
+        const disabled = env[CLAUDE_COMPAT_DISABLE_ENV];
+        if (disabled !== undefined && disabled !== "" && disabled !== "0")
+            return null;
+        const raw = env[CLAUDE_RULES_DIRS_ENV];
+        if (!raw)
+            return null;
+        const dirs = raw.split(delimiter).filter(Boolean);
+        if (dirs.length === 0)
+            return null;
+        return buildClaudeRulesSection(collectClaudeRules(dirs, opts), opts);
+    }
+    catch {
+        return null;
+    }
+}
+/** Append `section` to a system prompt exactly once; no-op without a section. */
+export function appendClaudeRules(systemPrompt, section) {
+    if (!section)
+        return systemPrompt;
+    if (systemPrompt.includes(CLAUDE_RULES_HEADER))
+        return systemPrompt;
+    return `${systemPrompt}\n\n${section}`;
+}
+//# sourceMappingURL=claudeRules.js.map