@boopkit/cli 0.6.12 → 0.6.13

package/README.md

@@ -24,7 +24,8 @@ boop init my-app
 cd my-app
 ```
 
-`boop init` creates the project directory, applies the `web-app` profile, installs capability packages from npm, and scaffolds files into your project — including a `.boop.json` manifest that records what profile and capabilities are installed.
+`boop init` creates the project directory, applies the `web-app` profile, installs capability packages from npm, and scaffolds files into your project — including a `.boop/config.json` manifest that records what profile and capabilities are installed.
+It finishes by committing the scaffold to a new git repository and setting up the project's beads issue tracker in Dolt server mode.
 
 ```bash
 # See what was installed, what's configured, and what to do next
@@ -52,7 +53,9 @@ boop add users-and-accounts
 
 Start simple, grow deliberately. That's the shape of a boop project: a strong starting point you can extend without collecting scaffolding debt.
 
-A **profile** is a named starting point. It defines the kernel (TypeScript config, `package.json`, `src/server.ts`, deployment setup) and a set of default capabilities.
+A **profile** is a named starting point.
+It defines a set of default capabilities, and what `boop init` writes before they are installed:
+either a kernel (TypeScript config, `package.json`, `src/server.ts`, deployment setup) or a `templates/` folder of its own.
 
 A **capability** is a composable feature bundle. Each capability package ships:
 
