@anhvupt/tito 0.3.0 → 0.3.3

package/README.md

@@ -19,9 +19,11 @@ specialists, and it updates the docs named in the plan before a pull request.
   uncertain or critical work, and Agent only for an approved implementation
   slice.
 - **Plans that make decisions:** Tito confirms the goal and what is out of
-  scope, then asks one batch of clarifying questions, lighter on `solo-fast`.
-  One obvious reading continues after a one-line confirmation. Tito still asks
-  before locking a technical decision or a product-vision change. The plan
+  scope, then asks only the questions that are large; zero is fine.
+  `client-careful` still asks for medium decisions. `solo-balanced` and
+  `solo-fast` decide small and medium choices and report them on a `Decided:`
+  line. One obvious reading continues after a one-line confirmation. Tito asks
+  before locking a large decision or a product-vision change. The plan
   records that decision and includes signatures, schemas, pseudocode, or
   guidance code when that makes implementation clearer. Decisions name the
   convention they follow. Test cases carry a layer tag: `[unit]`,
@@ -66,6 +68,7 @@ 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
 has its own plan and branch. Tito does not code in the chat. Every change,
 including a small one, goes to a sub-agent, and Tito returns to the user.
+Before writing an approved slice, Tito lists installed skills, reads only each name and description, and names in the handoff the ones the writer must read.
 When two or more slices are independent, Tito sends those sub-agents together,
 each on its own branch, up to that cap, and does not line them up one after
 another. Check out each branch only after you accept that branch.
@@ -107,7 +110,9 @@ The first `init` prints the plan and writes nothing. In a terminal, omitting
 `--profile` asks you to choose `client-careful`, `solo-balanced`, or
 `solo-fast`. A script or piped command must still pass `--profile`.
 `--confirm` creates the missing `tito.yaml`, specialist agents, and `/tito`
-skills. If `AGENTS.md` already exists, Tito appends its bootstrap and leaves
+skills. It also installs Tito's scoped rules under `.cursor/rules/`
+(pull-request, screen-language, init-upgrade-admin, and commit-branch). If
+`AGENTS.md` already exists, Tito appends its bootstrap and leaves
 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`),
@@ -130,7 +135,8 @@ npx tito upgrade --confirm
 ```
 
 `--confirm` installs the latest `@anhvupt/tito` and replaces Tito-owned
-agents, skills, and the Tito section of `AGENTS.md`. Consumer rules, consumer
+agents, skills, those Tito-owned scoped rules, and the Tito section of
+`AGENTS.md`. 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.
 
 Tito is installed in each project. It is not a required global command.
@@ -178,6 +184,9 @@ node dist/cli.js admin list
 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 worktree tidy
