@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/cli/roles-readme.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rolesReadmePath = exports.ROLES_README_MARKER = void 0;
+exports.installRolesReadme = installRolesReadme;
+exports.removeRolesReadme = removeRolesReadme;
+// @implements A-SPEC-153
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Identifies the file as ours, so `--remove` never reclaims something a user wrote. */
+exports.ROLES_README_MARKER = '<!-- holmes-kit:roles-guide -->';
+const rolesReadmePath = (root) => path.join(root, '.ax', 'roles', 'README.md');
+exports.rolesReadmePath = rolesReadmePath;
+/**
+ * The guidance MUST be markdown, not a `.yaml` template.
+ *
+ * `loadRolePolicy` reads only `.yaml`/`.yml`, so a directory holding just this file yields no policy
+ * and the gate's decision does not move by one bit. Shipping an active `policy.yaml` instead would
+ * put every newly initialised project behind a fail-closed role gate on its first run — the same
+ * bricking REQ-146 measured when it tried to make a spec field required, and REQ-152 avoided by
+ * making roles opt-in. A `.yaml.example` name would also work today, but only because of how the
+ * loader currently filters; markdown cannot be mistaken for a policy under any future rule.
+ */
+const CONTENT = `${exports.ROLES_README_MARKER}
+# 역할 정책 (선택 기능 — 지금은 꺼져 있습니다)
+
+이 디렉터리에 \`.yaml\` 파일이 **하나라도** 생기면 역할 게이트가 켜집니다. 이 README만 있는 동안에는
+아무것도 바뀌지 않습니다.
+
+## 켜는 법
+
+\`.ax/roles/policy.yaml\`을 만듭니다:
+
+\`\`\`yaml
+roles:
+  pm:         { allow: [WRITE_SPEC] }
+  architect:  { allow: [WRITE_SPEC] }
+  developer:  { allow: [WRITE_CODE, WRITE_TEST] }
+  tester:     { allow: [WRITE_TEST] }
+  reviewer:   { allow: [] }
+  maintainer: { allow: [WRITE_CODE, WRITE_TEST, WRITE_SPEC] }
+
+# 역할을 지정하지 않고 실행했을 때 어느 역할로 취급할지.
+# 생략하면 역할 미지정은 거부됩니다(fail-closed).
+default: maintainer
+\`\`\`
+
+역할 이름은 프로젝트가 정합니다 — 위는 예시일 뿐입니다.
+\`allow\`에 쓰는 동작명은 게이트가 실제로 판정하는 이름입니다: \`WRITE_CODE\`, \`WRITE_TEST\`,
+\`WRITE_SPEC\`, \`APPROVE\`.
+
+## 역할을 지정하는 법
+
+에이전트를 기동할 때 **환경변수**로 줍니다:
+
+\`\`\`bash
+HOLMES_ROLE=reviewer claude
+\`\`\`
+
+세션은 자기 환경을 바꿀 수 없으므로 **에이전트가 스스로 역할을 주장할 수 없습니다.** 승인
+(\`HOLMES_APPROVAL\`)과 같은 대역외 원칙입니다.
+
+## \`default\`를 왜 코드가 정하지 않는가
+
+"역할 미지정이면 만능"을 코드에 넣으면 \`HOLMES_ROLE\`을 비우는 것만으로 모든 제한이 우회됩니다.
+Reviewer에게 코드 작성을 막는 규율이 "설정 안 하면 그만"이 되죠. 그래서 기본값은 **프로젝트가 이 파일에
+적을 때만** 존재하고, 이 디렉터리는 보호 경로라 에이전트가 고칠 수 없습니다.
+
+## 주의
+
+- 이 디렉터리는 **git에 커밋**됩니다 — 거버넌스 설정은 팀이 공유해야 합니다.
+- \`default\`가 정의되지 않은 역할을 가리키면 **거부**됩니다. 오타가 조용히 통과하지 않습니다.
+- 현재 역할은 게이트 권한만 정합니다. 역할별 LLM 모델 배정·에이전트 기동은 아직 없습니다.
+`;
+/** Installs the guidance. A file the user has edited is left alone. */
+function installRolesReadme(root) {
+    const file = (0, exports.rolesReadmePath)(root);
+    if (fs.existsSync(file))
+        return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, CONTENT);
+}
+/**
+ * Reclaims the guidance on `init --remove`. Returns whether it was ours to remove.
+ *
+ * Only this file is touched — a project's real `policy.yaml` living beside it must survive, since
+ * removing the docs is not a request to disable governance.
+ */
+function removeRolesReadme(root) {
+    const file = (0, exports.rolesReadmePath)(root);
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (!text.includes(exports.ROLES_README_MARKER))
+        return false;
+    fs.rmSync(file);
+    return true;
+}

