mslxdff 0.1.55 → 0.1.57

package/src/upstream.js

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import os from "node:os";
 import { isFreeModel } from "./models.js";
 import { defaultStateFile } from "./state.js";
+import { fmtShanghaiYMDHMS } from "./time.js";
 
 let UndiciAgent = null;
 let UndiciFetch = null;
@@ -45,6 +46,7 @@ export function createUpstreamClient({
   },
   fetchImpl,
   hooks,
+  keepAlive = true,
 } = {}) {
   // 使用 undici 的 fetch 与 Agent 配对，避免 global fetch 与 npm undici Agent 不兼容
   if (!fetchImpl) fetchImpl = UndiciFetch || fetch;
@@ -91,6 +93,74 @@ export function createUpstreamClient({
     return true;
   }
 
+  function isResponsesModel(model) {
+    const m = String(model || "").toLowerCase();
+    return m.startsWith("muse-spark");
+  }
+
+  function chatToResponsesBody(chatBody) {
+    const msgs = Array.isArray(chatBody?.messages) ? chatBody.messages : [];
+    const system = msgs.filter((m) => m.role === "system").map((m) => String(m.content || "")).join("\n");
+    const nonSystem = msgs.filter((m) => m.role !== "system");
+    // 取最后一条 user 内容作为 input，其余拼到 input 前（保留上下文）
+    const inputParts = nonSystem.map((m) => {
+      const c = m.content;
+      if (typeof c === "string") return `${m.role}: ${c}`;
+      if (Array.isArray(c)) return `${m.role}: ${c.map((x) => x.text || "").join("")}`;
+      return `${m.role}: ${String(c || "")}`;
+    });
+    const input = inputParts.join("\n\n") || "hi";
+    const out = {
+      model: chatBody.model,
+      input,
+      stream: false, // muse-spark 的 chat 流式经 responses 的 SSE 格式不同，先以非流式 200 保证可用
+    };
+    if (system) out.instructions = system;
+    if (chatBody.tools) out.tools = chatBody.tools;
+    if (chatBody.tool_choice) out.tool_choice = chatBody.tool_choice;
+    if (chatBody.temperature != null) out.temperature = chatBody.temperature;
+    if (chatBody.max_tokens != null) out.max_output_tokens = chatBody.max_tokens;
+    return out;
+  }
+
+  function responsesToChatJson(respJson) {
+    // responses: {id, model, output:[{type:reasoning},{type:message, content:[{type:output_text,text}]}]}
+    let text = "";
+    for (const item of respJson.output || []) {
+      if (item.type === "message" && item.role === "assistant") {
+        for (const c of item.content || []) {
+          if (c.type === "output_text") text += c.text || "";
+          else if (c.type === "text") text += c.text || "";
+        }
+      }
+    }
+    if (!text) {
+      // 兜底：取 output_text 的第一个
+      for (const item of respJson.output || []) {
+        if (item.type === "message") {
+          const t = item.content?.[0]?.text;
+          if (t) { text = t; break; }
+        }
+      }
+    }
+    if (!text) text = "";
+    const chatJson = {
+      id: respJson.id || `resp_${Date.now()}`,
+      object: "chat.completion",
+      created: Math.floor((respJson.created_at || Date.now() / 1000)),
+      model: respJson.model,
+      choices: [
+        {
+          index: 0,
+          finish_reason: respJson.status === "completed" ? "stop" : "length",
+          message: { role: "assistant", content: text },
+        },
+      ],
+      usage: respJson.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+    };
+    return chatJson;
+  }
+
   function freeAnonLogFile() {
     // 按用户要求：放在当前项目目录，方便一眼看到；可用 env 覆盖
     return process.env.MSLXDFF_FREE_ANON_LOG || join(process.cwd(), "free-anon-extra.txt");
@@ -98,7 +168,7 @@ export function createUpstreamClient({
 
   function logFreeAnon({ model, publicStatus, anonStatus, anonAttempts, hit, totalMs }) {
     const file = freeAnonLogFile();
-    const line = `${new Date().toISOString()} model=${model} public=429 anonTries=${anonAttempts} anonStatus=${anonStatus ?? "none"} hit=${hit ? "YES额外额度" : "NO无额外"} totalMs=${totalMs} count=${hit ? "1" : "0"}\n`;
+    const line = `${fmtShanghaiYMDHMS(new Date())} model=${model} public=429 anonTries=${anonAttempts} anonStatus=${anonStatus ?? "none"} hit=${hit ? "YES额外额度" : "NO无额外"} totalMs=${totalMs} count=${hit ? "1" : "0"}\n`;
     try {
       mkdirSync(dirname(file), { recursive: true });
     } catch {}
@@ -118,7 +188,7 @@ export function createUpstreamClient({
   const keepAliveConnections = envInt("MSLXDFF_UPSTREAM_KEEPALIVE_CONNECTIONS", 20);
   let dispatcher = null;
   let agent = null;
-  if (UndiciAgent) {
+  if (keepAlive && UndiciAgent) {
     try {
       agent = new UndiciAgent({
         keepAliveTimeout,
@@ -134,13 +204,15 @@ export function createUpstreamClient({
   }
 
   async function chat(body) {
-    const url = `${baseUrl}/zen/v1/chat/completions`;
+    const isResp = isResponsesModel(body?.model);
+    const url = isResp ? `${baseUrl}/zen/v1/responses` : `${baseUrl}/zen/v1/chat/completions`;
+    const reqBody = isResp ? chatToResponsesBody(body) : body;
     const t0 = performance.now();
     const attempts = [];
     let waitMs = 0;
     for (let attempt = 0; ; attempt++) {
       const t = performance.now();
-      const result = await attemptOnce(url, body);
+      const result = await attemptOnce(url, reqBody);
       attempts.push({
         attempt,
         type: result instanceof Error ? "network" : `http${result.status}`,
@@ -177,7 +249,7 @@ export function createUpstreamClient({
           await sleep(anonDelay);
           waitMs += anonDelay;
           const t2 = performance.now();
-          anonResult = await attemptOnce(url, body, { anonymous: true });
+          anonResult = await attemptOnce(url, reqBody, { anonymous: true });
           attempts.push({
             attempt: `anon-${i}`,
             type: anonResult instanceof Error ? "network" : `http${anonResult.status}`,
@@ -185,7 +257,23 @@ export function createUpstreamClient({
           });
           if (anonResult instanceof Error) continue;
           if (anonResult.status !== 429) {
-            anonResult._t = {
+            // responses 模型的 anon 命中也需转回 chat 形状
+            let outAnon = anonResult;
+            if (isResp && anonResult.ok) {
+              try {
+                const txt = await anonResult.text();
+                const j = JSON.parse(txt);
+                if (j && Array.isArray(j.output)) {
+                  const chatJson = responsesToChatJson(j);
+                  const newHeaders = new Headers(anonResult.headers);
+                  newHeaders.set("content-type", "application/json");
+                  outAnon = new Response(JSON.stringify(chatJson), { status: anonResult.status, headers: newHeaders });
+                } else {
+                  outAnon = new Response(txt, { status: anonResult.status, headers: anonResult.headers });
+                }
+              } catch { outAnon = anonResult; }
+            }
+            outAnon._t = {
               attempts,
               waitMs,
               totalMs: Math.round(performance.now() - t0),
@@ -195,7 +283,7 @@ export function createUpstreamClient({
             hit = true;
             hitAt = i + 1;
             consecutiveHits += 1;
-            logFreeAnon({ model: body?.model, publicStatus: 429, anonStatus: anonResult.status, anonAttempts: i + 1, hit: true, totalMs: anonResult._t.totalMs });
+            logFreeAnon({ model: body?.model, publicStatus: 429, anonStatus: anonResult.status, anonAttempts: i + 1, hit: true, totalMs: outAnon._t.totalMs });
             // 额外在 txt 里强调连续命中
             try {
               if (consecutiveHits >= 2) {
@@ -204,7 +292,7 @@ export function createUpstreamClient({
               }
             } catch {}
             if (process.env.MSLXDFF_DEBUG === "1") try { console.log(`[free-anon] ${body?.model} public 429 -> anon ${anonResult.status} after ${i + 1} try HIT`); } catch {}
-            return anonResult;
+            return outAnon;
           }
         }
         // 3 次 anon 仍 429
@@ -222,6 +310,36 @@ export function createUpstreamClient({
           return anonResult;
         }
       }
+      // Muse Spark 走 /responses，需把 responses 的 JSON 转回 chat.completions 形状，保持上层无感
+      if (isResp && result.ok) {
+        try {
+          const txt = await result.text();
+          const j = JSON.parse(txt);
+          // responses 成功态：{output:[...]}；chat 态：{choices:[...]}。非 responses 形状则原样回
+          if (j && Array.isArray(j.output)) {
+            const chatJson = responsesToChatJson(j);
+            const newBody = JSON.stringify(chatJson);
+            const newHeaders = new Headers(result.headers);
+            newHeaders.set("content-type", "application/json");
+            const transformed = new Response(newBody, { status: result.status, headers: newHeaders });
+            transformed._t = {
+              attempts,
+              waitMs,
+              totalMs: Math.round(performance.now() - t0),
+            };
+            // 保留原始 timing 供日志
+            if (result._t) transformed._t = { ...transformed._t, ...result._t };
+            return transformed;
+          }
+          // 不是 responses 形状，回退：用原文本重建可读 Response
+          const fallback = new Response(txt, { status: result.status, headers: result.headers });
+          fallback._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+          return fallback;
+        } catch {
+          result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+          return result;
+        }
+      }
       result._t = {
         attempts,
         waitMs,

package/docs/adr/0001-reasoning-content-injection.md

@@ -1,14 +0,0 @@
-# ADR-0001: Inject a reasoning_content placeholder on outbound assistant messages
-
-The Zen upstream's thinking-mode models (deepseek-family at minimum) return
-`400 "The reasoning_content in the thinking mode must be passed back"` when a
-multi-turn request echoes an assistant message without its `reasoning_content`.
-Clients speaking plain OpenAI format never send that field, so the proxy writes
-a `" "` placeholder into assistant messages before forwarding. Scope is `all`
-for deepseek-family models and `tool_calls` for kimi-family models; messages
-that already carry non-empty `reasoning_content` are left untouched.
-
-The alternative — telling clients to manage `reasoning_content` themselves —
-would break standard OpenAI-compatible clients, so the proxy eats this
-compatibility cost instead. Matches `/root/9router` v0.5.45
-`open-sse/utils/reasoningContentInjector.js`.

package/docs/adr/0002-models-free-filter.md

@@ -1,12 +0,0 @@
-# ADR-0002: /v1/models exposes only free models, matched by suffix or whitelist
-
-The upstream `/zen/v1/models` list contains ~60 models; exposing them all would
-pollute clients with paid models this proxy can't serve for free. `/v1/models`
-therefore filters to: `id` ending in `-free`, OR the explicit whitelist entry
-`big-pickle`. The whitelist exists because `big-pickle` is a free model without
-the `-free` suffix, and a suffix-only filter would silently drop it.
-
-A plain `endsWith("-free")` filter was considered and rejected for exactly that
-reason. Matches `/root/9router` v0.5.45
-`src/app/api/providers/suggested-models/filters.js`
-(`KNOWN_FREE_OPENCODE_MODELS = ["big-pickle"]`).

package/docs/adr/0003-zero-state-no-auth.md

@@ -1,10 +0,0 @@
-# ADR-0003: Zero-state, no-DB, no-account local proxy
-
-Status: partially superseded by [ADR-0004](./0004-bearer-token.md) — the
-no-auth clause below is replaced; the zero-DB / no-account / no-cloud principles
-stand.
-
-By design this proxy holds no database, no token store, no account rotation,
-and no cloud sync. A single static bearer token is the only credential, kept
-in a 0600 state file (see ADR-0004); everything else is stateless per-process
-memory at most.

package/docs/adr/0004-bearer-token.md

@@ -1,18 +0,0 @@
-# ADR-0004: Single static bearer token, persisted in a 0600 state file
-
-The proxy requires a bearer token on `/v1/*` so an accidentally-exposed port
-isn't an open relay. There is no account system: the token is a random
-`crypto` 32-byte value (hex), generated once on first run, persisted to a
-state file (default `~/.config/mslxdff/state.json`, `0600`, path overridable
-via `MSLXDFF_STATE_FILE`), and printed to stdout on creation. Rotate with
-`mslxdff -refresh-token`, which regenerates, rewrites the file, prints the
-new token, and exits (does not start the server).
-
-Auth is enforced with a constant-time string compare on
-`Authorization: Bearer <token>`; mismatches get `401` with `WWW-Authenticate`.
-`/health` stays public (no token). Tokens never appear in logs.
-
-Alternatives rejected: a fixed default token (same key on every install),
-per-user accounts (needs a DB — that's the 9Router provisioning surface we
-rejected in ADR-0003), and unauthenticated local-only binding (fragile;
-a proxy relay deserves an explicit secret even on localhost).

package/docs/adr/0005-peer-mesh.md

@@ -1,53 +0,0 @@
-# ADR-0005: Peer mesh for same-model failover across machines
-
-> **Update (group model):** peers are now configured through named groups, and the
-> group name doubles as the join password (supersedes the random join key). CLI:
-> `-creategroup <name>` on the leader (no address needed — the first joiner seeds
-> the leader's own entry from the address it connects from), `-addtogroup <leader-host> <name>`
-> elsewhere. Every member (leader included) re-registers with the leader on a timer
-> (`MSLXDFF_GROUP_SYNC_MS`, default 60s) and rebuilds its local peer list from the
-> freshest member map, so membership changes propagate to all nodes automatically.
-> The `-peer` commands are removed; peers are an internal mechanism. Wrong group
-> names/tokens are counted per source IP: `MSLXDFF_BAN_THRESHOLD` (default 5)
-> failures ban the IP for `MSLXDFF_BAN_WINDOW_MS` (default 48h); `-resetban [ip]`
-> clears bans.
-
-A single mslxdff instance depends on one upstream quota; when that upstream
-starts rate-limiting or failing for a model, the only local fallback is
-switching to a *different* model. That changes the model out from under the
-client. To keep the requested model working while the local path recovers,
-multiple instances can be joined into a group: when the local upstream
-fails for model X, the instance forwards the request (still model X) to a
-group member that runs its own mslxdff and has its own upstream quota.
-
-## Design
-
-- **Peers are plain mslxdff instances.** Each peer is identified by
-  `{ url, token }` (its bearer token, per ADR-0004). Configured with
-  `mslxdff -peer add <token> <url> [name]`, removed with `-peer remove`,
-  listed with `-peer list`; persisted in the state file. No new protocol —
-  forwarding is a normal authenticated `POST /v1/chat/completions` to the
-  peer, reusing the existing API surface.
-- **Local-first routing.** A request always tries the local upstream first.
-  Only on local failure (network error or HTTP ≥ 400) does it iterate peers
-  for the *same model*, round-robin over currently-available peers.
-- **Model lock.** Forwarded requests carry `x-mslxdff-model-lock: <model>`
-  so the receiving peer uses exactly that model — it must not re-select or
-  fall back to another model, keeping "same model, different machine" true.
-- **Hop bound.** Forwarded requests carry `x-mslxdff-hops` (incremented each
-  hop). A peer receiving hops ≥ `maxHops` (default 3, `MSLXDFF_MAX_HOPS`)
-  stops forwarding further, bounding mesh depth and preventing loops.
-- **Peer cooldown.** A peer that fails a request enters a cooldown window
-  (default 30s, `MSLXDFF_PEER_COOLDOWN_MS`), during which it is skipped by
-  the round-robin, so the mesh rotates to healthy peers instead of
-  hammering a down one. Mirrors the model cooldown in ADR-0001.
-
-## Why not alternatives
-
-- **Point the whole proxy at another machine** (client-side failover): the
-  client can't detect per-model upstream failure, and every request pays the
-  cross-machine latency even when local is healthy.
-- **Different model per machine**: violates the requirement of keeping the
-  same model, and hides the model-change from the client.
-- **Central coordinator / service discovery**: overkill for a handful of
-  private instances; static peer config is zero-config and debuggable.

package/docs/adr/0006-broadband-member.md

@@ -1,103 +0,0 @@
-# ADR-0006: 宽带动态IP成员（broadband）经 Leader 中继共享配额
-
-> **状态**：规划完成，待实现（基于 v0.1.33）。用户确认：`--broadband` 为唯一语义，不设 `--relay` 别名；默认 `127.0.0.1` 监听。
-
-## 1. 背景与问题
-
-现有组模型（ADR-0005）假设组员均为公网 VPS，`A->D` 直连 `http://D公网IP:8989/v1/chat/completions` 用 `D` 的出口 IP 打 `opencode.ai`，实现 `IP级免费池` 分散。家庭宽带 `D` 有公网 IP 但：
-
-1. **入站不可达**：无端口映射/CGNAT，`probeHealth GET http://D:8989/health` 恒 `fail`，`peer-race` 直接跳过，`D` 的配额永不被用。
-2. **IP 动态**：`refreshGroupMembers` 透传旧 `myUrl`，IP 变更后 60s 同步期内全组仍用旧 IP。
-3. **语义缺失**：组内无法区分 `static(VPS直连)` 与 `broadband(家庭中继)`，`-group list` 无标识。
-
-需求：家庭 `D` 以 `broadband` 类型加入，无需公网入站，经 `Leader` 中继仍用 `D` 的家庭出口打上游，且全程可观测。
-
-## 2. 决策
-
-新增成员类型 `kind: "broadband"`（默认 `kind: "static"` 兼容老数据），`broadband` 隐含 `relay` 中继：
-
-* **加入**：`mslxdff -addtogroup <leader-host> <group> --broadband`（唯一旗标，不设 `--relay`）。
-* **监听**：`--broadband` 下默认 `listen 127.0.0.1:8989`，仅本机 `WorkBuddy` 可用；不加该旗标的为 `static` 走 `0.0.0.0`。
-* **共享**：`D --WS--> Leader` 常驻出站，`A(429) -> Leader -> D -> opencode.ai -> D -> Leader -> A`，上游仍见 `D` 家庭 IP。
-* **展示**：`-help` 新增用法行，`-group list / -status / -log` 标注 `[broadband] via leader Xs ago ip=...`。
-
-## 3. 设计
-
-### 3.1 成员模型
-
-`state.json groups[name].members[id]` 扩展：
-
-```json
-"home-D": {
-  "url": "relay://home-D",
-  "token": "...",
-  "kind": "broadband",
-  "publicIp": "183.14.22.78",
-  "lastSeen": 1724212345678,
-  "status": {"upstreamOk": true, "latencyMs": 4200}
-}
-```
-
-* `static`：`url: http://IP:8989`，参与 `probeHealth`。
-* `broadband`：`url: relay://id`，不探活，只看 `lastSeen`（`>90s` 标 `cooling`）+ `status`，`rankModels` 同 `slow` 5m 冷却共用。
-
-### 3.2 连接与心跳
-
-**D 端（家庭）**
-* 解析 `--broadband`，建 `WS wss://Leader/v1/groups/relay/connect?group=my@mslxd`，`Authorization: Bearer <token>`。
-* `hello {group, token, kind:"broadband", version}` → Leader 回 `welcome {memberId}`。
-* `heartbeat 30s {status:{upstreamOk, models, load}}`，`publicIp` 由 Leader 的 `clientIp(req)` 填，不靠 `ifconfig.me`。
-* 断线指数退避 `1s/2s/4s...` 重连，IP 变更导致 `TCP RST` 自动重建即完成 IP 更新。
-
-**Leader 端（VPS）**
-* `GET /v1/groups/relay/connect` 升级 WS，鉴权 `membersForToken`，存 `relayConns[group][id]=ws`，`ws.remoteIp=clientIp`。
-* 每条 `heartbeat` 对比 `remoteIp` vs `members[id].publicIp`，变则 `saveGroups` + `evt relay-ip-change` 入 `events.log`。
-* `lastSeen >90s` 或 `WS断开` 立即标 `cooling`，`A` 下次 `candidatesFor` 自动避开。
-
-### 3.3 转发路径
-
-```
-用户 -> A: POST /v1/chat/completions {model: deepseek, stream:true}
-A -> opencode.ai (用A IP) 429
-A选 candidatesFor -> [B(static), home-D(broadband via Leader), ...] 按 latency EMA
-A -> Leader: POST /v1/groups/relay/forward {target: home-D, body, hops:1, reqId}
-Leader -> D (WS): {reqId, body:{model,messages}}
-D -> opencode.ai (用D家庭IP) 200 SSE chunk*
-D --WS {reqId, data:chunk}--> Leader --HTTP chunk--> A --SSE--> 用户
-A断开 -> Leader --WS {abort reqId}--> D controller.abort()
-```
-
-* `hops` 每跳 +1，`MAX_HOPS=3` 防环；`broadband` 节点自身 `429` 时可直接 `fetch` 到 VPS `static` 节点（出站直连，无需中继）。
-* 多请求复用一条 WS，`reqId` 复用现有 `relay` 日志的 `reqId/detail` 串联。
-
-### 3.4 可观测
-
-* `-help`：` -addtogroup <host> <name> [--broadband]  宽带动态IP成员（经Leader中继，无需公网入站，默认127.0.0.1）`
-* `-group list`：`3. relay://home-D [broadband] ok via leader 12s ago ip=183.14.22.78`
-* `-log [N]`：`relay-ip-change / relay-forward / relay-heartbeat / client-abort` 均带 `reqId/detail`。
-
-## 4. 实现清单
-
-| 文件 | 改动 |
-|---|---|
-| `bin/mslxdff.js` | `-addtogroup` 解析 `--broadband`，`WS` 客户端+心跳+重连，`listen` 在 `broadband` 下绑 `127.0.0.1`，`printHelp` 新增行，`groupSyncTimer` 对 `broadband` 组 30s |
-| `src/groups.js` | 成员结构 `kind/publicIp/lastSeen/status`，`addGroupMember/upsertMember/syncPeersFromMembers` 支持 `broadband`，`refreshGroupMembers` 透传 `kind` |
-| `src/peers.js` | 新增 `relayVia` 字段，`add({relayVia, kind}) / isRelay`，`broadband` 不进 `ordered()` 直连池 |
-| `src/routes.js` | 新增 `WS /v1/groups/relay/connect` + `POST /v1/groups/relay/forward`，`forwardToPeer` 中继分支，`hops` 处理 |
-| `src/state.js` | 持久化 `kind/publicIp/lastSeen`，新增 `load/save` 兼容 |
-| `src/logs.js` | `relay-*` 事件类型 |
-
-依赖：`ws`（或 Node 22 原生 `WebSocket`，服务端需 `upgrade` 处理）。
-
-## 5. 验证
-
-1. **IP变更**：`D` 拨号重拨，`WS` 重连，`events.log` 出现 `relay-ip-change old->new`，`-group list` IP 更新，`A` 经 `Leader` 仍命中 `D`。
-2. **配额共享**：`A` 指定 `deepseek 429`，`-log` 显示 `peer-race via=relay-leader target=home-D`，`D` 的 `upstream-done 200` 且 `detail.exitReason:normal`，回包完整。
-3. **本地可用**：`D` 本机 `curl http://127.0.0.1:8989/v1/chat/completions` 200，外网 `curl http://家庭公网IP:8989` 超时（符合预期）。
-4. **`-help` / `-group list`** 均含 `broadband` 标识。
-
-## 6. 风险与取舍
-
-* `Leader` 单点中继增加 `10-30ms` 延迟，可接受；`Leader` 宕则 `broadband` 配额暂不可用（`static` 组员仍直连可用）。
-* 多并发复用单 `WS` 需 `reqId` 复用与背压控制，首版可限并发 3（复用 `PEER_RACE_LIMIT`）。
-* 不设 `--relay` 别名，术语统一为 `broadband`，内部变量 `relay` 仅作实现名。

package/docs/agents/domain.md

@@ -1,51 +0,0 @@
-# Domain Docs
-
-How the engineering skills should consume this repo's domain documentation when exploring the codebase.
-
-## Before exploring, read these
-
-- **`CONTEXT.md`** at the repo root, or
-- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
-- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
-
-If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
-
-## File structure
-
-Single-context repo (most repos):
-
-```
-/
-├── CONTEXT.md
-├── docs/adr/
-│   ├── 0001-event-sourced-orders.md
-│   └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/adr/                          ← system-wide decisions
-└── src/
-    ├── ordering/
-    │   ├── CONTEXT.md
-    │   └── docs/adr/                  ← context-specific decisions
-    └── billing/
-        ├── CONTEXT.md
-        └── docs/adr/
-```
-
-## Use the glossary's vocabulary
-
-When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
-
-If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
-
-## Flag ADR conflicts
-
-If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
-
-> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -1,30 +0,0 @@
-# Issue tracker: Local Markdown
-
-Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
-
-## Conventions
-
-- One feature per directory: `.scratch/<feature-slug>/`
-- The spec is `.scratch/<feature-slug>/spec.md`
-- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
-- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
-- Comments and conversation history append to the bottom of the file under a `## Comments` heading
-
-## When a skill says "publish to the issue tracker"
-
-Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
-
-## When a skill says "fetch the relevant ticket"
-
-Read the file at the referenced path. The user will normally pass the path or the issue number directly.
-
-## Wayfinding operations
-
-Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
-
-- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
-- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
-- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
-- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
-- **Claim**: set `Status: claimed` and save before any work.
-- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/docs/agents/triage-labels.md

@@ -1,15 +0,0 @@
-# Triage Labels
-
-The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
-
-| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
-| -------------------------- | -------------------- | ---------------------------------------- |
-| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
-| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
-| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
-| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
-| `wontfix`                  | `wontfix`            | Will not be actioned                     |
-
-When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
-
-Edit the right-hand column to match whatever vocabulary you actually use.