mindweave 0.0.1 → 2.1.2

package/dist/governor/scope.js

@@ -0,0 +1,91 @@
+/**
+ * scope.ts — which glob-scoped rules this session has activated.
+ *
+ * A rule may carry `globs`, meaning "apply this once the work heads that way". The
+ * question is when that gets decided.
+ *
+ * It used to be decided AT RENDER: every model call rebuilt the set of every path the
+ * session had ever touched, relativized each one, and matched every scoped rule's globs
+ * against all of them. That is O(paths x rules) on every step of every turn, against a
+ * path set that only ever grew — so the cost of a rule the user set once climbed for as
+ * long as the session lasted.
+ *
+ * It is now decided AT ACCESS, which is the only shape that stays correct
+ * (`getManagedAndUserConditionalRules(targetPath, processedPaths)` resolves conditional
+ * rules for the ONE file being touched, with a processed-set for dedup). When a path is
+ * read or written we test it once, against only the rules that have not already fired,
+ * and remember the NAMES that matched. Rendering is then a set lookup per rule.
+ *
+ * Remembering the match rather than the path is what makes this durable. A compaction
+ * clears the read ledger because the contents it described are gone from the screen —
+ * but "this session has worked in src/api" is not a fact about the screen, and a name
+ * already in `matched` is never removed. The earlier fix for that bug carried a second
+ * copy of every path forward to re-derive the same answer; this needs no carry at all.
+ */
+import { relative } from "node:path";
+import { anyPathMatches } from "./glob.js";
+/**
+ * How many project-relative paths are kept for RE-EVALUATION.
+ *
+ * Only used when the rule set itself changes (the user edits a rule file, or the model
+ * writes a new one) and rules that never ran must be judged against work already done.
+ * Matching for rules that have already fired does not consult this at all — those names
+ * are sticky — so overflowing the cap can only mean a NEWLY ADDED scoped rule misses
+ * paths touched long ago. It still fires on the next matching path.
+ *
+ * Bounded because this is the one structure here that would otherwise grow with session
+ * length, which is exactly the property being removed.
+ */
+const MAX_REMEMBERED_PATHS = 2_000;
+export function createRuleScope() {
+    return { matched: new Set(), paths: new Set() };
+}
+/** Project-relative POSIX form, computed ONCE per path instead of once per render. */
+function relPosix(root, absPath) {
+    return relative(root, absPath).split("\\").join("/");
+}
+/**
+ * Record that the session touched `absPath`, and fire any scoped rule it matches.
+ *
+ * Cheap by construction: a rule already in `matched` is skipped, so the work per path
+ * shrinks as rules fire, and a project with no scoped rules does no matching at all.
+ */
+export function noteScopePath(scope, rules, root, absPath) {
+    const rel = relPosix(root, absPath);
+    if (scope.paths.size < MAX_REMEMBERED_PATHS)
+        scope.paths.add(rel);
+    const one = [rel];
+    for (const rule of rules) {
+        if (!rule.globs || rule.globs.length === 0)
+            continue; // always-on: nothing to decide
+        if (scope.matched.has(rule.name))
+            continue; // already fired — never re-tested
+        if (anyPathMatches(one, rule.globs))
+            scope.matched.add(rule.name);
+    }
+}
+/**
+ * Re-judge every remembered path against the CURRENT rule set.
+ *
+ * Called when the rules themselves change — a reload from disk, or the model writing a
+ * new one — because a rule that did not exist when a path was touched never got its
+ * chance. This is the only O(paths x rules) pass left, and it runs on rule changes
+ * rather than on every model call.
+ *
+ * Additive: it never un-matches. A rule deleted from disk simply stops being rendered,
+ * because rendering filters by the live rule list, not by this set.
+ */
+export function rescope(scope, rules) {
+    const paths = [...scope.paths];
+    if (paths.length === 0)
+        return;
+    for (const rule of rules) {
+        if (!rule.globs || rule.globs.length === 0)
+            continue;
+        if (scope.matched.has(rule.name))
+            continue;
+        if (anyPathMatches(paths, rule.globs))
+            scope.matched.add(rule.name);
+    }
+}
+//# sourceMappingURL=scope.js.map

