@njeybe/nativ 2.8.0 → 2.9.1

package/dist/core/milestone-archive.js

@@ -0,0 +1,299 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { parseJsonLoose } from './enforcement.js';
+import { loadPlan, savePlan, withFileLock, writeJsonAtomicSync } from './lock-manager.js';
+import { resolveMainRoot } from './root-resolver.js';
+import { executeVerification } from './verifier/executor.js';
+import { digestOutput } from './verifier/output-digest.js';
+import { loadEscalationFile } from '../governor/store.js';
+import { resolveGitHead } from '../governor/test-integrity.js';
+import { CHECK_OVERRIDE_NAMES, } from '../scanner/types.js';
+export const DEFAULT_SUITE_TIMEOUT_MS = 600_000;
+/** An expected "no": the message is written for the person running the command. */
+export class ArchiveRefusal extends Error {
+}
+/** Ids of tasks moved out to archive files; they count as existing, completed tasks. */
+export function archivedTaskIds(plan) {
+    return plan.milestones.flatMap((m) => m.archived?.taskIds ?? []);
+}
+/** The plan as dependency checks should see it: archived tasks appear as completed. */
+export function withArchivedAsDone(plan) {
+    const tasks = archivedTaskIds(plan).map((id) => ({ id, status: 'completed' }));
+    const done = { id: '', name: '', status: 'completed', tasks };
+    return { ...plan, milestones: [...plan.milestones, done] };
+}
+const planPathOf = (targetDir) => path.join(targetDir, '.ai', 'master_plan.json');
+const archiveFile = (targetDir, id) => path.join(targetDir, '.ai', 'archive', `${id}.json`);
+const configFile = (targetDir) => path.join(resolveMainRoot(targetDir), '.nativ', 'config.json');
+function assertSafeId(id) {
+    if (!/^[\w-][\w.-]*$/.test(id)) {
+        throw new ArchiveRefusal(`"${id}" is not a valid milestone id.`);
+    }
+}
+function readConfig(targetDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(configFile(targetDir), 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return {};
+        throw new ArchiveRefusal(`.nativ/config.json cannot be read (${err?.message}).`);
+    }
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = parseJsonLoose(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        // Reported below, same as valid JSON of the wrong shape.
+    }
+    throw new ArchiveRefusal('.nativ/config.json is not a valid JSON object. Fix it first.');
+}
+/** The suite to run: --check wins over the saved regressionCommand. */
+function resolveSuite(targetDir, check) {
+    const raw = check ?? readConfig(targetDir).regressionCommand;
+    const command = typeof raw === 'string' ? raw.trim() : '';
+    if (!command) {
+        throw new ArchiveRefusal('No test suite is set. Pass --check "<command>" once (it is saved), '
+            + 'or set "regressionCommand" in .nativ/config.json.');
+    }
+    if (['none', 'skip'].includes(command.toLowerCase())) {
+        throw new ArchiveRefusal(`"${command}" runs no tests, so it cannot protect an archive.`);
+    }
+    if (CHECK_OVERRIDE_NAMES.test(command)) {
+        throw new ArchiveRefusal('The check command must not set NATIV_CI_OVERRIDE or NATIV_HEADLESS_OVERRIDE.');
+    }
+    return command;
+}
+/** Tracked files with changes, leaving out nativ's own folders; null when git cannot tell. */
+function dirtyTrackedFiles(targetDir) {
+    const args = [
+        'status', '--porcelain', '--untracked-files=no', '--', '.', ':(exclude).ai', ':(exclude).nativ',
+    ];
+    const res = spawnSync('git', args, { cwd: targetDir, encoding: 'utf8' });
+    if (res.status !== 0)
+        return null;
+    return res.stdout.split('\n').map((line) => line.slice(3).trim()).filter(Boolean);
+}
+function assertTreeClean(targetDir, inRepo) {
+    const dirty = dirtyTrackedFiles(targetDir);
+    if (dirty === null && inRepo) {
+        throw new ArchiveRefusal('Could not read the git status of this project.');
+    }
+    if (dirty?.length) {
+        const names = dirty.slice(0, 5).join(', ');
+        throw new ArchiveRefusal(`Tracked code has uncommitted changes: ${names}. Commit first.`);
+    }
+}
+function assertArchivable(plan, id, targetDir) {
+    const milestone = plan.milestones.find((m) => m.id === id);
+    if (!milestone)
+        throw new ArchiveRefusal(`Milestone "${id}" not found.`);
+    if (milestone.archived)
+        throw new ArchiveRefusal(`Milestone ${id} is already archived.`);
+    if (!milestone.tasks.length)
+        throw new ArchiveRefusal(`Milestone ${id} has no tasks to archive.`);
+    const open = milestone.tasks.filter((t) => t.status !== 'completed').map((t) => t.id);
+    if (open.length) {
+        throw new ArchiveRefusal(`Milestone ${id} has unfinished tasks: ${open.join(', ')}.`);
+    }
+    const taskIds = new Set(milestone.tasks.map((t) => t.id));
+    const escalated = loadEscalationFile(targetDir, plan.projectName).escalations
+        .filter((e) => e && taskIds.has(e.taskId) && (!e.status || e.status === 'pending_review'))
+        .map((e) => e.id);
+    if (escalated.length) {
+        const names = escalated.join(', ');
+        throw new ArchiveRefusal(`Milestone ${id} has open escalations: ${names}. Settle them first.`);
+    }
+    return milestone;
+}
+function assertRequest(ids, summaries) {
+    if (!ids.length)
+        throw new ArchiveRefusal('Name at least one milestone to archive.');
+    ids.forEach(assertSafeId);
+    const missing = ids.filter((id) => typeof summaries[id] !== 'string' || !summaries[id].trim());
+    if (missing.length) {
+        throw new ArchiveRefusal(`A summary is required for: ${missing.join(', ')}.`);
+    }
+}
+async function runSuite(command, targetDir, timeout) {
+    const result = await executeVerification(command, targetDir, timeout);
+    if (result.success)
+        return;
+    const detail = digestOutput(`${result.stdout}\n${result.stderr}`.trim(), 15);
+    throw new ArchiveRefusal(`The test suite failed: ${result.error ?? command}\n${detail}`);
+}
+/** Writes the archive and proves it can be read back whole; the plan depends on this. */
+function writeConfirmed(file, milestone, readBack) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeJsonAtomicSync(file, milestone);
+    if (JSON.stringify(JSON.parse(readBack(file))) !== JSON.stringify(milestone)) {
+        throw new Error('the file read back does not match the milestone');
+    }
+}
+/** A file that is not there (or whose folder is a plain file) is already removed. */
+const isAbsent = (err) => err?.code === 'ENOENT' || err?.code === 'ENOTDIR';
+/** Tries every file; rethrows the first real error only after all were attempted. */
+function removeArchives(files, remove = (f) => fs.rmSync(f, { force: true })) {
+    let failure = null;
+    for (const file of files) {
+        try {
+            remove(file);
+        }
+        catch (err) {
+            if (!isAbsent(err) && failure === null)
+                failure = err;
+        }
+    }
+    if (files.length) {
+        try {
+            fs.rmdirSync(path.dirname(files[0]));
+        }
+        catch {
+            // Other archives are still in the folder.
+        }
+    }
+    if (failure !== null)
+        throw failure;
+}
+function toStub(milestone, summary, check, commit) {
+    const archived = {
+        summary: summary.trim(),
+        commit,
+        check,
+        archivedAt: new Date().toISOString(),
+        taskCount: milestone.tasks.length,
+        taskIds: milestone.tasks.map((t) => t.id),
+        file: `.ai/archive/${milestone.id}.json`,
+    };
+    return { ...milestone, status: 'completed', tasks: [], archived };
+}
+function moveActiveOffArchived(plan) {
+    const active = plan.milestones.find((m) => m.id === plan.activeMilestoneId);
+    if (!active?.archived)
+        return;
+    const open = plan.milestones.find((m) => !m.archived && m.status !== 'completed');
+    if (open)
+        plan.activeMilestoneId = open.id;
+}
+/** Under the plan lock: archive files first, confirmed, and only then the plan. */
+function commitArchive(plan, request, suite, commit, targetDir, deps) {
+    const readBack = deps.readBack ?? ((f) => fs.readFileSync(f, 'utf8'));
+    const written = [];
+    const archived = [];
+    try {
+        for (const id of request.ids) {
+            const milestone = assertArchivable(plan, id, targetDir);
+            const file = archiveFile(targetDir, id);
+            written.push(file);
+            writeConfirmed(file, milestone, readBack);
+            const stub = toStub(milestone, request.summaries[id], suite, commit);
+            plan.milestones[plan.milestones.indexOf(milestone)] = stub;
+            archived.push({ id, file: stub.archived.file, taskCount: stub.archived.taskCount });
+        }
+        moveActiveOffArchived(plan);
+        if (!(deps.save ?? savePlan)(planPathOf(targetDir), plan)) {
+            throw new Error('the plan could not be saved');
+        }
+    }
+    catch (err) {
+        let message = err instanceof ArchiveRefusal
+            ? err.message
+            : `Nothing was archived, the plan is unchanged: ${err?.message}.`;
+        try {
+            removeArchives(written, deps.remove);
+        }
+        catch (cleanup) {
+            message += ` Some archive files could not be removed: ${cleanup?.message}.`;
+        }
+        throw new ArchiveRefusal(message);
+    }
+    return { archived, activeMilestoneId: plan.activeMilestoneId, commit, warnings: [] };
+}
+function saveSuite(targetDir, command) {
+    try {
+        const config = { ...readConfig(targetDir), regressionCommand: command };
+        writeJsonAtomicSync(configFile(targetDir), config);
+        return [];
+    }
+    catch (err) {
+        return [`The archive is done, but --check was not saved: ${err?.message}`];
+    }
+}
+function loadOrRefuse(planPath) {
+    const plan = loadPlan(planPath);
+    if (!plan)
+        throw new ArchiveRefusal('.ai/master_plan.json could not be read.');
+    return plan;
+}
+/** Refuses without side effects, runs the suite once outside the lock, then re-checks and commits. */
+export async function archiveMilestones(targetDir, request, deps = {}) {
+    const timeout = request.timeout ?? DEFAULT_SUITE_TIMEOUT_MS;
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new ArchiveRefusal('--timeout must be a positive number.');
+    }
+    const ids = [...new Set(request.ids)];
+    assertRequest(ids, request.summaries);
+    const planPath = planPathOf(targetDir);
+    const before = loadOrRefuse(planPath);
+    ids.forEach((id) => assertArchivable(before, id, targetDir));
+    const commit = resolveGitHead(targetDir);
+    assertTreeClean(targetDir, commit !== null);
+    const suite = resolveSuite(targetDir, request.check);
+    // The lock stays free during the long suite, so everything is checked again once it is held.
+    await runSuite(suite, targetDir, timeout);
+    const result = await withFileLock(planPath, () => {
+        assertTreeClean(targetDir, commit !== null);
+        if (resolveGitHead(targetDir) !== commit) {
+            throw new ArchiveRefusal('HEAD moved while the suite ran. Run the command again.');
+        }
+        const plan = loadOrRefuse(planPath);
+        return commitArchive(plan, { ...request, ids }, suite, commit, targetDir, deps);
+    });
+    return { ...result, warnings: request.check !== undefined ? saveSuite(targetDir, suite) : [] };
+}
+function readArchive(targetDir, id, expected) {
+    let saved;
+    try {
+        saved = JSON.parse(fs.readFileSync(archiveFile(targetDir, id), 'utf8'));
+    }
+    catch (err) {
+        throw new ArchiveRefusal(`The archive file of ${id} cannot be read (${err?.message}). The plan is unchanged.`);
+    }
+    const taskIds = Array.isArray(saved?.tasks) ? saved.tasks.map((t) => t.id) : null;
+    if (saved?.id !== id || JSON.stringify(taskIds) !== JSON.stringify(expected.taskIds)) {
+        throw new ArchiveRefusal(`The archive file of ${id} does not match the plan. The plan is unchanged.`);
+    }
+    return saved;
+}
+/** Puts the tasks back; the archive file goes only after the plan is safely saved. */
+export async function restoreMilestone(targetDir, id, deps = {}) {
+    assertSafeId(id);
+    const planPath = planPathOf(targetDir);
+    return withFileLock(planPath, () => {
+        const plan = loadOrRefuse(planPath);
+        const index = plan.milestones.findIndex((m) => m.id === id);
+        if (index < 0)
+            throw new ArchiveRefusal(`Milestone "${id}" not found.`);
+        const info = plan.milestones[index].archived;
+        if (!info)
+            throw new ArchiveRefusal(`Milestone ${id} is not archived.`);
+        const saved = readArchive(targetDir, id, info);
+        plan.milestones[index] = saved;
+        if (!(deps.save ?? savePlan)(planPath, plan)) {
+            throw new ArchiveRefusal(`The plan could not be saved. The archive file of ${id} is kept.`);
+        }
+        const warnings = [];
+        try {
+            removeArchives([archiveFile(targetDir, id)]);
+        }
+        catch (err) {
+            warnings.push(`Restored, but the archive file was not removed: ${err?.message}`);
+        }
+        return { id, taskCount: saved.tasks.length, warnings };
+    });
+}