@@ -67,7 +70,8 @@ Capabilities can declare `requires` relationships (e.g. `users-and-accounts` req
 
 ## Profiles
 
-A profile names a set of capabilities. Two ship today.
+A profile names a set of capabilities.
+Three ship today, and `boop init` can scaffold from two of them.
 
 ### `web-app`
 
@@ -75,7 +79,19 @@ Full-stack web application — Express + Handlebars + Tailwind CSS + PostgreSQL
 
 Ships with application capabilities (`web`, `api`, `services`, `database`), development skills (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`), and the `hello` demo capability.
 
-This is the profile `boop init` scaffolds from — it carries a kernel, so there is an application to write.
+This is the default profile for `boop init`.
+It carries a kernel, so there is an application to write.
+
+### `base`
+
+Planning, writing and issue tracking for a project that isn't an application: setting up an AWS environment, a research project, a migration plan.
+Ships with `project-mgmt`, `product-design` and `skills`, and nothing code-shaped.
+
+It carries no kernel, but it ships its own templates,
+so `boop init my-project --profile base` writes a project with `specs/`, `reference/` and `docs/` folders,
+agent instructions for work whose output is documents and tracked issues,
+and a beads issue tracker ready to use.
+When the project grows code of its own, `boop add coding` brings in the coding skills.
 
 ### `development`
 
@@ -83,7 +99,10 @@ The development capabilities on their own (`coding`, `testing`, `project-mgmt`,
 
 For a project with no application domain boop has anything to say about: a CLI, a library, a data pipeline. Those share no application layers at all, but they are developed the same way.
 
-It carries no kernel — no runtime, no port, no deploy target — so there is nothing for `boop init` to scaffold and `boop init --profile development` is refused. Use it by naming it as the `profile` in an existing project's `.boop/config.json`, or reach for `boop add` on the capabilities you want. Boop's own repository is the first project to declare it.
+It carries neither a kernel nor templates — no runtime, no port, no deploy target, and no files of its own to write —
+so there is nothing for `boop init` to scaffold and `boop init --profile development` is refused.
+Use it by naming it as the `profile` in an existing project's `.boop/config.json`, or reach for `boop add` on the capabilities you want.
+Boop's own repository is the first project to declare it.
 
 List profiles with `boop list profiles`.
 
@@ -173,6 +192,7 @@ Most days you'll use `init`, `add`, and `status`. The rest are there when you ne
 Flags:
 
 - `boop init --no-install` / `boop add --no-install` — skip `npm install`
+- `boop init --no-beads` — skip the scaffold commit and `bd init`, so no git repository, beads database or Dolt server is created
 - `boop add --dry-run` — preview changes without writing
 - `boop update --force` — overwrite locally modified scaffold files (creates `.bak` backups)
 - `boop update --prune` — remove scaffold files no longer shipped by the capability
@@ -214,6 +234,7 @@ Boop itself is light — Node and npm. The other requirements come from whicheve
 - **Node.js 24+** (the `web-app` profile enforces this)
 - **npm** (or any package manager that respects workspaces)
 - **beads (`bd`) 1.1.2+** — if you use the agent workflows or `boop loop`. The tree-building workflows depend on `bd gate` and `bd epic close-eligible` (1.1.x) and on 1.1.2 dependency semantics (plain `blocks` edges; `waits-for` is not used), and `boop loop` needs beads in Dolt server mode. See [beads](https://github.com/gastownhall/beads).
+- **`jq`** — optional, and only for `boop loop`. The loop projects its beads queue read through `jq` to keep it small; without `jq` it warns once and falls back to a larger read that still works. `brew install jq` on macOS.
 - **PostgreSQL** — if the `database` capability is installed
 - **RabbitMQ / CloudAMQP account** — if `background-jobs` is installed
 - **SendGrid account** — if `email` is installed

package/dist/capability-versions.json

@@ -8,7 +8,7 @@
   "@boopkit/cap-hello": "0.4.1",
   "@boopkit/cap-noticeboard": "0.4.1",
   "@boopkit/cap-oauth-client": "0.1.1",
-  "@boopkit/cap-oauth-server": "0.1.0",
+  "@boopkit/cap-oauth-server": "0.1.2",
   "@boopkit/cap-product-design": "0.6.7",
   "@boopkit/cap-project-mgmt": "0.4.9",
   "@boopkit/cap-services": "0.4.2",

package/dist/cli.js

@@ -57,7 +57,8 @@ program
     .argument('<name>', 'Project name')
     .option('-p, --profile <profile>', 'Profile to use', 'web-app')
     .option('--no-install', 'Skip npm install')
-    .action(init_1.runInit);
+    .option('--no-beads', 'Skip bd init, so no beads database or Dolt server is created')
+    .action((name, options) => (0, init_1.runInit)(name, options));
 program
     .command('list')
     .description('List available profiles or capabilities')

package/dist/commands/add.js

@@ -1,12 +1,56 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAdd = runAdd;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const preflight_1 = require("../lib/preflight");
 const execute_1 = require("../lib/execute");
 const interpolate_1 = require("../lib/interpolate");
 const list_1 = require("./list");
 const capability_1 = require("../lib/capability");
+function hasDevScript(projectDir) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf-8'));
+        return Boolean(pkg.scripts?.dev);
+    }
+    catch {
+        return false;
+    }
+}
 function runAdd(capabilityName, options) {
     // 0. Validate capability argument is provided
     if (!capabilityName) {
@@ -110,7 +154,10 @@ function runAdd(capabilityName, options) {
             nextSteps.push({ text: `Run \`npm run ${first}\` — ${desc}` });
         }
     }