package/dist/governor/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/governor/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C;;;;;;;;;;;GAWG;AACH,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAYnC,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;AAClD,CAAC;AAED,sFAAsF;AACtF,SAAS,QAAQ,CAAC,IAAY,EAAE,OAAe;IAC7C,OAAO,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAgB,EAChB,KAAsB,EACtB,IAAY,EACZ,OAAe;IAEf,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,oBAAoB;QAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClE,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS,CAAC,+BAA+B;QACrF,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,kCAAkC;QAC9E,IAAI,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,OAAO,CAAC,KAAgB,EAAE,KAAsB;IAC9D,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACrD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC3C,IAAI,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}

package/dist/governor/skills.js

@@ -0,0 +1,176 @@
+/**
+ * skills.ts — reusable procedures the model can run on demand.
+ *
+ * A skill is a named playbook: `<project-state>/skills/<name>/SKILL.md`, with a
+ * `name` / `description` / `when_to_use` header and a markdown body of steps.
+ * The key design is **progressive disclosure**: only
+ * the lightweight catalog (name + description + when-to-use) ever sits in the
+ * prompt, so a project can have many skills at near-zero token cost; the full
+ * body is read only when the skill is actually invoked — by the user typing
+ * `/name`, or by the model calling the `use_skill` tool when a description fits.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+import { parseGlobs } from "./rules.js";
+import { anyPathMatches } from "./glob.js";
+const SKILL_FILE = "SKILL.md";
+/** Discover the project's skills, reading only each one's frontmatter (catalog). */
+export async function loadSkillCatalog(stateDir) {
+    const dir = join(stateDir, "skills");
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return []; // no skills dir yet
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue; // skills are directories: <name>/SKILL.md
+        const skillDir = join(dir, entry.name);
+        try {
+            const raw = await fs.readFile(join(skillDir, SKILL_FILE), "utf8");
+            const { data } = parseFrontmatter(raw);
+            const globs = parseGlobs(data.globs || data.paths);
+            skills.push({
+                name: data.name || entry.name,
+                description: data.description || "",
+                whenToUse: data.when_to_use || data.whenToUse || "",
+                dir: skillDir,
+                ...(data["argument-hint"] ? { argumentHint: data["argument-hint"] } : {}),
+                ...(globs.length > 0 ? { globs } : {}),
+            });
+        }
+        catch {
+            // No SKILL.md (or unreadable) — not a skill directory; skip it.
+        }
+    }
+    skills.sort((a, b) => a.name.localeCompare(b.name));
+    return skills;
+}
+/** Load a skill's full body (the steps), read fresh on invocation. Null if gone. */
+export async function loadSkillBody(skill) {
+    try {
+        const raw = await fs.readFile(join(skill.dir, SKILL_FILE), "utf8");
+        return parseFrontmatter(raw).body;
+    }
+    catch {
+        return null;
+    }
+}
+/** Find a skill by its invocation name (case-insensitive). */
+export function findSkill(skills, name) {
+    const wanted = name.trim().toLowerCase().replace(/^\//, "");
+    return skills.find((s) => s.name.toLowerCase() === wanted);
+}
+/**
+ * The skills visible in the catalog this turn: every always-listed skill plus any
+ * glob-scoped skill whose patterns match the working set. (Scoped-out skills are
+ * still invokable by name — this only controls catalog noise.)
+ */
+export function activeSkills(skills, workingSet = []) {
+    return skills.filter((s) => !s.globs || s.globs.length === 0 || anyPathMatches(workingSet, s.globs));
+}
+/**
+ * Render the catalog for the system prompt: one line per visible skill with its
+ * name (+ argument hint), description, and when-to-use. "" when none are visible.
+ * Content only — the engine frames it.
+ */
+/**
+ * Caps on the always-loaded skill catalog.
+ *
+ * This block renders into the CACHED system prefix on every session and only ever
+ * grows: every create_skill adds a line, permanently, and nothing trims it.
+ *
+ * The cap is on LENGTH PER ENTRY rather than on the number of entries, and that is a
+ * deliberate departure from "keep the most recent N". A skill is only reachable by
+ * NAME — use_skill takes one, and there is no tool that lists them — so an entry
+ * dropped from this catalog is a skill the model can no longer invoke at all. Trading
+ * a capability away to save tokens is the wrong trade. Clipping a rambling description
+ * costs nothing by comparison: the name still appears, the skill stays callable, and
+ * its full text is loaded on use anyway.
+ *
+ * The entry cap below is a backstop against the absurd case, set far above any real
+ * project, and it says so when it bites.
+ */
+const MAX_SKILL_LINE_CHARS = 200;
+const MAX_SKILL_ENTRIES = 100;
+/** Clip to `max` on a word boundary where possible, with an ellipsis. */
+function clip(text, max) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max);
+    const space = cut.lastIndexOf(" ");
+    return `${(space > max * 0.6 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+export function renderSkillCatalog(skills, workingSet) {
+    // OMITTING the working set means "list everything", not "list nothing". It used to
+    // default to `[]`, which quietly filtered every glob-scoped skill out — so a caller
+    // that had no working set to give showed an incomplete catalog, and a skill reachable
+    // only by name became uninvokable.
+    //
+    // The engine relies on this: the catalog renders into the CACHED system prompt, so it
+    // must be byte-identical all session. Filtering it by the working set made a
+    // glob-scoped skill appear the moment a matching file was read, changing the system
+    // prompt and invalidating the tools, system and message caches at once.
+    const visible = workingSet === undefined ? skills : activeSkills(skills, workingSet);
+    if (visible.length === 0)
+        return "";
+    const shown = visible.slice(0, MAX_SKILL_ENTRIES);
+    const lines = shown.map((s) => {
+        const hint = s.argumentHint ? ` ${s.argumentHint}` : "";
+        const desc = s.description ? `: ${s.description}` : "";
+        const when = s.whenToUse ? ` — use when: ${s.whenToUse}` : "";
+        // The name and its argument hint are never clipped — they are what makes the
+        // skill callable. Only the prose after them is.
+        return `- ${s.name}${hint}${clip(`${desc}${when}`, MAX_SKILL_LINE_CHARS)}`;
+    });
+    if (visible.length > shown.length) {
+        lines.push(`> WARNING: ${visible.length - shown.length} more skill(s) exist but are not listed here. ` +
+            `Keep the catalog under ${MAX_SKILL_ENTRIES} skills, or scope them with \`globs\` so they appear only when relevant.`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Substitute a skill's argument string into its body: `$ARGUMENTS` → the whole
+ * string, `$1`/`$2`/… → positional tokens. If the body has no such placeholder
+ * but arguments were given, they're appended as additional context — so both
+ * parameterized and plain skills handle args sensibly.
+ */
+export function substituteSkillArgs(body, argString) {
+    const args = argString.trim();
+    const positional = args.length > 0 ? args.split(/\s+/) : [];
+    const hasPlaceholder = /\$ARGUMENTS\b/.test(body) || POSITIONAL.test(body);
+    // ONE pass over the original body. Two chained replaces meant a `$1` inside the
+    // user's own argument string was then treated as a placeholder and substituted again.
+    const out = body.replace(SUBSTITUTION, (match, digit) => {
+        if (digit === undefined)
+            return args;
+        // Leave the placeholder visible when nothing was supplied for it. Blanking it makes
+        // a skill that expected an argument read as though it never wanted one.
+        return positional[Number(digit) - 1] ?? match;
+    });
+    if (!hasPlaceholder && args)
+        return `${out}\n\nAdditional context from the user: ${args}`;
+    return out;
+}
+/**
+ * A positional placeholder: `$1`–`$9`, and NOT the start of a longer number.
+ *
+ * A skill body is a markdown playbook, so it very reasonably contains shell
+ * (`awk '{print $1}'`) and money (`$100`). The old pattern was `/\$(\d+)/`, which
+ * matched `$100` as positional argument one hundred, found nothing, and substituted
+ * the empty string — so `Budget is $100` silently became `Budget is `, and with no
+ * arguments at all EVERY `$n` in the body was deleted. The instructions the model was
+ * told to follow were quietly not the instructions on disk. Single digit matches the
+ * shell convention the syntax is borrowed from.
+ */
+const POSITIONAL_SRC = String.raw `\$([1-9])(?!\d)`;
+/** Detects one, for deciding whether the skill declared any placeholder at all. */
+const POSITIONAL = new RegExp(POSITIONAL_SRC);
+/** Replaces every placeholder in one pass. Shares POSITIONAL's source so the two
+ *  cannot drift into disagreeing about what counts as a placeholder. */
+const SUBSTITUTION = new RegExp(String.raw `\$ARGUMENTS\b|` + POSITIONAL_SRC, "g");
+//# sourceMappingURL=skills.js.map

