frontier-mcp 0.5.0 → 1.0.0

package/dist/workspace.js

@@ -41,15 +41,26 @@ const ROOT_MARKERS = [
  * A workspace with no `.scratch/` is not — that is a fresh project.
  */
 export function resolveWorkspace(root, context) {
+    return locateWorkspace(root, context).root;
+}
+/** {@link resolveWorkspace}, saying which source won. */
+export function locateWorkspace(root, context) {
     const argument = given(root);
     if (argument !== undefined) {
-        return requireDirectory(resolve(context.cwd, argument), 'root argument');
+        return {
+            root: requireDirectory(resolve(context.cwd, argument), 'root argument'),
+            resolvedBy: 'root argument',
+        };
     }
     const fromEnv = given(context.env[WORKSPACE_ENV_VAR]);
     if (fromEnv !== undefined) {
-        return requireDirectory(resolve(context.cwd, fromEnv), WORKSPACE_ENV_VAR);
+        return {
+            root: requireDirectory(resolve(context.cwd, fromEnv), WORKSPACE_ENV_VAR),
+            resolvedBy: `$${WORKSPACE_ENV_VAR}`,
+        };
     }
-    return findRootMarker(resolve(context.cwd)) ?? resolve(context.cwd);
+    const cwd = resolve(context.cwd);
+    return (findRootMarker(cwd) ?? { root: cwd, resolvedBy: 'working directory, no root marker found' });
 }
 /**
  * An empty override was not supplied. Falling through to the next source is the
@@ -67,8 +78,9 @@ function given(value) {
 function findRootMarker(from) {
     let dir = from;
     for (;;) {
-        if (ROOT_MARKERS.some(marker => marker.matches(join(dir, marker.name))))
-            return dir;
+        const marker = ROOT_MARKERS.find(candidate => candidate.matches(join(dir, candidate.name)));
+        if (marker !== undefined)
+            return { root: dir, resolvedBy: marker.name };
         const parent = dirname(dir);
         if (parent === dir)
             return undefined;

package/dist/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,iFAAiF;AACjF,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,YAAY,GAAG;IACnB,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE;IAC1C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE;CAClC,CAAC;AAQF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAwB,EAAE,OAAyB;IAClF,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,eAAe,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACtD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CAAC,KAAyB;IACtC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,GAAG,GAAG,IAAI,CAAC;IAEf,SAAS,CAAC;QACR,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAEpF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,SAAS,CAAC;QACrC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,MAAc;IACpD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,wBAAwB,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qFAAqF;AACrF,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,IAAY;IAC1B,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/docs/agents/issue-tracker.md

@@ -1,8 +1,12 @@
 # Issue tracker — FrontierMCP and file fallback
 
+Tracker doc revision 7. To check a vendored copy, compare this number with the one in the
+`frontier://tracker-doc` resource of the server you run; a lower number, or no revision line, is
+stale.
+
 Use **FrontierMCP** as the issue tracker. Its canonical storage is markdown under `.scratch/`.
 Vocabulary is defined in the project's `CONTEXT.md` when present — Effort, Board, Header doc, Map,
-Spec, Ticket, Edge, Frontier.
+Spec, Ticket, Edge, Frontier, Handle, Temporary key.
 
 When **FrontierMCP** (server name `frontier`) is loaded in your session, use the tools below. They
 own the schema, compute the graph, and answer orientation questions for a fraction of the token cost
@@ -30,7 +34,7 @@ session.** Moving to another worktree mid-session does not retarget it: pass `ro
 reports no Efforts — that is the worktree being served correctly, not the tracker going missing.
 
 **Every call that writes opens with `root: <path>`**, naming the repository it just changed. Read it
-— a Ticket id is not repo-unique, so `T10 updated` looks the same whichever repository answered, and
+— a Ticket id is unique within a repository, not across them, so `T10 updated` looks the same whichever repository answered, and
 this line is the only part of the result that tells you. Reads do not carry it, and neither do the
 read paths of write-capable tools: `edit_map` with no section fields, `spec` with no `content`, and
 `migrate_effort` with `preview`.
@@ -44,14 +48,14 @@ Eight tools permanently. Optional arguments extend an existing tool; there is no
 
 | Tool | Use when |
 | --- | --- |
-| `list_efforts` | Orient — list Efforts with Ticket counts, header doc kinds, and Frontier size. |
+| `list_efforts` | Orient — list Efforts with Ticket counts, header doc kinds, and Frontier size. A repository with no `.scratch/` at all gets `no tracker here`, the marker that located the root, and a `start one` line to copy; an empty `.scratch/` still reads `(no efforts)`. |
 | `get_board` | See the whole Effort cheaply — Destination, one summary line per Ticket, Frontier marked. Never returns bodies. |
 | `get_tickets` | Fetch full bodies for specific ids after the Board tells you which Tickets matter. |
 | `create_tickets` | Publish a breakdown in one call. Declare Edges with temporary keys; the server assigns ids and numbers. |
-| `update_ticket` | Claim, resolve, drop, reopen, release, set title/kind/type, set triage, replace Edges, comment, or tick acceptance criteria. One Ticket per call. |
+| `update_ticket` | Claim, resolve, drop, reopen, release, set title/kind/type, set triage, replace Edges, comment, tick acceptance criteria, or `drop_keys` to delete Unimported frontmatter keys. One Ticket per call. |
 | `edit_map` | Edit Map sections — Destination, Notes, fog, Out of scope. Decisions-so-far regenerates from resolved Tickets. |
 | `spec` | Read or write a Spec as a whole document. |
-| `migrate_effort` | Normalize Legacy Tickets in an Effort. Preview writes nothing; filename rename is opt-in. |
+| `migrate_effort` | Normalize Foreign Tickets — those whose file does not conform to the schema — in an Effort. Filenames never change. Preview writes nothing and names a Ticket it would mint by its handle (`<effort>#<order>`), not a predicted id. |
 
 ### Typical agent flow
 
@@ -76,7 +80,21 @@ Eight tools permanently. Optional arguments extend an existing tool; there is no
 | release a stale claim | `update_ticket` with `{ release: true }` |
 | edit the Map | `edit_map` |
 | write or read the Spec | `spec` |
-| normalize legacy files | `migrate_effort` |
+| normalize foreign files | `migrate_effort` |
+
+Two Ticket files carrying one id are listed in each Board's warnings, with claimant files for the
+first few, and every write addressed to that id is refused. Fix it by hand, giving all but one a new id; the server never
+renumbers. Under a pattern whose only variable token is `<N>`, every `create_tickets` result carries
+a standing warning that the pattern collides across branches — it describes the configuration, not
+that call; the remedy is a mixed pattern such as `T<N>-<b36{4}>`. When a Ticket's frontmatter carries
+keys outside the schema, `get_tickets` appends them as a fenced `yaml` block under `## Unimported
+frontmatter` — the whole fence for a Ticket with no `id`, only the unimported entries otherwise. The
+read leaves the file unchanged, and no ordinary write removes them: pass `update_ticket` `drop_keys`
+with the names to delete. A schema key or a key the fence does not carry fails the call and writes
+nothing; the rest of the fence stays byte-identical. Dropping the last one from a Ticket with no `id`
+leaves it no longer Foreign, still listed under the Board's `no id` warning. A Board counts `resolved` Tickets
+with no `answer_gist`, `dropped` with no `dropped_reason` and `claimed` with no `claimed_by` or `claimed_at` in its
+warnings, so set the field with the Status.
 
 Claims are compare-and-set — a parallel session that already holds the Ticket wins. Writes carry the
 `revision` from the last read; a mismatch is refused, never retried over the caller's edit.
@@ -87,41 +105,56 @@ These conventions are canonical whether FrontierMCP is loaded or not. FrontierMC
 the same files; a session without the server still produces valid Tickets by following this section.
 
 **Canonical is not licence to allocate ids by hand.** When FrontierMCP is loaded, ids come from
-`create_tickets` and are never derived by scanning. The server allocates each candidate under a
-repo-global `.scratch/.frontier-id-T<n>.guard` and re-scans while holding every guard; a file
-written straight to disk takes part in none of that, so it is the naive `max + 1` that
-[ADR 0005](../adr/0005-ids-are-allocated-under-a-guard-and-a-rescan.md) was written against —
-measured there, four processes creating three Tickets each produced thirteen files carrying four
-distinct ids, and duplicates are silent. A *guessed* id passed to `create_tickets` costs nothing;
-the server allocates and discards the guess. Only the hand-written file breaks.
+`create_tickets`, and you never scan for one: the server mints every id it is present for. It knows
+the repo's id pattern, and under a pattern containing `<N>` it counts under a guard
+(`.scratch/.frontier-id-N-<n>.guard`, keyed on the counter value) that a file written straight to
+disk cannot take — ADR 0006 in the frontier-mcp repository. Hand-writing while the server is loaded
+bypasses the mint whatever the pattern.
 
 ### Layout
 
-- One Effort per directory: `.scratch/<effort-slug>/`
+- One Effort per directory: `.scratch/<effort-slug>/`.
+- `.scratch/frontier.yml`, beside the Effort directories, is the one other file FrontierMCP reads.
+  Its one key, `id_pattern`, shapes Ticket ids. The server reads it once at start; restart a running
+  server after editing it.
 - The header doc is `spec.md` (from `/to-spec`) or `map.md` (from `/wayfinder`). An Effort charted as a
   Map may later gain a Spec — that is wayfinder's handoff, not a mistake.
 - Tickets are one file per Ticket under `.scratch/<effort-slug>/issues/` — never a single combined
   tickets file.
-- Ticket filenames are `<NN>-T<n>-<slug>.md`. `NN` is sort order only and may be rewritten. `T<n>` is
-  the identity and never changes.
-- **Ticket ids are `T<n>`, unique across the whole repo.** With FrontierMCP loaded, `create_tickets`
-  assigns them and you never scan for the next one. Only when the server is absent: before creating
-  a Ticket by hand, scan every `.scratch/*/issues/` for the highest existing `T` number and continue
-  from there — ids do not restart per Effort. A bare `T47` therefore resolves anywhere in the repo,
-  including in commit messages.
+- Ticket filenames are `<NN>-<id>-<slug>.md`. `NN` is sort order only and may be rewritten. The id
+  is the identity and never changes.
+- **Ticket ids are unique across the whole repo**, so a bare id resolves anywhere in it, including
+  in commit messages. With FrontierMCP loaded, `create_tickets` assigns them. Only when the server is
+  absent, mint one by hand:
+  1. Read `id_pattern` from `.scratch/frontier.yml`. No file or no key means `T<b36{6}>`.
+  2. Check the pattern is legal: it begins with a literal letter or underscore; literals are only
+     `A-Z a-z 0-9 . _ -`; the tokens are `<N>`, `<b36{n}>` and `<b16{n}>` with n from 1 to 64, and
+     `<effort>` is refused; at most one `<N>`; at least one `<N>` or random token; a minted id is at
+     most 64 characters, counting `<N>` as one. If the file is not valid YAML, is not a mapping,
+     `id_pattern` is not a string, or the pattern breaks a rule, **do not mint** — fix the file first.
+     Never fall back to the default: an id minted in a format nobody asked for is permanent.
+  3. Render it. Every `<b36{n}>` is exactly n characters from `0-9a-z`, every `<b16{n}>` exactly n
+     from `0-9a-f`, lowercase always. `<N>` is decimal with no leading zeros. Anything outside `<>`
+     is literal.
+  4. **No `<N>` in the pattern:** draw the random tokens. Do not scan for a highest id.
+  5. **`<N>` in the pattern:** scan every `.scratch/*/issues/` for the highest `<N>` among ids that
+     match the whole pattern and add one; under a mixed pattern, count first, then draw the random
+     part. A hand-writer cannot take the server's guard, so if any session might be minting at the
+     same time you can both reach the same number unseen.
+  6. Check the id is not already in use anywhere in `.scratch/`.
 - Formal metadata goes in YAML frontmatter. Prose stays prose.
 
 ### Ticket frontmatter
 
 ```yaml
 ---
-id: T12                     # T<n>, repo-unique, never reused
-title: Parse legacy tickets without frontmatter
+id: T12                     # shaped by id_pattern; repo-unique, never reused or changed
+title: Parse tickets without frontmatter
 kind: build                 # build | decision
 type: research              # decision only: research | prototype | grilling | task
 status: open                # open | claimed | resolved | dropped
 triage: ready-for-agent     # see triage-labels.md
-blocked_by: [T09, T11]      # plain ids, resolved repo-wide
+blocked_by: [T9, T11]       # plain ids, resolved repo-wide
 claimed_by:                 # required when status: claimed
 claimed_at:                 # timestamp, set with claimed_by
 answer_gist:                # required when status: resolved — one line, every kind
@@ -164,8 +197,8 @@ When FrontierMCP is loaded, prefer the MCP calls in the table above over hand-ed
 
 **Everything below holds only while FrontierMCP is absent from the session.** With the server
 loaded, `create_tickets` publishes the breakdown and is the only thing that may allocate an id;
-hand-writing the file bypasses the guards, per the File conventions preamble.
+hand-writing the file bypasses the mint, per the File conventions preamble.
 
 When a skill says "publish to the issue tracker" and FrontierMCP is not loaded, create
-`.scratch/<effort-slug>/issues/<NN>-T<n>-<slug>.md` (creating directories as needed), assign the next
-repo-global `T<n>` by scanning as described above, and write frontmatter matching the template above.
+`.scratch/<effort-slug>/issues/<NN>-<id>-<slug>.md` (creating directories as needed), mint the id
+as the Layout steps above describe, and write frontmatter matching the template above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontier-mcp",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "An MCP server exposing the markdown issue tracker under a repo's .scratch/ as a queryable graph",
   "license": "MIT",
   "repository": {
@@ -25,19 +25,19 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "@modelcontextprotocol/server": "^2.4.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
-    "@release-it/conventional-changelog": "^12.0.0",
-    "@types/node": "^24.10.1",
-    "oxfmt": "^0.62.0",
-    "oxlint": "^1.77.0",
-    "release-it": "^21.0.1",
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@release-it/conventional-changelog": "^12.0.2",
+    "@types/node": "^24.19.2",
+    "oxfmt": "^0.78.0",
+    "oxlint": "^1.93.0",
+    "release-it": "^21.1.2",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^5.1.0"
   },
   "engines": {
     "node": "^20.20.2 || ^22.17.1 || ^24.15.0"