@ikarmic/forge-core 5.1.0 → 5.1.1

package/dist/journey/stages.js

@@ -0,0 +1,107 @@
+/**
+ * The six stages of a guided journey.
+ *
+ * A stage is a prompt suffix plus a tool set, which is the point: gating reuses
+ * the sandbox the agent already applies, so "implementation cannot start yet"
+ * is the write tools being absent from the list rather than an instruction the
+ * model may decline. That is the one enforcement mechanism in this design that
+ * a model cannot talk past.
+ *
+ * `allowTools` takes its write-tool names from `FILE_WRITE_TOOL_NAMES` rather
+ * than retyping them: a tool added to that list and missed here would be a
+ * write the Build gate does not cover (RB-13).
+ */
+import { FILE_WRITE_TOOL_NAMES } from '../tools/write-tools.js';
+const READ_TOOLS = ['read_file', 'list_files', 'search_files', 'find_symbol', 'list_symbols', 'find_references'];
+/**
+ * "This stage runs no tools."
+ *
+ * It cannot be `[]`: `applySandbox` treats an empty `allowTools` as *no
+ * whitelist at all*, so an empty list would hand a host-driven stage every
+ * tool, writes included. `vscode/src/chat/modes.ts` already learned this and
+ * carries its own copy of the same trick; this one lives in core so a surface
+ * wiring stages into a sandbox gets the safe value without rediscovering it.
+ */
+export const NO_TOOLS_SENTINEL = '__forge_no_tools__';
+export const STAGES = [
+    {
+        id: 'survey',
+        usesModel: false,
+        promptSuffix: '',
+        allowTools: [NO_TOOLS_SENTINEL],
+        artefact: 'survey facts',
+        gateOptions: [],
+    },
+    {
+        id: 'interview',
+        usesModel: false,
+        promptSuffix: '',
+        allowTools: [NO_TOOLS_SENTINEL],
+        artefact: 'interview answers',
+        gateOptions: [],
+    },
+    {
+        id: 'plan',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'PLAN STAGE — state the plan and stop.',
+            '- Produce a short numbered plan of the work, grounded in what you can read.',
+            '- You cannot ask questions at this stage: the interview is over. Where something',
+            '  is genuinely undecided, state it as an assumption in the plan.',
+            '- Do not write or change any file.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS],
+        artefact: 'a plan, in chat',
+        gateOptions: ['Approve the plan', 'Revise it', 'Skip to the spec'],
+    },
+    {
+        id: 'spec',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'SPEC STAGE — produce exactly two sections and stop.',
+            '- `## requirements.md` then `## design.md`, each starting with its own heading line.',
+            '- Inside a section use `###` or deeper for headings: any `##` line ends the section.',
+            '- Requirements: user stories with EARS-syntax acceptance criteria, e.g. "WHEN <trigger> THE SYSTEM SHALL <response>".',
+            '  Number each requirement (1, 2, 3, ...) and its criteria (1.1, 1.2, ...) so the implementation plan can cite them.',
+            '- Design: ground it in what you read: data flow, schemas, interfaces, API endpoints, and the existing patterns to follow.',
+            '- The implementation plan is a separate stage: do not write tasks here.',
+            '- You cannot write files at this stage. Reply with the sections as text, with no preamble and no closing summary.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS],
+        artefact: 'requirements.md, design.md',
+        gateOptions: ['Approve the spec', 'Revise it'],
+    },
+    {
+        id: 'implPlan',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'IMPLEMENTATION PLAN STAGE — produce `## tasks.md` and stop.',
+            '- A markdown checklist: "- [ ] 1. Title", subtasks indented as "  - [ ] 1.1 Title".',
+            '- Under each task add a line like "_Requirements: 2.1, 3.2_", citing the requirement numbers you were given.',
+            '- One checkbox per line, never two on a line.',
+            '- You cannot write files at this stage. Reply with the document as text, with no preamble and no closing summary.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS],
+        artefact: 'tasks.md',
+        gateOptions: ['Approve the tasks', 'Revise them'],
+    },
+    {
+        id: 'build',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'BUILD STAGE — do the task you were given and stop at it.',
+            '- Work only on the current task; the next one is gated on the person.',
+            '- Run the project\'s own check when the change could break something.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS, ...FILE_WRITE_TOOL_NAMES, 'run_command'],
+        artefact: 'ticked tasks',
+        gateOptions: ['Continue to the next task', 'Retry this one', 'Skip it', 'Stop', 'Run the rest without asking'],
+    },
+];
+export function stageById(id) {
+    return STAGES.find((s) => s.id === id);
+}

