@njeybe/nativ 2.0.0

package/dist/commands/hook.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { ARCHITECT_ROLE, ROLE_ENV, evaluateHookPayload, isTaskUnlocked, loadEnforcementMode, parseJsonLoose, } from '../core/enforcement.js';
+import { resolveProjectRoot } from '../core/root-resolver.js';
+import { recordRoleViolation } from '../core/telemetry.js';
+/** Payloads are a few hundred bytes; anything past this is not a hook call. */
+const MAX_STDIN_BYTES = 1_000_000;
+function readStdin(stream) {
+    return new Promise((resolve) => {
+        let data = '';
+        let settled = false;
+        const done = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(data);
+        };
+        stream.setEncoding('utf8');
+        stream.on('data', (chunk) => {
+            data += chunk;
+            if (data.length > MAX_STDIN_BYTES)
+                done();
+        });
+        stream.on('end', done);
+        stream.on('error', done);
+    });
+}
+/**
+ * `nativ hook check`: the PreToolUse hook entry point. Reads Claude Code's JSON from stdin and prints the
+ * hook decision to stdout. It always exits 0 and fails open: a broken payload, unreadable state or a bug
+ * here must never stop an agent's tool call. Only `block` mode ever denies, and only on a real violation.
+ */
+export async function runHookCheck(targetDirArg, options = {}) {
+    const write = options.output ?? ((text) => process.stdout.write(text));
+    try {
+        const raw = await readStdin(options.input ?? process.stdin);
+        let payload;
+        try {
+            payload = raw.trim() ? JSON.parse(raw) : null;
+        }
+        catch {
+            process.stderr.write('nativ hook check: stdin was not JSON; allowing.\n');
+            return;
+        }
+        const fallbackCwd = targetDirArg ? path.resolve(targetDirArg) : process.env.CLAUDE_PROJECT_DIR || process.cwd();
+        const { output, result } = evaluateHookPayload(payload, { mode: options.mode, role: options.role, fallbackCwd });
+        if (result && result.decision !== 'allow' && result.rule && result.relPath && fs.existsSync(path.join(result.root, '.ai'))) {
+            const toolName = payload.tool_name ?? 'unknown';
+            await recordRoleViolation(result.root, {
+                rule: result.rule,
+                mode: result.mode === 'block' ? 'block' : 'warn',
+                tool: toolName,
+                path: result.relPath,
+                taskIds: result.taskIds,
+            });
+        }
+        if (output)
+            write(JSON.stringify(output));
+    }
+    catch (err) {
+        process.stderr.write(`nativ hook check: ${err instanceof Error ? err.message : String(err)}; allowing.\n`);
+    }
+}
+/** `nativ hook status`: what the hook would enforce right now. Read-only. */
+export function getHookStatus(targetDirArg) {
+    const root = resolveProjectRoot(targetDirArg);
+    const activeTasks = [];
+    try {
+        const plan = parseJsonLoose(fs.readFileSync(path.join(root, '.ai', 'master_plan.json'), 'utf8'));
+        for (const milestone of plan.milestones ?? []) {
+            for (const task of milestone.tasks ?? []) {
+                if (task.status === 'in_progress' && typeof task.id === 'string') {
+                    activeTasks.push({ id: task.id, targetFiles: task.targetFiles ?? [], unlocked: isTaskUnlocked(root, task.id) });
+                }
+            }
+        }
+    }
+    catch {
+        // No plan: nothing is in progress.
+    }
+    return { ok: true, root, mode: loadEnforcementMode(root), role: (process.env[ROLE_ENV] ?? '').toLowerCase() || 'worker', activeTasks };
+}
+export function runHookStatus(targetDirArg, options = {}) {
+    const status = getHookStatus(targetDirArg);
+    if (options.json) {
+        console.log(JSON.stringify(status, null, 2));
+        return status;
+    }
+    const modeColor = status.mode === 'block' ? pc.red : status.mode === 'warn' ? pc.yellow : pc.dim;
+    console.log(pc.bold('\nnativ role enforcement'));
+    console.log(`  Mode:   ${modeColor(status.mode)}`);
+    console.log(`  Role:   ${status.role}${status.role === ARCHITECT_ROLE ? pc.dim(' (may edit .ai/ contracts)') : ''}`);
+    if (!status.activeTasks.length) {
+        console.log(pc.dim('  No task is in progress: only contract and secret paths are protected.\n'));
+    }
+    else {
+        for (const task of status.activeTasks) {
+            console.log(`  Task:   ${pc.cyan(task.id)}${task.unlocked ? pc.yellow('  [unlocked]') : ''}`);
+            console.log(pc.dim(`          ${task.targetFiles.join(', ') || 'no target files'}`));
+        }
+        console.log('');
+    }
+    return status;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,3 @@
+export declare function runInit(targetDirArg?: string, options?: {
+    force?: boolean;
+}): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import pc from 'picocolors';
+import { detectProject } from '../scanner/detector.js';
+import { buildContextContent } from '../scanner/context-builder.js';
+import { runSetup, printSetupResult } from './setup.js';
+import { stampManaged } from '../core/setup-assets.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function getTemplatesDir() {
+    // In dist/commands/init.js -> ../../templates
+    const candidate = path.resolve(__dirname, '../../templates');
+    if (fs.existsSync(candidate))
+        return candidate;
+    // Fallback for direct development: src/../templates
+    return path.resolve(__dirname, '../templates');
+}
+export async function runInit(targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const templatesDir = getTemplatesDir();
+    console.log(pc.bold(pc.cyan('\nNativ: Initializing Multi-Tier Pipeline...')));
+    console.log(pc.dim(`Target directory: ${targetDir}`));
+    // 1. Run scanner
+    console.log(pc.yellow('Scanning repository structure & tech stack...'));
+    const projectInfo = detectProject(targetDir);
+    console.log(pc.green(`✔ Identified: ${pc.bold(projectInfo.projectName)} (${pc.cyan(projectInfo.repositoryType)})`));
+    console.log(pc.dim('  ├─ Workspace Topology: ') + pc.white(projectInfo.repositoryType));
+    if (projectInfo.monorepoWorkspaces.length > 0) {
+        console.log(pc.dim('  │  └─ Workspaces: ') + pc.white(projectInfo.monorepoWorkspaces.join(', ')));
+    }
+    console.log(pc.dim('  ├─ Runtime & Language: ') + pc.white(projectInfo.runtime));
+    console.log(pc.dim('  ├─ Framework: ') + pc.white(projectInfo.framework));
+    const ormDisplay = projectInfo.detectedOrmConfig
+        ? `${projectInfo.databaseOrm} (${projectInfo.detectedOrmConfig})`
+        : projectInfo.databaseOrm;
+    console.log(pc.dim('  ├─ Database & ORM: ') + pc.white(ormDisplay));
+    if (projectInfo.ecosystemManifests.length > 0) {
+        console.log(pc.dim('  ├─ Manifests Scanned: ') + pc.dim(projectInfo.ecosystemManifests.join(', ')));
+    }
+    console.log(pc.dim('  └─ Verification Gate: ') + pc.cyan(projectInfo.verificationCommand));
+    console.log();
+    // 2. Prepare directories
+    const aiDir = path.join(targetDir, '.ai');
+    const subagentsDir = path.join(aiDir, 'subagents');
+    fs.mkdirSync(subagentsDir, { recursive: true });
+    const timestamp = new Date().toISOString();
+    // 3. Write .ai/context.md
+    const contextTemplate = fs.readFileSync(path.join(templatesDir, 'dot-ai/context.md'), 'utf8');
+    const contextContent = buildContextContent(contextTemplate, projectInfo);
+    const contextPath = path.join(aiDir, 'context.md');
+    if (!fs.existsSync(contextPath) || options.force) {
+        fs.writeFileSync(contextPath, contextContent, 'utf8');
+        console.log(pc.green('✔ Created .ai/context.md'));
+    }
+    else {
+        console.log(pc.dim('- Skipped existing .ai/context.md'));
+    }
+    // 4. Write .ai/db_schema.json
+    const dbTemplate = fs.readFileSync(path.join(templatesDir, 'dot-ai/db_schema.json'), 'utf8');
+    const dbContent = dbTemplate
+        .replace(/\{\{PROJECT_NAME\}\}/g, projectInfo.projectName)
+        .replace(/\{\{TIMESTAMP\}\}/g, timestamp)
+        .replace(/\{\{DETECTED_DATABASE_ENGINE\}\}/g, projectInfo.databaseOrm !== 'None detected' ? projectInfo.databaseOrm : 'PostgreSQL');
+    const dbPath = path.join(aiDir, 'db_schema.json');
+    if (!fs.existsSync(dbPath) || options.force) {
+        fs.writeFileSync(dbPath, dbContent, 'utf8');
+        console.log(pc.green('✔ Created .ai/db_schema.json'));
+    }
+    // 5. Write .ai/api_contracts.json
+    const apiTemplate = fs.readFileSync(path.join(templatesDir, 'dot-ai/api_contracts.json'), 'utf8');
+    const apiContent = apiTemplate
+        .replace(/\{\{PROJECT_NAME\}\}/g, projectInfo.projectName)
+        .replace(/\{\{TIMESTAMP\}\}/g, timestamp);
+    const apiPath = path.join(aiDir, 'api_contracts.json');
+    if (!fs.existsSync(apiPath) || options.force) {
+        fs.writeFileSync(apiPath, apiContent, 'utf8');
+        console.log(pc.green('✔ Created .ai/api_contracts.json'));
+    }
+    // 6. Write .ai/ui_specs.md
+    const uiTemplate = fs.readFileSync(path.join(templatesDir, 'dot-ai/ui_specs.md'), 'utf8');
+    const uiPath = path.join(aiDir, 'ui_specs.md');
+    if (!fs.existsSync(uiPath) || options.force) {
+        fs.writeFileSync(uiPath, uiTemplate, 'utf8');
+        console.log(pc.green('✔ Created .ai/ui_specs.md'));
+    }
+    // 7. Write .ai/master_plan.json
+    const planTemplate = fs.readFileSync(path.join(templatesDir, 'dot-ai/master_plan.json'), 'utf8');
+    const planContent = planTemplate
+        .replace(/\{\{PROJECT_NAME\}\}/g, projectInfo.projectName)
+        .replace(/\{\{TIMESTAMP\}\}/g, timestamp)
+        .replace(/\{\{VERIFICATION_COMMAND\}\}/g, projectInfo.verificationCommand);
+    const planPath = path.join(aiDir, 'master_plan.json');
+    if (!fs.existsSync(planPath) || options.force) {
+        fs.writeFileSync(planPath, planContent, 'utf8');
+        console.log(pc.green('✔ Created .ai/master_plan.json'));
+    }
+    // 7. Write Sub-agent specifications
+    const subagentFiles = [
+        'backend.md',
+        'frontend.md',
+        'database.md',
+        'qa-tester.md',
+        'flutter-developer.md',
+        'devops-agent.md',
+        'security-auditor.md',
+        'db-migration.md',
+    ];
+    for (const file of subagentFiles) {
+        const src = path.join(templatesDir, 'dot-ai/subagents', file);
+        const dest = path.join(subagentsDir, file);
+        if (fs.existsSync(src) && (!fs.existsSync(dest) || options.force)) {
+            // Stamped so a later `nativ update` can tell an untouched guide from one a person edited.
+            fs.writeFileSync(dest, stampManaged(fs.readFileSync(src, 'utf8')), 'utf8');
+            console.log(pc.green(`✔ Created .ai/subagents/${file}`));
+        }
+    }
+    // 8. Write root CLAUDE.md
+    const claudeSrc = path.join(templatesDir, 'CLAUDE.md');
+    const claudeDest = path.join(targetDir, 'CLAUDE.md');
+    if (fs.existsSync(claudeSrc) && (!fs.existsSync(claudeDest) || options.force)) {
+        fs.writeFileSync(claudeDest, stampManaged(fs.readFileSync(claudeSrc, 'utf8')), 'utf8');
+        console.log(pc.green('✔ Created CLAUDE.md (Project Manager Directive)'));
+    }
+    // 9. Write root GEMINI.md
+    const geminiSrc = path.join(templatesDir, 'GEMINI.md');
+    const geminiDest = path.join(targetDir, 'GEMINI.md');
+    if (fs.existsSync(geminiSrc) && (!fs.existsSync(geminiDest) || options.force)) {
+        fs.writeFileSync(geminiDest, stampManaged(fs.readFileSync(geminiSrc, 'utf8')), 'utf8');
+        console.log(pc.green('✔ Created GEMINI.md (optional Gemini/Antigravity architect adapter)'));
+    }
+    // 10. Claude Code configuration: MCP server, hooks, permissions, agents, AGENTS.md. Merges; never overwrites.
+    console.log(pc.yellow('Configuring Claude Code (MCP server, hooks, agents)...'));
+    const setup = await runSetup(targetDir, { quiet: true });
+    if (setup) {
+        printSetupResult(setup);
+    }
+    console.log(pc.bold(pc.cyan('\n✨ Pipeline Scaffolding Completed Successfully!\n')));
+    console.log(pc.bold('Next Steps:'));
+    console.log(pc.white(` 1. Run ${pc.green('claude')} in this directory and ask the ${pc.magenta('architect')} agent to design your contracts (database, API, UI). You approve each step.`));
+    console.log(pc.white(` 2. The architect writes ${pc.cyan('.ai/db_schema.json')}, ${pc.cyan('.ai/api_contracts.json')}, ${pc.cyan('.ai/ui_specs.md')}, and ${pc.cyan('.ai/master_plan.json')}.`));
+    console.log(pc.white(` 3. Ask Claude to run ${pc.green('nativ task next')} and delegate each task to a ${pc.magenta('worker')} agent; use ${pc.magenta('verifier')} for an independent check.`));
+    console.log(pc.dim(` Run ${pc.white('nativ doctor')} any time, and after updating Claude Code, to confirm the integration is intact.\n`));
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `nativ mcp` — runs the native MCP server over stdio.
+ * Nothing may be written to stdout here: it carries the JSON-RPC stream. Diagnostics go to stderr.
+ */
+export declare function runMcp(targetDirArg?: string): Promise<void>;

package/dist/commands/mcp.js

@@ -0,0 +1,16 @@
+import path from 'node:path';
+import { startMcpServer } from '../mcp/server.js';
+/**
+ * `nativ mcp` — runs the native MCP server over stdio.
+ * Nothing may be written to stdout here: it carries the JSON-RPC stream. Diagnostics go to stderr.
+ */
+export async function runMcp(targetDirArg) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    try {
+        await startMcpServer(targetDir);
+    }
+    catch (err) {
+        process.stderr.write(`✖ Failed to start Nativ MCP server: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,17 @@
+import { type SetupResult } from '../core/setup-assets.js';
+export interface SetupCommandOptions {
+    command?: string;
+    enforcement?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    json?: boolean;
+    /** Suppresses the report; `nativ init` prints its own. */
+    quiet?: boolean;
+}
+export declare function printSetupResult(result: SetupResult): void;
+/**
+ * `nativ setup`: writes the Claude Code configuration (.mcp.json, .claude/settings.json, .claude/agents/,
+ * AGENTS.md, .nativ/config.json), merging into what exists and never overwriting user-authored content.
+ * Safe to run any number of times.
+ */
+export declare function runSetup(targetDirArg?: string, options?: SetupCommandOptions): Promise<SetupResult | null>;

package/dist/commands/setup.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import pc from 'picocolors';
+import { applySetup } from '../core/setup-assets.js';
+const MODES = ['off', 'warn', 'block'];
+const ICON = { created: '+', updated: '~', unchanged: '=', skipped: '!' };
+export function printSetupResult(result) {
+    const paint = (action, text) => action === 'created' ? pc.green(text) : action === 'updated' ? pc.cyan(text) : action === 'skipped' ? pc.yellow(text) : pc.dim(text);
+    for (const change of result.changes) {
+        const verb = result.dryRun && (change.action === 'created' || change.action === 'updated') ? `would be ${change.action}` : change.action;
+        console.log(paint(change.action, `  ${ICON[change.action]} ${change.path}`) + pc.dim(`  ${verb}${change.detail ? `: ${change.detail}` : ''}`));
+    }
+    for (const warning of result.warnings)
+        console.log(pc.yellow(`\n⚠ ${warning}`));
+}
+/**
+ * `nativ setup`: writes the Claude Code configuration (.mcp.json, .claude/settings.json, .claude/agents/,
+ * AGENTS.md, .nativ/config.json), merging into what exists and never overwriting user-authored content.
+ * Safe to run any number of times.
+ */
+export async function runSetup(targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    if (options.enforcement !== undefined && !MODES.includes(options.enforcement)) {
+        const message = `--enforcement must be one of: ${MODES.join(', ')}`;
+        if (options.json)
+            console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+        else
+            console.error(pc.red(`\n✖ ${message}\n`));
+        process.exitCode = 1;
+        return null;
+    }
+    const setupOptions = {
+        command: options.command,
+        enforcement: options.enforcement,
+        force: options.force,
+        dryRun: options.dryRun,
+    };
+    const result = applySetup(targetDir, setupOptions);
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, root: result.root, dryRun: result.dryRun, cli: result.invocation, changes: result.changes, warnings: result.warnings }, null, 2));
+        return result;
+    }
+    if (options.quiet)
+        return result;
+    console.log(pc.bold(pc.cyan(`\nnativ setup${result.dryRun ? ' (dry run)' : ''}`)) + pc.dim(`  ${result.root}`));
+    printSetupResult(result);
+    const changed = result.changes.filter((c) => c.action === 'created' || c.action === 'updated').length;
+    console.log(changed
+        ? pc.green(`\n✔ ${result.dryRun ? `${changed} change(s) pending` : `${changed} file(s) written`}.`) + pc.dim(' Restart Claude Code (or run /hooks) to load the hooks.\n')
+        : pc.green('\n✔ Everything is already set up. Nothing changed.\n'));
+    return result;
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,5 @@
+export interface StatusOptions {
+    telemetry?: boolean;
+    json?: boolean;
+}
+export declare function runStatus(targetDirArg?: string, options?: StatusOptions): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { loadTelemetry, formatTelemetrySummary, recomputeTelemetrySummary } from '../core/telemetry.js';
+export async function runStatus(targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const planPath = path.join(targetDir, '.ai', 'master_plan.json');
+    const telemetryPath = path.join(targetDir, '.ai', 'telemetry.json');
+    if (!fs.existsSync(planPath)) {
+        console.error(pc.red(`\n✖ No .ai/master_plan.json found in: ${targetDir}`));
+        console.log(pc.yellow('Run `nativ init` first to scaffold the environment.\n'));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const raw = fs.readFileSync(planPath, 'utf8');
+        const plan = JSON.parse(raw);
+        const telemetry = loadTelemetry(telemetryPath, plan.projectName);
+        if (options.json) {
+            console.log(JSON.stringify({
+                projectName: plan.projectName,
+                overallStatus: plan.overallStatus,
+                activeMilestoneId: plan.activeMilestoneId,
+                milestones: plan.milestones,
+                telemetry: telemetry.summary,
+                tasksTelemetry: telemetry.tasks,
+            }, null, 2));
+            return;
+        }
+        console.log(pc.bold(pc.cyan(`\n📊 AI Agent Workflow Status: ${plan.projectName}`)));
+        console.log(pc.dim(`Overall Status: ${plan.overallStatus.toUpperCase()} | Active Milestone: ${plan.activeMilestoneId}`));
+        let totalTasks = 0;
+        let completedTasks = 0;
+        let inProgressTasks = 0;
+        let blockedTasks = 0;
+        for (const m of plan.milestones) {
+            console.log(pc.bold(`\n🚩 Milestone [${m.id}]: ${m.name} (${m.status})`));
+            for (const t of m.tasks) {
+                totalTasks++;
+                let statusBadge = pc.gray('○ pending');
+                if (t.status === 'completed') {
+                    completedTasks++;
+                    statusBadge = pc.green('✔ completed');
+                }
+                else if (t.status === 'in_progress') {
+                    inProgressTasks++;
+                    statusBadge = pc.yellow('▶ in_progress');
+                }
+                else if (t.status === 'blocked') {
+                    blockedTasks++;
+                    statusBadge = pc.red('✖ blocked');
+                }
+                console.log(`  ${statusBadge} ${pc.bold(t.id)}: ${t.title}`);
+                console.log(pc.dim(`    Agent: [${t.assignedSubagent}] | Verify: \`${t.verificationCommand || 'none'}\``));
+                if (t.notes) {
+                    console.log(pc.red(`    Note: ${t.notes}`));
+                }
+            }
+        }
+        const pct = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+        console.log(pc.bold(pc.cyan(`\n📈 Completion: ${completedTasks}/${totalTasks} tasks (${pct}%)`)));
+        if (options.telemetry || telemetry.summary.totalTasksCompleted > 0) {
+            // Re-derive the summary in memory so it reflects current rates even before the next write.
+            recomputeTelemetrySummary(telemetry);
+            console.log(formatTelemetrySummary(telemetry, { completedTasks }) + '\n');
+        }
+        else {
+            console.log(pc.dim('\nTip: Run `nativ status --telemetry` for full token, duration, and cost metrics.\n'));
+        }
+    }
+    catch (err) {
+        console.error(pc.red(`✖ Failed to read or parse .ai/master_plan.json: ${err.message}`));
+        process.exitCode = 1;
+    }
+}