package/dist/holmes/cli/settings-merge.js

@@ -0,0 +1,122 @@
+"use strict";
+// @implements A-SPEC-100.2
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOLMES_OWNED_MCP_ENV = void 0;
+exports.isHolmesCommand = isHolmesCommand;
+exports.hookScriptPath = hookScriptPath;
+exports.mergeHooks = mergeHooks;
+exports.removeHooks = removeHooks;
+exports.enableMcpServer = enableMcpServer;
+exports.disableMcpServer = disableMcpServer;
+exports.mergeMcpServers = mergeMcpServers;
+exports.removeMcpServer = removeMcpServer;
+/** A hook entry belongs to holmes-kit iff its command references our hook scripts. */
+function isHolmesCommand(command) {
+    return /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop)\.js/.test(command) || /\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(command);
+}
+/**
+ * The script path out of a hook command line, e.g. `node "/pkg/dist/.../stop.js"` -> `/pkg/dist/.../stop.js`.
+ * `init` quotes the path (installs live under paths that may contain spaces), so an unquoting parse is
+ * mandatory, not defensive: a naive `\S+` capture keeps the quotes and every existence check then fails.
+ * Returns '' when no argument is present — callers treat that as unresolvable.
+ */
+function hookScriptPath(command) {
+    const m = /(?:^|\s)(?:node(?:\.exe)?\s+)?(?:"([^"]+)"|'([^']+)'|([^\s"']*[/\\][^\s"']*))/.exec(command);
+    return m?.[1] ?? m?.[2] ?? m?.[3] ?? '';
+}
+const hasHolmes = (g) => (g.hooks ?? []).some((h) => isHolmesCommand(h.command));
+/**
+ * Add or replace holmes-kit's PreToolUse + Stop entries. Every other hook group, every other event,
+ * and all unrelated top-level keys (permissions, …) are preserved byte-for-byte in value.
+ */
+function mergeHooks(existing, plan) {
+    const out = { ...(existing ?? {}) };
+    const hooks = { ...(out.hooks ?? {}) };
+    const upsert = (event, group) => {
+        const groups = (hooks[event] ?? []).map((g) => ({ ...g, hooks: [...(g.hooks ?? [])] }));
+        const idx = groups.findIndex(hasHolmes);
+        if (idx >= 0)
+            groups[idx] = group; // in-place replace: corrects an upgraded path
+        else
+            groups.push(group);
+        hooks[event] = groups;
+    };
+    upsert('PreToolUse', { matcher: plan.preToolUseMatcher, hooks: [{ type: 'command', command: plan.preToolUseCommand }] });
+    upsert('Stop', { hooks: [{ type: 'command', command: plan.stopCommand }] }); // Stop takes NO matcher
+    out.hooks = hooks;
+    return out;
+}
+/** Remove every holmes-owned hook entry, dropping groups that become empty. Inverse of mergeHooks. */
+function removeHooks(existing) {
+    const out = { ...(existing ?? {}) };
+    if (!out.hooks)
+        return out;
+    const hooks = {};
+    for (const [event, groups] of Object.entries(out.hooks)) {
+        const kept = (groups ?? [])
+            .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isHolmesCommand(h.command)) }))
+            .filter((g) => g.hooks.length > 0);
+        if (kept.length > 0)
+            hooks[event] = kept;
+    }
+    if (Object.keys(hooks).length > 0)
+        out.hooks = hooks;
+    else
+        delete out.hooks;
+    return out;
+}
+/** Union — never replace a user's other enabled servers. */
+function enableMcpServer(existing, name) {
+    const out = { ...(existing ?? {}) };
+    out.enabledMcpjsonServers = [...new Set([...(out.enabledMcpjsonServers ?? []), name])];
+    return out;
+}
+function disableMcpServer(existing, name) {
+    const out = { ...(existing ?? {}) };
+    const rest = (out.enabledMcpjsonServers ?? []).filter((n) => n !== name);
+    if (rest.length > 0)
+        out.enabledMcpjsonServers = rest;
+    else
+        delete out.enabledMcpjsonServers;
+    return out;
+}
+/**
+ * Merge only `mcpServers['holmes-kit']`. `args` MUST be absolute: the MCP server is spawned with the
+ * TARGET project's cwd, so a repo-relative path (as this project's own .mcp.json uses) would not resolve.
+ */
+/**
+ * @implements A-SPEC-179
+ * The env keys holmes itself decides in the server entry. Everything else there belongs to whoever
+ * put it there.
+ */
+exports.HOLMES_OWNED_MCP_ENV = ['HOLMES_SPECS'];
+function mergeMcpServers(existing, name, mcpBinPath, specsDir) {
+    const out = { ...(existing ?? {}) };
+    // @implements A-SPEC-179
+    // Merge, not replace. Measured 2026-08-13 while previewing `--force` on holmes-kit's own
+    // workspace: `HOLMES_MCP_AUTORELOAD: "1"` — the REQ-162 supervisor opt-in — would have been
+    // dropped without a word. `--force` means "refresh the wiring", not "turn off what I switched on".
+    // The owned keys go on TOP so `--specs-dir` still wins; unknown keys survive underneath, because a
+    // whitelist of "keys worth keeping" assumes we know everything an operator may set.
+    // `mcpServers` values are deliberately `unknown` — this file does not own their shape. Read just
+    // the one field, defensively: a non-object entry must not throw during a re-wire.
+    const prevEntry = existing?.mcpServers?.[name];
+    const prev = (prevEntry && typeof prevEntry === 'object' ? prevEntry.env : undefined) ?? {};
+    out.mcpServers = {
+        ...(out.mcpServers ?? {}),
+        [name]: { command: 'node', args: [mcpBinPath], env: { ...prev, HOLMES_SPECS: specsDir } },
+    };
+    return out;
+}
+function removeMcpServer(existing, name) {
+    const out = { ...(existing ?? {}) };
+    if (!out.mcpServers)
+        return out;
+    const servers = { ...out.mcpServers };
+    delete servers[name];
+    if (Object.keys(servers).length > 0)
+        out.mcpServers = servers;
+    else
+        delete out.mcpServers;
+    return out;
+}