package/dist/core/profiles.d.ts

@@ -6,9 +6,17 @@ export interface ProfileSettings {
     governorMode: 'auto_adopt' | 'guard';
     testIntegrity: 'off' | 'warn' | 'block';
     allowHeadlessBypass: boolean;
+    verifyIsolation: 'none' | 'clean';
+    verifyIsolationFailure: 'warn' | 'block';
+    skippedCheck: 'allow' | 'warn' | 'block';
     description: string;
 }
 export declare const PROFILE_DEFAULTS: Record<NativProfile, ProfileSettings>;
 export declare function loadProfile(root: string): NativProfile;
 export declare function resolveActiveProfileSettings(root: string): ProfileSettings;
 export declare function setProfile(root: string, profile: NativProfile): ProfileSettings;
+export interface VerifySettings {
+    verifyEnv: string[];
+    verifyLinks: string[];
+}
+export declare function loadVerifySettings(root: string): VerifySettings;

package/dist/core/profiles.js

@@ -9,6 +9,9 @@ export const PROFILE_DEFAULTS = {
         governorMode: 'auto_adopt',
         testIntegrity: 'off',
         allowHeadlessBypass: true,
+        verifyIsolation: 'none',
+        verifyIsolationFailure: 'warn',
+        skippedCheck: 'allow',
         description: 'Hackathon & scratchpad mode: frictionless exploration, auto-adopting contracts, and relaxed scope.',
     },
     solo: {
@@ -17,7 +20,11 @@ export const PROFILE_DEFAULTS = {
         governorMode: 'auto_adopt',
         testIntegrity: 'warn',
         allowHeadlessBypass: true,
-        description: 'Single-developer agility: advisory scope warnings, self-evolving contracts, and streamlined execution.',
+        verifyIsolation: 'clean',
+        verifyIsolationFailure: 'warn',
+        skippedCheck: 'warn',
+        description: 'Single-developer agility: advisory scope warnings, self-evolving contracts, '
+            + 'and streamlined execution.',
     },
     enterprise: {
         profile: 'enterprise',
@@ -25,7 +32,11 @@ export const PROFILE_DEFAULTS = {
         governorMode: 'guard',
         testIntegrity: 'block',
         allowHeadlessBypass: false,
-        description: 'Full team rigor: strict contract boundaries, test integrity protection, circuit breakers, and air-gap.',
+        verifyIsolation: 'clean',
+        verifyIsolationFailure: 'block',
+        skippedCheck: 'block',
+        description: 'Full team rigor: strict contract boundaries, test integrity protection, '
+            + 'circuit breakers, and air-gap.',
     },
 };
 const CONFIG_FILE = path.join('.nativ', 'config.json');
@@ -55,6 +66,15 @@ export function resolveActiveProfileSettings(root) {
         if (raw.testIntegrity === 'off' || raw.testIntegrity === 'warn' || raw.testIntegrity === 'block') {
             base.testIntegrity = raw.testIntegrity;
         }
+        if (raw.verifyIsolation === 'none' || raw.verifyIsolation === 'clean') {
+            base.verifyIsolation = raw.verifyIsolation;
+        }
+        if (raw.verifyIsolationFailure === 'warn' || raw.verifyIsolationFailure === 'block') {
+            base.verifyIsolationFailure = raw.verifyIsolationFailure;
+        }
+        if (raw.skippedCheck === 'allow' || raw.skippedCheck === 'warn' || raw.skippedCheck === 'block') {
+            base.skippedCheck = raw.skippedCheck;
+        }
     }
     catch {
         // Keep base defaults
@@ -68,6 +88,27 @@ export function setProfile(root, profile) {
         config.enforcement = profileSettings.enforcement;
         config.governorMode = profileSettings.governorMode;
         config.testIntegrity = profileSettings.testIntegrity;
+        config.verifyIsolation = profileSettings.verifyIsolation;
+        config.verifyIsolationFailure = profileSettings.verifyIsolationFailure;
+        config.skippedCheck = profileSettings.skippedCheck;
     });
     return profileSettings;
 }