package/dist/commands/task.d.ts

@@ -0,0 +1,83 @@
+import { MasterPlan, MasterPlanTask, SubagentType } from '../scanner/types.js';
+import { loadPlan, savePlan, withPlanLock } from '../core/lock-manager.js';
+export { loadPlan, savePlan, withPlanLock };
+export declare function getRoleGuide(assignedSubagent: SubagentType): string;
+export declare function getRecommendedContractSlice(assignedSubagent: SubagentType): string;
+export declare function runTaskList(targetDirArg?: string, options?: {
+    available?: boolean;
+    status?: string;
+    milestone?: string;
+    fastPath?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export declare function runTaskNext(targetDirArg?: string, options?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function runTaskStart(taskId: string, targetDirArg?: string): Promise<void | null>;
+export interface TaskUnlockOptions {
+    /** Why scope enforcement is being lifted; kept in .nativ/unlocks.json. */
+    reason?: string;
+    /** Re-locks the task instead. */
+    revoke?: boolean;
+}
+/**
+ * Lifts role enforcement's target-file scope for one task (emergency escape hatch), or restores it with
+ * --revoke. Contract and secret paths stay protected either way. Deliberately CLI-only and not an MCP
+ * tool: an agent must not be able to remove its own guardrail.
+ */
+export declare function runTaskUnlock(taskId: string, targetDirArg?: string, options?: TaskUnlockOptions): Promise<void>;
+export interface TaskCompleteOptions {
+    notes?: string;
+    skipVerify?: boolean;
+    timeout?: number;
+}
+export declare function runTaskComplete(taskId: string, targetDirArg?: string, options?: TaskCompleteOptions): Promise<void>;
+export declare function runTaskBlock(taskId: string, reason: string, targetDirArg?: string): Promise<void | null>;
+export declare function runTaskEscalate(taskId: string, targetDirArg?: string, options?: {
+    type?: string;
+    details?: string;
+    affected?: string;
+}): Promise<void | null>;
+export declare const FAST_PATH_MILESTONE_NAME = "Fast-Path Tasks";
+export declare function generateNextTaskId(plan: MasterPlan): string;
+export declare function generateNextMilestoneId(plan: MasterPlan): string;
+export interface TaskAddOptions {
+    /** Milestone ID or name; defaults to the active milestone (or the fast-path milestone with fastPath). */
+    milestone?: string;
+    /** Assigned sub-agent (default backend). */
+    agent?: string;
+    /** Verification command run by the `task complete` gatekeeper. */
+    verify?: string;
+    /** Target files, comma-separated or as an array. */
+    files?: string | string[];
+    description?: string;
+    fastPath?: boolean;
+    /** Dependency task IDs, comma-separated or as an array. */
+    deps?: string | string[];
+    notes?: string;
+    json?: boolean;
+}
+export interface TaskAddResult {
+    task: MasterPlanTask;
+    milestoneId: string;
+    milestoneName: string;
+    createdMilestone: boolean;
+    reopenedMilestone: boolean;
+}
+/**
+ * Appends a task to .ai/master_plan.json with an auto-incremented ID.
+ * Routing: --milestone wins; otherwise fast-path tasks go to the fast-path milestone (created on
+ * first use) and planned tasks to the active milestone. Completed milestones are reopened.
+ */
+export declare function runTaskAdd(title: string, targetDirArg?: string, options?: TaskAddOptions): Promise<TaskAddResult | null>;
+export interface ProposePatchOptions {
+    taskId: string;
+    target: 'db_schema' | 'api_contracts';
+    operation: 'ADD' | 'ALTER' | 'DROP' | 'RENAME';
+    path: string;
+    value?: any;
+    reason: string;
+    baseHash?: string;
+    json?: boolean;
+}
+export declare function runTaskProposePatch(targetDirArg: string | undefined, options: ProposePatchOptions): Promise<import("../governor/types.js").GovernorVerdict>;