frontier-mcp 0.1.0

package/dist/storage/markdown/ticket.js

@@ -0,0 +1,97 @@
+import { STATUSES } from '../../domain.js';
+import { parseLegacyBody } from './legacy.js';
+import { splitFrontmatter } from './frontmatter.js';
+/** `<NN>-<rest>.md` — `NN` carries sort order and nothing else. */
+const FILENAME_ORDER = /^(\d+)/;
+/**
+ * Parse one Ticket file. Schema-conformant files read from their frontmatter;
+ * everything else falls through to the Legacy parser and is flagged, because a
+ * server that is useless until its repo is migrated never gets installed.
+ */
+export function parseTicket(effort, file, fallbackOrder, revision) {
+    const { fields, body } = splitFrontmatter(file.contents);
+    const order = readOrder(file.filename) ?? fallbackOrder;
+    if (fields === undefined)
+        return parseLegacy(effort, order, file.contents, revision);
+    const id = text(fields['id']);
+    return {
+        id,
+        handle: handleFor(id, effort, order),
+        title: text(fields['title']) ?? '(untitled)',
+        kind: readKind(fields['kind']),
+        type: text(fields['type']),
+        status: readStatus(text(fields['status'])) ?? 'open',
+        triage: text(fields['triage']),
+        answerGist: text(fields['answer_gist']),
+        droppedReason: text(fields['dropped_reason']),
+        claimedBy: text(fields['claimed_by']),
+        claimedAt: text(fields['claimed_at']),
+        blockedBy: readEdgeList(fields['blocked_by']),
+        effort,
+        order,
+        legacy: false,
+        unrecognizedStatus: undefined,
+        collapsedRefs: [],
+        revision,
+        body: body.trim(),
+    };
+}
+function parseLegacy(effort, order, contents, revision) {
+    const inferred = parseLegacyBody(contents);
+    return {
+        id: inferred.id,
+        handle: handleFor(inferred.id, effort, order),
+        title: inferred.title,
+        kind: inferred.kind,
+        type: inferred.type,
+        status: inferred.status,
+        triage: inferred.triage,
+        // A Legacy file records its answer as prose in the body, not as a field.
+        answerGist: undefined,
+        droppedReason: undefined,
+        claimedBy: undefined,
+        claimedAt: undefined,
+        blockedBy: inferred.blockedBy,
+        effort,
+        order,
+        legacy: true,
+        unrecognizedStatus: inferred.unrecognizedStatus,
+        collapsedRefs: inferred.collapsedRefs,
+        revision,
+        body: contents.trim(),
+    };
+}
+/**
+ * A Ticket with no id still has to be nameable, or a whole Effort of Legacy Tickets
+ * has no route to its own bodies. `<effort>#<order>` is that fallback — an
+ * address, deliberately not an id: it is not repo-stable and never appears as
+ * an Edge.
+ */
+function handleFor(id, effort, order) {
+    return id ?? `${effort}#${String(order)}`;
+}
+/** `<NN>-...` gives sort order. A file with no numeric prefix has none of its own. */
+function readOrder(filename) {
+    const match = FILENAME_ORDER.exec(filename);
+    return match?.[1] === undefined ? undefined : Number(match[1]);
+}
+function readKind(value) {
+    return text(value) === 'decision' ? 'decision' : 'build';
+}
+function readStatus(value) {
+    return STATUSES.find(status => status === value);
+}
+/** A `blocked_by` list. Anything that is not a list of scalars reads as no Edges. */
+function readEdgeList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(entry => text(entry)).filter((entry) => entry !== undefined);
+}
+/** YAML scalars arrive as numbers and booleans too; only non-empty strings count. */
+function text(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const asText = String(value).trim();
+    return asText === '' ? undefined : asText;
+}
+//# sourceMappingURL=ticket.js.map

package/dist/storage/markdown/ticket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket.js","sourceRoot":"","sources":["../../../src/storage/markdown/ticket.ts"],"names":[],"mappings":"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"}

