@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/skills/index.d.ts

@@ -6,6 +6,8 @@
  * internal directory layout.
  */
 export type { Skill, SkillRegistry, SkillRoots, SkillSource } from './types.js';
+export { builtinSkills } from './builtin.js';
+export { loadRemoteSkills } from './remote.js';
 export { GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, discoverSkills, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkillsDir, resolveSkillRoots, skillsRegistryFromList, } from './loader.js';
 export { parseSkill } from './parser.js';
 export { buildSkillsBlock, composeSkillsPrompt, scoreSkill, selectSkills, } from './activator.js';

package/dist/skills/index.js

@@ -5,6 +5,8 @@
  * callers can use skills + the community catalog without knowing the
  * internal directory layout.
  */
+export { builtinSkills } from './builtin.js';
+export { loadRemoteSkills } from './remote.js';
 export { GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, discoverSkills, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkillsDir, resolveSkillRoots, skillsRegistryFromList, } from './loader.js';
 export { parseSkill } from './parser.js';
 export { buildSkillsBlock, composeSkillsPrompt, scoreSkill, selectSkills, } from './activator.js';

package/dist/skills/loader.d.ts

@@ -6,6 +6,7 @@
  * root wins (local > project > global). The result is an immutable
  * snapshot: call {@link reload} to re-read disk.
  */
+import { type RemoteSkillOptions } from './remote.js';
 import type { Skill, SkillRegistry, SkillRoots, SkillSource } from './types.js';
 /** Local skill root: `<cwd>/skills/`. Lives next to the project's source so it can be checked into git. */
 export declare const LOCAL_SKILLS_DIR = "skills";
@@ -31,7 +32,9 @@ export declare function parseSkillsDir(dir: string, kind: SkillSource['kind']):
  * Discover all skills visible from `cwd`. Walks local → project → global,
  * merges, and resolves duplicates by precedence (first-wins).
  */
-export declare function discoverSkills(cwd: string): Promise<Skill[]>;
+export declare function discoverSkills(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): Promise<Skill[]>;
 /**
  * Build an immutable registry from a pre-loaded skill list. Use this when
  * tests want to inject a known set without touching the filesystem. Use
@@ -42,9 +45,13 @@ export declare function skillsRegistryFromList(skills: Skill[], roots: SkillRoot
  * Build a registry by discovering skills from disk relative to `cwd`.
  * The registry caches its initial load; call `reload()` to refresh.
  */
-export declare function loadSkillsRegistry(cwd: string): SkillRegistry;
+export declare function loadSkillsRegistry(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): SkillRegistry;
 /**
  * Async variant: build a registry and immediately load its initial contents.
  * Useful for callers that want a fully-populated registry in one step.
  */
-export declare function loadSkillsRegistryAsync(cwd: string): Promise<SkillRegistry>;
+export declare function loadSkillsRegistryAsync(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): Promise<SkillRegistry>;

package/dist/skills/loader.js