package/dist/holmes/config/config.js

@@ -0,0 +1,70 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.loadConfig = loadConfig;
+// @implements A-SPEC-125.5
+// src/holmes/config/config.ts
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.DEFAULT_CONFIG = {
+    guardrail: { enforcement: 'block', enforceHighRisk: true, overrideRequiresAdr: true },
+    highRiskDomains: ['@auth', '@payment'],
+    storage: { specStore: 'local-markdown' },
+};
+function deepMerge(base, ov) {
+    if (ov == null || typeof ov !== 'object')
+        return base;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(ov)) {
+        const b = base[k];
+        out[k] = b && typeof b === 'object' && !Array.isArray(b) && v && typeof v === 'object' ? deepMerge(b, v) : v;
+    }
+    return out;
+}
+function loadConfig(root) {
+    const f = path.join(root, 'ax.config.json');
+    if (!fs.existsSync(f))
+        return structuredClone(exports.DEFAULT_CONFIG);
+    // FAIL-SAFE: a malformed/unreadable config must never crash the loader (it gates the guardrail).
+    // Fall back to the strict DEFAULT_CONFIG (enforcement:'block') so a broken file cannot silently
+    // weaken or disable governance — a bad config degrades to the safest posture, not to an exception.
+    try {
+        return structuredClone(deepMerge(exports.DEFAULT_CONFIG, JSON.parse(fs.readFileSync(f, 'utf8'))));
+    }
+    catch {
+        return structuredClone(exports.DEFAULT_CONFIG);
+    }
+}

