@pome-sh/cli 0.20.0 → 0.21.0

package/dist/src/scaffolds/mcp-loop/loop.js

@@ -1,331 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// Model-agnostic MCP tool-call loop (spec §2 — the "mcp-loop" scaffold).
-//
-// Speaks the SAME agent contract as the existing example agents: it reads
-// POME_TASK, the twin's POME_<TWIN>_MCP_URL, and POME_AUTH_TOKEN from the
-// environment (the CLI runner sets these per cell). It connects to the twin's
-// stateless MCP endpoint (JSON-RPC over Streamable HTTP), exposes the twin's
-// tools to the model via the Vercel AI SDK, and runs a tool-call loop until the
-// model finishes or hits the turn budget.
-//
-// NO new runtime dep: the MCP client is a ~40-line JSON-RPC-over-fetch client
-// against the twin's stateless Streamable-HTTP server (see
-// packages/twin-github/src/mcp.ts — single POST per request, `application/json`
-// response, `tools/list` → { tools }, `tools/call` → { content:[{text}], isError }).
-//
-// Trace signals (best-effort, NOT analyzed in v1): when POME_ADAPTER_SIGNALS_PATH
-// is set, the loop appends ToolUseEvent / ToolResultEvent rows whose on-disk
-// shape is isomorphic with @pome-sh/adapter-claude-sdk's signals.ts, so traces
-// stay comparable across scaffolds and v2's explanation layer inherits them.
-import { appendFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { generateText, stepCountIs, dynamicTool, jsonSchema, } from "ai";
-const MCP_PROTOCOL_VERSION = "2025-06-18";
-// A minimal Streamable-HTTP MCP client. Each request is one POST; the twin is
-// stateless (no Mcp-Session-Id, no SSE for single requests). We still send an
-// `initialize` once for protocol-correctness even though the twin doesn't
-// require session state.
-export function createHttpMcpClient(opts) {
-    const doFetch = opts.fetchImpl ?? fetch;
-    let nextId = 1;
-    let initialized = false;
-    async function rpc(method, params) {
-        const id = nextId++;
-        const headers = {
-            "content-type": "application/json",
-            // The twin replies with application/json for single requests, but a
-            // spec-compliant client advertises it accepts SSE too.
-            accept: "application/json, text/event-stream",
-        };
-        if (opts.authToken)
-            headers.authorization = `Bearer ${opts.authToken}`;
-        const res = await doFetch(opts.url, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
-        });
-        if (!res.ok) {
-            throw new Error(`MCP ${method} failed: HTTP ${res.status}`);
-        }
-        const body = (await res.json());
-        if ("error" in body) {
-            throw new Error(`MCP ${method} error ${body.error.code}: ${body.error.message}`);
-        }
-        return body.result;
-    }
-    async function ensureInitialized() {
-        if (initialized)
-            return;
-        await rpc("initialize", {
-            protocolVersion: MCP_PROTOCOL_VERSION,
-            capabilities: {},
-            clientInfo: { name: "pome-mcp-loop", version: "1" },
-        });
-        initialized = true;
-    }
-    return {
-        async listTools() {
-            await ensureInitialized();
-            const result = (await rpc("tools/list"));
-            const tools = Array.isArray(result.tools) ? result.tools : [];
-            return tools.flatMap((t) => {
-                if (t &&
-                    typeof t === "object" &&
-                    typeof t.name === "string") {
-                    const obj = t;
-                    const schema = obj.inputSchema && typeof obj.inputSchema === "object"
-                        ? obj.inputSchema
-                        : { type: "object", properties: {} };
-                    return [
-                        {
-                            name: obj.name,
-                            description: typeof obj.description === "string" ? obj.description : undefined,
-                            inputSchema: schema,
-                        },
-                    ];
-                }
-                return [];
-            });
-        },
-        async callTool(name, args) {
-            await ensureInitialized();
-            const result = (await rpc("tools/call", { name, arguments: args ?? {} }));
-            const content = Array.isArray(result.content) ? result.content : [];
-            const text = content
-                .map((part) => part &&
-                typeof part === "object" &&
-                typeof part.text === "string"
-                ? (part.text)
-                : "")
-                .join("");
-            return { text, isError: result.isError === true };
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Best-effort trace signals (isomorphic with @pome-sh/adapter-claude-sdk).
-// ---------------------------------------------------------------------------
-// Hand-built JSON-line rows matching the adapter's on-disk shapes (no
-// shared-types runtime dep). The CLI runner merges this file into the canonical
-// events.jsonl after the subprocess exits.
-function emitToolUse(signalsPath, row) {
-    if (!signalsPath)
-        return;
-    try {
-        appendFileSync(signalsPath, JSON.stringify({
-            ts: new Date().toISOString(),
-            event_id: randomUUID(),
-            parent_event_id: null,
-            kind: "ToolUseEvent",
-            tool_use_id: row.tool_use_id,
-            tool_name: row.tool_name,
-            input: row.input,
-        }) + "\n");
-    }
-    catch {
-        // best-effort: never let trace I/O fail the agent.
-    }
-}
-function emitToolResult(signalsPath, row) {
-    if (!signalsPath)
-        return;
-    try {
-        appendFileSync(signalsPath, JSON.stringify({
-            ts: new Date().toISOString(),
-            event_id: randomUUID(),
-            parent_event_id: null,
-            kind: "ToolResultEvent",
-            tool_use_id: row.tool_use_id,
-            output: row.output,
-            is_error: row.is_error,
-        }) + "\n");
-    }
-    catch {
-        // best-effort.
-    }
-}
-// Append ONE authoritative LlmCallEvent per generateText step (one model
-// round-trip). The capture-server proxy can't read token/cost from the
-// encrypted CONNECT tunnel; the scaffold holds the AI SDK response and is the
-// only source that knows usage. The matrix runs mcp-loop cells with capture
-// OFF (see cli/src/matrix/index.ts), so these rows are the SOLE LlmCallEvent
-// rows and runResourceMetrics sums them without double-counting proxy latency.
-//
-// On-disk shape matches llmCallEventSchema (src/types/shared.ts): host/port/
-// bytes_in/bytes_out are non-null (the scaffold never sees the HTTP/byte layer,
-// so bytes are honestly 0 and host is synthetic); url/method/status are null;
-// model/prompt_tokens/completion_tokens/cost_usd carry real values.
-function emitLlmCall(signalsPath, row) {
-    if (!signalsPath)
-        return;
-    try {
-        appendFileSync(signalsPath, JSON.stringify({
-            ts: new Date().toISOString(),
-            event_id: randomUUID(),
-            parent_event_id: null,
-            kind: "LlmCallEvent",
-            host: row.host,
-            port: 443,
-            latency_ms: row.latency_ms,
-            bytes_in: 0,
-            bytes_out: 0,
-            url: null,
-            method: null,
-            status: null,
-            model: row.model,
-            prompt_tokens: row.prompt_tokens,
-            completion_tokens: row.completion_tokens,
-            cost_usd: row.cost_usd,
-        }) + "\n");
-    }
-    catch {
-        // best-effort: never let trace I/O fail the agent.
-    }
-}
-// Read the Vercel AI Gateway's per-call cost from a step's providerMetadata.
-// ProviderMetadata = Record<string, Record<string, JSONValue>>; the gateway
-// surfaces cost under providerMetadata.gateway.cost. Defensive: returns the
-// number only when finite, else null (provider/route dependent — may be absent).
-function readGatewayCost(pm) {
-    if (!pm || typeof pm !== "object")
-        return null;
-    const gateway = pm.gateway;
-    if (!gateway || typeof gateway !== "object")
-        return null;
-    const cost = gateway.cost;
-    return typeof cost === "number" && Number.isFinite(cost) ? cost : null;
-}
-// Coerce a possibly-undefined SDK token count to a schema-valid non-negative
-// integer, or null when absent/non-finite.
-function coerceTokenCount(n) {
-    return typeof n === "number" && Number.isFinite(n) ? Math.max(0, Math.round(n)) : null;
-}
-// ---------------------------------------------------------------------------
-// The loop.
-// ---------------------------------------------------------------------------
-// 12 turns: matches the example agents' 8-turn loop with headroom for
-// multi-step (T5) scenarios. Wall-clock is the runner's scenario-timeout SIGTERM
-// (spec §2 / plan) — the loop does not run a second timeout.
-export const DEFAULT_MAX_TURNS = 12;
-// Build the AI SDK tool set from the twin's MCP tools. Each tool's `execute`
-// dispatches back through the MCP client and emits best-effort trace signals.
-function buildToolSet(tools, mcp, signalsPath, onToolCall) {
-    const set = {};
-    for (const t of tools) {
-        set[t.name] = dynamicTool({
-            description: t.description ?? `MCP tool ${t.name}`,
-            inputSchema: jsonSchema(t.inputSchema),
-            execute: async (input) => {
-                onToolCall();
-                const toolUseId = randomUUID();
-                emitToolUse(signalsPath, {
-                    tool_use_id: toolUseId,
-                    tool_name: t.name,
-                    input,
-                });
-                const result = await mcp.callTool(t.name, input);
-                emitToolResult(signalsPath, {
-                    tool_use_id: toolUseId,
-                    output: result.text,
-                    is_error: result.isError,
-                });
-                // Hand the raw tool text back to the model; the AI SDK serializes it.
-                return result.text;
-            },
-        });
-    }
-    return set;
-}
-// Run the tool-call loop. The model + MCP client are injected so this is fully
-// unit-testable with a mocked model and a fake MCP client (no network, no key).
-export async function runMcpLoop(options) {
-    const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
-    const signalsPath = options.signalsPath ?? null;
-    const mcpTools = await options.mcp.listTools();
-    let toolCallCount = 0;
-    const toolSet = buildToolSet(mcpTools, options.mcp, signalsPath, () => {
-        toolCallCount += 1;
-    });
-    const messages = [{ role: "user", content: options.task }];
-    const modelId = options.modelId ?? "unknown";
-    const host = options.host ?? "ai-gateway";
-    const t0 = Date.now();
-    const result = await generateText({
-        model: options.model,
-        system: options.system,
-        messages,
-        tools: toolSet,
-        // Keep stepping while the model emits tool calls, up to the turn budget.
-        stopWhen: stepCountIs(maxTurns),
-    });
-    const elapsed = Date.now() - t0;
-    // Emit one authoritative LlmCallEvent per step (each step = one model call).
-    // The generateText wall-clock is split evenly across steps so the summed
-    // latency_ms over rows equals the real wall-clock (the SDK exposes no
-    // per-step timing). Tokens/cost are exact per step.
-    const stepCount = result.steps.length;
-    const perStepLatency = Math.max(0, Math.round(elapsed / Math.max(1, stepCount)));
-    for (const step of result.steps) {
-        emitLlmCall(signalsPath, {
-            host,
-            latency_ms: perStepLatency,
-            model: modelId,
-            prompt_tokens: coerceTokenCount(step.usage?.inputTokens),
-            completion_tokens: coerceTokenCount(step.usage?.outputTokens),
-            cost_usd: readGatewayCost(step.providerMetadata),
-        });
-    }
-    return {
-        text: result.text,
-        toolCallCount,
-        steps: result.steps.length,
-        // The ai-level finishReason is a string union (the provider-level
-        // {unified, raw} object is flattened by generateText).
-        finishReason: result.finishReason,
-    };
-}
-// Discover the twin MCP URL from POME_<TWIN>_MCP_URL. The runner currently sets
-// POME_GITHUB_MCP_URL; this is generic over twins (Stripe/Slack land the same
-// shape). POME_TWIN_NAMES, when present, picks the active twin; otherwise the
-// first POME_*_MCP_URL wins.
-export function resolveMcpUrl(env = process.env) {
-    const names = (env.POME_TWIN_NAMES ?? "")
-        .split(",")
-        .map((s) => s.trim().toUpperCase())
-        .filter(Boolean);
-    for (const name of names) {
-        const v = env[`POME_${name}_MCP_URL`];
-        if (v && v.trim())
-            return v.trim();
-    }
-    // Fall back to any POME_<X>_MCP_URL in the environment.
-    for (const [k, v] of Object.entries(env)) {
-        if (/^POME_[A-Z0-9]+_MCP_URL$/.test(k) && v && v.trim())
-            return v.trim();
-    }
-    return null;
-}
-// Resolve the full env contract or throw a clear error naming the missing var.
-export function resolveLoopEnv(env = process.env) {
-    const task = env.POME_TASK?.trim();
-    if (!task)
-        throw new Error("mcp-loop: POME_TASK is required");
-    const mcpUrl = resolveMcpUrl(env);
-    if (!mcpUrl) {
-        throw new Error("mcp-loop: no POME_<TWIN>_MCP_URL found in the environment (e.g. POME_GITHUB_MCP_URL)");
-    }
-    const model = env.POME_MATRIX_MODEL?.trim();
-    if (!model) {
-        throw new Error("mcp-loop: POME_MATRIX_MODEL is required (set by the matrix)");
-    }
-    const signalsRaw = env.POME_ADAPTER_SIGNALS_PATH;
-    return {
-        task,
-        mcpUrl,
-        authToken: env.POME_AUTH_TOKEN?.trim() || undefined,
-        model,
-        promptPath: env.POME_MATRIX_PROMPT_PATH?.trim() || undefined,
-        signalsPath: signalsRaw && signalsRaw.length > 0 ? signalsRaw : null,
-    };
-}

package/dist/src/scaffolds/mcp-loop/providers.d.ts

@@ -1,29 +0,0 @@
-import type { LanguageModel } from "ai";
-export declare function gatewayEnabled(env?: NodeJS.ProcessEnv): boolean;
-export type ProviderId = "anthropic" | "openai" | "openrouter" | "google";
-export type ResolvedProvider = {
-    provider: ProviderId;
-    /** The single env var that must be set for this provider. */
-    envKey: string;
-    /** The provider-native model id (the part after `provider/`, or the bare id). */
-    modelId: string;
-};
-export declare function resolveProvider(model: string): ResolvedProvider | null;
-export declare function resolveLlmHost(model: string, env?: NodeJS.ProcessEnv): string;
-export type ModelPreflight = {
-    ok: true;
-    provider: ProviderId | "gateway";
-    envKey: string;
-} | {
-    ok: false;
-    reason: "unknown-provider";
-    model: string;
-} | {
-    ok: false;
-    reason: "missing-key";
-    provider: ProviderId;
-    envKey: string;
-};
-export declare function preflightModel(model: string, env?: NodeJS.ProcessEnv): ModelPreflight;
-export declare function preflightModelMessage(pf: ModelPreflight): string;
-export declare function resolveModel(model: string, env?: NodeJS.ProcessEnv): LanguageModel;

package/dist/src/scaffolds/mcp-loop/providers.js

@@ -1,142 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// Model-string → Vercel AI SDK model resolver, plus a key-preflight helper the
-// matrix (and the entrypoint) can call before any network I/O.
-//
-// One env var per provider (spec §2). A provider-prefixed model string like
-// `openai/gpt-5`, `anthropic/claude-opus-4-8`, `openrouter/qwen-3-235b`, or
-// `google/gemini-2.5-pro` picks the provider; bare ids (`claude-*`, `gpt-*`,
-// `gemini-*`, `o1`/`o3`) are mapped by prefix to stay back-compatible with the
-// claude-agent-sdk-style native ids. The piece after the first `/` (or the bare
-// id) is the provider-native model id handed to the SDK.
-//
-// Resolution is dependency-light at module load: the provider factory packages
-// are imported, but a model is only constructed when `resolveModel()` is called,
-// so a missing key fails at preflight (clear) rather than at the first token.
-import { createAnthropic } from "@ai-sdk/anthropic";
-import { createOpenAI } from "@ai-sdk/openai";
-import { createGoogleGenerativeAI } from "@ai-sdk/google";
-import { createOpenRouter } from "@openrouter/ai-sdk-provider";
-import { gateway } from "@ai-sdk/gateway";
-// When a Vercel AI Gateway key is present, every provider/model slug routes
-// through the gateway with that ONE key — no per-provider key needed, and it
-// reaches providers the per-provider path doesn't model (deepseek/, meta/,
-// xai/, qwen, ...). This is the preferred path for the model matrix: one key,
-// the whole fleet.
-export function gatewayEnabled(env = process.env) {
-    const v = env.AI_GATEWAY_API_KEY;
-    return v !== undefined && v.trim() !== "";
-}
-// Map a (possibly provider-prefixed) model string to its provider + native id +
-// required env var. Mirrors the matrix preflight table in
-// cli/src/matrix/preflight.ts — keep the two in sync. Returns null for an
-// unknown prefix so callers can fail clearly.
-export function resolveProvider(model) {
-    const m = model.trim();
-    const slash = m.indexOf("/");
-    const prefix = slash >= 0 ? m.slice(0, slash) : "";
-    const rest = slash >= 0 ? m.slice(slash + 1) : m;
-    if (prefix === "anthropic" || m.startsWith("claude")) {
-        return { provider: "anthropic", envKey: "ANTHROPIC_API_KEY", modelId: rest };
-    }
-    if (prefix === "openrouter") {
-        // OpenRouter model ids are themselves slashed (`qwen/qwen-3-235b`), so keep
-        // everything after the FIRST segment intact.
-        return { provider: "openrouter", envKey: "OPENROUTER_API_KEY", modelId: rest };
-    }
-    if (prefix === "openai" ||
-        m.startsWith("gpt-") ||
-        m.startsWith("o1") ||
-        m.startsWith("o3")) {
-        return { provider: "openai", envKey: "OPENAI_API_KEY", modelId: rest };
-    }
-    if (prefix === "google" || m.startsWith("gemini")) {
-        return { provider: "google", envKey: "GOOGLE_API_KEY", modelId: rest };
-    }
-    return null;
-}
-// Resolve the synthetic host the scaffold stamps on its emitted LlmCallEvent
-// rows (the scaffold talks to the AI SDK, never the HTTP/byte layer). When the
-// gateway key is present every slug routes through "ai-gateway"; otherwise map
-// the resolved provider to its public API host. An unknown provider defaults to
-// "ai-gateway" (the only reachable path without a per-provider mapping). Kept
-// here alongside gatewayEnabled/resolveProvider so host derivation lives where
-// the provider knowledge already is.
-const PROVIDER_HOSTS = {
-    anthropic: "api.anthropic.com",
-    openai: "api.openai.com",
-    google: "generativelanguage.googleapis.com",
-    openrouter: "openrouter.ai",
-};
-export function resolveLlmHost(model, env = process.env) {
-    if (gatewayEnabled(env))
-        return "ai-gateway";
-    const resolved = resolveProvider(model);
-    if (!resolved)
-        return "ai-gateway";
-    return PROVIDER_HOSTS[resolved.provider];
-}
-export function preflightModel(model, env = process.env) {
-    // Gateway key present → any slug is reachable with that one key.
-    if (gatewayEnabled(env)) {
-        const known = resolveProvider(model);
-        return {
-            ok: true,
-            provider: known?.provider ?? "gateway",
-            envKey: "AI_GATEWAY_API_KEY",
-        };
-    }
-    const resolved = resolveProvider(model);
-    if (!resolved)
-        return { ok: false, reason: "unknown-provider", model };
-    const value = env[resolved.envKey];
-    if (value === undefined || value.trim() === "") {
-        return {
-            ok: false,
-            reason: "missing-key",
-            provider: resolved.provider,
-            envKey: resolved.envKey,
-        };
-    }
-    return { ok: true, provider: resolved.provider, envKey: resolved.envKey };
-}
-// Human-readable one-liner for a failed model preflight.
-export function preflightModelMessage(pf) {
-    if (pf.ok)
-        return `model preflight ok (${pf.provider})`;
-    if (pf.reason === "unknown-provider") {
-        return `mcp-loop: unknown provider for model "${pf.model}" (expected one of anthropic/ openai/ openrouter/ google/, or a bare claude*/gpt-*/o1/o3/gemini* id)`;
-    }
-    return `mcp-loop: missing ${pf.envKey} (${pf.provider}) — set it and re-run`;
-}
-// Construct the AI SDK LanguageModel for a model string. Throws (clearly) on an
-// unknown provider or a missing key — call preflightModel() first if you want to
-// fail before any model construction. The provider factory reads the key from
-// the env var explicitly (not the SDK default) so the key the matrix preflighted
-// is exactly the one used — notably Google's SDK default reads
-// GOOGLE_GENERATIVE_AI_API_KEY, but we standardize on GOOGLE_API_KEY.
-export function resolveModel(model, env = process.env) {
-    // Gateway key present → hand the full provider/model slug to the gateway,
-    // which routes it with the single AI_GATEWAY_API_KEY.
-    if (gatewayEnabled(env)) {
-        return gateway(model.trim());
-    }
-    const resolved = resolveProvider(model);
-    if (!resolved) {
-        throw new Error(`mcp-loop: cannot resolve provider for model "${model}"`);
-    }
-    const apiKey = env[resolved.envKey];
-    if (!apiKey || apiKey.trim() === "") {
-        throw new Error(`mcp-loop: ${resolved.envKey} is not set`);
-    }
-    switch (resolved.provider) {
-        case "anthropic":
-            return createAnthropic({ apiKey })(resolved.modelId);
-        case "openai":
-            return createOpenAI({ apiKey })(resolved.modelId);
-        case "openrouter":
-            return createOpenRouter({ apiKey }).chat(resolved.modelId);
-        case "google":
-            return createGoogleGenerativeAI({ apiKey })(resolved.modelId);
-    }
-}

package/dist/src/task/githubSeedCompat.d.ts

@@ -1,3 +0,0 @@
-import { seedSchema } from "@pome-sh/twin-github";
-export declare function normalizeLegacyGitHubSeed(input: unknown): unknown;
-export declare function parseGitHubSeedState(input: unknown): ReturnType<typeof seedSchema.parse>;

package/dist/src/task/githubSeedCompat.js

@@ -1,48 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-import { parseSeed, seedSchema } from "@pome-sh/twin-github";
-// Bundled scenario sidecars and legacy compile output used singular `assignee`
-// on issues; @pome-sh/twin-github's seedSchema expects `assignees[]`. Zod strips
-// unknown keys, so migrate before parse.
-export function normalizeLegacyGitHubSeed(input) {
-    if (!input || typeof input !== "object" || Array.isArray(input))
-        return input;
-    const seed = input;
-    if (!Array.isArray(seed.repositories))
-        return input;
-    return {
-        ...seed,
-        repositories: seed.repositories.map((repo) => {
-            if (!repo || typeof repo !== "object" || Array.isArray(repo))
-                return repo;
-            const record = repo;
-            if (!Array.isArray(record.issues))
-                return repo;
-            return {
-                ...record,
-                issues: record.issues.map((issue) => normalizeLegacyIssueAssignee(issue)),
-            };
-        }),
-    };
-}
-function normalizeLegacyIssueAssignee(issue) {
-    if (!issue || typeof issue !== "object" || Array.isArray(issue))
-        return issue;
-    const record = issue;
-    if (!("assignee" in record) || "assignees" in record)
-        return issue;
-    const { assignee, ...rest } = record;
-    if (assignee === null || assignee === undefined || assignee === "") {
-        return { ...rest, assignees: [] };
-    }
-    if (typeof assignee === "string") {
-        return { ...rest, assignees: [assignee] };
-    }
-    return issue;
-}
-export function parseGitHubSeedState(input) {
-    const seed = seedSchema.parse(parseSeed(normalizeLegacyGitHubSeed(input)));
-    if (seed.repositories.length === 0) {
-        throw new Error("GitHub seed must contain at least one repository");
-    }
-    return seed;
-}

package/dist/src/task/insertCriterion.d.ts

@@ -1,15 +0,0 @@
-/**
- * F-1074 — append one rendered criterion to a task file's `## Success Criteria`,
- * touching nothing else.
- *
- * It does NOT parse and re-serialize the markdown. Re-serializing is how the
- * readable artifact drifts, and the north-star check on this ticket is that it
- * does not: authoring a criterion changes exactly one line.
- */
-export declare class MissingCriteriaSectionError extends Error {
-    constructor(path: string);
-}
-export declare class DuplicateCriterionError extends Error {
-    constructor(path: string, line: string);
-}
-export declare function insertCriterion(source: string, line: string, path?: string): string;

package/dist/src/task/insertCriterion.js

@@ -1,67 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * F-1074 — append one rendered criterion to a task file's `## Success Criteria`,
- * touching nothing else.
- *
- * It does NOT parse and re-serialize the markdown. Re-serializing is how the
- * readable artifact drifts, and the north-star check on this ticket is that it
- * does not: authoring a criterion changes exactly one line.
- */
-const HEADING_RE = /^##\s+Success Criteria\s*$/;
-const NEXT_HEADING_RE = /^##\s+/;
-// Mirrors CRITERION_LINE_RE in ./parseTask.ts. Used ONLY to find where the last
-// existing criterion sits — never to validate one; that is the parser's job.
-const CRITERION_RE = /^[-*]\s+\[(?:code|model)(?::[a-z][a-z0-9_-]*)?\]\s+.+$/;
-export class MissingCriteriaSectionError extends Error {
-    constructor(path) {
-        super(`${path} has no \`## Success Criteria\` section. Add one and run this again — ` +
-            `pome will not invent a section in a file it did not write.`);
-        this.name = "MissingCriteriaSectionError";
-    }
-}
-// Found by driving the command: authoring a criterion a task already carries
-// adds it twice, and the grader scores both — the denominator inflates and the
-// task's percentage moves for a reason nobody wrote down. That is the exact
-// class of silent denominator change this milestone exists to remove, so it is
-// a refusal rather than a warning.
-export class DuplicateCriterionError extends Error {
-    constructor(path, line) {
-        super(`${path} already has this criterion:\n  ${line}\n` +
-            `Adding it again would score it twice and inflate the task's denominator.`);
-        this.name = "DuplicateCriterionError";
-    }
-}
-export function insertCriterion(source, line, path = "this task file") {
-    const lines = source.split("\n");
-    const start = lines.findIndex((l) => HEADING_RE.test(l));
-    if (start === -1)
-        throw new MissingCriteriaSectionError(path);
-    let end = lines.length;
-    for (let i = start + 1; i < lines.length; i += 1) {
-        if (NEXT_HEADING_RE.test(lines[i])) {
-            end = i;
-            break;
-        }
-    }
-    let insertAt = -1;
-    for (let i = start + 1; i < end; i += 1) {
-        const existing = lines[i].trim();
-        if (!CRITERION_RE.test(existing))
-            continue;
-        if (existing === line.trim())
-            throw new DuplicateCriterionError(path, line);
-        insertAt = i + 1;
-    }
-    if (insertAt === -1) {
-        // Empty section: land after the heading's blank line, so the result reads
-        // like every shipped task instead of butting against the heading.
-        insertAt = lines[start + 1]?.trim() === "" ? start + 2 : start + 1;
-    }
-    // F-1134 — a section whose only content is its blank line puts `insertAt` on
-    // the NEXT heading, so the criterion would land against it with nothing
-    // between. Cosmetic (it parses either way), but this is the very first write
-    // into a freshly scaffolded task, which is the file an author reads hardest.
-    const blankAfter = NEXT_HEADING_RE.test(lines[insertAt] ?? "") ? [""] : [];
-    lines.splice(insertAt, 0, line, ...blankAfter);
-    return lines.join("\n");
-}

package/dist/src/task/parseTask.d.ts

@@ -1,35 +0,0 @@
-import { type Task } from "./taskSchema.js";
-export declare function parseTaskFile(path: string): Promise<Task>;
-/** The task's declared twins, read WITHOUT requiring criteria (F-1074).
- *  `taskSchema` demands at least one criterion, and `pome checks add` needs the
- *  twin list BEFORE it has written one. Reuses this module's own section
- *  splitter and config schema, so it is not a second parser. */
-export declare function readConfigTwins(markdown: string): string[];
-/** One `[code]` criterion as an authoring surface sees it: the sentence, the twin
- *  whose declared vocabulary is supposed to grade it, and the human-facing marker
- *  reconstructed the way `parseCriteria` reconstructs it for error messages — so
- *  a report can echo a line the author can find by searching the file. */
-export interface CodeCriterion {
-    marker: string;
-    twin: string;
-    text: string;
-}
-/** The task's `[code]` criteria with each one's attributed twin, read WITHOUT the
- *  full task schema (F-1134). Same reason `readConfigTwins` exists, one step
- *  further along: `pome checks add` and `pome checks lint` audit files that are
- *  mid-edit, and `taskSchema` refuses one carrying no criteria or no resolvable
- *  seed. Reuses this module's own section splitter and criterion grammar, so it
- *  is not a second parser.
- *
- *  TOLERANT BY DESIGN. `parseCriteria` throws on a retired marker or a tag naming
- *  no declared twin, and it is right to — it gates a run. This reader only warns,
- *  so a line it cannot understand is skipped instead: turning an author's
- *  half-finished file into a crash is how a warning surface stops being used. */
-export declare function readCodeCriteria(markdown: string): CodeCriterion[];
-export declare function parseTask(markdown: string, slug?: string, sidecarSeed?: unknown, taskPath?: string): Task;
-/** The flat seed a single twin boots from. Single-twin scenarios return the
- *  flat `seedState` as-is; multi-twin scenarios return that twin's slice of the
- *  per-twin envelope (decided from `config.twins`, per the envelope-iff-multi-twin
- *  rule). Used by the local runner to seed each twin harness. */
-export declare function seedStateForTwin(scenario: Task, twin: string): unknown;
-export declare function formatTaskError(error: unknown, filePath: string): string;