@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/utils/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Error types for plan operations.
+ */
+/**
+ * Error thrown when a plan is not found.
+ * Includes structured data for fuzzy matching and helpful error messages.
+ */
+export class BlueprintNotFoundError extends Error {
+    searchedPath;
+    availableSlugs;
+    requestedSlug;
+    constructor(slug, searchedPath, availableSlugs) {
+        const message = buildPlanNotFoundMessage(slug, searchedPath, availableSlugs);
+        super(message);
+        this.name = 'BlueprintNotFoundError';
+        this.requestedSlug = slug;
+        this.searchedPath = searchedPath;
+        this.availableSlugs = availableSlugs;
+        // Maintains proper stack trace for where our error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, BlueprintNotFoundError);
+        }
+    }
+}
+/**
+ * Build error message parts for plan not found errors.
+ */
+function buildErrorParts(slug, searchedPath, availableSlugs) {
+    const parts = [`Plan ${slug} not found.`, `Searched: ${searchedPath}`];
+    if (!availableSlugs.length) {
+        parts.push('No plans available.');
+        return parts;
+    }
+    parts.push(`Available plans: ${availableSlugs.join(', ')}`);
+    return parts;
+}
+/**
+ * Build a helpful error message when a plan is not found.
+ * Includes searched path and available slugs.
+ */
+function buildPlanNotFoundMessage(slug, searchedPath, availableSlugs) {
+    return buildErrorParts(slug, searchedPath, availableSlugs).join('\n');
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/blueprint/utils/freshness.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Freshness Calculator for Implementation Plans
+ *
+ * Calculates freshness scores using exponential decay.
+ * Score = e^(-k * days), where k is calibrated so score = 0.5 at warning threshold.
+ */
+import type { BlueprintStatus } from '#core/schema';
+export type { FreshnessScore } from '#query/types';
+import type { FreshnessScore } from '#query/types';
+/**
+ * Calculate the freshness score for a plan.
+ *
+ * Uses exponential decay: score = e^(-k * days)
+ * The decay constant k is calibrated so score = 0.5 at the warning threshold.
+ *
+ * @param lastUpdated - The date the plan was last updated
+ * @param planStatus - The status of the plan (affects thresholds)
+ * @returns FreshnessScore with score, days since update, and status
+ */
+export declare function calculateFreshness(lastUpdated: Date, planStatus: BlueprintStatus): FreshnessScore;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/esm/blueprint/utils/freshness.js

@@ -0,0 +1,66 @@
+/**
+ * Freshness Calculator for Implementation Plans
+ *
+ * Calculates freshness scores using exponential decay.
+ * Score = e^(-k * days), where k is calibrated so score = 0.5 at warning threshold.
+ */
+/**
+ * Threshold configuration by plan status (in days).
+ *
+ * - in-progress: Actively worked on, needs frequent updates
+ * - draft: Not yet started, more relaxed thresholds
+ * - planned: Scheduled future work, relaxed thresholds
+ * - parked: Intentionally paused work, same thresholds as planned/draft
+ * - completed: Reference documentation, very relaxed thresholds
+ * - archived: Historical record, most relaxed thresholds
+ */
+const THRESHOLDS = {
+    'in-progress': { warning: 7, stale: 14, critical: 30 },
+    draft: { warning: 14, stale: 30, critical: 60 },
+    planned: { warning: 14, stale: 30, critical: 60 },
+    parked: { warning: 14, stale: 30, critical: 60 },
+    completed: { warning: 180, stale: 365, critical: 730 },
+    archived: { warning: 365, stale: 730, critical: 1460 },
+};
+/**
+ * Calculate the freshness score for a plan.
+ *
+ * Uses exponential decay: score = e^(-k * days)
+ * The decay constant k is calibrated so score = 0.5 at the warning threshold.
+ *
+ * @param lastUpdated - The date the plan was last updated
+ * @param planStatus - The status of the plan (affects thresholds)
+ * @returns FreshnessScore with score, days since update, and status
+ */
+export function calculateFreshness(lastUpdated, planStatus) {
+    const now = new Date();
+    // Use UTC calendar components to avoid DST-induced off-by-one errors
+    const nowUTC = Date.UTC(now.getFullYear(), now.getMonth(), now.getDate());
+    const lastUTC = Date.UTC(lastUpdated.getFullYear(), lastUpdated.getMonth(), lastUpdated.getDate());
+    const daysSinceUpdate = Math.floor((nowUTC - lastUTC) / (1000 * 60 * 60 * 24));
+    const thresholds = THRESHOLDS[planStatus];
+    // Calibrate k so that score = 0.5 at warning threshold
+    // e^(-k * warning) = 0.5
+    // -k * warning = ln(0.5) = -ln(2)
+    // k = ln(2) / warning
+    const k = Math.LN2 / thresholds.warning;
+    // Exponential decay: score = e^(-k * days)
+    // Use Math.max(0, daysSinceUpdate) to handle future dates
+    const score = Math.exp(-k * Math.max(0, daysSinceUpdate));
+    // Determine status based on thresholds
+    let status;
+    if (daysSinceUpdate >= thresholds.critical) {
+        status = 'critical';
+    }
+    else if (daysSinceUpdate >= thresholds.stale) {
+        status = 'stale';
+    }
+    else if (daysSinceUpdate >= thresholds.warning) {
+        status = 'aging';
+    }
+    else {
+        status = 'fresh';
+    }
+    return { score, daysSinceUpdate, status };
+}
+//# sourceMappingURL=freshness.js.map

package/dist/esm/blueprint/utils/package-assets.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Walk up from this file's location until the given path (relative to the
+ * package root) is found. Works whether running from src/ or dist/esm/.
+ */
+export declare function resolvePackageAsset(relativeFromRoot: string): string;
+//# sourceMappingURL=package-assets.d.ts.map

