frontier-mcp 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# frontier-mcp
+
+An MCP server that serves the markdown issue tracker under `.scratch/` as a queryable graph — so agents
+stop re-parsing prose to learn what is open, blocked, or takeable.
+
+## Requirements
+
+- Node 24 or later
+- npx to run it; pnpm for development of this package
+
+## Install once (user scope)
+
+Register FrontierMCP once in your **user-level** MCP config, pinned to a released version. Every
+repository you open then gets the server automatically — no per-repo `mcp.json` file.
+
+In Cursor, edit `~/.cursor/mcp.json` (create the file if it does not exist); other MCP clients take the
+same command and arguments in their own user-scope server list:
+
+```json
+{
+  "mcpServers": {
+    "frontier": {
+      "command": "npx",
+      "args": ["-y", "frontier-mcp@x.y.z"]
+    }
+  }
+}
+```
+
+Replace `x.y.z` with a published version — see the
+[releases](https://github.com/51ck/frontier-mcp/releases). The pin is the version you get; nothing
+bumps it for you.
+
+Restart your editor after saving.
+
+## First use in a repository
+
+1. Open the repository in your editor. FrontierMCP resolves the workspace from the session working
+   directory — walking upward to the nearest `.scratch/` or `.git/` — so opening the project is the
+   only setup step.
+2. Read the tracker configuration document once: fetch MCP resource `frontier://tracker-doc`, or read
+   [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md) in a repo that vendors it.
+3. Call `list_efforts` to see whether `.scratch/` exists yet.
+4. Call `get_board` on an Effort to see the Frontier, then `get_tickets` only for the ids you work.
+
+A repository with no `.scratch/` directory is not an error. Create the first Effort with
+`create_tickets`, `edit_map`, or `spec` and `create: true`.
+
+## Override the workspace
+
+Optional, per call or per session:
+
+- Pass `root` on any tool call to read another directory.
+- Set `FRONTIER_ROOT` in the server environment for a non-standard layout.
+
+## Tools
+
+Eight tools: `list_efforts`, `get_board`, `get_tickets`, `create_tickets`, `update_ticket`,
+`edit_map`, `spec`, `migrate_effort`. See the tracker configuration document for when to use each.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm run check
+pnpm run build
+node src/bin.ts
+```
+
+## Releasing
+
+Publishing is CI-only via [release-it](https://github.com/release-it/release-it). There is no local
+publish script, and adding one would mean minting the long-lived npm token that the CI setup exists
+to avoid.
+
+1. Merge the work you want to ship to `master`.
+2. On GitHub: **Actions → Release → Run workflow**, pick `patch` / `minor` / `major`.
+3. The workflow runs checks + tests, bumps `package.json`, updates `CHANGELOG.md`, tags
+   `v*`, creates a GitHub Release, and publishes to npm with `pnpm`.
+4. Bump the pinned version in your user MCP config (`frontier-mcp@x.y.z`) when you want the
+   new build — pins stay manual on purpose.
+
+The workflow is dispatchable from any branch but refuses to run off `master`: release-it commits,
+tags and pushes before it publishes, so a release from a feature branch would rewrite that branch.
+
+Local dry-run (no tag, no publish). It needs a clean working tree and an upstream branch, so commit
+first:
+
+```bash
+pnpm run release:dry
+```
+
+npm publishing uses **Trusted Publishing** — GitHub Actions OIDC, configured for this repo on
+npmjs.com, so there is no `NPM_TOKEN` to rotate.
+
+Before changing `.release-it.json` or the workflow, read the release-it bullet in
+[AGENTS.md](./AGENTS.md) Work Guidance. Several settings there look removable and are not — the
+absent `registry-url`, `npm.skipChecks`, and the pnpm 10 pin each exist for a reason recorded in one
+place so it cannot drift.
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createFrontierMCP } from './server.js';
+const frontier = createFrontierMCP();
+// The index is built by a full scan before the transport connects, so the first
+// call is served warm. A workspace that cannot be scanned yet is not fatal:
+// every call resolves its own workspace regardless.
+await frontier.warmUp().catch(() => { });
+await frontier.server.connect(new StdioServerTransport());
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;AAErC,gFAAgF;AAChF,4EAA4E;AAC5E,oDAAoD;AACpD,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAExC,MAAM,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC"}

package/dist/domain.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The vocabulary from CONTEXT.md, as types. Everything above the storage driver
+ * speaks in these terms.
+ */
+/**
+ * Which Header doc an Effort holds. An Effort has zero, one, or two — a Map, a
+ * Spec, or a Map that later gained a Spec.
+ *
+ * Deliberately not named for a "kind": CONTEXT.md reserves Kind for a Ticket's
+ * `build`/`decision` shape.
+ */
+export type HeaderDoc = 'map' | 'spec';
+/** Which of the two shapes a Ticket is. */
+export type Kind = 'build' | 'decision';
+/**
+ * The shape of a minted id: `T<n>`, visibly an id so it is never mistaken for a
+ * sort position. Ids preserved verbatim through migration need not match — those
+ * occupy their name without being part of the counter.
+ *
+ * Both sides of the storage seam test against this, so it lives with the rest of
+ * the vocabulary rather than in either of them.
+ */
+export declare const MINTED_ID: RegExp;
+/** A Ticket's position in the graph's lifecycle. Owned by the server. */
+export type Status = 'open' | 'claimed' | 'resolved' | 'dropped';
+export declare const STATUSES: readonly Status[];
+/**
+ * A Ticket without its body — everything a Board line needs. Bodies are fetched
+ * separately, so a Board never pays for prose it does not show.
+ */
+export interface TicketSummary {
+    /** `T<n>`, unique repo-wide. Absent on a Legacy Ticket that carries no id. */
+    readonly id: string | undefined;
+    /**
+     * How to name this Ticket in a call. The id when it has one; otherwise
+     * `<effort>#<order>`, which is the only handle an id-less Legacy Ticket has
+     * until migration mints it a real one.
+     */
+    readonly handle: string;
+    readonly title: string;
+    readonly kind: Kind;
+    /** `research` / `prototype` / `grilling` / `task`. Only when `kind` is `decision`. */
+    readonly type: string | undefined;
+    readonly status: Status;
+    /** A `/triage` label. A separate field from {@link status}. */
+    readonly triage: string | undefined;
+    /** Required when resolved — the one line that makes a Board of finished work readable. */
+    readonly answerGist: string | undefined;
+    /** Required when dropped. What the Map's Out-of-scope section renders. */
+    readonly droppedReason: string | undefined;
+    /** Who holds the claim, and when they took it. Set together. */
+    readonly claimedBy: string | undefined;
+    readonly claimedAt: string | undefined;
+    /** Edges: the Tickets that must finish first, as plain ids resolved repo-wide. */
+    readonly blockedBy: readonly string[];
+    /** The slug of the Effort that owns this Ticket. */
+    readonly effort: string;
+    /** Sort order within its Effort. Order only — never identity. */
+    readonly order: number;
+    /**
+     * A Ticket predating the schema, parsed best-effort. Its title, status, and
+     * Edges are inferences an agent should distrust.
+     */
+    readonly legacy: boolean;
+    /** The raw `Status:` text of a Legacy Ticket whose value did not map. */
+    readonly unrecognizedStatus: string | undefined;
+    /** Sub-slice references (`T38.1`) coarsened to the Ticket that exists. */
+    readonly collapsedRefs: readonly string[];
+    /**
+     * An opaque token for what was read. A write passes back the one it read and
+     * is refused if the stored Ticket has moved on. The markdown driver builds it
+     * from the file's modification time and size; another driver would use
+     * whatever its store offers, so nothing above the seam may parse it.
+     */
+    readonly revision: string;
+}
+/** A Ticket with its prose. */
+export interface Ticket extends TicketSummary {
+    readonly body: string;
+}
+/**
+ * One Effort: enough to choose one without opening it. Frontier size is not a
+ * field — it is computed from the Tickets, like the Frontier itself.
+ */
+export interface Effort {
+    /** The Effort's identity. Unique within a workspace. */
+    readonly slug: string;
+    /** Which Header docs the Effort holds, `map` before `spec`. */
+    readonly headerDocs: readonly HeaderDoc[];
+    /** How many Tickets the Effort holds. */
+    readonly ticketCount: number;
+    /**
+     * Where this line of enquiry is going, from the Map's Destination. Absent
+     * when the Effort has no Map, or a Map that has not been given one.
+     */
+    readonly destination: string | undefined;
+    /**
+     * The opening of the Effort's Spec. Not a Destination — a Spec has no such
+     * section — but it is the orienting text a Spec-only Effort does have, and a
+     * Board that opens with nothing leaves every Ticket line below uninterpretable.
+     */
+    readonly specOpening: string | undefined;
+}
+/**
+ * The mutation points on a Ticket, in the vocabulary rather than the storage
+ * format. A field left out is left alone; `null` clears one that was set.
+ *
+ * `answer` is a body mutation point rather than a field — a Ticket body is
+ * opaque apart from the three places the schema says are edited.
+ */
+export interface TicketEdit {
+    readonly status?: Status;
+    readonly triage?: TriageRole;
+    readonly claimedBy?: string | null;
+    readonly claimedAt?: string | null;
+    readonly answerGist?: string | null;
+    readonly droppedReason?: string | null;
+    readonly answer?: string;
+    /** Replaces the Edge list outright. An empty list clears it. */
+    readonly blockedBy?: readonly string[];
+    /** Appended to the comment log, verbatim. Nothing is added around it. */
+    readonly comment?: string;
+    /** Acceptance criteria to tick, addressed by their text. */
+    readonly tick?: readonly string[];
+}
+/**
+ * A Ticket asked for but not yet minted an id.
+ *
+ * `key` is the caller's own temporary name for this draft, and exists only for
+ * the length of the call: sibling drafts declare Edges on it before any id
+ * exists, which is what removes the create-then-wire second pass. It is never
+ * stored, and never appears in a file.
+ */
+export interface TicketDraft {
+    /**
+     * The caller's temporary name. Never `T<n>` — a key shaped like an id could
+     * not be told apart from the real one an Edge might mean.
+     */
+    readonly key: string | undefined;
+    readonly title: string;
+    readonly kind: Kind;
+    readonly type: string | undefined;
+    readonly triage: TriageRole | undefined;
+    /** Edges, each either a real Ticket id or a sibling draft's {@link key}. */
+    readonly blockedBy: readonly string[];
+    /** The prose, written verbatim. A draft with none produces a Ticket with none. */
+    readonly body: string | undefined;
+}
+/** The five roles `/triage` writes. A Status is never one of these. */
+export declare const TRIAGE_ROLES: readonly ['needs-triage', 'needs-info', 'ready-for-agent', 'ready-for-human', 'wontfix'];
+export type TriageRole = (typeof TRIAGE_ROLES)[number];
+/**
+ * A Map's typed sections, without Decisions-so-far — that section is derived
+ * from resolved Tickets and never read from the file.
+ */
+export interface MapDocument {
+    readonly destination: string | undefined;
+    readonly notes: string | undefined;
+    /** Fog patches under Not yet specified, in file order. */
+    readonly notYetSpecified: readonly string[];
+    /** Hand-ruled Out-of-scope items. Dropped Tickets are not here — they render. */
+    readonly outOfScope: readonly string[];
+    readonly revision: string;
+}
+/**
+ * A section mutation on a Map. A field left out is left alone. Decisions-so-far
+ * is never a field — it is regenerated from Tickets on every write.
+ */
+export interface MapEdit {
+    readonly destination?: string;
+    readonly notes?: string;
+    /** Append a fog patch to Not yet specified. */
+    readonly addFog?: string;
+    /** Remove a fog patch matched on its text. Fails when none match. */
+    readonly graduateFog?: string;
+    /** Append a hand-ruled item to Out of scope. */
+    readonly ruleOut?: string;
+}
+/**
+ * A Spec as an opaque document. Nothing edits it section by section; the driver
+ * stores the bytes and the tool layer may present them with framing the store
+ * itself does not know about.
+ */
+export interface SpecDocument {
+    /** Opaque Spec document as stored. */
+    readonly body: string;
+    readonly revision: string;
+}
+/** How a migration call may rewrite filenames. */
+export interface MigrateOptions {
+    /**
+     * Report every change and write nothing. Planned mint ids come from the
+     * current scan (`max + 1`) without taking allocation guards.
+     */
+    readonly preview: boolean;
+    /**
+     * Rename Ticket files to `<NN>-T<n>-<slug>.md`. Off by default so relative
+     * links in Maps and Tickets keep resolving.
+     */
+    readonly rename: boolean;
+}
+/** One Ticket a migration would touch, or did. */
+export interface MigrationChange {
+    /** Handle before the call — the id when it had one, else `<effort>#<order>`. */
+    readonly beforeHandle: string;
+    /** Id after migration — preserved or newly minted. */
+    readonly id: string;
+    readonly title: string;
+    /** True when this call (or preview) assigns a fresh id. */
+    readonly minted: boolean;
+    /** True when the file was Legacy and gains schema frontmatter. */
+    readonly normalized: boolean;
+    /**
+     * Cosmetic Ticket filenames (basenames only) when rename would move the file.
+     * Absent when filenames stay put. Not filesystem paths — those stay below the
+     * storage seam.
+     */
+    readonly fromName: string | undefined;
+    readonly toName: string | undefined;
+    /** Edges as they will be written after bare sort-order remapping. */
+    readonly blockedBy: readonly string[];
+}
+/** The result of migrating one Effort — enough for the tool to render a report. */
+export interface MigrationReport {
+    readonly effort: string;
+    readonly preview: boolean;
+    readonly renamed: boolean;
+    readonly changes: readonly MigrationChange[];
+}
+//# sourceMappingURL=domain.d.ts.map