package/dist/governor/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/governor/skills.ts"],"names":[],"mappings":"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"}

package/dist/governor/types.js

@@ -0,0 +1,16 @@
+/**
+ * types.ts — the governor's data contracts.
+ *
+ * The "governor" is the per-project control layer: the user's standing **rules**
+ * (always followed), reusable **skills** (procedures loaded on demand), and the
+ * **forbidden** list (paths/actions the tools must never touch). All of it is
+ * scoped to one project and stored under that project's state directory — the
+ * same `~/.mindweave/projects/<project>/` folder sessions already use.
+ *
+ * Everything here is plain JSON-friendly data on purpose. The forbidden config
+ * in particular rides on `ToolContext` (which deliberately holds only plain
+ * data), and the path/command checks are pure functions over it — exactly like
+ * the existing `guard.ts` deny-list, just user-defined instead of built-in.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/governor/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/governor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/governor/write.js

@@ -0,0 +1,182 @@
+/**
+ * write.ts — persist a new rule or forbidden path for a project.
+ *
+ * The governor owns the on-disk formats, so the act of "make this a rule" or
+ * "forbid this" lives here; the tools in src/tools are thin wrappers that call
+ * these and then mirror the change into the live session so it takes effect
+ * immediately. Files land under the project's state dir (the same per-project
+ * folder sessions use), so they persist for every future launch in this project.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { projectDir } from "../memory/store.js";
+import { parseForbidden, parseForbiddenCommands } from "./forbidden.js";
+/** A filesystem-safe slug from a human name/phrase (kebab, ≤50 chars). */
+export function slugify(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 50) || "rule");
+}
+/**
+ * Flatten a value to a single line before it goes into frontmatter.
+ *
+ * These headers are a line-oriented `key: value` format, and every value here is
+ * model-supplied text. A newline inside one starts what the loader reads as a NEW
+ * key, so a rule whose name ended in "\nglobs: **" would come back scoped to
+ * everything, and a skill's description could rewrite its own `when_to_use`. The
+ * value is written, then read back and believed, so it has to stay one field.
+ */
+function oneLine(value) {
+    return value.replace(/[\r\n]+/g, " ").trim();
+}
+/**
+ * Build a frontmatter header, flattening EVERY value on the way in.
+ *
+ * `oneLine` used to be applied field by field at each call site, and one field was
+ * missed: `globs` went in raw as `globs: ${globs.join(", ")}`. That is the field
+ * deciding when a rule fires, and a newline inside it writes whatever the model
+ * likes into the header — a second key, or a `---` that closes it early and turns
+ * the rest of the rule into body.
+ *
+ * Written as one place that flattens everything, so the next field added cannot
+ * repeat the mistake. Empty values are dropped rather than emitted blank.
+ */
+function frontmatter(fields) {
+    const lines = ["---"];
+    for (const [key, raw] of Object.entries(fields)) {
+        const value = oneLine(raw ?? "");
+        if (value)
+            lines.push(`${key}: ${value}`);
+    }
+    lines.push("---", "");
+    return lines.join("\n");
+}
+/** A short name derived from a rule's text (first few words) when none is given. */
+export function deriveRuleName(body) {
+    return slugify(body.split(/\s+/).slice(0, 6).join(" "));
+}
+/**
+ * Save a standing rule as `rules/<slug>.md` in the project's state dir and return
+ * it. Overwrites a rule file of the same slug (re-stating a rule updates it). Pass
+ * `globs` to SCOPE the rule (fires only when the work touches matching files);
+ * omit them for an always-on rule (the default).
+ */
+export async function writeRule(cwd, name, body, description = "", globs = []) {
+    const dir = join(projectDir(cwd), "rules");
+    await fs.mkdir(dir, { recursive: true });
+    const file = join(dir, `${slugify(name)}.md`);
+    const header = frontmatter({
+        name,
+        description,
+        globs: globs.join(", "),
+    });
+    await fs.writeFile(file, `${header}${body}\n`, "utf8");
+    return { name: oneLine(name), description: oneLine(description), body, ...(globs.length > 0 ? { globs } : {}) };
+}
+/**
+ * Create (or overwrite) a skill at `skills/<slug>/SKILL.md` in the project's
+ * state dir and return its catalog metadata. The directory name is the skill's
+ * invocation name; the frontmatter carries description / when-to-use / hint /
+ * scope so it loads back identically.
+ */
+export async function writeSkill(cwd, skill) {
+    const name = slugify(skill.name);
+    const dir = join(projectDir(cwd), "skills", name);
+    await fs.mkdir(dir, { recursive: true });
+    const description = oneLine(skill.description);
+    const whenToUse = oneLine(skill.whenToUse ?? "");
+    const argumentHint = oneLine(skill.argumentHint ?? "");
+    const header = frontmatter({
+        name, // already the slug: no newline can survive slugify
+        description,
+        when_to_use: whenToUse,
+        "argument-hint": argumentHint,
+        globs: skill.globs?.join(", ") ?? "",
+    });
+    await fs.writeFile(join(dir, "SKILL.md"), `${header}${skill.body}\n`, "utf8");
+    return {
+        name,
+        description,
+        whenToUse,
+        dir,
+        ...(argumentHint ? { argumentHint } : {}),
+        ...(skill.globs && skill.globs.length > 0 ? { globs: skill.globs } : {}),
+    };
+}
+/**
+ * Append a pattern to `forbidden.md` in the project's state dir. Idempotent —
+ * returns `{ added: false }` if it was already forbidden. The pattern is
+ * normalized the same way the loader normalizes (drop leading `./`, trailing `/`).
+ */
+export async function appendForbidden(cwd, pattern) {
+    const normalized = pattern.trim().replace(/^\.?\//, "").replace(/\/+$/, "");
+    if (!normalized)
+        return { added: false, pattern: normalized };
+    const base = projectDir(cwd);
+    const file = join(base, "forbidden.md");
+    let text = "";
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch {
+        /* no forbidden.md yet */
+    }
+    if (parseForbidden(text).includes(normalized))
+        return { added: false, pattern: normalized };
+    await fs.mkdir(base, { recursive: true });
+    const separator = text && !text.endsWith("\n") ? "\n" : "";
+    await fs.writeFile(file, `${text}${separator}${normalized}\n`, "utf8");
+    return { added: true, pattern: normalized };
+}
+/**
+ * Append an MCP tool name to `forbidden-mcp-tools.md`. Sibling of
+ * appendForbiddenCommand; tool names are identifiers, kept verbatim.
+ */
+export async function appendForbiddenMcpTool(cwd, name) {
+    const normalized = name.trim();
+    if (!normalized)
+        return { added: false, pattern: normalized };
+    const base = projectDir(cwd);
+    const file = join(base, "forbidden-mcp-tools.md");
+    let text = "";
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch {
+        /* no forbidden-mcp-tools.md yet */
+    }
+    if (parseForbiddenCommands(text).includes(normalized))
+        return { added: false, pattern: normalized };
+    await fs.mkdir(base, { recursive: true });
+    const separator = text && !text.endsWith("\n") ? "\n" : "";
+    await fs.writeFile(file, `${text}${separator}${normalized}\n`, "utf8");
+    return { added: true, pattern: normalized };
+}
+/**
+ * Append a command pattern to `forbidden-commands.md` in the project's state dir.
+ * Idempotent — `{ added: false }` if it was already forbidden. Sibling of
+ * appendForbidden; command patterns are kept verbatim (trimmed), not path-normalized.
+ */
+export async function appendForbiddenCommand(cwd, pattern) {
+    const normalized = pattern.trim();
+    if (!normalized)
+        return { added: false, pattern: normalized };
+    const base = projectDir(cwd);
+    const file = join(base, "forbidden-commands.md");
+    let text = "";
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch {
+        /* no forbidden-commands.md yet */
+    }
+    if (parseForbiddenCommands(text).includes(normalized))
+        return { added: false, pattern: normalized };
+    await fs.mkdir(base, { recursive: true });
+    const separator = text && !text.endsWith("\n") ? "\n" : "";
+    await fs.writeFile(file, `${text}${separator}${normalized}\n`, "utf8");
+    return { added: true, pattern: normalized };
+}
+//# sourceMappingURL=write.js.map

package/dist/governor/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/governor/write.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Mindweave — entry point.
+ *
+ * This file does one thing: start the terminal UI. It deliberately stays tiny.
+ * All real logic lives in its own lane (cli / dynamo / tools / memory / alternator)
+ * so the project stays easy to understand as it grows.
+ *
+ * The shebang above + the `bin` entry in package.json make this the `mindweave`
+ * command: install once (`npm link` / `npm i -g`), then `cd` into any project and
+ * type `mindweave`. The session roots at the current directory (process.cwd()), so it
+ * just works wherever you run it.
+ */
+import { render } from "ink";
+import { createElement } from "react";
+import { App } from "./cli/App.js";
+import { loadConfig } from "./cli/bootstrap.js";
+import { sweepTempInBackground } from "./tools/tempSweep.js";
+import { parseStartupArgs, hasInteractiveInput, NO_TERMINAL_MESSAGE } from "./cli/startupArgs.js";
+import { enterAltScreen } from "./cli/altScreen.js";
+import { TERMINAL_RESTORE } from "./cli/terminalRestore.js";
+import { instrumentStdout, flush as flushPerf, perf, perfEnabled } from "./cli/perfLog.js";
+import { MAX_FPS } from "./cli/frameRate.js";
+import { framebufferStdout } from "./cli/framebuffer/writer.js";
+// --help / --version answer and exit, BEFORE anything reads config, sweeps a
+// directory, or starts the UI. They used to fall through to the interactive app,
+// which then hung forever with no TTY to render into — the one thing a packaging
+// tool or a script does with a new CLI.
+const startup = parseStartupArgs(process.argv.slice(2));
+if (startup.kind === "print") {
+    process.stdout.write(startup.text + "\n");
+    process.exit(0);
+}
+// Nothing below this point can run without a terminal to read from, and the failure
+// without one is a stack trace through React internals on a process that exits 0.
+// --help, --version and --reset-terminal are answered above, so they still work
+// wherever they are called from.
+if (!hasInteractiveInput(process.stdin)) {
+    process.stderr.write(NO_TERMINAL_MESSAGE);
+    process.exit(1);
+}
+if (startup.kind === "reset") {
+    // Repairing a terminal a dead run left in mouse-reporting mode. Nothing else may run
+    // first: this is typed when the terminal is already misbehaving, and loading config or
+    // sweeping temp would only add ways for it to fail before it writes the one thing it
+    // came to write. Escapes go out only to a real terminal, since into a pipe they would
+    // be corruption rather than repair.
+    if (process.stdout.isTTY) {
+        process.stdout.write(TERMINAL_RESTORE);
+        process.stdout.write("terminal restored\n");
+    }
+    else {
+        process.stdout.write("not a terminal, nothing to restore\n");
+    }
+    process.exit(0);
+}
+// Load config (global ~/.mindweave/.env + project .env) so provider API keys are
+// available no matter which project we're launched in.
+loadConfig();
+// Clear out the temp files and directories earlier runs left behind: screenshots past
+// their retention window, and the scratch (cwd hand-off files, command wrappers, test
+// fixtures) that every call site removes on its way out and nothing removes when a run
+// ends badly. Startup rather than shutdown precisely because that catches what a crash
+// left behind, and detached so a slow or unreadable temp directory cannot delay the UI.
+sweepTempInBackground();
+// Times every frame the renderer writes to the real terminal. No-op unless
+// MINDWEAVE_PERF names a file — see cli/perfLog.ts for why this cannot be measured
+// from a test probe.
+instrumentStdout(process.stdout);
+process.on("exit", flushPerf);
+enterAltScreen();
+// Ink renders into a FRAMEBUFFER rather than straight to the terminal: each frame is
+// parsed into a cell grid, diffed against what is already on screen, and only the
+// cells that actually differ are written. Measured on a transcript-shaped screen,
+// that is ~13x fewer bytes per frame (2,345 -> 178). See `cli/framebuffer/`.
+//
+// `incrementalRendering` is deliberately NOT enabled alongside it, and this is load
+// bearing rather than a preference: that mode makes Ink emit only the LINES it thinks
+// changed, interleaved with its own cursor movements, instead of a complete frame.
+// The framebuffer's parser expects a whole frame — a partial one would be read as a
+// full screen and everything it omitted would be blanked. One diff or the other, and
+// ours is per-cell where Ink's is per-line.
+// The frame-rate cap is what sets typing latency — see `cli/frameRate.ts` for the
+// measurements and for why it is a timer rather than a cost.
+render(createElement(App), {
+    maxFps: MAX_FPS,
+    stdout: framebufferStdout(process.stdout, perfEnabled() ? (s) => perf(`frame in=${s.inBytes} out=${s.outBytes}`) : undefined),
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}