package/dist/storage/markdown/write.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A revision token: the file's modification time and size as read. Opaque above
+ * the seam — only this module builds one or compares two.
+ */
+export declare function revisionOf(mtimeMs: number, size: number): string;
+export declare function currentRevision(path: string): Promise<string | undefined>;
+/**
+ * Take an exclusive guard on one revision of one file, or fail.
+ *
+ * `open(..., 'wx')` is an atomic create-if-absent — the same primitive the spec
+ * names for id allocation. Racing processes all read the same revision, so they
+ * all derive the same guard name and exactly one creation succeeds. That is the
+ * compare-and-set an optimistic mtime check cannot provide across processes:
+ * without it, two sessions genuinely do both come away believing they hold the
+ * same Ticket.
+ *
+ * The guard is keyed to the revision it guards, so it cannot wedge anything. Any
+ * successful write changes the revision, which changes the name, so a guard left
+ * behind by a crash names a revision that will never be current again. It is
+ * swept on sight anyway once it is older than {@link GUARD_STALE_MS}.
+ *
+ * See ADR 0004 for why this is a guard rather than a lock file.
+ */
+export declare function withGuard<T>(path: string, revision: string, write: () => Promise<T>): Promise<T>;
+/** Raised when another process holds the guard for this exact revision. */
+export declare class GuardHeld extends Error {
+    constructor();
+}
+export declare function writeAtomically(path: string, contents: string): Promise<void>;
+/**
+ * The first half of {@link writeAtomically}, for a caller that has several files
+ * to land together: write the contents beside the target and hand back the
+ * temporary path, leaving the rename to the caller.
+ *
+ * Everything that can fail — a full disk, a bad path, a name too long — fails
+ * here, where nothing is visible yet. That is what lets a batch stage every file
+ * before renaming any, and so be all-or-none rather than merely per-file atomic.
+ */
+export declare function stage(path: string, contents: string): Promise<string>;
+/** Discard a staged file. Never throws: it runs on the path where something already went wrong. */
+export declare function unstage(temporary: string): Promise<void>;
+//# sourceMappingURL=write.d.ts.map

package/dist/storage/markdown/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/storage/markdown/write.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO/E;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACtB,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAED,2EAA2E;AAC3E,qBAAa,SAAU,SAAQ,KAAK;IAClC,cAGC;CACF;AAsBD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASnF;AAED;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW3E;AAED,mGAAmG;AACnG,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D"}

package/dist/storage/markdown/write.js