package/dist/esm/blueprint/utils/package-assets.js

@@ -0,0 +1,20 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Walk up from this file's location until the given path (relative to the
+ * package root) is found. Works whether running from src/ or dist/esm/.
+ */
+export function resolvePackageAsset(relativeFromRoot) {
+    let dir = path.dirname(new URL(import.meta.url).pathname);
+    for (let i = 0; i < 8; i++) {
+        const candidate = path.join(dir, relativeFromRoot);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return path.join(process.cwd(), relativeFromRoot);
+}
+//# sourceMappingURL=package-assets.js.map

package/dist/esm/blueprint/utils/string.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Escape special regex characters in a string so it can be used safely
+ * inside a `new RegExp(...)` constructor.
+ *
+ * Inlined as a pure helper to keep this package self-contained.
+ */
+export declare function escapeRegex(str: string): string;
+//# sourceMappingURL=string.d.ts.map

package/dist/esm/blueprint/utils/string.js

@@ -0,0 +1,10 @@
+/**
+ * Escape special regex characters in a string so it can be used safely
+ * inside a `new RegExp(...)` constructor.
+ *
+ * Inlined as a pure helper to keep this package self-contained.
+ */
+export function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=string.js.map

package/dist/esm/blueprint/utils/tech-debt-root.d.ts

@@ -0,0 +1,4 @@
+export declare const WEBPRESSO_TECH_DEBT_DIR = "webpresso/tech-debt";
+export declare const DEFAULT_TECH_DEBT_DIR = "tech-debt";
+export declare function resolveTechDebtRoot(projectPath?: string): string;
+//# sourceMappingURL=tech-debt-root.d.ts.map

package/dist/esm/blueprint/utils/tech-debt-root.js

@@ -0,0 +1,18 @@
+/**
+ * Resolves the tech-debt directory for a consumer repo.
+ *
+ * Generic consumers use `<repo>/tech-debt`. Webpresso keeps its historical
+ * `<repo>/webpresso/tech-debt` layout as a fallback when that directory or the
+ * `webpresso/config.yaml` sentinel is present.
+ */
+import { resolveConsumerRoot } from './blueprint-root.js';
+export const WEBPRESSO_TECH_DEBT_DIR = 'webpresso/tech-debt';
+export const DEFAULT_TECH_DEBT_DIR = 'tech-debt';
+export function resolveTechDebtRoot(projectPath) {
+    return resolveConsumerRoot({
+        defaultDir: DEFAULT_TECH_DEBT_DIR,
+        webpressoDir: WEBPRESSO_TECH_DEBT_DIR,
+        projectPath,
+    });
+}
+//# sourceMappingURL=tech-debt-root.js.map

package/dist/esm/blueprint/verification.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Verification block markdown helper.
+ *
+ * Owns three responsibilities, in order:
+ *
+ * 1. **Validate** caller-supplied evidence against the Evidence Contract
+ *    (see `./evidence.ts`). Trivial payloads, empty lists, and any evidence
+ *    item with `result === 'fail'` reject the transition without touching
+ *    markdown.
+ * 2. **Serialize** the canonicalized evidence into a stable markdown block
+ *    rooted under a fixed canonical header (`VERIFICATION_BLOCK_HEADER`).
+ *    The stable header is the anti-forgery anchor: future re-ingests can
+ *    detect tampering by re-canonicalizing and comparing.
+ * 3. **Edit** the blueprint `_overview.md` in-place (read → edit → write)
+ *    atomically and then trigger a re-ingest of the projection DB.
+ *
+ * This module is consumed by `wp_blueprint_task_verify` (Task 3.2). It does
+ * not register MCP tools and has no transitive MCP dependency.
+ */
+import { type Evidence } from './evidence.js';
+/**
+ * Canonical header used to anchor the verification block under a task.
+ *
+ * Stability of this string is part of the contract — re-ingest, audits,
+ * and tamper-detection all rely on grep-able presence. Do not change
+ * casing or punctuation without a migration plan.
+ */
+export declare const VERIFICATION_BLOCK_HEADER = "**Verification:**";
+export interface VerificationSuccess {
+    readonly ok: true;
+    readonly markdown: string;
+    readonly status: 'done';
+}
+export interface VerificationFailure {
+    readonly ok: false;
+    readonly next_action: 'verify_task';
+    readonly failures: readonly string[];
+}
+export type VerificationResult = VerificationSuccess | VerificationFailure;
+/**
+ * Apply an evidence list to a blueprint markdown buffer. Pure function — does
+ * not touch the filesystem.
+ *
+ * On success: returns the rewritten markdown with the canonical verification
+ * block inserted under the target task and the task status set to `done`.
+ *
+ * On failure: returns `next_action: 'verify_task'` with a structured failure
+ * list. Markdown is NOT modified on failure.
+ */
+export declare function applyVerification(markdown: string, taskId: string, evidence: readonly Evidence[]): VerificationResult;
+export interface WriteVerificationOptions {
+    readonly filePath: string;
+    readonly taskId: string;
+    readonly evidence: readonly Evidence[];
+    readonly cwd: string;
+    readonly reingest: (args: {
+        readonly cwd: string;
+    }) => Promise<void> | void;
+}
+/**
+ * Filesystem-backed wrapper around {@link applyVerification}.
+ *
+ * Reads the blueprint markdown, applies the verification, writes the result
+ * back, and triggers a re-ingest via the injected callback so the SQLite
+ * projection reflects the new state immediately.
+ *
+ * On failure, neither the file nor the projection is touched.
+ *
+ * Idempotency: re-applying the same canonical evidence produces the same
+ * bytes; the file write is a no-op semantically, and the re-ingest call
+ * remains fast because the underlying ingester is hash-aware.
+ */
+export declare function writeVerification(options: WriteVerificationOptions): Promise<VerificationResult>;
+/**
+ * Serialize evidence to the canonical markdown block.
+ *
+ * Format:
+ *
+ * ```text
+ * **Verification:**
+ *
+ * ```webpresso-evidence-v1
+ * [<canonical-json-evidence-array>]
+ * ```
+ * ```
+ *
+ * The fenced block uses a custom language tag (`webpresso-evidence-v1`) so
+ * future versions can introduce parallel formats without conflicting with
+ * existing tools' fence-language detection.
+ */
+export declare function serializeVerificationBlock(evidence: readonly Evidence[]): string;
+/**
+ * Parse evidence back out of a canonical verification block.
+ *
+ * Returns the parsed (and zod-validated) evidence list, or `null` if the
+ * block is missing, malformed, or contains evidence that no longer satisfies
+ * the Evidence Contract (which would indicate tampering).
+ */
+export declare function parseVerificationBlock(block: string): readonly Evidence[] | null;
+/**
+ * Read the canonical verification evidence recorded inside a specific task
+ * section only. This intentionally does not scan the whole markdown buffer:
+ * evidence for Task 1.1 must never satisfy Task 1.2 idempotency, sync, or
+ * finalization checks.
+ */
+export declare function readTaskVerification(markdown: string, taskId: string): readonly Evidence[] | null;
+/**
+ * Assert that a task has its own canonical verification block with at least
+ * one passing evidence item. Returns the task-local evidence on success.
+ */
+export declare function assertTaskHasCanonicalPassingEvidence(markdown: string, taskId: string): readonly Evidence[];
+/**
+ * Assert that each supplied task id has task-local canonical passing evidence.
+ */
+export declare function assertAllTasksHaveCanonicalPassingEvidence(markdown: string, taskIds: readonly string[]): void;
+//# sourceMappingURL=verification.d.ts.map

package/dist/esm/blueprint/verification.js

@@ -0,0 +1,246 @@
+/**
+ * Verification block markdown helper.
+ *
+ * Owns three responsibilities, in order:
+ *
+ * 1. **Validate** caller-supplied evidence against the Evidence Contract
+ *    (see `./evidence.ts`). Trivial payloads, empty lists, and any evidence
+ *    item with `result === 'fail'` reject the transition without touching
+ *    markdown.
+ * 2. **Serialize** the canonicalized evidence into a stable markdown block
+ *    rooted under a fixed canonical header (`VERIFICATION_BLOCK_HEADER`).
+ *    The stable header is the anti-forgery anchor: future re-ingests can
+ *    detect tampering by re-canonicalizing and comparing.
+ * 3. **Edit** the blueprint `_overview.md` in-place (read → edit → write)
+ *    atomically and then trigger a re-ingest of the projection DB.
+ *
+ * This module is consumed by `wp_blueprint_task_verify` (Task 3.2). It does
+ * not register MCP tools and has no transitive MCP dependency.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { escapeRegex } from '#utils/string';
+import { canonicalizeEvidenceList, evidenceListSchema } from './evidence.js';
+import { completeTask } from './markdown/helpers.js';
+import { buildTaskHeaderRegexForId, buildTaskSectionBoundaryRegex, TASK_HEADING_PREFIX_PATTERN, } from './markdown/task-heading.js';
+/**
+ * Canonical header used to anchor the verification block under a task.
+ *
+ * Stability of this string is part of the contract — re-ingest, audits,
+ * and tamper-detection all rely on grep-able presence. Do not change
+ * casing or punctuation without a migration plan.
+ */
+export const VERIFICATION_BLOCK_HEADER = '**Verification:**';
+const VERIFICATION_FENCE_LANG = 'webpresso-evidence-v1';
+const VERIFICATION_BLOCK_PATTERN = new RegExp(`\\n*${escapeRegex(VERIFICATION_BLOCK_HEADER)}\\n+\`\`\`${VERIFICATION_FENCE_LANG}\\n[\\s\\S]*?\\n\`\`\`\\n*`, 'g');
+/**
+ * Apply an evidence list to a blueprint markdown buffer. Pure function — does
+ * not touch the filesystem.
+ *
+ * On success: returns the rewritten markdown with the canonical verification
+ * block inserted under the target task and the task status set to `done`.
+ *
+ * On failure: returns `next_action: 'verify_task'` with a structured failure
+ * list. Markdown is NOT modified on failure.
+ */
+export function applyVerification(markdown, taskId, evidence) {
+    const parsed = evidenceListSchema.safeParse(evidence);
+    if (!parsed.success) {
+        return failure(parsed.error.issues.map((issue) => formatZodIssue(issue)));
+    }
+    const items = parsed.data;
+    const failingItems = items.filter((item) => item.result === 'fail');
+    if (failingItems.length > 0) {
+        return failure(failingItems.map((item, idx) => `evidence[${idx}] (kind=${item.kind}) has result: 'fail' — cannot transition to done`));
+    }
+    const passing = items.filter((item) => item.result === 'pass');
+    if (passing.length === 0) {
+        return failure(['evidence list contains zero passing items']);
+    }
+    const taskHeader = buildTaskHeaderRegexForId(taskId);
+    if (!taskHeader.test(markdown)) {
+        return failure([`task ${taskId} not found in blueprint markdown`]);
+    }
+    const block = serializeVerificationBlock(items);
+    // Replace any existing verification block inside the target task region
+    // BEFORE we mutate status so we cleanly replace rather than append.
+    const withoutExistingBlock = removeVerificationFromTask(markdown, taskId);
+    // Reuse the canonical task-completion mutation so verification and lifecycle
+    // completion cannot drift on status / blocked-state / acceptance behavior.
+    const withStatus = completeTask(withoutExistingBlock, taskId);
+    // Insert the canonical block immediately after the status line of the
+    // target task.
+    const withBlock = insertVerificationAfterStatus(withStatus, taskId, block);
+    return { ok: true, markdown: withBlock, status: 'done' };
+}
+/**
+ * Filesystem-backed wrapper around {@link applyVerification}.
+ *
+ * Reads the blueprint markdown, applies the verification, writes the result
+ * back, and triggers a re-ingest via the injected callback so the SQLite
+ * projection reflects the new state immediately.
+ *
+ * On failure, neither the file nor the projection is touched.
+ *
+ * Idempotency: re-applying the same canonical evidence produces the same
+ * bytes; the file write is a no-op semantically, and the re-ingest call
+ * remains fast because the underlying ingester is hash-aware.
+ */
+export async function writeVerification(options) {
+    const { filePath, taskId, evidence, cwd, reingest } = options;
+    const markdown = await readFile(filePath, 'utf8');
+    const result = applyVerification(markdown, taskId, evidence);
+    if (!result.ok) {
+        return result;
+    }
+    if (result.markdown !== markdown) {
+        await writeFile(filePath, result.markdown, 'utf8');
+    }
+    await reingest({ cwd });
+    return result;
+}
+/**
+ * Serialize evidence to the canonical markdown block.
+ *
+ * Format:
+ *
+ * ```text
+ * **Verification:**
+ *
+ * ```webpresso-evidence-v1
+ * [<canonical-json-evidence-array>]
+ * ```
+ * ```
+ *
+ * The fenced block uses a custom language tag (`webpresso-evidence-v1`) so
+ * future versions can introduce parallel formats without conflicting with
+ * existing tools' fence-language detection.
+ */
+export function serializeVerificationBlock(evidence) {
+    const json = canonicalizeEvidenceList(evidence);
+    return `${VERIFICATION_BLOCK_HEADER}\n\n\`\`\`${VERIFICATION_FENCE_LANG}\n${json}\n\`\`\``;
+}
+/**
+ * Parse evidence back out of a canonical verification block.
+ *
+ * Returns the parsed (and zod-validated) evidence list, or `null` if the
+ * block is missing, malformed, or contains evidence that no longer satisfies
+ * the Evidence Contract (which would indicate tampering).
+ */
+export function parseVerificationBlock(block) {
+    const pattern = new RegExp(`${escapeRegex(VERIFICATION_BLOCK_HEADER)}\\s*\\n+\`\`\`${VERIFICATION_FENCE_LANG}\\n([\\s\\S]*?)\\n\`\`\``, 'm');
+    const match = block.match(pattern);
+    if (!match)
+        return null;
+    const jsonText = match[1];
+    if (jsonText === undefined)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(jsonText);
+    }
+    catch {
+        return null;
+    }
+    const parsed = evidenceListSchema.safeParse(raw);
+    if (!parsed.success)
+        return null;
+    return parsed.data;
+}
+/**
+ * Read the canonical verification evidence recorded inside a specific task
+ * section only. This intentionally does not scan the whole markdown buffer:
+ * evidence for Task 1.1 must never satisfy Task 1.2 idempotency, sync, or
+ * finalization checks.
+ */
+export function readTaskVerification(markdown, taskId) {
+    const section = readTaskSection(markdown, taskId);
+    if (section === null)
+        return null;
+    return parseVerificationBlock(section);
+}
+/**
+ * Assert that a task has its own canonical verification block with at least
+ * one passing evidence item. Returns the task-local evidence on success.
+ */
+export function assertTaskHasCanonicalPassingEvidence(markdown, taskId) {
+    const evidence = readTaskVerification(markdown, taskId);
+    if (evidence === null) {
+        throw new Error(`Task ${taskId} is missing task-local canonical verification evidence`);
+    }
+    if (!evidence.some((item) => item.result === 'pass')) {
+        throw new Error(`Task ${taskId} verification contains no passing evidence`);
+    }
+    return evidence;
+}
+/**
+ * Assert that each supplied task id has task-local canonical passing evidence.
+ */
+export function assertAllTasksHaveCanonicalPassingEvidence(markdown, taskIds) {
+    for (const taskId of taskIds) {
+        assertTaskHasCanonicalPassingEvidence(markdown, taskId);
+    }
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function failure(failures) {
+    return { ok: false, next_action: 'verify_task', failures };
+}
+function formatZodIssue(issue) {
+    const path = issue.path.length > 0 ? issue.path.map(String).join('.') : '(root)';
+    return `${path}: ${issue.message}`;
+}
+function removeVerificationFromTask(markdown, taskId) {
+    return mapTaskSection(markdown, taskId, (section) => {
+        return section.replace(VERIFICATION_BLOCK_PATTERN, '\n\n').replace(/\n{3,}/g, '\n\n');
+    });
+}
+function readTaskSection(markdown, taskId) {
+    const headerPattern = buildTaskHeaderRegexForId(taskId);
+    const headerMatch = markdown.match(headerPattern);
+    if (!headerMatch || headerMatch.index === undefined)
+        return null;
+    const startIndex = headerMatch.index;
+    const restOfContent = markdown.slice(startIndex + headerMatch[0].length);
+    const nextSectionMatch = restOfContent.match(buildTaskSectionBoundaryRegex());
+    const endIndex = nextSectionMatch?.index !== undefined
+        ? startIndex + headerMatch[0].length + nextSectionMatch.index
+        : markdown.length;
+    return markdown.slice(startIndex, endIndex);
+}
+function insertVerificationAfterStatus(markdown, taskId, block) {
+    return mapTaskSection(markdown, taskId, (section) => {
+        const statusMatch = section.match(/(\*\*Status:\*\*\s*.+\n+)/i);
+        if (!statusMatch || statusMatch.index === undefined) {
+            // Fallback: append after the heading line.
+            const headingMatch = section.match(new RegExp(`(####\\s+${TASK_HEADING_PREFIX_PATTERN}Task\\s+[^\\n]+\\n+)`));
+            if (!headingMatch) {
+                return `${section}\n\n${block}\n`;
+            }
+            return section.replace(headingMatch[0], `${headingMatch[0]}${block}\n\n`);
+        }
+        return section.replace(statusMatch[0], `${statusMatch[0]}${block}\n\n`);
+    });
+}
+/**
+ * Apply a transform to the section of `markdown` covering the task with
+ * `taskId` (from its `#### Task X.Y:` heading to the next task or phase
+ * boundary). Sections outside the target task are returned unchanged.
+ */
+function mapTaskSection(markdown, taskId, transform) {
+    const headerPattern = buildTaskHeaderRegexForId(taskId);
+    const headerMatch = markdown.match(headerPattern);
+    if (!headerMatch || headerMatch.index === undefined)
+        return markdown;
+    const startIndex = headerMatch.index;
+    const restOfContent = markdown.slice(startIndex + headerMatch[0].length);
+    const nextSectionMatch = restOfContent.match(buildTaskSectionBoundaryRegex());
+    const endIndex = nextSectionMatch?.index !== undefined
+        ? startIndex + headerMatch[0].length + nextSectionMatch.index
+        : markdown.length;
+    const before = markdown.slice(0, startIndex);
+    const section = markdown.slice(startIndex, endIndex);
+    const after = markdown.slice(endIndex);
+    return `${before}${transform(section)}${after}`;
+}
+//# sourceMappingURL=verification.js.map

package/dist/esm/build/generate-skills-dir.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+/**
+ * generate-skills-dir.ts
+ *
+ * Reads catalog/agent/skills/<name>/SKILL.md and writes
+ * skills/<slug>/SKILL.md at the package root.
+ *
+ * Slug sanitization: spaces and non-alphanumeric chars become `-`;
+ * leading/trailing dashes are stripped; output is lowercased.
+ *
+ * Exits non-zero if a slug collision is detected.
+ */
+export {};
+//# sourceMappingURL=generate-skills-dir.d.ts.map

package/dist/esm/build/generate-skills-dir.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+/**
+ * generate-skills-dir.ts
+ *
+ * Reads catalog/agent/skills/<name>/SKILL.md and writes
+ * skills/<slug>/SKILL.md at the package root.
+ *
+ * Slug sanitization: spaces and non-alphanumeric chars become `-`;
+ * leading/trailing dashes are stripped; output is lowercased.
+ *
+ * Exits non-zero if a slug collision is detected.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+const PACKAGE_ROOT = dirname(dirname(import.meta.dirname));
+const CATALOG_SKILLS = join(PACKAGE_ROOT, 'catalog', 'agent', 'skills');
+const SKILLS_OUT = join(PACKAGE_ROOT, 'skills');
+function toSlug(name) {
+    return name
+        .replace(/[^a-z0-9]+/gi, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+}
+function main() {
+    if (!existsSync(CATALOG_SKILLS)) {
+        console.error(`catalog skills directory not found: ${CATALOG_SKILLS}`);
+        process.exit(1);
+    }
+    const entries = readdirSync(CATALOG_SKILLS).filter((entry) => {
+        const fullPath = join(CATALOG_SKILLS, entry);
+        return statSync(fullPath).isDirectory();
+    });
+    const seen = new Map();
+    let count = 0;
+    for (const entry of entries) {
+        const skillMdPath = join(CATALOG_SKILLS, entry, 'SKILL.md');
+        if (!existsSync(skillMdPath)) {
+            // Skip skill dirs without a SKILL.md (e.g. template-only dirs)
+            continue;
+        }
+        const slug = toSlug(entry);
+        if (seen.has(slug)) {
+            console.error(`Slug collision: "${entry}" and "${seen.get(slug)}" both produce slug "${slug}". Aborting.`);
+            process.exit(1);
+        }
+        seen.set(slug, entry);
+        const content = readFileSync(skillMdPath, 'utf-8');
+        const outDir = join(SKILLS_OUT, slug);
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(join(outDir, 'SKILL.md'), content, 'utf-8');
+        count++;
+    }
+    console.log(`generate-skills-dir: wrote ${count} skills to ${SKILLS_OUT}`);
+}
+main();
+//# sourceMappingURL=generate-skills-dir.js.map

package/dist/esm/ci/act-helper.d.ts

@@ -0,0 +1,29 @@
+export type CiActSecretProfileId = 'none' | 'github-api' | 'neon-control-plane';
+export interface CiActSecretProfile {
+    readonly id: CiActSecretProfileId;
+    readonly description: string;
+    readonly allowedKeys: readonly string[];
+    readonly requiredKeys: readonly string[];
+    readonly defaultSources: readonly string[];
+}
+export interface ResolveCiActSecretProfileOptions {
+    readonly workflowPath?: string;
+    readonly jobName?: string;
+    readonly explicitProfileId?: string;
+}
+export declare function isCiActSecretProfileId(value: string): value is CiActSecretProfileId;
+export declare function getCiActSecretProfile(profileId: CiActSecretProfileId): CiActSecretProfile;
+export declare function resolveCiActSecretProfile(options: ResolveCiActSecretProfileOptions): CiActSecretProfile;
+export declare function pickAllowedSecrets(secretMap: Record<string, string>, allowedKeys: readonly string[]): Record<string, string>;
+export declare function listMissingRequiredSecrets(secretMap: Record<string, string>, requiredKeys: readonly string[]): string[];
+export declare function normalizeActSecretsWithOptions(secretMaps: Array<Record<string, string>>, options: {
+    mapGithubPatToToken: boolean;
+}): Record<string, string>;
+export declare function renderSecretsFile(secretMap: Record<string, string>): string;
+export declare function injectDefaultActArgs(args: string[], platform?: NodeJS.Platform, arch?: NodeJS.Architecture): string[];
+export interface TempSecretsFile {
+    readonly path: string;
+    cleanup(): void;
+}
+export declare function writeTempSecretsFile(secretMap: Record<string, string>): TempSecretsFile;
+//# sourceMappingURL=act-helper.d.ts.map