package/dist/holmes/context/bundler.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextBundler = void 0;
+const tiers_1 = require("./tiers");
+const render_1 = require("./render");
+const tokens_1 = require("./tokens");
+const DEFAULT_MAX_DISTANCE = 6;
+/**
+ * Largest share of the budget any ONE entry may occupy before it is truncated.
+ *
+ * Half leaves room for at least one more entry in every case while still letting the seed — usually
+ * the thing the caller most wants in full — dominate. The seed remains mandatory, so a bundle can
+ * still exceed its budget when the seed alone is bigger than the cap; that overflow is documented
+ * below and is the only case where it happens.
+ */
+const MAX_ENTRY_BUDGET_SHARE = 0.5;
+/**
+ * Appended to any entry the cap shortened, so a cut document never reads as a complete one.
+ *
+ * HONEST LIMIT: the marker costs ~10 tokens, so a budget smaller than that cannot be honoured — a
+ * bundle asked for 5 tokens comes back with 10. The alternative is dropping the marker and returning
+ * silently-truncated content, which is worse: a reader acting on half a spec while believing they
+ * have all of it is in a worse position than one who knows the budget was unusable. Budgets that
+ * small are degenerate anyway; every realistic size is honoured exactly.
+ */
+const TRUNCATION_MARKER = '\n… [truncated to fit the context budget]';
+/** Priority order for tiers: hot fills first, then domain, then cold. */
+const TIER_PRIORITY = { hot: 0, domain: 1, cold: 2 };
+/**
+ * Assembles a tiered, budget-filled context bundle around a seed node.
+ *
+ * Pure/deterministic given the injected content source: no Date, randomness,
+ * or LLM calls. Same (seedId, tokenBudget) always yields a deep-equal bundle.
+ */
+class ContextBundler {
+    graph;
+    content;
+    maxDistance;
+    constructor(graph, content, opts) {
+        this.graph = graph;
+        this.content = content;
+        this.maxDistance = opts?.maxDistance ?? DEFAULT_MAX_DISTANCE;
+    }
+    getContextBundle(seedId, tokenBudget) {
+        const dist = (0, tiers_1.bfsDistances)(this.graph, seedId, this.maxDistance);
+        const candidates = [];
+        for (const [nodeId, distance] of dist) {
+            const tier = (0, tiers_1.tierForDistance)(distance);
+            const detail = (0, render_1.renderDetail)(nodeId, this.content(nodeId), tier);
+            const tokens = (0, tokens_1.estimateTokens)(detail);
+            candidates.push({ nodeId, tier, distance, detail, tokens });
+        }
+        // Deterministic total order: tier priority, then distance, then nodeId.
+        candidates.sort((a, b) => {
+            const tierDiff = TIER_PRIORITY[a.tier] - TIER_PRIORITY[b.tier];
+            if (tierDiff !== 0)
+                return tierDiff;
+            const distDiff = a.distance - b.distance;
+            if (distDiff !== 0)
+                return distDiff;
+            return a.nodeId < b.nodeId ? -1 : a.nodeId > b.nodeId ? 1 : 0;
+        });
+        // No single entry may take more than this share of the budget.
+        //
+        // The budget stops OVERFLOW, not CROWDING OUT. Measured on this repository: seeding a bundle on
+        // a long H-SPEC at budget 2000 produced ONE entry holding 100% of the bundle — a "context
+        // bundle" containing nothing but the seed the caller already had, with three other candidates
+        // dropped. Capping the share means a long document is truncated rather than allowed to consume
+        // the room every other entry needed.
+        //
+        // Truncation is marked in the text: a silently shortened document reads as a complete one, and a
+        // reader acting on a spec's first half while believing they have all of it is worse off than one
+        // who knows to go read the rest.
+        const perEntryCap = Math.max(1, Math.floor(tokenBudget * MAX_ENTRY_BUDGET_SHARE));
+        const capped = candidates.map((c) => {
+            if (c.tokens <= perEntryCap)
+                return c;
+            // estimateTokens is proportional to length, so scaling the text by the token ratio lands close
+            // to the cap. The MARKER's own tokens are subtracted first: without that, truncating at a tiny
+            // budget still overshot — a probe at budget 1 produced 11 tokens, because the marker alone
+            // costs more than the cap. The recomputed count is what is actually recorded.
+            const markerTokens = (0, tokens_1.estimateTokens)(TRUNCATION_MARKER);
+            const room = Math.max(0, perEntryCap - markerTokens);
+            const keep = Math.max(0, Math.floor(c.detail.length * (room / c.tokens)));
+            const detail = `${c.detail.slice(0, keep)}${TRUNCATION_MARKER}`;
+            return { ...c, detail, tokens: (0, tokens_1.estimateTokens)(detail) };
+        });
+        const entries = [];
+        const dropped = [];
+        let usedTokens = 0;
+        for (const candidate of capped) {
+            // The seed (distance 0) is mandatory: it is always included even if its
+            // tokens alone exceed the remaining/total budget, since a bundle
+            // without its own seed node is meaningless. This is the only case
+            // where usedTokens may exceed tokenBudget.
+            const isSeed = candidate.nodeId === seedId;
+            if (isSeed || usedTokens + candidate.tokens <= tokenBudget) {
+                entries.push(candidate);
+                usedTokens += candidate.tokens;
+            }
+            else {
+                dropped.push(candidate.nodeId);
+            }
+        }
+        return {
+            seedId,
+            budget: tokenBudget,
+            usedTokens,
+            entries,
+            dropped: dropped.sort(),
+        };
+    }
+}
+exports.ContextBundler = ContextBundler;