+const DEFAULT_VERIFY_LINKS = ['node_modules', '.venv', 'venv'];
+const BLOCKED_ENV = new Set(['CI', 'GITHUB_ACTIONS', 'GITLAB_CI']);
+function stringList(value, fallback) {
+    if (!Array.isArray(value))
+        return fallback;
+    return value.filter((v) => typeof v === 'string' && v.length > 0);
+}
+export function loadVerifySettings(root) {
+    let raw = {};
+    try {
+        raw = parseJsonLoose(fs.readFileSync(path.join(root, CONFIG_FILE), 'utf8'));
+    }
+    catch {
+        // Missing config keeps defaults
+    }
+    const verifyEnv = stringList(raw.verifyEnv, []).filter((n) => !BLOCKED_ENV.has(n) && !n.startsWith('NATIV_'));
+    return { verifyEnv, verifyLinks: stringList(raw.verifyLinks, DEFAULT_VERIFY_LINKS) };
+}

package/dist/core/root-resolver.d.ts

@@ -35,3 +35,7 @@ export declare function linkWorktreeNodeModules(worktreeDir: string, rootDir: st
  * project root are never deleted.
  */
 export declare function safeUnlinkWorktreeNodeModules(worktreeDir: string): boolean;
+/** Links a folder of the project root into a worktree (junction on Windows). */
+export declare function linkWorktreeDir(worktreeDir: string, rootDir: string, name: string): boolean;
+/** Removes only the link, never the folder it points to. */
+export declare function safeUnlinkWorktreeDir(worktreeDir: string, name: string): boolean;

package/dist/core/root-resolver.js

@@ -193,3 +193,35 @@ export function safeUnlinkWorktreeNodeModules(worktreeDir) {
     }
     return false;
 }