package/dist/journey/survey.d.ts

@@ -0,0 +1,10 @@
+import type { SurveyFacts } from './types.js';
+/** Ceiling on the tree walk, so a monorepo costs the same as a small repo. */
+export declare const MAX_SURVEY_FILES = 400;
+/** Second ceiling: a tree of mostly empty or non-source directories is bounded too. */
+export declare const MAX_SURVEY_DIRS = 2000;
+/**
+ * Read what this workspace already says about itself. Never throws: a fact that
+ * cannot be read is absent.
+ */
+export declare function surveyWorkspace(cwd: string, request: string): Promise<SurveyFacts>;

package/dist/journey/survey.js

@@ -0,0 +1,203 @@
+/**
+ * The Survey: what the workspace already answers, read before anyone is asked
+ * anything.
+ *
+ * There is no model here, by design (spec decision 18). A survey fact that a
+ * model produced could be hallucinated, and the asymmetry is brutal: a missing
+ * fact costs one extra interview question, while a wrong fact is a confident
+ * silent guess. Everything below is a file read, each one independently
+ * guarded, so an unreadable or hostile workspace yields absent facts rather
+ * than wrong ones or an exception.
+ *
+ * Nothing here decides "greenfield" or "brownfield". It reports facts; the
+ * question set is derived from which of them came back empty.
+ */
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { isOutsideRel } from '../tools/shared.js';
+import { detectProjectChecks } from '../verify/detect.js';
+/** Ceiling on the tree walk, so a monorepo costs the same as a small repo. */
+export const MAX_SURVEY_FILES = 400;
+/** Second ceiling: a tree of mostly empty or non-source directories is bounded too. */
+export const MAX_SURVEY_DIRS = 2000;
+const MANIFESTS = ['package.json', 'Cargo.toml', 'pyproject.toml', 'go.mod', 'pom.xml', 'Gemfile', 'composer.json'];
+const CONVENTION_FILES = ['AGENTS.md', 'CLAUDE.md'];
+const SOURCE_EXT = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.rb', '.php', '.cs', '.kt', '.swift',
+]);
+const IGNORE_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', '.next', 'coverage', 'target', 'vendor', '__pycache__', '.venv',
+]);
+const STOPWORDS = new Set([
+    'add', 'the', 'and', 'this', 'our', 'for', 'with', 'from', 'into', 'build', 'create', 'make', 'need', 'want',
+    'support', 'existing', 'that', 'them', 'app', 'repo', 'project', 'please', 'also', 'new',
+]);
+const MAX_RELATED = 20;
+/**
+ * True when `name` inside `root` resolves to something still inside `root`.
+ * A repository can ship a symlink or junction, so the check resolves links on
+ * both sides and tests the relative path with `isOutsideRel` (RB-20).
+ */
+function containedIn(root, name) {
+    try {
+        const realRoot = realpathSync(root);
+        const realTarget = realpathSync(path.join(root, name));
+        return !isOutsideRel(path.relative(realRoot, realTarget));
+    }
+    catch {
+        return false;
+    }
+}
+function firstContainedManifest(cwd) {
+    return MANIFESTS.find((m) => containedIn(cwd, m));
+}
+/**
+ * History, read rather than run: a ref anywhere under `refs/heads`, or a
+ * packed-refs file. Branch names nest (`refs/heads/user/feature/x`), so each
+ * directory's children are joined to *that* directory, and a single unreadable
+ * directory skips rather than ending the scan.
+ */
+function hasCommits(cwd) {
+    const git = path.join(cwd, '.git');
+    try {
+        // A worktree or submodule has `.git` as a file holding `gitdir: …`. Following
+        // it would mean parsing a path out of another repo's layout; a worktree only
+        // exists for a repo that already has history, so take that as the answer.
+        if (statSync(git).isFile())
+            return true;
+    }
+    catch {
+        return false;
+    }
+    if (existsSync(path.join(git, 'packed-refs')))
+        return true;
+    const stack = [path.join(git, 'refs', 'heads')];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory())
+                stack.push(path.join(dir, e.name));
+            else
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Repo-relative source paths, breadth-first, bounded, never entering an ignored
+ * directory.
+ *
+ * The directory is tracked explicitly rather than read from the `Dirent`
+ * parent-directory property: that one arrived in Node 20.12 / 18.20, and this
+ * also runs in the VS Code extension host, which ships older Node across the
+ * supported `engines.vscode` range. A fallback there would build paths that do
+ * not exist, and the walk would quietly see only the top level — reporting
+ * *wrong* facts, which is the one thing this file promises never to do.
+ * `journey-survey.test.ts` forbids that identifier here, prose included, since
+ * the mistake cannot fail on a developer's newer Node.
+ *
+ * Directories visited are capped as well as files, so a huge non-source tree
+ * outside `IGNORE_DIRS` cannot make this walk unbounded on the editor's thread.
+ */
+function sourceFiles(cwd) {
+    const out = [];
+    const queue = [cwd];
+    let visited = 0;
+    while (queue.length > 0 && out.length < MAX_SURVEY_FILES && visited < MAX_SURVEY_DIRS) {
+        const dir = queue.shift();
+        visited += 1;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (out.length >= MAX_SURVEY_FILES)
+                break;
+            const abs = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!IGNORE_DIRS.has(e.name))
+                    queue.push(abs);
+            }
+            else if (SOURCE_EXT.has(path.extname(e.name))) {
+                out.push(path.relative(cwd, abs));
+            }
+        }
+    }
+    return out;
+}
+/** Source paths whose name mentions a noun from the request. Deterministic, no index needed. */
+function relatedTo(request, files) {
+    const tokens = [...new Set((request.toLowerCase().match(/[a-z][a-z0-9-]{2,}/g) ?? []).filter((w) => !STOPWORDS.has(w)))];
+    if (tokens.length === 0)
+        return [];
+    const hits = files.filter((f) => {
+        const lower = f.toLowerCase();
+        return tokens.some((tok) => lower.includes(tok));
+    });
+    return hits.slice(0, MAX_RELATED);
+}
+function presentFiles(cwd, names) {
+    return names.filter((n) => containedIn(cwd, n));
+}
+function priorSpecIds(cwd) {
+    try {
+        return readdirSync(path.join(cwd, '.forge', 'specs'), { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read what this workspace already says about itself. Never throws: a fact that
+ * cannot be read is absent.
+ */
+export async function surveyWorkspace(cwd, request) {
+    const facts = {
+        checks: [],
+        isGitRepo: false,
+        hasCommits: false,
+        sourceFileCount: 0,
+        conventionFiles: [],
+        relatedSymbols: [],
+        priorSpecIds: [],
+    };
+    const manifest = firstContainedManifest(cwd);
+    if (manifest) {
+        // Only ask detect.ts about a manifest we have established is inside the
+        // workspace, so a symlinked one is never read for its scripts either.
+        try {
+            const detected = await detectProjectChecks(cwd);
+            facts.checks = detected.checks;
+            facts.manifest = { path: manifest, ...(detected.packageManager ? { packageManager: detected.packageManager } : {}) };
+        }
+        catch {
+            facts.manifest = { path: manifest };
+        }
+    }
+    try {
+        facts.isGitRepo = existsSync(path.join(cwd, '.git'));
+    }
+    catch {
+        facts.isGitRepo = false;
+    }
+    if (facts.isGitRepo)
+        facts.hasCommits = hasCommits(cwd);
+    const files = sourceFiles(cwd);
+    facts.sourceFileCount = files.length;
+    facts.relatedSymbols = relatedTo(request, files);
+    facts.conventionFiles = presentFiles(cwd, CONVENTION_FILES);
+    facts.priorSpecIds = priorSpecIds(cwd);
+    return facts;
+}

package/dist/journey/trigger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tier 1 of the journey trigger: does this message deserve a read-only Survey?
+ *
+ * It decides whether to *look*, not whether to show a card. A false positive
+ * costs a few auto-approved, token-capped reads; a false positive on the card
+ * is the nagging that kills the feature (spec anti-goal 1). So this is
+ * deliberately generous and the vetoes carry the weight.
+ *
+ * Signals are noun-driven, not verb-driven: a change verb on its own trips on
+ * everything ("add a button"), so it only counts beside a noun that implies
+ * many files.
+ */
+import type { TriggerVerdict } from './types.js';
+/**
+ * `typed` is what the person wrote, `sent` what goes to the model. They differ
+ * when a slash command, skill or `@agent` mention expanded into a long body;
+ * judging that text would offer a journey for a one-line request (RB-16).
+ */
+export declare function shouldSurvey(typed: string, sent: string): TriggerVerdict;

package/dist/journey/trigger.js

@@ -0,0 +1,79 @@
+const BUILD_VERBS = /\b(?:build|create|make|develop|scaffold|set up|generate|write me)\b/i;
+const CHANGE_VERBS = /\b(?:add|extend|integrate|migrate|refactor|support|introduce|replace|rework|wire up|hook up|implement)\b/i;
+const SYSTEM_NOUNS = /\b(?:app|application|system|platform|crm|erp|cms|web ?site|api|backend|frontend|dashboard|portal|saas|marketplace|game)\b/i;
+/** Nouns that imply many files rather than one element. */
+const SCALE_NOUNS = /\b(?:module|subsystem|service|integration|pipeline|workflow|migration|multi-?tenancy|auth|authentication|authorisation|authorization|sso|oauth|billing|payments|notifications|search|reporting|analytics|audit log|admin panel|permissions|rbac|onboarding|checkout)\b/i;
+/** Hard vetoes: the person has already told us the scope is small. */
+const SMALL_VERBS = /\b(?:fix|typo|rename|bump|tweak|format|indent|lint|spelling|revert)\b/i;
+const UI_ATOM = /\b(?:button|label|icon|tooltip|placeholder|colour|color|margin|padding|border|font)\b/i;
+const CROSS_CUTTING = /\b(?:across|everywhere|all our|end-to-end|throughout|every (?:page|screen|endpoint))\b/i;
+const PLURAL_DELIVERABLE = /\b(?:pages|endpoints|models|screens|tables|services|roles|reports)\b/i;
+const REQUIREMENT_INTENT = /\b(?:need|want|should|must|would like|let (?:people|users|them|me))\b/i;
+const LONGISH_WORDS = 25;
+const MIN_LIST_SEPARATORS = 3;
+/** Cap before any regex runs, so a pathological message cannot stall the editor. */
+const MAX_INPUT = 4000;
+/**
+ * Technology names that are shaped exactly like filenames. Without this,
+ * "Build me a Next.js SaaS platform" — close to the canonical phrasing of the
+ * flagship scenario — is vetoed as naming a file and silently gets nothing.
+ */
+const TECH_TOKENS = /\b(?:next|node|nuxt|vue|three|d3|express|react|nest|ember|backbone|socket|chart|moment|day)\.(?:js|io|ts)\b/gi;
+/**
+ * A file path or extension means a scoped change, however big the noun beside it.
+ *
+ * Two narrowings against the version in `vscode/src/chat/large-request.ts`:
+ * technology names are removed first, and the extension must be letters, so a
+ * version number ("the 2.0 release") is not a filename.
+ */
+function namesAFile(text) {
+    const withoutTech = text.replace(TECH_TOKENS, ' ');
+    return /[\\/]|\.[a-z]{1,5}\b/i.test(withoutTech.replace(/[.!?]+(?=\s|$)/g, ''));
+}
+function listSeparators(text) {
+    const commasAndAnds = (text.match(/,|\band\b/gi) ?? []).length;
+    const bullets = (text.match(/^\s*(?:[-*•]|\d+[.)])\s/gm) ?? []).length;
+    return commasAndAnds + bullets;
+}
+/**
+ * `typed` is what the person wrote, `sent` what goes to the model. They differ
+ * when a slash command, skill or `@agent` mention expanded into a long body;
+ * judging that text would offer a journey for a one-line request (RB-16).
+ */
+export function shouldSurvey(typed, sent) {
+    const full = typed.trim();
+    if (!full)
+        return { survey: false, reasons: ['empty'] };
+    if (full !== sent.trim())
+        return { survey: false, reasons: ['expanded command'] };
+    if (/^\/\w/.test(full))
+        return { survey: false, reasons: ['slash command'] };
+    if (/(?:^|\s)@\S/.test(full))
+        return { survey: false, reasons: ['@agent mention'] };
+    const t = full.slice(0, MAX_INPUT);
+    if (namesAFile(t))
+        return { survey: false, reasons: ['veto: names a file or path'] };
+    if (SMALL_VERBS.test(t))
+        return { survey: false, reasons: ['veto: small-change verb'] };
+    const reasons = [];
+    const change = CHANGE_VERBS.test(t);
+    if (BUILD_VERBS.test(t) && SYSTEM_NOUNS.test(t))
+        reasons.push('build verb + system noun');
+    if (change && SCALE_NOUNS.test(t))
+        reasons.push('change verb + scale noun');
+    if (change && SYSTEM_NOUNS.test(t))
+        reasons.push('change verb + system noun');
+    if (CROSS_CUTTING.test(t))
+        reasons.push('cross-cutting scope');
+    if (change && PLURAL_DELIVERABLE.test(t))
+        reasons.push('plural deliverables');
+    if (t.split(/\s+/).length >= LONGISH_WORDS && REQUIREMENT_INTENT.test(t) && listSeparators(t) >= MIN_LIST_SEPARATORS) {
+        reasons.push('long multi-requirement message');
+    }
+    if (reasons.length === 0)
+        return { survey: false, reasons: ['no scope signal'] };
+    // One UI element with a single weak signal is a scoped edit, not a subsystem.
+    if (UI_ATOM.test(t) && reasons.length < 2)
+        return { survey: false, reasons: ['veto: single UI element'] };
+    return { survey: true, reasons };
+}

package/dist/journey/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared types for the guided journey. Types only, no logic, so every other
+ * file in `journey/` can import this one without a cycle.
+ *
+ * Design: docs/superpowers/specs/2026-10-23-guided-journey-design.md (rev 3)
+ */
+import type { DetectedCheck } from '../verify/detect.js';
+/** Tier-1 verdict: whether a read-only Survey is worth running, and why. */
+export interface TriggerVerdict {
+    survey: boolean;
+    /** Human-readable signals or vetoes; the offer card shows these. */
+    reasons: string[];
+}
+/**
+ * What the Survey read. Every field is absent or empty when it was not read —
+ * never guessed. There is deliberately no greenfield/brownfield flag: a
+ * workspace that is half-scaffolded is neither, and a label would have to lie
+ * about it. `journey-questions.test.ts` forbids that identifier anywhere under
+ * `src/`, prose included, which is why this note spells it out in words.
+ */
+export interface SurveyFacts {
+    manifest?: {
+        path: string;
+        packageManager?: string;
+    };
+    checks: DetectedCheck[];
+    isGitRepo: boolean;
+    hasCommits: boolean;
+    sourceFileCount: number;
+    conventionFiles: string[];
+    relatedSymbols: string[];
+    priorSpecIds: string[];
+}
+/** Tier-2 decision, with the evidence that earns the card. */
+export interface JourneyOffer {
+    offer: boolean;
+    evidence: string[];
+}
+/**
+ * One interview question. `answeredBy` is the precondition: when it returns a
+ * value, the Survey already answered this and the question is never asked.
+ */
+export interface InterviewQuestion {
+    id: string;
+    question: string;
+    options?: string[];
+    multiSelect?: boolean;
+    answeredBy: (facts: SurveyFacts) => string | undefined;
+}
+/** A question the person answered, carried into the system prompt. */
+export interface Answer {
+    id: string;
+    question: string;
+    answer: string;
+}
+export type StageId = 'survey' | 'interview' | 'plan' | 'spec' | 'implPlan' | 'build';
+export interface Stage {
+    id: StageId;
+    /** Survey and Interview are host-driven and run no model at all. */
+    usesModel: boolean;
+    promptSuffix: string;
+    allowTools: readonly string[];
+    artefact: string;
+    gateOptions: readonly string[];
+}
+export interface JourneyState {
+    /** `'done'` once the journey is over, including when a saved stage id is unknown. */
+    current: StageId | 'done';
+    answers: Answer[];
+    /** Index into the approved `tasks.md` during the Build stage. */
+    taskCursor: number;
+}

package/dist/journey/types.js

@@ -0,0 +1 @@
+export {};

package/dist/skills/builtin.js

@@ -51,7 +51,7 @@ ${keys}
 1. Read the file first. If it does not exist, create it with only the keys you are setting.
 2. Change only what was asked. Keep every other key and keep the file valid JSON (double quotes, no trailing commas, no comments).
 3. A secret never goes in a project file. Name an environment variable (\`apiKeyEnv\`) instead of pasting a key.
-4. Do not widen permissions (\`autoApproveTools\`, \`permission\` allow rules, \`autoApproveCommands\`) unless the user asked for exactly that, and say what the change allows.
+4. Do not widen permissions (\`autoApproveTools\`, \`permission\` allow rules, \`autoApproveCommands\`) unless the user named what to allow. A general request such as "make the prompts go away" or "allow everything" names nothing: do not write it, and never grant \`run_command\`, \`write_file\`, \`edit_file\`, \`apply_patch\` or \`sub_agent\` because of it. Say in one sentence why, then offer the narrow forms: allow one named tool, or choose "Always allow" on a specific command when its card appears. When you do widen, say what the change allows.
 5. After saving, say what changed and where. Most changes apply on the next message; \`caCertificates\` and the language need a window reload, MCP servers and skills need \`/reload\`.
 6. Do not run Forge commands that write to the real \`~/.forge\` to test a change. Edit the file and let the user check it.
 `;

package/dist/specs/generate.d.ts

@@ -12,15 +12,24 @@
 import type { SpecSections } from './types.js';
 /** Read-only tools exposed to the model during spec-mode generation. */
 export declare const SPEC_READONLY_TOOLS: readonly string[];
+export declare function splitSpecSections(raw: string): SpecSections;
+/**
+ * The Spec stage's two documents. Returns **only** those two keys: a model that
+ * volunteers a `## tasks.md` section despite being told not to must not be able
+ * to smuggle it into a draft, because the person has not reached the
+ * implementation-plan gate yet.
+ */
+export declare function splitRequirementsDesign(raw: string): {
+    requirements: string;
+    design: string;
+};
 /**
- * Split a spec-mode run's final text into its three sections. Each
- * section is introduced by a `## <file>.md` markdown heading (case-
- * insensitive, arbitrary surrounding whitespace); the body runs until
- * the next matching heading or end of text. Section order in `raw`
- * does not matter.
+ * The ImplPlan stage's single document.
  *
- * Throws when any of the three expected headings is missing: callers
- * should surface this as a generation failure rather than write partial
- * or malformed files.
+ * Throws when the reply holds no task at all: an empty body or a prose-only
+ * "Plan is complete." would otherwise be written by `writeDraftTasks` and then
+ * approved, because `approveDraft` only checks that the file exists — leaving a
+ * spec with nothing to run, which is the very outcome that guard exists to
+ * prevent. Failing generation here sends the journey back to "Revise".
  */
-export declare function splitSpecSections(raw: string): SpecSections;
+export declare function splitTasksSection(raw: string): string;