package/dist/holmes/context/render.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDetail = renderDetail;
+const DOMAIN_PREVIEW_CHARS = 200;
+const COLD_LINE_CHARS = 80;
+/** First non-empty line of content, or '' if none. */
+function firstNonEmptyLine(content) {
+    return content.split('\n').find((l) => l.trim().length > 0) ?? '';
+}
+/**
+ * Renders a node's content at the detail level appropriate for its context
+ * tier. Deterministic: fixed char limits, no ellipsis, no randomness.
+ * - hot: full content (nodeId alone if content is null).
+ * - domain: nodeId + up to 200-char preview of content.
+ * - cold: nodeId + first non-empty line, truncated to 80 chars.
+ */
+// @implements A-SPEC-111.1
+function renderDetail(nodeId, content, tier) {
+    if (content === null)
+        return nodeId;
+    switch (tier) {
+        case 'hot':
+            return content;
+        case 'domain':
+            return `${nodeId}\n${content.slice(0, DOMAIN_PREVIEW_CHARS)}`;
+        case 'cold':
+            return `${nodeId}\n${firstNonEmptyLine(content).slice(0, COLD_LINE_CHARS)}`;
+    }
+}

package/dist/holmes/context/tiers.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUB_DEGREE = exports.REL_COST = void 0;
+exports.tierForDistance = tierForDistance;
+exports.bfsDistances = bfsDistances;
+/**
+ * Distance→tier classifier. 0|1 -> hot, 2|3 -> domain, else cold.
+ *
+ * NOTE: since edge weighting landed, the input is a traversal COST, not a hop count. A spec-chain
+ * hop costs 1 and a `calls` hop costs 2, so a directly-called symbol arrives at 2 and lands in
+ * `domain` rather than `hot` — deliberately: what a file implements is the hot context, what calls it
+ * is surrounding context. Reading this parameter as "number of hops" would misjudge every call edge.
+ */
+function tierForDistance(distance) {
+    if (distance <= 1)
+        return 'hot';
+    if (distance <= 3)
+        return 'domain';
+    return 'cold';
+}
+/**
+ * Deterministic BFS from seedId over graph.neighbors(), recording the shortest
+ * hop distance to each reachable node (seed distance is 0). Nodes beyond
+ * maxDistance are not enqueued (and thus not included in the result). Ties
+ * are broken by visiting neighbors in sorted order (neighbors() already
+ * returns sorted, deduped ids), so results are deterministic.
+ */
+/**
+ * What one hop of each relation costs.
+ *
+ * `implements` and `depends_on` are the traceability chain the bundle exists to carry, so they cost
+ * one. A `calls` hop costs more, because call edges make the graph far denser and a distance
+ * calibrated for the spec chain then reaches nearly everything: measured on this repository, adding
+ * call edges took a budget-8000 bundle from 164 entries to 252 — 91% of the whole graph — while the
+ * distance bound of 6 stayed untouched. A token budget alone does not fix that; it just fills the
+ * budget with distant nodes instead of overflowing.
+ *
+ * This is REQ-127's edge-type weighting: bounding propagation by KIND, not only by depth and hubs.
+ */
+exports.REL_COST = { implements: 1, depends_on: 1, calls: 2, imports: 2 };
+const DEFAULT_REL_COST = 2;
+/**
+ * Deterministic weighted shortest-path from seedId, recording the cheapest cost to each reachable
+ * node (seed cost 0). Nodes beyond maxDistance are never enqueued.
+ *
+ * Costs are small integers, so this uses a bucket queue rather than a comparison heap — O(V+E+maxD)
+ * and no ordering ambiguity. Ties are broken by visiting neighbours in sorted order, which
+ * `neighborsWithRel` already guarantees, so results stay byte-identical across runs.
+ */
+/**
+ * Degree above which a node is a HUB and the walk stops expanding past it.
+ *
+ * Measured after call edges landed: from every seed tried, distance 6 reached 100% of a 1,159-node
+ * graph, so the distance bound contributed nothing and only the token budget was holding the bundle
+ * down. The connector is not `calls` — it is SPEC nodes acting as `implements` hubs, since every file
+ * anchoring to a spec is two cheap hops from every other file anchoring to it. Weighting call edges
+ * alone therefore could not fix it.
+ *
+ * A hub is still INCLUDED (it is genuinely adjacent); the walk simply does not travel THROUGH it,
+ * which is the same rule impact propagation uses and the reason a bound can stay meaningful on a
+ * small-world graph.
+ */
+exports.HUB_DEGREE = 24;
+function bfsDistances(graph, seedId, maxDistance, hubDegree = exports.HUB_DEGREE) {
+    const dist = new Map();
+    dist.set(seedId, 0);
+    // buckets[d] holds nodes whose current best cost is d; processed in ascending d.
+    const buckets = Array.from({ length: maxDistance + 1 }, () => []);
+    buckets[0].push(seedId);
+    for (let d = 0; d <= maxDistance; d++) {
+        for (let i = 0; i < buckets[d].length; i++) {
+            const current = buckets[d][i];
+            if (dist.get(current) !== d)
+                continue; // stale entry, already improved
+            if (d >= maxDistance)
+                continue;
+            const around = graph.neighborsWithRel(current);
+            // Damping applies to the FAN-OUT that makes a node a hub, never to the spec chain.
+            //
+            // Blanket damping was tried and broke the one thing the bundle exists to carry: an A-SPEC
+            // anchored by forty files is a hub, so the walk stopped AT it and never reached the H-SPEC and
+            // REQ above — traceability severed at the first popular spec. What makes such a node a hub is
+            // its `implements` fan-in (many files -> one spec); the chain climbs by `depends_on`, which is
+            // one-to-few by construction and never the cause of the blow-up.
+            //
+            // So a hub still stops LATERAL travel — sibling files anchored to the same spec — while the
+            // chain keeps climbing. The climb is OUTGOING `depends_on` only: a shared parent (one REQ with
+            // many slices hanging under it) is itself a bidirectional hub, and following it downward walks
+            // from any slice into every other one. Allowing both directions here put reach back at 38-45%
+            // of the graph; restricting to parents is what keeps the chain intact AND the bundle bounded.
+            // The seed is always expanded either way — refusing that would answer "nothing is nearby" for
+            // exactly the widely-used symbols people most often change.
+            const isHub = d > 0 && around.length > hubDegree;
+            const reachable = isHub
+                ? graph.parentsOf(current).map((id) => ({ id, rel: 'depends_on' }))
+                : around;
+            for (const { id: next, rel } of reachable) {
+                const cost = d + (exports.REL_COST[rel] ?? DEFAULT_REL_COST);
+                if (cost > maxDistance)
+                    continue;
+                const known = dist.get(next);
+                if (known === undefined || cost < known) {
+                    dist.set(next, cost);
+                    buckets[cost].push(next);
+                }
+            }
+        }
+    }
+    return dist;
+}

package/dist/holmes/context/tokens.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokens = estimateTokens;
+/** Approximate token count (~4 chars/token). Deterministic heuristic, not a real tokenizer. */
+// @implements A-SPEC-111.1
+function estimateTokens(text) {
+    return text.length === 0 ? 0 : Math.ceil(text.length / 4);
+}