@anhvupt/tito 0.3.4 → 0.4.0

package/README.md

@@ -63,6 +63,8 @@ mode decides whether it may change anything:
 | DevOps engineer | Plan | Change infrastructure, with approval |
 | Tech docs writer | — | Update technical documentation |
 | User docs writer | — | Update user documentation |
+| Cleanup specialist | — | Remove leftover files |
+| Local startup | — | Start missing local processes; ask before pending migrations |
 
 Several read-only specialists may work together. Coding sub-agents follow the
 profile cap: `client-careful` 3, `solo-balanced` 6, and `solo-fast` 12. Each
@@ -93,6 +95,7 @@ core and exposed through both chat and the CLI:
 - `/tito` is the open-ended coordinator.
 - `/tito-inspect` and `tito inspect` produce the same repository report.
 - `/tito-apply` and `tito apply --dry-run` produce the same adoption plan.
+- `/tito-local-startup` brings this repo's local stack up.
 
 Tito-coordinated chat responses begin with `Hola, Tito here!` so you can see
 that the coordinator is active. The greeting is not added to CLI or
@@ -117,13 +120,16 @@ the existing guidance in place. It refuses to overwrite a Tito file that is
 already there. In a terminal, `tito init --confirm` then asks for the git base
 (`dev`, `develop`, `main`, or `master`), screen language (`vi` or `en`),
 tenancy (`single` or `multi`), optional comma-separated surface ids, and
-whether to auto-create a pull request after implementation. That question is
+whether to auto-create a pull request after implementation, and whether to
+auto-merge a slice pull request after checks pass. The auto-create question is
 `Auto-create a pull request after implementation? [Y/n]`. Enter, `y`, or `yes`
-stores yes. `n` or `no` stores no. Empty surface ids omit `product.surfaces`.
+stores yes. `n` or `no` stores no. The auto-merge question is
+`Auto-merge a slice pull request after checks pass? [y/N]`. Enter, `n`, or
+`no` stores no. `y` or `yes` stores yes. Empty surface ids omit `product.surfaces`.
 A non-interactive init with `--profile` does not ask; it stores
-`git.autoPullRequest: true` and does not invent the other product fields.
+`git.autoPullRequest: true` and `git.autoMerge: false` and does not invent the other product fields.
 Preview without `--confirm` does not ask and does not write. An existing
-`tito.yaml` is left unchanged. Storing the answer does not open a pull request.
+`tito.yaml` is left unchanged. Storing those answers does not open or merge a pull request.
 Errors on a terminal are red, and `NO_COLOR` turns that off.
 Open a new Cursor chat, then start with `/tito`.
 
@@ -137,7 +143,9 @@ npx tito upgrade --confirm
 `--confirm` installs the latest `@anhvupt/tito` and replaces Tito-owned
 agents, skills, those Tito-owned scoped rules, and the Tito section of
 `AGENTS.md`, which includes the stop that shows the test cases before any source edit. Consumer rules, consumer
-agents, and other project skills stay untouched. In a terminal, `tito upgrade --confirm` asks only for settings missing from `tito.yaml`: git base, screen language, tenancy, surfaces, and auto-create pull request. Enter on that last question still stores yes. It does not change a value that is already present, and it does not change the profile. A non-interactive upgrade does not ask. If `tito.yaml` is missing, it skips those questions.
+agents, and other project skills stay untouched. In a terminal, `tito upgrade --confirm` asks only for settings missing from `tito.yaml`: git base, screen language, tenancy, surfaces, auto-create pull request, and auto-merge. Enter on the auto-create question still stores yes. Enter on the auto-merge question stores no. It does not change a value that is already present, and it does not change the profile. A non-interactive upgrade does not ask. If `tito.yaml` is missing, it skips those questions.
+
+`tito init` and `tito upgrade` install Tito's shell and MCP guard hooks in `.cursor/hooks.json`. A missing file is created with both Tito entries. A valid file gets each missing `tito hook` entry appended; other keys stay. An existing Tito entry is left unchanged. Cloud agents do not run beforeMCPExecution. Remove a guard by deleting Tito's entry, or the file if it only has those entries. Invalid JSON is a conflict: `init --confirm` refuses and writes nothing.
 
 Tito is installed in each project. It is not a required global command.
 An opt-in local admin index (`tito admin add|list|remove|refresh`) can register