package/dist/domain.d.ts.map

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

package/dist/domain.js

@@ -0,0 +1,23 @@
+/**
+ * The vocabulary from CONTEXT.md, as types. Everything above the storage driver
+ * speaks in these terms.
+ */
+/**
+ * The shape of a minted id: `T<n>`, visibly an id so it is never mistaken for a
+ * sort position. Ids preserved verbatim through migration need not match — those
+ * occupy their name without being part of the counter.
+ *
+ * Both sides of the storage seam test against this, so it lives with the rest of
+ * the vocabulary rather than in either of them.
+ */
+export const MINTED_ID = /^T(\d+)$/;
+export const STATUSES = ['open', 'claimed', 'resolved', 'dropped'];
+/** The five roles `/triage` writes. A Status is never one of these. */
+export const TRIAGE_ROLES = [
+    'needs-triage',
+    'needs-info',
+    'ready-for-agent',
+    'ready-for-human',
+    'wontfix',
+];
+//# sourceMappingURL=domain.js.map

package/dist/domain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.js","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,UAAU,CAAC;AAKpC,MAAM,CAAC,MAAM,QAAQ,GAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;AAiItF,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,cAAc;IACd,YAAY;IACZ,iBAAiB;IACjB,iBAAiB;IACjB,SAAS;CACD,CAAC"}