@@ -11,6 +11,8 @@ import { readdir, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { discoverPlugins } from '../plugins/loader.js';
+import { builtinSkills } from './builtin.js';
+import { isHttpUrl, loadRemoteSkills } from './remote.js';
 import { parseSkill } from './parser.js';
 /** Local skill root: `<cwd>/skills/`. Lives next to the project's source so it can be checked into git. */
 export const LOCAL_SKILLS_DIR = 'skills';
@@ -61,19 +63,30 @@ export async function parseSkillsDir(dir, kind) {
  * Discover all skills visible from `cwd`. Walks local → project → global,
  * merges, and resolves duplicates by precedence (first-wins).
  */
-export async function discoverSkills(cwd) {
+export async function discoverSkills(cwd, extraDirs = [], remote = {}) {
     const roots = resolveSkillRoots(cwd);
     const [localSkills, projectSkills, globalSkills] = await Promise.all([
         parseSkillsDir(roots.local, 'local'),
         parseSkillsDir(roots.project, 'project'),
         parseSkillsDir(roots.global, 'global'),
     ]);
+    // Folders named in the `skillPaths` setting rank after the user's own folders and before plugins.
+    // An entry that is an http(s) URL is fetched (one skill file, or an index of them); the rest are folders.
+    const extraSkills = (await Promise.all(extraDirs.map(async (d) => {
+        if (isHttpUrl(d)) {
+            const got = await loadRemoteSkills(d, remote);
+            for (const w of got.warnings)
+                remote.onWarning?.(w);
+            return got.skills;
+        }
+        return parseSkillsDir(path.resolve(cwd, d.startsWith('~') ? path.join(homedir(), d.slice(1)) : d), 'global');
+    }))).flat();
     // Plugin skills rank below the user's own: they never shadow a skill written locally.
     const pluginSkills = (await Promise.all((await discoverPlugins(cwd)).map((p) => (p.skillsDir ? parseSkillsDir(p.skillsDir, p.scope) : Promise.resolve([]))))).flat();
-    // Order matters: first to claim a name wins. local > project > global > plugins.
+    // Order matters: first to claim a name wins. local > project > global > plugins > built in.
     const seen = new Set();
     const merged = [];
-    for (const list of [localSkills, projectSkills, globalSkills, pluginSkills]) {
+    for (const list of [localSkills, projectSkills, globalSkills, extraSkills, pluginSkills, builtinSkills()]) {
         for (const skill of list) {
             if (seen.has(skill.name))
                 continue;
@@ -105,11 +118,11 @@ export function skillsRegistryFromList(skills, roots) {
  * Build a registry by discovering skills from disk relative to `cwd`.
  * The registry caches its initial load; call `reload()` to refresh.
  */
-export function loadSkillsRegistry(cwd) {
+export function loadSkillsRegistry(cwd, extraDirs = [], remote = {}) {
     const roots = resolveSkillRoots(cwd);
     let cache = null;
     const refresh = async () => {
-        cache = await discoverSkills(cwd);
+        cache = await discoverSkills(cwd, extraDirs, remote);
         return cache;
     };
     return {
@@ -123,8 +136,8 @@ export function loadSkillsRegistry(cwd) {
  * Async variant: build a registry and immediately load its initial contents.
  * Useful for callers that want a fully-populated registry in one step.
  */
-export async function loadSkillsRegistryAsync(cwd) {
-    const registry = loadSkillsRegistry(cwd);
+export async function loadSkillsRegistryAsync(cwd, extraDirs = [], remote = {}) {
+    const registry = loadSkillsRegistry(cwd, extraDirs, remote);
     await registry.reload();
     return registry;
 }

package/dist/skills/marketplace.js

@@ -11,6 +11,7 @@
 import { normalizeGithubSource } from '../mcp/marketplace.js';
 import { parseSkill } from './parser.js';
 import { DEFAULT_SKILL_CATALOG_URL, SKILL_CATALOG_VERSION, } from './marketplace-types.js';
+import { isOutsideRel } from '../tools/shared.js';
 /**
  * Sanitize a catalog-provided name to a safe filename charset before it is
  * used to build a path on disk. Mirrors `installDirNameFor`'s sanitization
@@ -168,7 +169,7 @@ export async function installSkillFromCatalog(params) {
     const filePath = path.join(dest, `${safeName}.md`);
     const resolvedDest = path.resolve(dest);
     const rel = path.relative(resolvedDest, path.resolve(filePath));
-    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    if (isOutsideRel(rel)) {
         return null;
     }
     await fs.writeFile(filePath, rawContent, 'utf8');

package/dist/skills/remote.d.ts

@@ -0,0 +1,14 @@
+import type { Skill } from './types.js';
+export interface RemoteSkillOptions {
+    fetch?: typeof fetch;
+    /** Defaults to `~/.forge/skill-cache`. */
+    cacheDir?: string;
+    ttlMs?: number;
+    now?: () => number;
+}
+export interface RemoteSkills {
+    skills: Skill[];
+    warnings: string[];
+}
+export declare const isHttpUrl: (s: string) => boolean;
+export declare function loadRemoteSkills(url: string, options?: RemoteSkillOptions): Promise<RemoteSkills>;

package/dist/skills/remote.js

@@ -0,0 +1,131 @@
+/**
+ * Skills from a URL: either one skill file (Markdown with front matter) or an index,
+ * `{ "skills": [{ "url": "a.md" }, ...] }`, whose links may be relative to the index.
+ * Responses are cached on disk so a skill still works offline and a slow host is not asked on every run:
+ * a copy younger than the TTL is used as is; an older one is refreshed, and kept if the refresh fails.
+ * Anything that times out or is not a skill is skipped with one warning. Only http and https are fetched.
+ * The `skillPaths` setting that lists URLs is read from the user's config only.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { parseSkill } from './parser.js';
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_CHARS = 200_000;
+const MAX_INDEX_ENTRIES = 20;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/** A host that failed is not asked again for this long, so a dead URL does not add its timeout to every message. */
+const RETRY_AFTER_FAILURE_MS = 5 * 60 * 1000;
+const failures = new Map();
+export const isHttpUrl = (s) => /^https?:\/\//i.test(s);
+function cacheFile(dir, url) {
+    return path.join(dir, `${createHash('sha256').update(url).digest('hex').slice(0, 32)}.json`);
+}
+async function readCache(dir, url) {
+    try {
+        const entry = JSON.parse(await readFile(cacheFile(dir, url), 'utf8'));
+        return typeof entry.text === 'string' && typeof entry.fetchedAt === 'number' ? entry : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The text at `url`: a fresh cached copy, else the network, else a stale cached copy; throws if there is none. */
+async function fetchText(url, opts) {
+    const cached = await readCache(opts.cacheDir, url);
+    if (cached && opts.now() - cached.fetchedAt < opts.ttlMs)
+        return cached.text;
+    const failKey = `${opts.cacheDir}|${url}`;
+    const failed = failures.get(failKey);
+    const since = failed ? opts.now() - failed.at : 0;
+    if (failed && since >= 0 && since < RETRY_AFTER_FAILURE_MS) {
+        if (cached)
+            return cached.text;
+        throw new Error(failed.message);
+    }
+    try {
+        const res = await opts.fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const text = (await res.text()).slice(0, MAX_CHARS);
+        try {
+            await mkdir(opts.cacheDir, { recursive: true });
+            await writeFile(cacheFile(opts.cacheDir, url), JSON.stringify({ url, fetchedAt: opts.now(), text }), 'utf8');
+        }
+        catch {
+            // a cache that cannot be written only costs a fetch next time
+        }
+        failures.delete(failKey);
+        return text;
+    }
+    catch (err) {
+        failures.set(failKey, { at: opts.now(), message: err.message });
+        if (cached)
+            return cached.text;
+        throw err;
+    }
+}
+function fallbackName(url) {
+    const last = new URL(url).pathname.split('/').filter(Boolean).pop() ?? 'remote-skill';
+    return last.replace(/\.md$/i, '') || 'remote-skill';
+}
+function asSkill(url, text) {
+    const head = text.trimStart();
+    if (head.startsWith('<') || !head.startsWith('---'))
+        return undefined;
+    const skill = parseSkill(text, { kind: 'remote', path: url }, fallbackName(url));
+    return skill.description.trim() && skill.body ? skill : undefined;
+}
+export async function loadRemoteSkills(url, options = {}) {
+    const warnings = [];
+    if (!isHttpUrl(url))
+        return { skills: [], warnings: [`${url}: only http and https skill URLs are read; skipped`] };
+    const opts = {
+        fetch: options.fetch ?? fetch,
+        cacheDir: options.cacheDir ?? path.join(homedir(), '.forge', 'skill-cache'),
+        ttlMs: options.ttlMs ?? DEFAULT_TTL_MS,
+        now: options.now ?? Date.now,
+    };
+    const loadOne = async (target) => {
+        try {
+            const skill = asSkill(target, await fetchText(target, opts));
+            if (!skill)
+                warnings.push(`${target}: not a skill (needs front matter with a description); skipped`);
+            return skill;
+        }
+        catch (err) {
+            warnings.push(`${target}: ${err.message}; skipped`);
+            return undefined;
+        }
+    };
+    let text;
+    try {
+        text = await fetchText(url, opts);
+    }
+    catch (err) {
+        return { skills: [], warnings: [`${url}: ${err.message}; skipped`] };
+    }
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        let index;
+        try {
+            index = JSON.parse(text);
+        }
+        catch {
+            return { skills: [], warnings: [`${url}: not a skill or a skill index; skipped`] };
+        }
+        const list = Array.isArray(index) ? index : index?.skills;
+        if (!Array.isArray(list))
+            return { skills: [], warnings: [`${url}: not a skill or a skill index; skipped`] };
+        const targets = list
+            .map((e) => (typeof e === 'string' ? e : e?.url))
+            .filter((u) => typeof u === 'string' && u.length > 0)
+            .slice(0, MAX_INDEX_ENTRIES)
+            .map((u) => new URL(u, url).href);
+        const skills = (await Promise.all(targets.map(loadOne))).filter((s) => s !== undefined);
+        return { skills, warnings };
+    }
+    const skill = asSkill(url, text);
+    return skill ? { skills: [skill], warnings } : { skills: [], warnings: [`${url}: not a skill (needs front matter with a description); skipped`] };
+}

package/dist/skills/types.d.ts

@@ -38,6 +38,16 @@ export type SkillSource = {
 } | {
     kind: 'global';
     path: string;
+}
+/** Ships inside Forge; there is no file, `path` is a label. */
+ | {
+    kind: 'builtin';
+    path: string;
+}
+/** Fetched from a URL listed in `skillPaths`; `path` is the URL. */
+ | {
+    kind: 'remote';
+    path: string;
 };
 /** A parsed skill, ready for activation. */
 export interface Skill {

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;

package/dist/specs/generate.js

@@ -9,6 +9,7 @@
  * order) into the three separate document bodies `SpecStore.approve`
  * writes to disk.
  */
+import { convertToCheckboxes, parseTasks } from './tasks-parser.js';
 /** Read-only tools exposed to the model during spec-mode generation. */
 export const SPEC_READONLY_TOOLS = [
     'read_file',
@@ -23,37 +24,87 @@ const SECTION_MATCHES = [
     { key: 'design', header: 'design.md' },
     { key: 'tasks', header: 'tasks.md' },
 ];
+/** Where a section body ends: the next `## ` heading. */
+const STRICT_STOP = /^##\s+\S/m;
+/** Stage replies: a level-1 or level-2 heading, or any named section heading at level 1 to 3. */
+const LENIENT_STOP = /^(?:#{1,2}[ \t]+\S|#{1,3}[ \t]*`?(?:requirements|design|tasks)\.md`?[ \t]*$)/im;
+/** A line that is nothing but a code fence. */
+const FENCE_ONLY_LINE = /\n[ \t]*(?:```|~~~)[ \t]*$/;
+const FENCE_LINE_ANYWHERE = /^[ \t]*(?:```|~~~)/gm;
 /**
- * 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.
+ * Drop the closing fence a model leaves behind when it wrapped the whole reply
+ * in a code block: the opening fence sits before the first heading, so the last
+ * section ends with an unmatched closing one.
  *
- * 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.
+ * Only when the count is odd. A `tasks.md` that legitimately *ends* with a
+ * fenced code block has a balanced pair, and stripping that would eat the real
+ * document — which is what the existing one-shot test caught on the first run.
  */
-export function splitSpecSections(raw) {
+function dropUnmatchedTrailingFence(body) {
+    const fences = body.match(FENCE_LINE_ANYWHERE)?.length ?? 0;
+    if (fences % 2 === 0)
+        return body;
+    // `$` without /m anchors at the very end of the string, not before a trailing
+    // newline, so the trailing whitespace has to go before the fence can match.
+    return body.trimEnd().replace(FENCE_ONLY_LINE, '');
+}
+/**
+ * Find every section the text contains, validating nothing. Callers decide
+ * which they require, so the one-shot path can keep demanding all three while
+ * the journey's Spec stage asks for two and its ImplPlan stage for one.
+ *
+ * A section's body runs to the next `## ` heading or the end of the text, so an
+ * unrelated heading the model wrote between two sections ends only its own
+ * section. Text before the first heading is never part of a body, which is what
+ * makes a preamble harmless.
+ *
+ * `lenient` is for the journey's stage replies and is opt-in; the one-shot
+ * `splitSpecSections` passes false and reads exactly as it always has. Lenient
+ * does two things:
+ *
+ * - It strips the closing fence a wrapped reply leaves behind. This once ran for
+ *   both paths, which quietly changed what `/spec` persists (a wrapped reply
+ *   lost its closing fence, and a tilde block holding a bare backtick line lost
+ *   its own) and contradicted the plan's "nothing existing changes behaviour".
+ * - It accepts a section heading at level 1 to 3, optionally in backticks. A live
+ *   MiniMax-M3 run answered with `# tasks.md` and the strict parser threw "got:
+ *   none" although the model had done the work. Once a section may be headed
+ *   `###`, a body cannot end at "any `##` line" or the first section would
+ *   swallow the second, so it ends at a level-1/2 heading *or* at any named
+ *   section heading; a level-3 subsection inside a document stays inside it.
+ *
+ * The one-shot flaws are real and recorded in RB-31; they are not fixed here.
+ */
+function splitSections(raw, lenient) {
     const found = {};
     const foundHeaders = [];
     for (const { key, header } of SECTION_MATCHES) {
-        const re = new RegExp(`^##\\s*${escapeRegExp(header)}\\s*$`, 'im');
+        const re = lenient
+            ? new RegExp(`^#{1,3}[ \\t]*\`?${escapeRegExp(header)}\`?[ \\t]*$`, 'im')
+            : new RegExp(`^##\\s*${escapeRegExp(header)}\\s*$`, 'im');
         const match = re.exec(raw);
         if (!match)
             continue;
         const start = match.index + match[0].length;
         const rest = raw.slice(start);
         // Body runs until the next `## ...` heading line, or end of text.
-        const nextHeadingRe = /^##\s+\S/m;
-        const nextMatch = nextHeadingRe.exec(rest);
-        const body = nextMatch ? rest.slice(0, nextMatch.index) : rest;
+        const nextMatch = (lenient ? LENIENT_STOP : STRICT_STOP).exec(rest);
+        const slice = nextMatch ? rest.slice(0, nextMatch.index) : rest;
+        const body = lenient ? dropUnmatchedTrailingFence(slice) : slice;
         found[key] = key === 'tasks' ? splitInlineSubtasks(body.trim()) : body.trim();
         foundHeaders.push(header);
     }
+    return { found, foundHeaders };
+}
+function describeFound(foundHeaders) {
+    return foundHeaders.length > 0 ? foundHeaders.join(', ') : 'none';
+}
+export function splitSpecSections(raw) {
+    const { found, foundHeaders } = splitSections(raw, false);
+    // Strict on purpose: see `splitSections`. The one-shot path reads exactly as it always has.
     const missing = SECTION_MATCHES.filter((s) => found[s.key] === undefined);
     if (missing.length > 0) {
-        throw new Error(`Spec generation did not include all three sections (requirements.md/design.md/tasks.md): got: ${foundHeaders.length > 0 ? foundHeaders.join(', ') : 'none'}`);
+        throw new Error(`Spec generation did not include all three sections (requirements.md/design.md/tasks.md): got: ${describeFound(foundHeaders)}`);
     }
     return {
         requirements: found.requirements,
@@ -61,6 +112,115 @@ export function splitSpecSections(raw) {
         tasks: found.tasks,
     };
 }
+/**
+ * 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 function splitRequirementsDesign(raw) {
+    const { found, foundHeaders } = splitSections(raw, true);
+    const missing = ['requirements', 'design'].filter((k) => found[k] === undefined);
+    if (missing.length > 0) {
+        throw new Error(`Spec generation did not include ${missing.map((k) => `${k}.md`).join(' and ')}: got: ${describeFound(foundHeaders)}`);
+    }
+    return { requirements: found.requirements, design: found.design };
+}
+const CHECKBOX_LINE = /^\s*[-*+]\s+\[[ xX]\]\s+\S/;
+const FENCE_START = /^\s*(?:```|~~~)/;
+/** `_Requirements: 2_`, `*Requirements: 2*`, `**Requirements:** 1.1`: the footer under a task, however the model dressed it. */
+const REQUIREMENTS_FOOTER = /^\s*[_*]{1,2}Requirements\b.*$/i;
+/** A line that belongs to the task above it: indented, or its requirements footer. */
+function continuesTask(line) {
+    return /^\s+\S/.test(line) || REQUIREMENTS_FOOTER.test(line);
+}
+/**
+ * Cut a closing summary off the end of a task list.
+ *
+ * Nothing ends the *last* section of a reply, so a model that finishes with
+ * "Notes on two judgment calls… Plan is complete, next step would be executing
+ * task 1" has that text written into the persisted `tasks.md`. A live
+ * MiniMax-M3 run did exactly that. The checklist is the anchor: the document
+ * ends where the last checkbox's own block ends.
+ *
+ * That block is the task's indented lines and its requirements footer, and it
+ * may contain blank lines, so a blank run is looked *through* and kept when what
+ * follows still belongs to the task. A fenced block under the last task is part
+ * of it and is kept whole; an *unclosed* fence is trailer, because keeping it
+ * would persist a document that ends inside a code block. The anchor itself is
+ * the last checkbox `parseTasks` would see, so one inside a fenced example does
+ * not count.
+ *
+ * With no checkbox at all (a prose or numbered list) there is nothing to anchor
+ * on, so the text is returned as it is and approval converts it to checkboxes
+ * the way the one-shot path always has.
+ */
+function dropClosingSummary(tasks) {
+    const lines = tasks.split('\n');
+    let last = -1;
+    let inFence = false;
+    lines.forEach((line, i) => {
+        if (FENCE_START.test(line)) {
+            inFence = !inFence;
+            return;
+        }
+        if (!inFence && CHECKBOX_LINE.test(line))
+            last = i;
+    });
+    if (last === -1)
+        return tasks;
+    let end = last;
+    let i = last + 1;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === '') {
+            let next = i + 1;
+            while (next < lines.length && lines[next].trim() === '')
+                next += 1;
+            const rest = lines[next];
+            if (rest !== undefined && (continuesTask(rest) || FENCE_START.test(rest))) {
+                i = next;
+                continue;
+            }
+            break;
+        }
+        if (FENCE_START.test(line)) {
+            let close = i + 1;
+            while (close < lines.length && !FENCE_START.test(lines[close]))
+                close += 1;
+            if (close >= lines.length)
+                break;
+            end = close;
+            i = close + 1;
+            continue;
+        }
+        if (!continuesTask(line))
+            break;
+        end = i;
+        i += 1;
+    }
+    return lines.slice(0, end + 1).join('\n').trimEnd();
+}
+/**
+ * The ImplPlan stage's single document.
+ *
+ * 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 function splitTasksSection(raw) {
+    const { found, foundHeaders } = splitSections(raw, true);
+    if (found.tasks === undefined) {
+        throw new Error(`Spec generation did not include tasks.md: got: ${describeFound(foundHeaders)}`);
+    }
+    const tasks = dropClosingSummary(found.tasks);
+    if (parseTasks(convertToCheckboxes(tasks)).length === 0) {
+        throw new Error(`Spec generation produced a tasks.md with no tasks in it: got: ${describeFound(foundHeaders)}`);
+    }
+    return tasks;
+}
 // A task line with a numbered subtask glued on after it: "- [ ] 1. Title - [ ] 1.1 Sub".
 const INLINE_SUBTASK_RE = /^(\s*)([-*+]\s+\[[ xX]\]\s+.+?)\s+[-*+]\s+(\[[ xX]\]\s+\d.*)$/;
 /**

package/dist/specs/index.d.ts

@@ -6,8 +6,8 @@
  * `./generate.js`, added in a later task.
  */
 export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId } from './store.js';
-export type { SpecDraft, SpecRunRecord, SpecRuns, SpecSections, SpecSummary } from './types.js';
-export { SPEC_READONLY_TOOLS, splitSpecSections } from './generate.js';
+export type { SpecDraft, SpecDraftSections, SpecRunRecord, SpecRuns, SpecSections, SpecSummary } from './types.js';
+export { SPEC_READONLY_TOOLS, splitRequirementsDesign, splitSpecSections, splitTasksSection } from './generate.js';
 export { convertToCheckboxes, parseTasks, setTaskDone } from './tasks-parser.js';
 export type { SpecTask } from './tasks-parser.js';
 export { changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './sync.js';

package/dist/specs/index.js

@@ -6,6 +6,6 @@
  * `./generate.js`, added in a later task.
  */
 export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId } from './store.js';
-export { SPEC_READONLY_TOOLS, splitSpecSections } from './generate.js';
+export { SPEC_READONLY_TOOLS, splitRequirementsDesign, splitSpecSections, splitTasksSection } from './generate.js';
 export { convertToCheckboxes, parseTasks, setTaskDone } from './tasks-parser.js';
 export { changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './sync.js';

package/dist/specs/store.d.ts

@@ -7,7 +7,7 @@
  * generation happens entirely in memory (in the CLI/REPL layer), so a
  * cancelled review leaves no trace here.
  */
-import type { SpecDraft, SpecRunRecord, SpecRuns, SpecSections, SpecSummary } from './types.js';
+import type { SpecDraft, SpecDraftSections, SpecRunRecord, SpecRuns, SpecSections, SpecSummary } from './types.js';
 /** Spec ids become path segments; the leading-alphanumeric rule also rejects `.drafts`, `.` and `..`. */
 export declare function isSafeSpecId(id: string): boolean;
 /** Key for a task's run history: a reordered or renamed task stops matching old runs. */
@@ -33,7 +33,19 @@ export declare class SpecStore {
     /** Delete an approved spec's directory. Returns false when it didn't exist. */
     delete(id: string): Promise<boolean>;
     private draftDir;
-    createDraft(id: string, task: string, sections: SpecSections): Promise<SpecDraft>;
+    /**
+     * A draft may be created before its tasks exist: the journey's Spec stage
+     * writes requirements and design, and `tasks.md` arrives from the ImplPlan
+     * stage behind its own gate (`writeDraftTasks`). The one-shot `/spec` path
+     * passes all three and is unaffected.
+     */
+    createDraft(id: string, task: string, sections: SpecDraftSections): Promise<SpecDraft>;
+    /**
+     * Write (or replace) a draft's `tasks.md`, which is the ImplPlan stage's
+     * artefact. `writeFile` truncates, so running the stage again after the person
+     * chose "Revise them" replaces the list rather than appending to it.
+     */
+    writeDraftTasks(id: string, tasks: string): Promise<void>;
     getDraft(id: string): Promise<SpecDraft | null>;
     listDrafts(): Promise<SpecDraft[]>;
     /** Approve what is on disk now (the user may have edited it), converting tasks.md to checkboxes if needed. */