@@ -185,6 +193,8 @@ node dist/cli.js admin refresh
 node dist/cli.js admin remove --root /path/to/repo
 node dist/cli.js admin retro --week 2026-W40
 node dist/cli.js guard test-first --base main --test test/example.test.mjs
+node dist/cli.js hook before-shell
+node dist/cli.js hook before-mcp
 node dist/cli.js worktree tidy
 node dist/cli.js worktree tidy --confirm
 ```
@@ -215,6 +225,14 @@ merge duration say unavailable until GitHub data is added.
 only the repeated `--test` files. Later commits may not change `test/**`,
 `*.test.*`, or `*.spec.*` files. A failure names the file and the commit.
 
+`hook before-shell` is machine-only (no chat skill). It reads Cursor
+beforeShellExecution JSON on stdin and writes `{permission: allow|ask|deny}` to
+stdout, then exits 0. Invalid input fails open with allow. It asks before
+base-branch pushes and merges, force-pushes, `gh pr merge` (unless
+`git.autoMerge` is true), and `npm publish`. It denies `gh pr review --approve`.
+`hook before-mcp` is the same contract for beforeMCPExecution; cloud agents do
+not run that hook.
+
 ## How work moves
 
 The normal careful path is:
@@ -241,10 +259,13 @@ profile: client-careful
 git:
   defaultBase: develop
   autoPullRequest: true
+  autoMerge: false
 ```
 
 `git.autoPullRequest` is an optional boolean. Missing it is valid. A non-boolean value is rejected. Storing it does not open a pull request.
 
+`git.autoMerge` is an optional boolean. Missing it is valid and means off. A non-boolean value is rejected. `true` is the user's standing merge call. Storing it does not merge a pull request.
+
 `product.screenLanguage` is optional and accepts only `vi` or `en`. A missing product block is valid. A missing `screenLanguage` is valid. Unknown product fields are rejected. `product.tenancy` is optional (`single` or `multi`). `product.surfaces` is an optional list of `{ id }` entries. Missing `tenancy` and missing `surfaces` stay valid.
 
 ```yaml
@@ -255,13 +276,14 @@ product:
     - id: admin
 ```
 
-Optional `models` maps pipeline roles to Cursor model slugs. Each Tito specialist card compiles to one role: explorer, planner, implementer, reviewer, or finisher. Missing keys fall back to the defaults below. Empty or unknown keys are rejected. `tito init` writes the full block; `tito upgrade` adds missing roles without changing values you already set, and rewrites Tito-owned specialist cards so pinned slugs stay current.
+Optional `models` maps pipeline roles to Cursor model slugs. Each Tito specialist card compiles to one role: explorer, planner, advisor, implementer, reviewer, or finisher. Missing keys fall back to the defaults below. Empty or unknown keys are rejected. `tito init` writes the full block; `tito upgrade` adds missing roles without changing values you already set, and rewrites Tito-owned specialist cards so pinned slugs stay current.
 
 ```yaml
 models:
   explorer: cursor-grok-4.6-medium-fast
-  planner: claude-opus-5-5-medium
-  implementer: grok-4.7-high
+  planner: grok-4.7-high
+  advisor: claude-opus-5-5-medium
+  implementer: cursor-grok-4.6-high
   reviewer: grok-4.7-high
   finisher: composer-2.5
 ```
@@ -274,7 +296,11 @@ models:
 - When `screenLanguage` is missing and the screen language is unclear, Tito asks once. One obvious reading continues without a question.
 - Globalized apps store timestamps in UTC and show them in the user's timezone. There is no switch to turn that off.
 
-A commit subject is `<type>: <sentence>`. The type is the same token as the branch type: `feat`, `fix`, `hot-fix`, `chores`, `refactor`, or `debug`. Examples: `feat: add commit message rule`, `fix: reject a duplicate surface id`, `chores: record the commit prefix rule`, and `hot-fix: stop a bad release build`. The words after the colon are one finished sentence of at most 70 words. The type is not counted in those 70 words. The body is a separate description. When you review a plan, Tito saves that plan and your edit as separate files under `.tito/feedback/<slug>/`. `review.md` starts with front matter `outcome: accepted | edited | expanded`. Tito indexes only the plan name. The plan body stays in Cursor's plan file. After an approved slice is coded, every review fix goes into one plan named `review/<slug>` on the same branch. Tito asks before opening a pull request only after that plan is coded, or when you accept the code with no changes. The pull request description has four parts within 2 to 50 lines: a one-line problem, what changed, review fixes, and checks for lint, code quality, conventions, tests, build, and docs. When the user comments on an open pull request, Tito updates that pull request's description in the same turn. Review fixes lists every comment, including the earlier ones. A thread reply does not replace that update. Init creates `.github/pull_request_template.md` from Tito's template when it is missing. Upgrade replaces that file with Tito's template. Tito does not approve a pull request. Tito merges only when you call for the merge and the pull request already has an approval. Do not merge a slice branch into `main`, `master`, `dev`, or `develop`, on the machine or on the remote, unless the user calls for that merge and the pull request already has an approval. Finishing a slice leaves the branch as it is. After a pull request is merged, Tito asks before the next slice. Tito switches back to the base branch only when you say so clearly. Tito pushes directly to the base branch only when you clearly instruct that push.
+A commit subject is `<type>: <sentence>`. The type is the same token as the branch type: `feat`, `fix`, `hot-fix`, `chores`, `refactor`, or `debug`. Examples: `feat: add commit message rule`, `fix: reject a duplicate surface id`, `chores: record the commit prefix rule`, and `hot-fix: stop a bad release build`. The words after the colon are one finished sentence of at most 70 words. The type is not counted in those 70 words. The body is a separate description. When you review a plan, Tito saves that plan and your edit as separate files under `.tito/feedback/<slug>/`. `review.md` starts with front matter `outcome: accepted | edited | expanded`. Tito indexes only the plan name. The plan body stays in Cursor's plan file. After an approved slice is coded, every review fix goes into one plan named `review/<slug>` on the same branch. Tito asks before opening a pull request only after that plan is coded, or when you accept the code with no changes. The pull request description has four parts within 2 to 50 lines: a one-line problem, what changed, review fixes, and checks for lint, code quality, conventions, tests, build, and docs. When the user comments on an open pull request, Tito updates that pull request's description in the same turn. Review fixes lists every comment, including the earlier ones. A thread reply does not replace that update. Init creates `.github/pull_request_template.md` from Tito's template when it is missing. Upgrade replaces that file with Tito's template. Tito never approves a pull request. Tito merges a slice pull request into a base branch only via `gh pr merge --squash`, on your merge call or `git.autoMerge: true`, after the finisher re-runs the test-first guard, tests, build, and docs gate. An approval is not required. When auto-merge is on, Tito still waits when the profile is `client-careful` or the slice touches mandatory escalation (authentication, payments, secrets, migrations, production data, infrastructure). Finishing a slice leaves the branch as it is. After a pull request is merged, Tito asks before the next slice. Tito switches back to the base branch only when you say so clearly. Tito pushes directly to the base branch only when you clearly instruct that push.
+
+## Cost
+
+Real token usage is measured only by the opt-in `npm run eval:usage` script; file-size budgets in `npm test` stay estimates.
 
 ## Development
 
@@ -289,6 +315,8 @@ npm run build
 npm test
 ```
 
+`npm run eval:usage` spends Cursor tokens. It needs `CURSOR_API_KEY` and Node.js 22.13 or newer. It is not part of `npm test`. Pass `--record` to write `evals/usage-baseline.json`.
+
 ## Acknowledgement
 
 Tito is respectfully inspired by Francesc “Tito” Vilanova: quiet leadership,

package/dist/cli.js

@@ -15,6 +15,7 @@ import { RetroError, buildRetro, formatRetro, retroJson, saveRetro, } from "./co
 import { formatInitError } from "./core/terminal.js";
 import { TestFirstError, formatTestFirstReport, guardTestFirst, } from "./core/test-first.js";
 import { WorktreeError, formatTidyReport, tidyWorktrees } from "./core/worktree.js";
+import { decideMcp, decideShell } from "./core/hooks.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const help = `Tito — quiet orchestration for solo builders
 
@@ -30,6 +31,8 @@ Usage:
   tito admin refresh [--admin-root <path>]
   tito admin retro [--week <YYYY-Www>] [--timezone <IANA>] [--json] [--admin-root <path>]
   tito guard test-first --base <ref> --test <file> [--root <path>]
+  tito hook before-shell
+  tito hook before-mcp
   tito worktree tidy [--confirm] [--root <path>]
 
 Options:
@@ -43,6 +46,7 @@ Commands:
   upgrade        Install the latest Tito and replace Tito-owned files only.
   admin          Opt-in local repo index: add, list, remove, refresh, retro.
   guard          Check that commit 1 changes only the listed test files.
+  hook           Machine-only shell and MCP guards. Fail-open. No chat entry.
   worktree       Report stale worktrees. Confirm before removing merged clean ones.
 `;
 function fail(message) {
@@ -183,7 +187,7 @@ async function runInit(args) {
         const creatingYaml = report.titoYaml.status === "absent";
         let settings;
         if (creatingYaml && !input.isTTY)
-            settings = { autoPullRequest: true };
+            settings = { autoPullRequest: true, autoMerge: false };
         let plan = planInitialization(report, profile, settings);
         if (!confirm) {
             process.stdout.write(formatInitialization(plan));
@@ -488,6 +492,93 @@ function runGuard(args) {
         throw error;
     }
 }
+function currentBranch(cwd) {
+    const result = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (result.status !== 0)
+        return undefined;
+    const name = (result.stdout ?? "").trim();
+    return name.length > 0 ? name : undefined;
+}
+function autoMergeFromCwd(cwd) {
+    try {
+        return parseConfig(readFileSync(join(cwd, "tito.yaml"), "utf8")).git?.autoMerge === true;
+    }
+    catch {
+        return false;
+    }
+}
+function allowOpen(reason) {
+    process.stderr.write(`${reason}\n`);
+    process.stdout.write('{"permission":"allow"}\n');
+}
+function runHook(args) {
+    if (args.includes("-h") || args.includes("--help") || args.length === 0) {
+        process.stdout.write(help);
+        return;
+    }
+    if (args[0] !== "before-shell" && args[0] !== "before-mcp") {
+        fail("Unknown hook. Use: tito hook before-shell or tito hook before-mcp");
+        return;
+    }
+    let raw;
+    try {
+        raw = readFileSync(0, "utf8");
+    }
+    catch (error) {
+        allowOpen(error instanceof Error ? error.message : "Could not read stdin.");
+        return;
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        allowOpen("Empty hook input.");
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        allowOpen("Hook stdin is not JSON.");
+        return;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        allowOpen("Hook stdin is not a JSON object.");
+        return;
+    }
+    try {
+        if (args[0] === "before-mcp") {
+            const body = parsed;
+            const toolInput = typeof body.tool_input === "string"
+                ? body.tool_input
+                : body.tool_input === undefined
+                    ? ""
+                    : JSON.stringify(body.tool_input);
+            const cwd = process.cwd();
+            const verdict = decideMcp({
+                toolName: typeof body.tool_name === "string" ? body.tool_name : "",
+                toolInput,
+                currentBranch: currentBranch(cwd) ?? "",
+                autoMerge: autoMergeFromCwd(cwd),
+            });
+            process.stdout.write(`${JSON.stringify(verdict)}\n`);
+            return;
+        }
+        const body = parsed;
+        if (typeof body.command !== "string") {
+            allowOpen("Hook stdin is missing a command string.");
+            return;
+        }
+        const cwd = typeof body.cwd === "string" && body.cwd.length > 0 ? body.cwd : process.cwd();
+        const verdict = decideShell(body.command, currentBranch(cwd), autoMergeFromCwd(cwd));
+        process.stdout.write(`${JSON.stringify(verdict)}\n`);
+    }
+    catch (error) {
+        allowOpen(error instanceof Error ? error.message : "Hook decision failed.");
+    }
+}
 function runWorktree(args) {
     if (args.includes("-h") || args.includes("--help")) {
         process.stdout.write(help);
@@ -551,6 +642,10 @@ async function run(args) {
         runGuard(args.slice(1));
         return;
     }
+    if (args[0] === "hook") {
+        runHook(args.slice(1));
+        return;
+    }
     if (args[0] === "worktree") {
         runWorktree(args.slice(1));
         return;

package/dist/core/agents.js

@@ -12,6 +12,8 @@ const AGENT_FILE_NAMES = {
     "security-reviewer": "tito-security.md",
     "tech-docs-writer": "tito-tech-docs.md",
     "user-docs-writer": "tito-user-docs.md",
+    cleaner: "tito-cleaner.md",
+    startup: "tito-startup.md",
 };
 export function cursorAgentPath(id) {
     return `.cursor/agents/${AGENT_FILE_NAMES[id]}`;

package/dist/core/budgets.js

@@ -0,0 +1,292 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+export const estimateTokens = (text) => Math.ceil(text.length / 4);
+export const BUDGETS = Object.freeze({
+    ordinary: 1500,
+    "always-on": 2100,
+    planning: 4100,
+    "tito-skill": 5300,
+    command: 2500,
+    card: 400,
+});
+export const CEILINGS = Object.freeze({});
+const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const FIELD = /^(description|alwaysApply|globs|disable-model-invocation):[ \t]*(.*)$/;
+const FOLDED = /^>([+-])?$/;
+const MD_REF = /`([^`\n]+\.md)`/g;
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function rel(root, abs) {
+    return relative(root, abs).split(sep).join("/");
+}
+function surfaceDir(root, name) {
+    const nested = join(root, ".cursor", name);
+    if (isDir(nested))
+        return nested;
+    const flat = join(root, name);
+    return isDir(flat) ? flat : null;
+}
+function listFiles(dir, suffix) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(suffix))
+            .map((entry) => entry.name)
+            .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    }
+    catch {
+        return [];
+    }
+}
+function listDirs(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    }
+    catch {
+        return [];
+    }
+}
+function parseFrontMatter(text) {
+    const block = FRONT_MATTER.exec(text)?.[1];
+    if (block === undefined)
+        return {};
+    const fields = {};
+    const lines = block.replace(/\r/g, "").split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? "";
+        const match = FIELD.exec(line);
+        if (match === null) {
+            i += 1;
+            continue;
+        }
+        const key = match[1] ?? "";
+        const rest = (match[2] ?? "").trim();
+        if (FOLDED.test(rest)) {
+            const folded = [];
+            i += 1;
+            while (i < lines.length) {
+                const next = lines[i] ?? "";
+                if (next !== "" && !/^[ \t]/.test(next))
+                    break;
+                folded.push(next.replace(/^[ \t]+/, ""));
+                i += 1;
+            }
+            fields[key] = folded.filter((part) => part.length > 0).join(" ");
+            continue;
+        }
+        fields[key] = rest;
+        i += 1;
+    }
+    return fields;
+}
+function sumTokens(parts) {
+    return parts.reduce((total, part) => total + estimateTokens(part), 0);
+}
+function budgetFor(id) {
+    if (id.startsWith("command:"))
+        return BUDGETS.command;
+    if (id.startsWith("card:"))
+        return BUDGETS.card;
+    if (id === "ordinary")
+        return BUDGETS.ordinary;
+    if (id === "always-on")
+        return BUDGETS["always-on"];
+    if (id === "planning")
+        return BUDGETS.planning;
+    if (id === "tito-skill")
+        return BUDGETS["tito-skill"];
+    return 0;
+}
+function makeReport(id, files, missing, tokens) {
+    const budget = budgetFor(id);
+    const ceiling = CEILINGS[id];
+    if (ceiling === undefined) {
+        return { id, files, missing, tokens, budget };
+    }
+    return { id, files, missing, tokens, budget, ceiling };
+}
+function referencedMarkdown(agentsText) {
+    const found = [];
+    const seen = new Set();
+    for (const match of agentsText.matchAll(MD_REF)) {
+        const name = match[1];
+        if (name === undefined || seen.has(name))
+            continue;
+        seen.add(name);
+        found.push(name);
+    }
+    return found;
+}
+export function descriptionCatalog(root) {
+    const items = [];
+    const agentsDir = surfaceDir(root, "agents");
+    if (agentsDir !== null) {
+        for (const name of listFiles(agentsDir, ".md")) {
+            const abs = join(agentsDir, name);
+            const text = readText(abs);
+            if (text === null)
+                continue;
+            const description = parseFrontMatter(text).description ?? "";
+            if (description === "")
+                continue;
+            items.push({ source: rel(root, abs), text: description });
+        }
+    }
+    const rulesDir = surfaceDir(root, "rules");
+    if (rulesDir !== null) {
+        for (const name of listFiles(rulesDir, ".mdc")) {
+            const abs = join(rulesDir, name);
+            const text = readText(abs);
+            if (text === null)
+                continue;
+            const fields = parseFrontMatter(text);
+            const description = fields.description ?? "";
+            if (description === "")
+                continue;
+            if (fields.alwaysApply !== "false")
+                continue;
+            if ((fields.globs ?? "") !== "")
+                continue;
+            items.push({ source: rel(root, abs), text: description });
+        }
+    }
+    const skillsDir = surfaceDir(root, "skills");
+    if (skillsDir !== null) {
+        for (const folder of listDirs(skillsDir)) {
+            const abs = join(skillsDir, folder, "SKILL.md");
+            const text = readText(abs);
+            if (text === null)
+                continue;
+            const fields = parseFrontMatter(text);
+            if (fields["disable-model-invocation"] === "true")
+                continue;
+            const description = fields.description ?? "";
+            if (description === "")
+                continue;
+            items.push({ source: rel(root, abs), text: description });
+        }
+    }
+    return items;
+}
+export function measurePaths(root) {
+    const reports = [];
+    const ordinaryFiles = [];
+    const ordinaryTexts = [];
+    const ordinaryMissing = [];
+    const agentsText = readText(join(root, "AGENTS.md"));
+    if (agentsText === null) {
+        ordinaryMissing.push("AGENTS.md");
+    }
+    else {
+        ordinaryFiles.push("AGENTS.md");
+        ordinaryTexts.push(agentsText);
+    }
+    const rulesDir = surfaceDir(root, "rules");
+    if (rulesDir !== null) {
+        for (const name of listFiles(rulesDir, ".mdc")) {
+            const abs = join(rulesDir, name);
+            const text = readText(abs);
+            if (text === null)
+                continue;
+            if (parseFrontMatter(text).alwaysApply !== "true")
+                continue;
+            ordinaryFiles.push(rel(root, abs));
+            ordinaryTexts.push(text);
+        }
+    }
+    const catalog = descriptionCatalog(root);
+    const alwaysOnFiles = [...ordinaryFiles];
+    const alwaysOnTexts = [...ordinaryTexts];
+    for (const item of catalog) {
+        if (!alwaysOnFiles.includes(item.source))
+            alwaysOnFiles.push(item.source);
+        alwaysOnTexts.push(item.text);
+    }
+    reports.push(makeReport("ordinary", ordinaryFiles, [...ordinaryMissing], sumTokens(ordinaryTexts)));
+    reports.push(makeReport("always-on", alwaysOnFiles, [...ordinaryMissing], sumTokens(alwaysOnTexts)));
+    const planningFiles = [...alwaysOnFiles];
+    const planningTexts = [...alwaysOnTexts];
+    const planningMissing = [...ordinaryMissing];
+    if (agentsText !== null) {
+        for (const ref of referencedMarkdown(agentsText)) {
+            const abs = join(root, ref);
+            const text = readText(abs);
+            if (text === null) {
+                planningMissing.push(ref);
+                continue;
+            }
+            if (!planningFiles.includes(ref))
+                planningFiles.push(ref);
+            planningTexts.push(text);
+        }
+    }
+    reports.push(makeReport("planning", planningFiles, planningMissing, sumTokens(planningTexts)));
+    const skillsDir = surfaceDir(root, "skills");
+    const titoAbs = join(skillsDir ?? join(root, ".cursor", "skills"), "tito", "SKILL.md");
+    const titoText = readText(titoAbs);
+    const titoFiles = [...planningFiles];
+    const titoTexts = [...planningTexts];
+    const titoMissing = [...planningMissing];
+    if (titoText === null) {
+        titoMissing.push(rel(root, titoAbs));
+    }
+    else {
+        titoFiles.push(rel(root, titoAbs));
+        titoTexts.push(titoText);
+    }
+    reports.push(makeReport("tito-skill", titoFiles, titoMissing, sumTokens(titoTexts)));
+    if (skillsDir !== null) {
+        for (const folder of listDirs(skillsDir)) {
+            if (folder === "tito")
+                continue;
+            const abs = join(skillsDir, folder, "SKILL.md");
+            const text = readText(abs);
+            if (text === null)
+                continue;
+            reports.push(makeReport(`command:${folder}`, [...alwaysOnFiles, rel(root, abs)], [...ordinaryMissing], sumTokens([...alwaysOnTexts, text])));
+        }
+    }
+    const agentsDir = surfaceDir(root, "agents");
+    if (agentsDir !== null) {
+        for (const name of listFiles(agentsDir, ".md")) {
+            const abs = join(agentsDir, name);
+            const text = readText(abs);
+            if (text === null)
+                continue;
+            reports.push(makeReport(`card:${name.replace(/\.md$/, "")}`, [rel(root, abs)], [], estimateTokens(text)));
+        }
+    }
+    return reports;
+}
+export function budgetFailures(reports) {
+    const failures = [];
+    for (const item of reports) {
+        if (item.tokens <= item.budget)
+            continue;
+        if (item.ceiling !== undefined) {
+            if (item.tokens <= item.ceiling)
+                continue;
+            failures.push(`${item.id}: ${item.tokens} > ceiling ${item.ceiling}`);
+            continue;
+        }
+        failures.push(`${item.id}: ${item.tokens} > budget ${item.budget}`);
+    }
+    return failures;
+}

package/dist/core/config.js

@@ -3,11 +3,19 @@ import { BRANCH_BASES } from "./git-flow.js";
 import { ACTIVE_RISK_PROFILE_IDS, isActiveRiskProfileId, isFutureRiskProfileId, } from "./profiles.js";
 export const CONFIG_SCHEMA_VERSION = 1;
 const FIELDS = new Set(["schemaVersion", "profile", "git", "product", "models"]);
-export const MODEL_ROLES = ["explorer", "planner", "implementer", "reviewer", "finisher"];
+export const MODEL_ROLES = [
+    "explorer",
+    "planner",
+    "advisor",
+    "implementer",
+    "reviewer",
+    "finisher",
+];
 export const DEFAULT_MODELS = Object.freeze({
     explorer: "cursor-grok-4.6-medium-fast",
-    planner: "claude-opus-5-5-medium",
-    implementer: "grok-4.7-high",
+    planner: "grok-4.7-high",
+    advisor: "claude-opus-5-5-medium",
+    implementer: "cursor-grok-4.6-high",
     reviewer: "grok-4.7-high",
     finisher: "composer-2.5",
 });
@@ -53,6 +61,8 @@ function assembleGit(parts) {
         git.defaultBase = parts.defaultBase;
     if (parts.autoPullRequest !== undefined)
         git.autoPullRequest = parts.autoPullRequest;
+    if (parts.autoMerge !== undefined)
+        git.autoMerge = parts.autoMerge;
     return Object.keys(git).length > 0 ? git : undefined;
 }
 function readGit(node) {
@@ -63,6 +73,7 @@ function readGit(node) {
     const seen = new Set();
     let defaultBase;
     let autoPullRequest = undefined;
+    let autoMerge = undefined;
     for (const item of node.items) {
         const key = isScalar(item.key) && typeof item.key.value === "string" ? item.key.value : null;
         if (key === null) {
@@ -94,11 +105,21 @@ function readGit(node) {
             }
             continue;
         }
+        if (key === "autoMerge") {
+            const value = isScalar(item.value) ? item.value.value : NON_SCALAR;
+            if (typeof value !== "boolean") {
+                issues.push(issue("unknown-field", 'Field "git.autoMerge" must be a boolean.', "git.autoMerge"));
+            }
+            else {
+                autoMerge = value;
+            }
+            continue;
+        }
         issues.push(issue("unknown-field", `Unknown field "git.${key}".`, `git.${key}`));
     }
     if (issues.length > 0)
         return { issues };
-    const git = assembleGit({ defaultBase, autoPullRequest });
+    const git = assembleGit({ defaultBase, autoPullRequest, autoMerge });
     return git ? { git, issues } : { issues };
 }
 function isScreenLanguage(value) {

package/dist/core/git-flow.js

@@ -159,16 +159,18 @@ export function pullRequestDescription(input) {
     return lines.join("\n");
 }
 export function mergeDecision(input) {
-    if (!input.userAskedToMerge) {
-        return { allowed: false, reason: "Wait for the user to call for the merge." };
+    if (input.userAskedToMerge) {
+        return { allowed: true, reason: "The user called for the merge." };
     }
-    if (!input.hasApproval) {
-        return { allowed: false, reason: "The pull request has no approval." };
+    if (input.autoMerge === true &&
+        input.profile !== "client-careful" &&
+        input.touchesEscalation !== true) {
+        return {
+            allowed: true,
+            reason: "git.autoMerge is the standing merge call.",
+        };
     }
-    return {
-        allowed: true,
-        reason: "The user called for the merge and the pull request has an approval.",
-    };
+    return { allowed: false, reason: "Wait for the user to call for the merge." };
 }
 export function canApprovePullRequest() {
     return false;