package/dist/edges.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Edge-graph validation, above the storage seam because a cycle is a rule about
+ * the domain rather than about storage — the same reason the Status model is
+ * checked in the tool layer.
+ */
+import type { TicketDraft } from './domain.ts';
+/**
+ * How an Edge on a batch of drafts reads once the ids are real: a temporary key
+ * becomes the id its draft was given, and anything else is already an id.
+ *
+ * Both sides of the seam need this and must agree — the tool layer resolves to
+ * check for cycles, the driver resolves to write the frontmatter, and a graph
+ * approved under one resolution and written under another would be neither.
+ */
+export declare function resolveDraftEdges(drafts: readonly TicketDraft[], ids: readonly string[]): (edge: string) => string;
+/** The Edges leaving one node, by id. A node nothing knows about has none. */
+export type EdgesOf = (id: string) => readonly string[];
+/**
+ * The cycle running through `node`, as the path back to itself, or undefined
+ * when there is none.
+ *
+ * A cycle is rejected at write time because it makes the Frontier undefined:
+ * nothing in one is ever takeable, and no reader can tell which Edge was the
+ * mistake. It is checked on creation and on Edge updates alike, since the
+ * second is the easier way to close a loop.
+ *
+ * Only a cycle through `node` counts. A cycle elsewhere in the workspace is
+ * somebody's hand edit and not this caller's to answer for — refusing it here
+ * would make an unrelated Effort unwritable, and the Board already reports the
+ * graph damage it causes.
+ */
+export declare function cycleThrough(node: string, edgesOf: EdgesOf): readonly string[] | undefined;
+/** How a refused cycle reads: the loop, in the direction the Edges point. */
+export declare function renderCycle(cycle: readonly string[]): string;
+//# sourceMappingURL=edges.d.ts.map