+/** Links a folder of the project root into a worktree (junction on Windows). */
+export function linkWorktreeDir(worktreeDir, rootDir, name) {
+    const source = path.join(rootDir, name);
+    const target = path.join(worktreeDir, name);
+    if (!fs.existsSync(source) || fs.existsSync(target))
+        return false;
+    try {
+        fs.symlinkSync(source, target, process.platform === 'win32' ? 'junction' : 'dir');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Removes only the link, never the folder it points to. */
+export function safeUnlinkWorktreeDir(worktreeDir, name) {
+    const target = path.join(worktreeDir, name);
+    try {
+        if (!fs.lstatSync(target).isSymbolicLink())
+            return false;
+        try {
+            fs.unlinkSync(target);
+        }
+        catch {
+            fs.rmdirSync(target);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/setup/gitignore-block.d.ts

@@ -0,0 +1,17 @@
+export declare const BLOCK_START = "# >>> nativ (managed) >>>";
+export declare const BLOCK_END = "# <<< nativ (managed) <<<";
+export type GitVisibility = 'hidden' | 'shared';
+/** Secret and machine-local paths: ignored even when the team shares nativ's files. */
+export declare const SHARED_PATHS: readonly ["/.nativ/*.local.json", "/.nativ/logs/", "/.nativ/*.log", "/.nativ/notify-state.json", "/.worktrees/"];
+/** Root-anchored paths nativ generated in this project, per the git-visibility choice. */
+export declare function listGeneratedPaths(root: string, visibility?: GitVisibility): string[];
+export declare function renderBlock(paths: string[], eol?: string): string;
+/** Inserts or replaces the managed block; text outside it and its line endings stay as they were. */
+export declare function applyBlock(existing: string | null, paths: string[]): string;
+export interface TrackedResult {
+    tracked: string[];
+    /** Command for the human to run; nativ never runs it. */
+    command: string;
+}
+/** Lists generated paths that git already tracks. Non-git folders give an empty list. */
+export declare function trackedNativPaths(root: string, paths: string[]): TrackedResult;

package/dist/core/setup/gitignore-block.js

@@ -0,0 +1,182 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { buildDesiredConfig, isObject } from './config-merger.js';
+import { AGENT_FILES, MCP_SERVER_NAME, managedState } from './types.js';
+export const BLOCK_START = '# >>> nativ (managed) >>>';
+export const BLOCK_END = '# <<< nativ (managed) <<<';
+/** Secret and machine-local paths: ignored even when the team shares nativ's files. */
+export const SHARED_PATHS = [
+    '/.nativ/*.local.json',
+    '/.nativ/logs/',
+    '/.nativ/*.log',
+    '/.nativ/notify-state.json',
+    '/.worktrees/',
+];
+const read = (root, rel) => {
+    try {
+        return fs.readFileSync(path.join(root, rel), 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/** Exactly what older nativ versions wrote for CLAUDE.md / GEMINI.md. */
+function isOldPointer(text) {
+    const lf = text.replace(/\r\n/g, '\n');
+    return ['Claude Code', 'Gemini / Antigravity'].some((t) => lf === `# ${t} directive\n\n@AGENTS.md\n`);
+}
+function isNativOwnedFile(text, allowPointer) {
+    if (text === null)
+        return false;
+    if (managedState(text) !== 'unmanaged')
+        return true;
+    return allowPointer && isOldPointer(text);
+}
+const parseObject = (text) => {
+    if (text === null)
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return isObject(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** nativ's own server entry, for whatever command setup was configured to use. */
+function ownedServer(entry) {
+    if (!isObject(entry) || typeof entry.command !== 'string')
+        return false;
+    if (Object.keys(entry).some((k) => k !== 'command' && k !== 'args'))
+        return false;
+    const args = entry.args;
+    if (!Array.isArray(args) || args.length === 0 || !args.every((a) => typeof a === 'string'))
+        return false;
+    const invocation = { command: entry.command, prefixArgs: args.slice(0, -1), portable: true };
+    const want = buildDesiredConfig(invocation).mcpServer;
+    return sameJson(entry, { command: want.command, args: want.args });
+}
+function onlyNativMcp(root) {
+    const json = parseObject(read(root, '.mcp.json'));
+    if (!json)
+        return false;
+    const keys = Object.keys(json).filter((k) => k !== 'mcpServers');
+    if (keys.length || !isObject(json.mcpServers))
+        return false;
+    const servers = json.mcpServers;
+    const names = Object.keys(servers);
+    return names.length > 0 && names.every((n) => n === MCP_SERVER_NAME && ownedServer(servers[n]));
+}
+/** CLI strings that setup wrote into hook commands; `nativ` is always a candidate. */
+function clisFromHooks(hooks) {
+    const found = new Set(['nativ']);
+    if (!isObject(hooks))
+        return [...found];
+    for (const groups of Object.values(hooks)) {
+        for (const g of Array.isArray(groups) ? groups : []) {
+            for (const h of isObject(g) && Array.isArray(g.hooks) ? g.hooks : []) {
+                const m = isObject(h) ? /^(.+) hook (check|context)$/.exec(String(h.command)) : null;
+                if (m)
+                    found.add(m[1]);
+            }
+        }
+    }
+    return [...found];
+}
+/** The generated config for an already-rendered CLI string (it may hold spaces or quotes). */
+function desiredFor(cli) {
+    const mark = 'CLIMARK';
+    const text = JSON.stringify(buildDesiredConfig({ command: mark, prefixArgs: [], portable: true }));
+    return JSON.parse(text.split(mark).join(JSON.stringify(cli).slice(1, -1)));
+}
+function ownedHooks(hooks, wants) {
+    if (!isObject(hooks))
+        return false;
+    const groupOk = (event, g) => wants.some((want) => {
+        const w = event === 'PreToolUse' ? want.preToolUse : event === 'SessionStart' ? want.sessionStart : null;
+        const hook = w && { type: 'command', command: w.command, timeout: w.timeout };
+        return w !== null && sameJson(g, { matcher: w.matcher, hooks: [hook] });
+    });
+    return Object.entries(hooks).every(([event, groups]) => Array.isArray(groups) && groups.every((g) => groupOk(event, g)));
+}
+// Setup unions entries, so a file may hold those of an older invocation too.
+function ownedPermissions(perms, wants) {
+    if (!isObject(perms))
+        return false;
+    const keys = ['allow', 'deny', 'ask'];
+    return Object.entries(perms).every(([k, v]) => {
+        const key = keys.find((x) => x === k);
+        return key !== undefined && Array.isArray(v) &&
+            v.every((e) => typeof e === 'string' && wants.some((w) => w[key].includes(e)));
+    });
+}
+function onlyNativSettings(root) {
+    const json = parseObject(read(root, '.claude/settings.json'));
+    if (!json)
+        return false;
+    const allowed = new Set(['permissions', 'hooks', 'enabledMcpjsonServers']);
+    if (Object.keys(json).some((k) => !allowed.has(k)))
+        return false;
+    const wants = clisFromHooks(json.hooks).map(desiredFor);
+    if (json.permissions !== undefined && !ownedPermissions(json.permissions, wants))
+        return false;
+    if (json.hooks !== undefined && !ownedHooks(json.hooks, wants))
+        return false;
+    const enabled = json.enabledMcpjsonServers;
+    return enabled === undefined || (Array.isArray(enabled) && enabled.every((s) => s === MCP_SERVER_NAME));
+}
+/** Root-anchored paths nativ generated in this project, per the git-visibility choice. */
+export function listGeneratedPaths(root, visibility = 'hidden') {
+    if (visibility === 'shared')
+        return [...SHARED_PATHS];
+    const paths = ['/.ai/', '/.nativ/', '/.worktrees/'];
+    for (const file of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
+        if (isNativOwnedFile(read(root, file), true))
+            paths.push(`/${file}`);
+    }
+    for (const file of AGENT_FILES) {
+        const rel = `.claude/agents/${file}`;
+        if (isNativOwnedFile(read(root, rel), false))
+            paths.push(`/${rel}`);
+    }
+    if (onlyNativMcp(root))
+        paths.push('/.mcp.json');
+    if (onlyNativSettings(root))
+        paths.push('/.claude/settings.json');
+    return paths;
+}
+export function renderBlock(paths, eol = '\n') {
+    return [BLOCK_START, ...paths, BLOCK_END].join(eol);
+}
+/** Inserts or replaces the managed block; text outside it and its line endings stay as they were. */
+export function applyBlock(existing, paths) {
+    const text = existing ?? '';
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const block = renderBlock(paths, eol);
+    const start = text.indexOf(BLOCK_START);
+    const endAt = start === -1 ? -1 : text.indexOf(BLOCK_END, start);
+    if (start !== -1 && endAt !== -1) {
+        return text.slice(0, start) + block + text.slice(endAt + BLOCK_END.length);
+    }
+    if (text.trim() === '')
+        return block + eol;
+    const sep = text.endsWith('\n') ? eol : eol + eol;
+    return text + sep + block + eol;
+}
+/** Lists generated paths that git already tracks. Non-git folders give an empty list. */
+export function trackedNativPaths(root, paths) {
+    const none = { tracked: [], command: '' };
+    const specs = paths.map((p) => p.replace(/^\//, '')).filter((p) => !p.includes('*'));
+    if (!specs.length)
+        return none;
+    const out = spawnSync('git', ['ls-files', '-z', '--', ...specs], { cwd: root, encoding: 'utf8' });
+    if (out.status !== 0 || !out.stdout)
+        return none;
+    const files = out.stdout.split('\0').filter(Boolean);
+    const tracked = specs.filter((s) => files.some((f) => f === s || f.startsWith(s.endsWith('/') ? s : `${s}/`)));
+    if (!tracked.length)
+        return none;
+    return { tracked, command: `git rm --cached -r -- ${tracked.join(' ')}` };
+}

package/dist/core/setup/pm-playbook.d.ts

@@ -2,4 +2,4 @@
  * The project manager's playbook. The SessionStart hook prints it into the main session only:
  * subagents load CLAUDE.md and AGENTS.md on every turn, so anything kept there is paid for by every worker.
  */
-export declare const PM_PLAYBOOK = "## Working as Project Manager\n\n- Start each session with `nativ task next --json` (or the `nativ_task_next` MCP tool).\n- Delegate, do not implement. Hand each task to the `worker` agent by task id, passing the task's `recommendedModel` (haiku, sonnet or opus) as the Agent tool's `model`; with none, the worker's default applies. Ask the `verifier` agent for an independent check before you mark a milestone done. Ask the `architect` agent for anything that changes a contract.\n- Before the architect designs on existing code, run the `explorer` when `.ai/codebase_map.md` is missing or its commit is well behind `HEAD`, and pass its report to the architect. Give the explorer the current commit (`git rev-parse --short HEAD`); it cannot look it up. Pass `model: haiku` for a single lookup such as \"where is the auth middleware?\".\n- Keep usage low. Run this session on Sonnet. Agent defaults: architect Opus, worker Sonnet, verifier Haiku. Pass `haiku` for mechanical tasks (wording, docs, renames) and `sonnet` for the verifier at the end of a milestone. Never pass a model the human did not choose.\n- Independent tasks can run in parallel in worktrees (`nativ worktree create <taskId>`). On a Claude subscription every agent draws from the same usage limit, so run two or three at a time, not ten.\n- You may not edit `.ai/`. If the enforcement hook warns about a file, that is a scope or contract gap: escalate with `nativ task escalate`, do not edit around it.\n- `nativ doctor` confirms the integration is intact. Run it after updating Claude Code or nativ, and whenever hooks or MCP tools seem to be missing.\n\n## Autonomous execution\n\nWhen told to run autonomously (\"run the queue\", \"execute milestone\", AFK mode):\n1. `nativ_task_next`, then `nativ_task_start`.\n2. Delegate to the `worker` agent with the task id and recommended model.\n3. The worker completes the task itself; `nativ task complete` already ran the check. Do not run `nativ_verify` or `nativ_task_complete` again for it.\n4. Loop to the next task immediately, without asking the human.\n5. Stop only when the milestone is done (ask the `verifier` for a milestone check, then tell the human) or when a task is blocked or escalated (present the four-part summary).\n\n## Talking to the human\n\nThe human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice, then one direct question. Say \"the app tried to link a record to an item that does not exist yet\", not \"foreign key constraint violation\". Never paste stack traces; put raw output in a collapsed `<details>` block.";
+export declare const PM_PLAYBOOK = "## Working as Project Manager\n\n- Start each session with `nativ task next --json` (or the `nativ_task_next` MCP tool).\n- Delegate, do not implement. Hand each task to the `worker` agent by task id, passing the task's `recommendedModel` (haiku, sonnet or opus) as the Agent tool's `model`; with none, the worker's default applies. Ask the `verifier` agent for an independent check before you mark a milestone done. Ask the `architect` agent for anything that changes a contract.\n- Before the architect designs on existing code, run the `explorer` when `.ai/codebase_map.md` is missing or its commit is well behind `HEAD`, and pass its report to the architect. Give the explorer the current commit (`git rev-parse --short HEAD`); it cannot look it up. Pass `model: haiku` for a single lookup such as \"where is the auth middleware?\".\n- Keep usage low. Run this session on Sonnet. Agent defaults: architect Opus, worker Sonnet, verifier Haiku. Pass `haiku` for mechanical tasks (wording, docs, renames) and `sonnet` for the verifier at the end of a milestone. Never pass a model the human did not choose.\n- Independent tasks can run in parallel in worktrees (`nativ worktree create <taskId>`). On a Claude subscription every agent draws from the same usage limit, so run two or three at a time, not ten.\n- You may not edit `.ai/`. If the enforcement hook warns about a file, that is a scope or contract gap: escalate with `nativ task escalate`, do not edit around it.\n- `nativ doctor` confirms the integration is intact. Run it after updating Claude Code or nativ, and whenever hooks or MCP tools seem to be missing.\n\n## Autonomous execution\n\nWhen told to run autonomously (\"run the queue\", \"execute milestone\", AFK mode):\n1. `nativ_task_next`, then `nativ_task_start`.\n2. Delegate to the `worker` agent with the task id and recommended model.\n3. The worker completes the task itself; `nativ task complete` already ran the check. Do not run `nativ_verify` or `nativ_task_complete` again for it.\n4. Loop to the next task immediately, without asking the human.\n5. Stop only when the milestone is done or when a task is blocked or escalated (present the four-part summary).\n\n## Finished milestones\n\n- Ask the `verifier` for the milestone check. If it passes, run `nativ milestone archive <id> --summary \"<one line>\"` (MCP: `nativ_milestone_archive`).\n- Tell the human what was archived, then suggest `/clear`: the plan holds the state, so a fresh context loses nothing.\n- For an old task, use `nativ task show <id>` instead of opening the plan.\n\n## Talking to the human\n\nThe human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice, then one direct question. Say \"the app tried to link a record to an item that does not exist yet\", not \"foreign key constraint violation\". Never paste stack traces; put raw output in a collapsed `<details>` block.";