+node dist/cli.js worktree tidy --confirm
 ```
 
 `inspect` reads `tito.yaml` when it exists and checks whether `AGENTS.md` is
@@ -196,10 +205,16 @@ registered paths, `remove` drops one path, and `refresh` writes local branch plu
 the last 50 commit subjects, dates, and file paths (secrets like `.env` skipped;
 no diffs) for chat and CLI to share.
 
+`worktree tidy` (chat: `/tito-worktree-tidy`) reports each linked worktree as protected, merged-clean, dirty, unmerged, behind, fresh, or missing. It removes a merged clean worktree and its local branch only with `--confirm`. It does not delete remote branches or rebase.
+
 `retro` builds that week's report from local git and saves `retros/<week>.json`
 and `retros/<week>.md` under the admin root. Review-fix counts, docs-blank, and
 merge duration say unavailable until GitHub data is added.
 
+`guard test-first` checks a slice branch against `--base`. Commit 1 may change
+only the repeated `--test` files. Later commits may not change `test/**`,
+`*.test.*`, or `*.spec.*` files. A failure names the file and the commit.
+
 ## How work moves
 
 The normal careful path is:
@@ -240,6 +255,17 @@ 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.
+
+```yaml
+models:
+  explorer: cursor-grok-4.6-medium-fast
+  planner: claude-opus-5-5-medium
+  implementer: grok-4.7-high
+  reviewer: grok-4.7-high
+  finisher: claude-sonnet-5-5-high
+```
+
 - Code stays English.
 - In a Vietnamese app (`screenLanguage: vi`), routes and slugs are Vietnamese first. The public path is native Vietnamese, for example `/tien-ich/ca-phe`. Do not invent that Vietnamese by translating an English slug word for word. If the product is bilingual, the English route comes second.
 - An English app (`screenLanguage: en`) keeps English routes and slugs.

package/dist/cli.js

@@ -9,10 +9,12 @@ import { InspectionError, formatInspection, inspectRepository, } from "./core/in
 import { PlanError, formatAdoptionPlan, planAdoption } from "./core/plan.js";
 import { ConfigValidationError, parseConfig } from "./core/config.js";
 import { INIT_SETTING_KEYS, InitError, applyInitialization, formatInitialization, planInitialization, promptForProfile, promptForSettings, } from "./core/init.js";
-import { applyUpgrade, formatUpgrade, mergeSettings, missingSettings, planUpgrade, titoOwnedFiles, } from "./core/upgrade.js";
+import { applyUpgrade, formatUpgrade, mergeSettings, missingSettings, planUpgrade, projectModels, titoOwnedFiles, } from "./core/upgrade.js";
 import { AdminError, addRepo, formatContexts, formatRepos, listRepos, refreshRepos, removeRepo, resolveAdminRoot, } from "./core/admin.js";
 import { RetroError, buildRetro, formatRetro, retroJson, saveRetro, } from "./core/retro.js";
 import { formatInitError } from "./core/terminal.js";
+import { TestFirstError, formatTestFirstReport, guardTestFirst, } from "./core/test-first.js";
+import { WorktreeError, formatTidyReport, tidyWorktrees } from "./core/worktree.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const help = `Tito — quiet orchestration for solo builders
 
@@ -27,6 +29,8 @@ Usage:
   tito admin remove --root <path> [--admin-root <path>]
   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 worktree tidy [--confirm] [--root <path>]
 
 Options:
   -h, --help     Show help
@@ -38,6 +42,8 @@ Commands:
   init           Install Tito files and specialist agents. Confirm before writing.
   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.
+  worktree       Report stale worktrees. Confirm before removing merged clean ones.
 `;
 function fail(message) {
     process.stderr.write(`${message}\n`);
@@ -239,13 +245,15 @@ async function runUpgrade(args) {
         fail(error instanceof Error ? error.message : "Invalid upgrade arguments.");
         return;
     }
-    const files = planUpgrade(root, titoOwnedFiles());
+    let files = planUpgrade(root, titoOwnedFiles(projectModels(root)));
     if (!confirm) {
         process.stdout.write(formatUpgrade(root, files));
         return;
     }
-    if (!filesOnly && input.isTTY)
+    if (!filesOnly && input.isTTY) {
         await fillMissingSettings(root);
+        files = planUpgrade(root, titoOwnedFiles(projectModels(root)));
+    }
     if (!filesOnly && !isTitoSource(root)) {
         const install = spawnSync("npm", ["install", "-D", "@anhvupt/tito@latest"], { cwd: root, encoding: "utf8" });
         if (install.status !== 0) {
@@ -421,6 +429,105 @@ function runRetro(args) {
         throw error;
     }
 }
+function runGuard(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        process.stdout.write(help);
+        return;
+    }
+    const [subcommand, ...rest] = args;
+    if (subcommand !== "test-first") {
+        fail("Unknown guard. Use: tito guard test-first --base <ref> --test <file>");
+        return;
+    }
+    let root = process.cwd();
+    let base;
+    let testFiles = [];
+    try {
+        const { values } = parseArgs({
+            args: rest,
+            options: {
+                base: { type: "string" },
+                root: { type: "string" },
+                test: { type: "string", multiple: true },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        if (values.base !== undefined)
+            base = values.base;
+        if (values.root !== undefined)
+            root = values.root;
+        if (Array.isArray(values.test))
+            testFiles = values.test;
+        else if (typeof values.test === "string")
+            testFiles = [values.test];
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Invalid guard arguments.");
+        return;
+    }
+    if (base === undefined) {
+        fail("Missing required option --base.");
+        return;
+    }
+    if (testFiles.length === 0) {
+        fail("Missing required option --test.");
+        return;
+    }
+    try {
+        const report = guardTestFirst({ root, base, testFiles });
+        process.stdout.write(formatTestFirstReport(report));
+        if (!report.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        if (error instanceof TestFirstError) {
+            fail(`${error.code}: ${error.message}`);
+            return;
+        }
+        throw error;
+    }
+}
+function runWorktree(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        process.stdout.write(help);
+        return;
+    }
+    if (args[0] !== "tidy") {
+        fail("Unknown worktree command. Use tito worktree tidy.");
+        return;
+    }
+    let root = process.cwd();
+    let confirm = false;
+    try {
+        const { values } = parseArgs({
+            args: args.slice(1),
+            options: {
+                confirm: { type: "boolean" },
+                root: { type: "string" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        confirm = values.confirm === true;
+        if (values.root !== undefined)
+            root = values.root;
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Invalid worktree arguments.");
+        return;
+    }
+    try {
+        process.stdout.write(formatTidyReport(tidyWorktrees({ root, confirm })));
+    }
+    catch (error) {
+        if (error instanceof WorktreeError) {
+            fail(`${error.code}: ${error.message}`);
+            return;
+        }
+        throw error;
+    }
+}
 async function run(args) {
     if (args[0] === "inspect") {
         runInspect(args.slice(1));
@@ -440,6 +547,14 @@ async function run(args) {
         runAdmin(args.slice(1));
         return;
     }
+    if (args[0] === "guard") {
+        runGuard(args.slice(1));
+        return;
+    }
+    if (args[0] === "worktree") {
+        runWorktree(args.slice(1));
+        return;
+    }
     let helpRequested = false;
     let versionRequested = false;
     try {

package/dist/core/agents.js

@@ -1,3 +1,4 @@
+import { resolveModels } from "./config.js";
 import { SPECIALIST_IDS, SPECIALISTS } from "./specialists.js";
 const AGENT_FILE_NAMES = {
     explorer: "tito-explorer.md",
@@ -15,8 +16,9 @@ const AGENT_FILE_NAMES = {
 export function cursorAgentPath(id) {
     return `.cursor/agents/${AGENT_FILE_NAMES[id]}`;
 }
-export function compileCursorAgent(id) {
+export function compileCursorAgent(id, models) {
     const manifest = SPECIALISTS[id];
+    const model = resolveModels(models)[manifest.model.role];
     const readOnly = manifest.modes.every((mode) => mode.capability === "read-only");
     const modes = manifest.modes
         .map((mode) => `- \`${mode.id}\`: ${mode.capability}`)
@@ -32,7 +34,7 @@ name: ${AGENT_FILE_NAMES[id].replace(/\.md$/, "")}
 description: >
   ${manifest.role}. Tito delegates this specialist only for: ${manifest.triggers.join("; ")}.
   You are not the root coordinator. Follow the assigned mode and stop condition.
-model: inherit
+model: ${model}
 readonly: ${readOnly}
 ---
 
@@ -61,9 +63,9 @@ Return the result to Tito. Suggest another specialist only from this manifest's
 ${manifest.stopCondition}
 `;
 }
-export function compiledCursorAgents() {
+export function compiledCursorAgents(models) {
     return SPECIALIST_IDS.map((id) => ({
         path: cursorAgentPath(id),
-        body: compileCursorAgent(id),
+        body: compileCursorAgent(id, models),
     }));
 }

package/dist/core/config.js

@@ -2,12 +2,23 @@ import { isMap, isScalar, isSeq, parseAllDocuments } from "yaml";
 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"]);
+const FIELDS = new Set(["schemaVersion", "profile", "git", "product", "models"]);
+export const MODEL_ROLES = ["explorer", "planner", "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",
+    reviewer: "grok-4.7-high",
+    finisher: "claude-sonnet-5-5-high",
+});
 export const SCREEN_LANGUAGES = ["vi", "en"];
 export const TENANCY_VALUES = ["single", "multi"];
 const PRODUCT_FIELDS = new Set(["screenLanguage", "tenancy", "surfaces"]);
 const SURFACE_ID = /^[a-z][a-z0-9-]*$/;
 const NON_SCALAR = Symbol("non-scalar");
+export function resolveModels(models) {
+    return { ...DEFAULT_MODELS, ...models };
+}
 export class ConfigValidationError extends Error {
     issues;
     constructor(issues) {
@@ -226,6 +237,42 @@ function readProduct(node) {
     const product = assembleProduct({ screenLanguage, tenancy, surfaces });
     return product ? { product, issues } : { issues };
 }
+function isModelRole(value) {
+    return MODEL_ROLES.includes(value);
+}
+function readModels(node) {
+    if (!isMap(node)) {
+        return { issues: [issue("unknown-field", 'Field "models" must be a mapping.', "models")] };
+    }
+    const issues = [];
+    const seen = new Set();
+    const models = {};
+    for (const item of node.items) {
+        const key = mappingKey(item.key);
+        if (key === null) {
+            issues.push(issue("unknown-field", "Mapping keys must be strings.", "models"));
+            continue;
+        }
+        if (seen.has(key)) {
+            issues.push(issue("duplicate-key", `Duplicate key "${key}".`, `models.${key}`));
+            continue;
+        }
+        seen.add(key);
+        if (!isModelRole(key)) {
+            issues.push(issue("unknown-field", `Unknown field "models.${key}".`, `models.${key}`));
+            continue;
+        }
+        const value = isScalar(item.value) ? item.value.value : NON_SCALAR;
+        if (typeof value !== "string" || value.trim().length === 0) {
+            issues.push(issue("unknown-field", `Field "models.${key}" must be a non-empty model slug.`, `models.${key}`));
+            continue;
+        }
+        models[key] = value.trim();
+    }
+    if (issues.length > 0)
+        return { issues };
+    return Object.keys(models).length > 0 ? { models, issues } : { issues };
+}
 function profileIssue(value) {
     if (typeof value !== "string") {
         return issue("unknown-profile", "Profile must be a string.", "profile");
@@ -268,6 +315,7 @@ export function parseConfig(text) {
     const values = new Map();
     let git;
     let product;
+    let models;
     for (const item of document.contents.items) {
         const key = isScalar(item.key) && typeof item.key.value === "string" ? item.key.value : null;
         if (key === null) {
@@ -298,6 +346,13 @@ export function parseConfig(text) {
                 product = parsed.product;
             continue;
         }
+        if (key === "models") {
+            const parsed = readModels(item.value);
+            issues.push(...parsed.issues);
+            if (parsed.models)
+                models = parsed.models;
+            continue;
+        }
         values.set(key, isScalar(item.value) ? item.value.value : NON_SCALAR);
     }
     if ((occurrences.get("schemaVersion") ?? 0) === 0) {
@@ -326,5 +381,7 @@ export function parseConfig(text) {
         result.git = git;
     if (product)
         result.product = product;
+    if (models)
+        result.models = models;
     return result;
 }

package/dist/core/git-flow.js

@@ -1,3 +1,4 @@
+import { recommendModel } from "./models.js";
 export const BRANCH_TYPES = [
     "feat",
     "fix",
@@ -172,3 +173,73 @@ export function mergeDecision(input) {
 export function canApprovePullRequest() {
     return false;
 }
+const PROTECTED_PUSH_BRANCHES = new Set(["main", "master", "dev", "develop"]);
+const SLICE_CHECKS = ["guard", "lint", "tests", "build", "docs"];
+export function finishSlice(input) {
+    if (input.role !== "finisher") {
+        return {
+            status: "refused",
+            pushed: false,
+            reason: `The ${input.role} may not open a pull request.`,
+        };
+    }
+    if (PROTECTED_PUSH_BRANCHES.has(input.branch)) {
+        return {
+            status: "refused",
+            pushed: false,
+            reason: `Refusing to push ${input.branch}.`,
+        };
+    }
+    if (input.autoPullRequest !== true) {
+        return {
+            status: "ask",
+            pushed: false,
+            reason: "Tito asks before opening a pull request.",
+        };
+    }
+    for (const check of SLICE_CHECKS) {
+        if (input.checks[check] !== true) {
+            return {
+                status: "failed",
+                pushed: false,
+                check,
+                reason: `The ${check} check failed. Nothing was pushed.`,
+            };
+        }
+    }
+    const recommendation = recommendModel({
+        host: "cursor",
+        role: "finisher",
+        catalog: input.catalog,
+    });
+    if (recommendation.status !== "selected") {
+        return {
+            status: "ask",
+            pushed: false,
+            reason: recommendation.reason,
+        };
+    }
+    const body = pullRequestDescription(input.description);
+    if (body === null) {
+        return {
+            status: "failed",
+            pushed: false,
+            reason: "The pull request description is not a valid four-part description.",
+        };
+    }
+    input.adapter.push(input.branch);
+    const opened = input.adapter.openPullRequest({
+        head: input.branch,
+        base: input.base,
+        title: input.description.problem.trim(),
+        body,
+        readyForReview: true,
+    });
+    return {
+        status: "opened",
+        model: recommendation.model,
+        url: opened.url,
+        pushed: true,
+        readyForReview: true,
+    };
+}

package/dist/core/init.js

@@ -2,7 +2,7 @@ import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSy
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compiledCursorAgents } from "./agents.js";
-import { SCREEN_LANGUAGES, TENANCY_VALUES, isSurfaceId, } from "./config.js";
+import { MODEL_ROLES, SCREEN_LANGUAGES, TENANCY_VALUES, isSurfaceId, resolveModels, } from "./config.js";
 import { BRANCH_BASES, PULL_REQUEST_TEMPLATE_PATH, pullRequestTemplate, } from "./git-flow.js";
 import { ACTIVE_RISK_PROFILE_IDS } from "./profiles.js";
 import { PlanError, TITO_BOOTSTRAP_START, planAdoption, titoBootstrapBlock, } from "./plan.js";
@@ -123,6 +123,8 @@ export function titoYamlBody(profile, settings) {
     }
     if (productLines.length > 0)
         lines.push("product:", ...productLines);
+    const models = resolveModels(settings.models);
+    lines.push("models:", ...MODEL_ROLES.map((role) => `  ${role}: ${models[role]}`));
     return `${lines.join("\n")}\n`;
 }
 function exists(root, path) {
@@ -142,6 +144,17 @@ export function shippedSkills() {
         body: readFileSync(join(root, entry.name, "SKILL.md"), "utf8"),
     }));
 }
+export function shippedCursorRules() {
+    const root = join(dirname(fileURLToPath(import.meta.url)), "../../templates/cursor/rules");
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".mdc"))
+        .map((entry) => entry.name)
+        .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+        .map((name) => ({
+        path: `.cursor/rules/${name}`,
+        body: readFileSync(join(root, name), "utf8"),
+    }));
+}
 function agentsBootstrap(report) {
     if (report.agentsMd === "absent") {
         return { path: "AGENTS.md", action: "create", body: titoBootstrapBlock() };
@@ -162,16 +175,17 @@ export function planInitialization(report, profile, settings) {
     const files = adoption.files.map((file) => {
         if (file.path === "AGENTS.md")
             return agentsBootstrap(report);
-        if (file.path === "tito.yaml" && file.action === "create" && settings !== undefined) {
+        if (file.path === "tito.yaml" && file.action === "create") {
             return {
                 path: "tito.yaml",
                 action: "create",
-                body: titoYamlBody(adoption.profile, settings),
+                body: titoYamlBody(adoption.profile, settings ?? {}),
             };
         }
         return file;
     });
-    const agents = compiledCursorAgents().map((agent) => exists(report.root, agent.path)
+    const models = report.titoYaml.status === "valid" ? report.titoYaml.config.models : settings?.models;
+    const agents = compiledCursorAgents(models).map((agent) => exists(report.root, agent.path)
         ? { path: agent.path, action: "conflict" }
         : { path: agent.path, action: "create", body: agent.body });
     const skills = shippedSkills().map((skill) => exists(report.root, skill.path)
@@ -181,10 +195,13 @@ export function planInitialization(report, profile, settings) {
     const pullRequest = exists(report.root, PULL_REQUEST_TEMPLATE_PATH)
         ? { path: PULL_REQUEST_TEMPLATE_PATH, action: "keep" }
         : { path: PULL_REQUEST_TEMPLATE_PATH, action: "create", body: template };
+    const rules = shippedCursorRules().map((rule) => exists(report.root, rule.path)
+        ? { path: rule.path, action: "keep" }
+        : { path: rule.path, action: "create", body: rule.body });
     return {
         root: adoption.root,
         profile: adoption.profile,
-        files: [...files, ...agents, ...skills, pullRequest],
+        files: [...files, ...agents, ...skills, pullRequest, ...rules],
     };
 }
 export function formatInitialization(plan) {