package/dist/edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edges.d.ts","sourceRoot":"","sources":["../src/edges.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAS1B;AAED,8EAA8E;AAC9E,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAoB1F;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE5D"}

package/dist/edges.js

@@ -0,0 +1,61 @@
+/**
+ * Edge-graph validation, above the storage seam because a cycle is a rule about
+ * the domain rather than about storage — the same reason the Status model is
+ * checked in the tool layer.
+ */
+/**
+ * How an Edge on a batch of drafts reads once the ids are real: a temporary key
+ * becomes the id its draft was given, and anything else is already an id.
+ *
+ * Both sides of the seam need this and must agree — the tool layer resolves to
+ * check for cycles, the driver resolves to write the frontmatter, and a graph
+ * approved under one resolution and written under another would be neither.
+ */
+export function resolveDraftEdges(drafts, ids) {
+    const byKey = new Map();
+    drafts.forEach((draft, index) => {
+        const id = ids[index];
+        if (draft.key !== undefined && id !== undefined)
+            byKey.set(draft.key, id);
+    });
+    return edge => byKey.get(edge) ?? edge;
+}
+/**
+ * The cycle running through `node`, as the path back to itself, or undefined
+ * when there is none.
+ *
+ * A cycle is rejected at write time because it makes the Frontier undefined:
+ * nothing in one is ever takeable, and no reader can tell which Edge was the
+ * mistake. It is checked on creation and on Edge updates alike, since the
+ * second is the easier way to close a loop.
+ *
+ * Only a cycle through `node` counts. A cycle elsewhere in the workspace is
+ * somebody's hand edit and not this caller's to answer for — refusing it here
+ * would make an unrelated Effort unwritable, and the Board already reports the
+ * graph damage it causes.
+ */
+export function cycleThrough(node, edgesOf) {
+    // Reachability is monotone, so a node explored once and found not to reach
+    // `node` never will. That also stops a pre-existing cycle downstream from
+    // spinning forever.
+    const explored = new Set([node]);
+    const walk = (from, trail) => {
+        for (const next of edgesOf(from)) {
+            if (next === node)
+                return [...trail, node];
+            if (explored.has(next))
+                continue;
+            explored.add(next);
+            const found = walk(next, [...trail, next]);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    return walk(node, [node]);
+}
+/** How a refused cycle reads: the loop, in the direction the Edges point. */
+export function renderCycle(cycle) {
+    return cycle.join(' -> ');
+}
+//# sourceMappingURL=edges.js.map

package/dist/edges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edges.js","sourceRoot":"","sources":["../src/edges.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA8B,EAC9B,GAAsB;IAEtB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAExC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC9B,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;QACtB,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACzC,CAAC;AAKD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAgB;IACzD,2EAA2E;IAC3E,0EAA0E;IAC1E,oBAAoB;IACpB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IAEzC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,KAAwB,EAAiC,EAAE;QACrF,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC;YAC3C,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACjC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAEnB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;YAC3C,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;QACxC,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,KAAwB;IAClD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/frontier.d.ts

@@ -0,0 +1,12 @@
+import type { TicketSummary } from './domain.ts';
+/**
+ * The Frontier: the Tickets takeable right now — open, unblocked, unclaimed.
+ * Computed on every read, never stored, because a stored frontier is a second
+ * place for the truth to live.
+ *
+ * Edges resolve repo-wide, so this takes every Ticket in the workspace rather
+ * than one Effort's: a Ticket can be blocked by one that lives elsewhere.
+ */
+export declare function frontierOf(all: readonly TicketSummary[]): ReadonlySet<TicketSummary>;
+export declare function indexById(all: readonly TicketSummary[]): ReadonlyMap<string, TicketSummary>;
+//# sourceMappingURL=frontier.d.ts.map

package/dist/frontier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier.d.ts","sourceRoot":"","sources":["../src/frontier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,SAAS,aAAa,EAAE,GAAG,WAAW,CAAC,aAAa,CAAC,CAIpF;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,aAAa,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAU3F"}

package/dist/frontier.js

@@ -0,0 +1,34 @@
+/**
+ * The Frontier: the Tickets takeable right now — open, unblocked, unclaimed.
+ * Computed on every read, never stored, because a stored frontier is a second
+ * place for the truth to live.
+ *
+ * Edges resolve repo-wide, so this takes every Ticket in the workspace rather
+ * than one Effort's: a Ticket can be blocked by one that lives elsewhere.
+ */
+export function frontierOf(all) {
+    const byId = indexById(all);
+    return new Set(all.filter(ticket => isTakeable(ticket, byId)));
+}
+export function indexById(all) {
+    const byId = new Map();
+    for (const ticket of all) {
+        // A Legacy Ticket may carry no id at all, and the first id wins so that a
+        // duplicate cannot silently displace the Ticket already answering to it.
+        if (ticket.id !== undefined && !byId.has(ticket.id))
+            byId.set(ticket.id, ticket);
+    }
+    return byId;
+}
+/**
+ * Status and Edges decide this, and nothing else. A Triage role never does:
+ * `/triage` and the graph must not compete for one field, so a Ticket labelled
+ * `wontfix` still counts as takeable here and the Board says so in its
+ * warnings, leaving the judgement to the reader.
+ */
+function isTakeable(ticket, byId) {
+    if (ticket.status !== 'open')
+        return false;
+    return ticket.blockedBy.every(id => byId.get(id)?.status === 'resolved');
+}
+//# sourceMappingURL=frontier.js.map

package/dist/frontier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier.js","sourceRoot":"","sources":["../src/frontier.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,GAA6B;IACtD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAE5B,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAA6B;IACrD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE9C,KAAK,MAAM,MAAM,IAAI,GAAG,EAAE,CAAC;QACzB,0EAA0E;QAC1E,yEAAyE;QACzE,IAAI,MAAM,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACnF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,MAAqB,EAAE,IAAwC;IACjF,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAE3C,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC,CAAC;AAC3E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createFrontierMCP, SERVER_NAME, SERVER_VERSION } from './server.ts';
+export type { CreateServerOptions, FrontierMCP } from './server.ts';
+export type { Effort, HeaderDoc } from './domain.ts';
+export type { StorageDriver } from './storage/driver.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createFrontierMCP, SERVER_NAME, SERVER_VERSION } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { StorageDriver } from './storage/driver.ts';
+export declare const SERVER_NAME = "frontier";
+export declare const SERVER_VERSION = "0.1.0";
+export interface CreateServerOptions {
+    /** The server process's working directory. */
+    readonly cwd?: string;
+    readonly env?: Readonly<Partial<Record<string, string>>>;
+    /**
+     * The storage driver to bind to a workspace. Markdown in v1; the seam is here
+     * so a SQLite driver can be swapped in without touching the tool layer.
+     */
+    readonly createDriver?: (root: string) => StorageDriver;
+    /** Debounce filesystem watcher events. Tests may shorten this. */
+    readonly watcherDebounceMs?: number;
+}
+export interface FrontierMCP {
+    readonly server: McpServer;
+    /**
+     * Build the index for the session's own workspace. Calls resolve their own
+     * workspace anyway, so a failure here is not fatal — it only forfeits the
+     * warm start.
+     */
+    warmUp(): Promise<void>;
+    /** Stop watchers and close the transport. */
+    close(): Promise<void>;
+}
+export declare function createFrontierMCP(options?: CreateServerOptions): FrontierMCP;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,qBAAqB,CAAC;AAwC5E,eAAO,MAAM,WAAW,aAAa,CAAC;AACtC,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC;IACxD,kEAAkE;IAClE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,6CAA6C;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAOD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,mBAAwB,GAAG,WAAW,CAmRhF"}