@@ -0,0 +1,134 @@
+import { rename, stat, writeFile, unlink } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+/**
+ * A revision token: the file's modification time and size as read. Opaque above
+ * the seam — only this module builds one or compares two.
+ */
+export function revisionOf(mtimeMs, size) {
+    return `${String(mtimeMs)}:${String(size)}`;
+}
+export async function currentRevision(path) {
+    try {
+        const info = await stat(path);
+        return revisionOf(info.mtimeMs, info.size);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write to a temporary file in the same directory, then rename over the target.
+ * Rename within a directory is atomic, so a reader sees either the old file or
+ * the new one and an interrupted write cannot leave a partial Ticket.
+ *
+ * The temporary name carries the process id and a counter rather than a random
+ * suffix, so a crashed write leaves something identifiable rather than a name
+ * nobody can attribute. There is no lock file: a crashed session must never be
+ * able to wedge the tracker.
+ */
+let sequence = 0;
+/**
+ * How long a guard may sit before it is assumed to belong to a crashed process.
+ * Only ever consulted for a guard whose revision is still current, which is a
+ * window of milliseconds in practice.
+ */
+const GUARD_STALE_MS = 30_000;
+/**
+ * Take an exclusive guard on one revision of one file, or fail.
+ *
+ * `open(..., 'wx')` is an atomic create-if-absent — the same primitive the spec
+ * names for id allocation. Racing processes all read the same revision, so they
+ * all derive the same guard name and exactly one creation succeeds. That is the
+ * compare-and-set an optimistic mtime check cannot provide across processes:
+ * without it, two sessions genuinely do both come away believing they hold the
+ * same Ticket.
+ *
+ * The guard is keyed to the revision it guards, so it cannot wedge anything. Any
+ * successful write changes the revision, which changes the name, so a guard left
+ * behind by a crash names a revision that will never be current again. It is
+ * swept on sight anyway once it is older than {@link GUARD_STALE_MS}.
+ *
+ * See ADR 0004 for why this is a guard rather than a lock file.
+ */
+export async function withGuard(path, revision, write) {
+    const guard = guardPath(path, revision);
+    try {
+        await writeFile(guard, `${String(process.pid)}\n`, { flag: 'wx' });
+    }
+    catch (error) {
+        if (error?.code !== 'EEXIST')
+            throw error;
+        if (!(await breakIfStale(guard)))
+            return Promise.reject(new GuardHeld());
+        return withGuard(path, revision, write);
+    }
+    try {
+        return await write();
+    }
+    finally {
+        await unlink(guard).catch(() => { });
+    }
+}
+/** Raised when another process holds the guard for this exact revision. */
+export class GuardHeld extends Error {
+    constructor() {
+        super('another session is writing this Ticket right now');
+        this.name = 'GuardHeld';
+    }
+}
+async function breakIfStale(guard) {
+    try {
+        const info = await stat(guard);
+        if (Date.now() - info.mtimeMs < GUARD_STALE_MS)
+            return false;
+        await unlink(guard);
+        return true;
+    }
+    catch {
+        // It vanished under us, which means the holder finished. Retrying is right.
+        return true;
+    }
+}
+/**
+ * Beside the file, hidden, and not `.md`, so no scan ever mistakes it for a
+ * Ticket. The revision is sanitized because it goes into a filename.
+ */
+function guardPath(path, revision) {
+    return join(dirname(path), `.${basename(path)}.${revision.replace(/[^\w.-]/g, '_')}.guard`);
+}
+export async function writeAtomically(path, contents) {
+    const temporary = await stage(path, contents);
+    try {
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await unstage(temporary);
+        throw error;
+    }
+}
+/**
+ * The first half of {@link writeAtomically}, for a caller that has several files
+ * to land together: write the contents beside the target and hand back the
+ * temporary path, leaving the rename to the caller.
+ *
+ * Everything that can fail — a full disk, a bad path, a name too long — fails
+ * here, where nothing is visible yet. That is what lets a batch stage every file
+ * before renaming any, and so be all-or-none rather than merely per-file atomic.
+ */
+export async function stage(path, contents) {
+    sequence += 1;
+    const temporary = join(dirname(path), `.frontier-${String(process.pid)}-${String(sequence)}.tmp`);
+    try {
+        await writeFile(temporary, contents, 'utf8');
+        return temporary;
+    }
+    catch (error) {
+        await unstage(temporary);
+        throw error;
+    }
+}
+/** Discard a staged file. Never throws: it runs on the path where something already went wrong. */
+export async function unstage(temporary) {
+    await unlink(temporary).catch(() => { });
+}
+//# sourceMappingURL=write.js.map

package/dist/storage/markdown/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../../src/storage/markdown/write.ts"],"names":[],"mappings":"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"}

package/dist/tools/create-tickets.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import type { Kind, Ticket, TicketDraft, TriageRole } from '../domain.ts';
+export declare const createTicketsInputSchema: {
+    effort: z.ZodString;
+    create: z.ZodOptional<z.ZodBoolean>;
+    tickets: z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            build: "build";
+            decision: "decision";
+        }>>;
+        type: z.ZodOptional<z.ZodString>;
+        triage: z.ZodOptional<z.ZodEnum<{
+            "needs-info": "needs-info";
+            "needs-triage": "needs-triage";
+            "ready-for-agent": "ready-for-agent";
+            "ready-for-human": "ready-for-human";
+            wontfix: "wontfix";
+        }>>;
+        blocked_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        body: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    root: z.ZodOptional<z.ZodString>;
+};
+export declare const createTicketsDescription: string;
+export interface DraftRequest {
+    readonly key?: string | undefined;
+    readonly title: string;
+    readonly kind?: Kind | undefined;
+    readonly type?: string | undefined;
+    readonly triage?: TriageRole | undefined;
+    readonly blocked_by?: readonly string[] | undefined;
+    readonly body?: string | undefined;
+}
+export interface PlannedBatch {
+    readonly drafts: readonly TicketDraft[];
+    /**
+     * The cycle check, re-run against the ids the batch is actually given and the
+     * workspace as it looks under the driver's reservations. A Ticket already on
+     * disk can declare an Edge on an id nobody has minted yet, and minting exactly
+     * that id is the moment that dangling Edge becomes a loop — which is invisible
+     * until the ids are real.
+     *
+     * It takes the Tickets rather than closing over the ones read here, because
+     * the read that produced those came before the reservations and may have
+     * missed the very Ticket whose dangling Edge is about to close.
+     */
+    readonly validate: (ids: readonly string[], tickets: readonly Ticket[]) => void;
+}
+/**
+ * Turn the request into drafts, refusing anything the schema or the graph does
+ * not allow. Everything resolvable without an id is settled here, so by the time
+ * the driver mints one the only rule left to check is the one that needed it.
+ */
+export declare function planBatch(requests: readonly DraftRequest[], existing: readonly Ticket[]): PlannedBatch;
+/**
+ * One line per Ticket: the id it was minted and the Edges as resolved — the two
+ * things a caller cannot work out for itself. The filename is deliberately not
+ * here: it is cosmetic, and the id is what everything addresses a Ticket by.
+ */
+export declare function renderCreated(effort: string, created: readonly Ticket[]): string;
+//# sourceMappingURL=create-tickets.d.ts.map

package/dist/tools/create-tickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-tickets.d.ts","sourceRoot":"","sources":["../../src/tools/create-tickets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAK1E,eAAO,MAAM,wBAAwB;IACnC,MAAM;IACN,MAAM;IAMN,OAAO;;;;;;;;;;;;;;;;;;IA8BP,IAAI;CACL,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAGmD,CAAC;AAEzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;CACjF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,YAAY,CAgBd;AAgHD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAgBhF"}

package/dist/tools/create-tickets.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+import { MINTED_ID, TRIAGE_ROLES } from '../domain.js';
+import { cycleThrough, renderCycle, resolveDraftEdges } from '../edges.js';
+import { indexById } from '../frontier.js';
+export const createTicketsInputSchema = {
+    effort: z.string().describe('Effort slug to create them in.'),
+    create: z
+        .boolean()
+        .optional()
+        .describe('Start the Effort if the workspace does not hold it. Otherwise an unknown slug fails.'),
+    tickets: z
+        .array(z.object({
+        key: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Your own temporary name for this Ticket, so siblings can declare Edges on it ' +
+            'before it has an id. Never stored. May not look like T<n>.'),
+        title: z.string().min(1),
+        kind: z.enum(['build', 'decision']).optional().describe('Defaults to build.'),
+        type: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('research / prototype / grilling / task. Only on a decision Ticket.'),
+        triage: z.enum(TRIAGE_ROLES).optional(),
+        blocked_by: z
+            .array(z.string().min(1))
+            .optional()
+            .describe('Edges: a real Ticket id from anywhere in the repo, or a key declared in this call.'),
+        body: z.string().optional().describe('The prose, written verbatim.'),
+    }))
+        .min(1)
+        .describe('The whole set, in the order they should be numbered.'),
+    root: z.string().optional().describe('Workspace directory. Defaults to the session workspace.'),
+};
+export const createTicketsDescription = 'Publish a whole breakdown in one call. Edges may name a sibling by a temporary key you choose; ' +
+    'the server mints repo-unique ids, numbers the files, and resolves the keys atomically — a ' +
+    'partial failure creates nothing. Cycles are refused. An unknown Effort needs create.';
+/**
+ * Turn the request into drafts, refusing anything the schema or the graph does
+ * not allow. Everything resolvable without an id is settled here, so by the time
+ * the driver mints one the only rule left to check is the one that needed it.
+ */
+export function planBatch(requests, existing) {
+    const drafts = requests.map(request => toDraft(request));
+    const keys = declaredKeys(drafts);
+    const provisional = drafts.map((draft, index) => draft.key ?? placeholderFor(index, keys));
+    checkEdges(drafts, keys, existing);
+    // Named by their keys, so a loop between two drafts reads in the caller's own
+    // vocabulary rather than in ids they have not seen yet.
+    checkCycles(drafts, provisional, existing);
+    return {
+        drafts,
+        validate: (ids, tickets) => {
+            checkCycles(drafts, ids, tickets, resolveDraftEdges(drafts, ids));
+        },
+    };
+}
+function toDraft(request) {
+    if (request.type !== undefined && (request.kind ?? 'build') !== 'decision') {
+        throw new Error(`"${request.title}" is a build Ticket, so it has no type — that field records which ` +
+            'wayfinder shape a decision Ticket is.');
+    }
+    return {
+        key: request.key,
+        title: request.title,
+        kind: request.kind ?? 'build',
+        type: request.type,
+        triage: request.triage,
+        blockedBy: request.blocked_by ?? [],
+        body: request.body,
+    };
+}
+function declaredKeys(drafts) {
+    const keys = new Set();
+    for (const draft of drafts) {
+        if (draft.key === undefined)
+            continue;
+        // A key shaped like an id is ambiguous: an Edge naming `T8` could mean the
+        // sibling draft or the Ticket already answering to it, and the server would
+        // have to guess which.
+        if (MINTED_ID.test(draft.key)) {
+            throw new Error(`Temporary key "${draft.key}" looks like a Ticket id. Pick a name that does not, ` +
+                'so an Edge naming it is never ambiguous.');
+        }
+        if (keys.has(draft.key))
+            throw new Error(`Temporary key "${draft.key}" is used twice.`);
+        keys.add(draft.key);
+    }
+    return keys;
+}
+/**
+ * An Edge is either a real id — which may point at nothing yet, since a dangling
+ * Edge is a Board warning rather than a refusal — or a key declared in this same
+ * call. Anything else is a typo, and letting it through would quietly turn a
+ * mistyped key into a dangling Edge nobody notices.
+ */
+function checkEdges(drafts, keys, existing) {
+    const ids = indexById(existing);
+    for (const draft of drafts) {
+        for (const edge of draft.blockedBy) {
+            if (keys.has(edge) || ids.has(edge) || MINTED_ID.test(edge))
+                continue;
+            throw new Error(`"${draft.title}" is blocked by "${edge}", which is neither a Ticket id nor a key ` +
+                `declared in this call. Declared keys: ${[...keys].join(', ') || '(none)'}`);
+        }
+    }
+}
+/**
+ * The graph the batch would produce: existing Tickets by id, plus the drafts
+ * under `names` — their temporary keys before allocation, their real ids after.
+ *
+ * A draft with no key is unreachable by any sibling, but still needs checking:
+ * once it has an id, its own Edges can lead back to it through the Tickets
+ * already on disk.
+ */
+function checkCycles(drafts, names, existing, resolve = edge => edge) {
+    const ids = indexById(existing);
+    const nodes = new Map();
+    const edges = new Map();
+    drafts.forEach((draft, index) => {
+        const name = names[index] ?? '';
+        nodes.set(name, draft);
+        edges.set(name, draft.blockedBy.map(resolve));
+    });
+    const edgesOf = id => edges.get(id) ?? ids.get(id)?.blockedBy ?? [];
+    for (const [node, draft] of nodes) {
+        const cycle = cycleThrough(node, edgesOf);
+        if (cycle !== undefined) {
+            throw new Error(`"${draft.title}" would close a cycle in the Edge graph: ${renderCycle(cycle)}. ` +
+                'Nothing in a cycle is ever takeable, so nothing was created.');
+        }
+    }
+}
+/** A name for a keyless draft that no Edge can collide with. */
+function placeholderFor(index, keys) {
+    let name = `#${String(index)}`;
+    while (keys.has(name))
+        name = `${name}.`;
+    return name;
+}
+/**
+ * One line per Ticket: the id it was minted and the Edges as resolved — the two
+ * things a caller cannot work out for itself. The filename is deliberately not
+ * here: it is cosmetic, and the id is what everything addresses a Ticket by.
+ */
+export function renderCreated(effort, created) {
+    const lines = [`${effort}: ${String(created.length)} created`];
+    for (const ticket of created) {
+        lines.push([
+            ticket.id ?? ticket.handle,
+            ticket.title,
+            ticket.blockedBy.length === 0 ? undefined : `blocked_by=${ticket.blockedBy.join(',')}`,
+        ]
+            .filter(part => part !== undefined)
+            .join('  '));
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=create-tickets.js.map

package/dist/tools/create-tickets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-tickets.js","sourceRoot":"","sources":["../../src/tools/create-tickets.ts"],"names":[],"mappings":"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"}

package/dist/tools/edit-map.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { MapDocument, MapEdit } from '../domain.ts';
+export declare const editMapInputSchema: {
+    effort: z.ZodString;
+    create: z.ZodOptional<z.ZodBoolean>;
+    destination: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    add_fog: z.ZodOptional<z.ZodString>;
+    graduate_fog: z.ZodOptional<z.ZodString>;
+    rule_out: z.ZodOptional<z.ZodString>;
+    expected_revision: z.ZodOptional<z.ZodString>;
+    root: z.ZodOptional<z.ZodString>;
+};
+export declare const editMapDescription: string;
+export interface EditMapRequest {
+    readonly destination?: string | undefined;
+    readonly notes?: string | undefined;
+    readonly add_fog?: string | undefined;
+    readonly graduate_fog?: string | undefined;
+    readonly rule_out?: string | undefined;
+}
+/** Turn the tool args into the edit the driver applies. */
+export declare function mapEditFor(request: EditMapRequest): MapEdit;
+/**
+ * Destination and Notes for orientation, then the fog and out-of-scope lists.
+ * Never the whole Map body, and never Decisions-so-far — that is derived.
+ */
+export declare function renderMap(effort: string, document: MapDocument): string;
+//# sourceMappingURL=edit-map.d.ts.map

package/dist/tools/edit-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-map.d.ts","sourceRoot":"","sources":["../../src/tools/edit-map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEzD,eAAO,MAAM,kBAAkB;IAC7B,MAAM;IACN,MAAM;IAQN,WAAW;IACX,KAAK;IACL,OAAO;IACP,YAAY;IAKZ,QAAQ;IAKR,iBAAiB;IAQjB,IAAI;CACL,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAIyE,CAAC;AAEzG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAQ3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM,CAwBvE"}

package/dist/tools/edit-map.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+export const editMapInputSchema = {
+    effort: z.string().describe('Effort slug whose Map to read or edit.'),
+    create: z
+        .boolean()
+        .optional()
+        .describe('Start a missing Effort and its Map. Only for Effort/Map that do not exist yet — ' +
+        'not a flag to send on every call. Does not change revision rules for mutations on an ' +
+        'existing Map; create with no section fields reads an existing Map like a plain read.'),
+    destination: z.string().optional().describe('Replace the Destination section.'),
+    notes: z.string().optional().describe('Replace the Notes section.'),
+    add_fog: z.string().min(1).optional().describe('Append a fog patch under Not yet specified.'),
+    graduate_fog: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Remove a fog patch matched on its text. Fails when none match.'),
+    rule_out: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Append a hand-ruled item under Out of scope. Never touches Decisions-so-far.'),
+    expected_revision: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Revision from a prior edit_map read. Required when overwriting an existing Map; ' +
+        'omitted when creating one.'),
+    root: z.string().optional().describe('Workspace directory. Defaults to the session workspace.'),
+};
+export const editMapDescription = "Read a Map's Destination and Notes, or edit one typed section — set Destination or Notes, " +
+    'add or graduate a fog patch, rule something out of scope — without rewriting the others. ' +
+    'Decisions-so-far is generated from resolved Tickets and never accepted as input. ' +
+    'Mutations pass expected_revision from a prior read so concurrent sessions cannot clobber each other.';
+/** Turn the tool args into the edit the driver applies. */
+export function mapEditFor(request) {
+    return {
+        ...(request.destination !== undefined ? { destination: request.destination } : {}),
+        ...(request.notes !== undefined ? { notes: request.notes } : {}),
+        ...(request.add_fog !== undefined ? { addFog: request.add_fog } : {}),
+        ...(request.graduate_fog !== undefined ? { graduateFog: request.graduate_fog } : {}),
+        ...(request.rule_out !== undefined ? { ruleOut: request.rule_out } : {}),
+    };
+}
+/**
+ * Destination and Notes for orientation, then the fog and out-of-scope lists.
+ * Never the whole Map body, and never Decisions-so-far — that is derived.
+ */
+export function renderMap(effort, document) {
+    const lines = [`effort: ${effort}`, `map revision: ${document.revision}`];
+    if (document.destination !== undefined) {
+        lines.push(labelled('destination', document.destination));
+    }
+    else {
+        lines.push('destination: (none)');
+    }
+    if (document.notes !== undefined) {
+        lines.push(labelled('notes', document.notes));
+    }
+    else {
+        lines.push('notes: (none)');
+    }
+    lines.push('', 'not yet specified:');
+    if (document.notYetSpecified.length === 0)
+        lines.push('  (none)');
+    else
+        for (const patch of document.notYetSpecified)
+            lines.push(`  - ${patch}`);
+    lines.push('', 'out of scope:');
+    if (document.outOfScope.length === 0)
+        lines.push('  (none)');
+    else
+        for (const item of document.outOfScope)
+            lines.push(`  - ${item}`);
+    return lines.join('\n');
+}
+function labelled(label, prose) {
+    const [first, ...rest] = prose.split('\n');
+    return [`${label}: ${first}`, ...rest.map(line => `  ${line}`)].join('\n');
+}
+//# sourceMappingURL=edit-map.js.map

package/dist/tools/edit-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-map.js","sourceRoot":"","sources":["../../src/tools/edit-map.ts"],"names":[],"mappings":"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"}