-    nextSteps.push({ text: 'Run `npm run dev` to start developing' });
+    // A project with no application code, such as a base scaffold, has no dev script
+    if (hasDevScript(targetDir)) {
+        nextSteps.push({ text: 'Run `npm run dev` to start developing' });
+    }
     if (options.json) {
         console.log(JSON.stringify({
             capability: capabilityName,
@@ -177,7 +224,7 @@ function runAdd(capabilityName, options) {
             console.log(`  ${(0, interpolate_1.interpolate)(pi.verify, vars)}`);
         }
     }
-    else {
+    else if (nextSteps.length > 0) {
         console.log('\nNext steps:');
         for (let i = 0; i < nextSteps.length; i++) {
             console.log(`  ${i + 1}. ${nextSteps[i].text}`);

package/dist/commands/init.d.ts

@@ -1,5 +1,21 @@
 export interface InitOptions {
     profile?: string;
     install?: boolean;
+    beads?: boolean;
 }
-export declare function runInit(name: string, options: InitOptions): void;
+type RunFn = (file: string, args: string[], opts: {
+    cwd: string;
+    stdio: 'inherit' | 'pipe';
+}) => unknown;
+/** Replaceable in tests, so no test runs a real git or `bd init`, or starts a Dolt server. */
+export interface InitDeps {
+    findBdFn?: (projectDir: string) => string | null;
+    execFileSyncFn?: RunFn;
+}
+/**
+ * Locate the bd binary: the project's own install first, because project-mgmt
+ * pins @beads/bd as a devDependency, then whatever is on PATH.
+ */
+export declare function findBd(projectDir: string, searchPath?: string): string | null;
+export declare function runInit(name: string, options: InitOptions, deps?: InitDeps): void;
+export {};

package/dist/commands/init.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBd = findBd;
 exports.runInit = runInit;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -44,9 +45,105 @@ const scaffold_1 = require("../lib/scaffold");
 const project_1 = require("../lib/project");
 const env_1 = require("../lib/env");
 const safe_io_1 = require("../lib/safe-io");
-function runInit(name, options) {
+/**
+ * Locate the bd binary: the project's own install first, because project-mgmt
+ * pins @beads/bd as a devDependency, then whatever is on PATH.
+ */
+function findBd(projectDir, searchPath = process.env.PATH ?? '') {
+    const dirs = [path.join(projectDir, 'node_modules', '.bin'), ...searchPath.split(path.delimiter).filter(Boolean)];
+    for (const dir of dirs) {
+        const candidate = path.join(dir, 'bd');
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // not in this directory — keep looking
+        }
+    }
+    return null;
+}
+function git(run, cwd, args) {
+    return String(run('git', args, { cwd, stdio: 'pipe' })).trim();
+}
+/** The top level of the repository the directory sits inside, or null when it is in none. */
+function findEnclosingRepo(dir, run) {
+    try {
+        return git(run, dir, ['rev-parse', '--show-toplevel']) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Only an identity the user configured counts; git would otherwise invent one from the hostname. */
+function hasGitIdentity(dir, run) {
+    try {
+        return ['user.name', 'user.email'].every(key => git(run, dir, ['config', key]) !== '');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Commit the scaffold in a new repository, so that bd init's commit is the
+ * second one rather than the first, and git status is clean afterwards.
+ * bd init would otherwise create the repository and commit only the files
+ * it touched, leaving the rest of the scaffold untracked.
+ */
+function commitScaffold(targetDir, name, run) {
+    if (!hasGitIdentity(targetDir, run)) {
+        console.error('Warning: Did not commit the scaffold: git has no user.name and user.email configured, and boop does not set them for you. ' +
+            'Set them with git config --global, then commit the scaffold yourself.');
+        return;
+    }
+    try {
+        console.log('\nCommitting the scaffold...');
+        git(run, targetDir, ['init']);
+        git(run, targetDir, ['add', '-A']);
+        git(run, targetDir, ['commit', '-q', '-m', `chore: scaffold ${name} with boop init`]);
+    }
+    catch (err) {
+        console.error(`Warning: Unable to commit the scaffold: ${err.message}`);
+    }
+}
+/** Commit the scaffold, then run `bd init` in the new project; report and return false rather than throw. */
+function initBeads(targetDir, name, args, deps) {
+    const findBdFn = deps.findBdFn ?? findBd;
+    const execFileSyncFn = deps.execFileSyncFn ?? child_process_1.execFileSync;
+    const bd = findBdFn(targetDir);
+    if (!bd) {
+        console.error('Warning: Unable to initialize beads: bd was not found on PATH or in node_modules/.bin. ' +
+            'Install it (npm install, or brew install beads) and run the bd init command below.');
+        return false;
+    }
+    // Observed with bd 1.1.2: inside an enclosing repository, bd init commits its
+    // files into that repository and points its core.hooksPath at a folder that
+    // does not exist, silently disabling the hooks it had.
+    const enclosingRepo = findEnclosingRepo(targetDir, execFileSyncFn);
+    if (enclosingRepo) {
+        console.error(`Warning: Skipped beads setup: the project is inside another git repository, ${enclosingRepo}. ` +
+            'bd init would commit into that repository and redirect its git hooks. ' +
+            'To give the project a repository of its own, run git init and commit the scaffold inside it, then run the bd init command below.');
+        return false;
+    }
+    commitScaffold(targetDir, name, execFileSyncFn);
+    try {
+        console.log('\nInitializing beads...');
+        execFileSyncFn(bd, args, { cwd: targetDir, stdio: 'inherit' });
+        return true;
+    }
+    catch (err) {
+        console.error(`Warning: Unable to initialize beads: ${err.message}`);
+        console.error('The project was scaffolded and left in place; run the bd init command below from inside it.');
+        return false;
+    }
+}
+function runInit(name, options, deps = {}) {
     const profileName = options.profile ?? 'web-app';
     const shouldInstall = options.install !== false;
+    // BOOP_SKIP_BEADS is set for the whole test suite (tests/jest.setup.ts), so the
+    // many tests that run init never start a Dolt server.
+    const shouldInitBeads = options.beads !== false && !process.env.BOOP_SKIP_BEADS;
     // --- Validate ---
     // Guard: project name must not be empty
     if (!name || !name.trim()) {
@@ -55,6 +152,10 @@ function runInit(name, options) {
         return;
     }
     const targetDir = path.resolve(process.cwd(), name);
+    // The name argument can be a path. The project is named after its folder,
+    // because a path is not a valid npm package name, a heading, or a beads
+    // prefix; the raw argument is kept only for messages about the folder.
+    const projectName = path.basename(targetDir);
     // Guard: target directory must not exist or must be empty
     if (fs.existsSync(targetDir)) {
         const entries = fs.readdirSync(targetDir);
@@ -71,21 +172,22 @@ function runInit(name, options) {
         process.exitCode = 1;
         return;
     }
-    // --- Guard: a profile with no kernel has no application to scaffold ---
-    // `boop init` exists to write a running project from kernel templates. A
-    // profile that names only development capabilities (profiles/development/)
-    // has no runtime, port or deploy target to render them with, so refuse here
-    // rather than emit a project that cannot start.
-    if (!profile.kernel) {
-        console.error(`Error: Profile "${profileName}" carries no kernel, so there is nothing to scaffold.`);
+    // --- Guard: a profile needs a kernel or templates of its own to scaffold ---
+    // The kernel templates render a running application, so a profile with no
+    // kernel (profiles/development/) has no runtime, port or deploy target to
+    // render them with. A kernel-less profile that ships its own templates/
+    // (profiles/base/) renders those instead; one with neither is refused here
+    // rather than emitting a project that cannot start.
+    const kernel = profile.kernel;
+    if (!kernel && !(0, scaffold_1.profileHasTemplates)(profileName)) {
+        console.error(`Error: Profile "${profileName}" carries neither a kernel nor a templates/ folder, so there is nothing to scaffold.`);
         console.error('It declares capabilities for a project that already exists: name it as the "profile" in that');
         console.error(`project's .boop/config.json, or run \`boop add\` for the capabilities you want.`);
         process.exitCode = 1;
         return;
     }
-    const kernel = profile.kernel;
-    // --- Node version check ---
-    const requiredNodeVersion = kernel.nodeVersion;
+    // --- Node version check (a profile with no kernel names no runtime to check) ---
+    const requiredNodeVersion = kernel?.nodeVersion;
     if (requiredNodeVersion && !process.env.BOOP_SKIP_VERSION_CHECK) {
         const minVersion = requiredNodeVersion.replace(/^[>=^~]+/, '');
         const currentMajor = parseInt(process.versions.node.split('.')[0], 10);
@@ -138,18 +240,23 @@ function runInit(name, options) {
     }
     // --- Scaffold kernel ---
     const variables = {
-        projectName: name,
-        port: kernel.port,
-        scripts: kernel.scripts,
-        nodeVersion: kernel.nodeVersion ?? '>=18.0.0',
+        projectName,
+        ...(kernel && {
+            port: kernel.port,
+            scripts: kernel.scripts,
+            nodeVersion: kernel.nodeVersion ?? '>=18.0.0',
+        }),
         ...hookVars,
     };
-    const kernelFiles = (0, scaffold_1.scaffoldKernel)(targetDir, variables);
+    const templatesDir = (0, scaffold_1.getTemplatesDir)(profileName);
+    const kernelFiles = (0, scaffold_1.scaffoldKernel)(targetDir, variables, false, templatesDir);
     // --- Merge kernel dependencies ---
-    (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
+    if (kernel) {
+        (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
+    }
     // --- Create minimal manifest so capability hash storage can find config.json ---
     (0, project_1.writeProjectManifest)(targetDir, {
-        name,
+        name: projectName,
         profile: profileName,
         boopVersion: '0.1.0',
         capabilities: [],
@@ -193,10 +300,12 @@ function runInit(name, options) {
         variables.hookInit = hookVars.hookInit;
         variables.hookPreRoutes = hookVars.hookPreRoutes;
         variables.hookPostRoutes = hookVars.hookPostRoutes;
-        (0, scaffold_1.scaffoldKernel)(targetDir, variables, true);
+        (0, scaffold_1.scaffoldKernel)(targetDir, variables, true, templatesDir);
         // Re-scaffolding overwrites package.json (template has empty deps),
         // so re-merge kernel deps + cap package deps that were added earlier.
-        (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
+        if (kernel) {
+            (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
+        }
         (0, scaffold_1.mergePackageJson)(targetDir, undefined, undefined, capDeps, { skipBackup: true });
     }
     // Post-install conflict check (when preflight was deferred)
@@ -294,12 +403,12 @@ function runInit(name, options) {
     }
     // --- Generate .env and .env.example ---
     if (envEntries.length > 0) {
-        (0, env_1.generateEnvFiles)(targetDir, envEntries, name);
+        (0, env_1.generateEnvFiles)(targetDir, envEntries, projectName);
     }
     // --- Write final manifest, preserving capabilityMeta from hash storage ---
     const existingManifest = (0, project_1.readProjectManifest)(targetDir);
     const manifest = {
-        name,
+        name: projectName,
         profile: profileName,
         boopVersion: '0.1.0',
         capabilities: installedCapabilities,
@@ -309,10 +418,10 @@ function runInit(name, options) {
     };
     (0, project_1.writeProjectManifest)(targetDir, manifest);
     // --- Print summary ---
-    console.log(`\nCreated project "${name}" with profile "${profileName}"\n`);
+    console.log(`\nCreated project "${projectName}" with profile "${profileName}"\n`);
     const scriptCount = Object.keys(allScripts).length;
     const parts = [
-        `${kernelFiles.length} kernel files`,
+        `${kernelFiles.length} ${kernel ? 'kernel' : 'template'} files`,
         `${installedCapabilities.length} capabilities`,
         `${capabilityFiles.length} capability files`,
         ...(scriptCount > 0 ? [`${scriptCount} scripts`] : []),
@@ -375,11 +484,26 @@ function runInit(name, options) {
             }
         }
     }
+    // --- Initialize beads (project-mgmt brings it) ---
+    // Last, because bd init appends to AGENTS.md, CLAUDE.md and .gitignore when
+    // they exist but creates them when they don't, and the templates never
+    // overwrite an existing file. Server mode, because boop loop refuses a
+    // project whose beads runs embedded. Git is touched only here, just before
+    // bd init, because that is when a repository gets created anyway. bd derives
+    // its database name from the prefix.
+    const bdInitArgs = ['init', '--non-interactive', '--server', '-p', projectName];
+    const beadsPending = installedCapabilities.includes('project-mgmt') &&
+        !(shouldInitBeads && initBeads(targetDir, projectName, bdInitArgs, deps));
     console.log(`\nNext steps:`);
     console.log(`  cd ${name}`);
     if (!shouldInstall) {
         console.log('  npm install');
     }
+    if (beadsPending) {
+        console.log(`  bd ${bdInitArgs.join(' ')}`);
+    }
     console.log('  boop status          ← check what needs configuration');
-    console.log('  npm run dev          ← start development server');
+    if (kernel) {
+        console.log('  npm run dev          ← start development server');
+    }
 }

package/dist/commands/loop-merge.d.ts

@@ -39,6 +39,7 @@ export interface MergeDeps {
     execSyncFn?: (cmd: string, opts?: {
         cwd?: string;
         stdio?: unknown;
+        maxBuffer?: number;
     }) => string;
     existsSyncFn?: (p: string) => boolean;
     readFileFn?: (p: string) => string;

package/dist/commands/loop-merge.js

@@ -138,7 +138,9 @@ function defaultBdList(deps) {
     const execSyncFn = deps.execSyncFn || defaultExec;
     return (status) => {
         try {
-            const raw = execSyncFn(`bd list --status=${status} --json 2>/dev/null`);
+            const raw = execSyncFn(`bd list --status=${status} --json 2>/dev/null`, {
+                maxBuffer: loop_1.BD_READ_MAX_BUFFER,
+            });
             return JSON.parse(raw);
         }
         catch {
@@ -150,7 +152,7 @@ function defaultGetParent(deps) {
     const execSyncFn = deps.execSyncFn || defaultExec;
     return (id) => {
         try {
-            const data = JSON.parse(execSyncFn(`bd show ${id} --json 2>/dev/null`));
+            const data = JSON.parse(execSyncFn(`bd show ${id} --json 2>/dev/null`, { maxBuffer: loop_1.BD_READ_MAX_BUFFER }));
             return (data[0] || data).parent || null;
         }
         catch {

package/dist/commands/loop.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Output cap for every `bd … --json` read the loop makes.
+ *
+ * Node's execSync defaults to 1 MiB and throws ENOBUFS past it. `bd ready --json`
+ * returns each issue WITH its full description, and `bd show --children --json`
+ * on a large container is the same trap — a mature backlog crosses 1 MiB and the
+ * read dies. The ready-queue read also projects its output (see
+ * READY_QUEUE_CMD); this cap is the backstop for the reads that cannot (boop-fl22).
+ */
+export declare const BD_READ_MAX_BUFFER: number;
 export interface LoopOptions {
     run?: boolean;
     prefix?: string;
@@ -111,7 +121,7 @@ export declare function writeWorktreeMetadata(ctx: WorktreeContext, meta: {
 interface ReadyIssue {
     id: string;
     issue_type: string;
-    parent?: string;
+    parent?: string | null;
 }
 export declare function buildPlanningPrompt(workContent: string, flowContent: string, prefix?: string): string;
 export type RunClaudeFn = (prompt: string, opts: {
@@ -135,6 +145,7 @@ export declare function planWork(opts: {
     runClaudeFn?: RunClaudeFn;
     execSyncFn?: (cmd: string, opts: {
         encoding: string;
+        maxBuffer?: number;
     }) => string;
 }): Promise<PlanResult>;
 export declare function findFallbackFeature(features: Array<{
@@ -165,7 +176,7 @@ export declare function resolveModel(optionModel: string | undefined, env?: Node
 export declare function shouldResumeUnclosedIssue(status: string | undefined): boolean;
 export declare function isIssueInScope(issue: {
     id: string;
-    parent?: string;
+    parent?: string | null;
 }, prefix: string, getParentById: (id: string) => string | null): boolean;
 /**
  * A workflow-owned feature root is a feature-type issue that owns child tasks
@@ -196,9 +207,17 @@ export declare function shouldCloseFeatureRoot(feature: {
 } | null, children: {
     status: string;
 }[]): boolean;
+/**
+ * Read the ready queue, filtered to what this loop may claim.
+ *
+ * THROWS on a failed read. It must never answer a broken read with an empty
+ * array: the caller treats "no issues" as a clean finish, so a swallowed
+ * failure makes the loop exit 0 with work undone (boop-fl22).
+ */
 export declare function getMatchingReadyIssues(prefix: string, includeFeatures: boolean, deps?: {
     execSyncFn?: (cmd: string, opts: {
         encoding: string;
+        maxBuffer?: number;
     }) => string;
 }): ReadyIssue[];
 /**