mellos-mapping 0.22.1 → 0.24.0

package/docs/map-api.md

@@ -0,0 +1,148 @@
+# Persistent maps and the MCP API
+
+Maps survive process restarts and new conversations. Begin with `mmap_read
+{resource: "pages"}`, match the effort to a saved page, then read only relevant
+records. A conversation is not a page identity. `mmap_view` remains the visual
+representation; `mmap_read` is the editable data contract.
+
+## Read
+
+`mmap_read` returns JSON text and the same object in `structuredContent`:
+`resource`, `project`, `page`, `revision`, `total`, `items`, `nextCursor`.
+The default page is represented by a null `page` and the record ID `_default`.
+Named page slugs and resource IDs remain stable; change display titles/labels
+instead of renaming identity. Edge IDs are `from->to`.
+
+| resource | Records |
+| --- | --- |
+| pages (default) | Page IDs, titles, kind, counts, context and each page's revision; a broken page is listed with its error |
+| map | One page's metadata/context/counts; it does not embed the entire graph |
+| nodes | Node IDs, labels, status and membership; request detail, evidence and sources through fields |
+| edges | ID, from, to and optional label |
+| layers / groups / lanes | The stored editable records |
+| neighborhood | Related nodes selected by id/ids, direction (dependencies/consumers/both) and depth (0–4) |
+| changes | Source-file verification state for selected nodes and up to 100 affected consumer IDs |
+
+Use `id` for exact lookup (missing is `NOT_FOUND`), `ids` for a selection,
+`query` for text matching, and status/layer/group/lane for node filtering.
+`fields` projects records while always retaining identity and edge endpoints.
+The default limit is 30, maximum 100. Repeat the same query with nextCursor;
+if the graph changes, the cursor returns `CONFLICT` instead of skipping records.
+An absent page is `NOT_FOUND`; an empty list is successful. The legacy view's
+empty-map behavior is retained for compatibility.
+
+Use a page or record response's revision for that page's next write. The top-level
+revision of a pages listing describes the listing, not any individual page.
+`ifRevision` can avoid resending unchanged graph data. It does not suppress
+source checks: files may change without a graph edit. Pagination checks graph
+revisions, not a filesystem snapshot of source files changing during the query.
+
+```json
+{"resource":"nodes","page":"payments","status":"in-progress","fields":["label","detail","evidence"],"limit":20}
+```
+
+## Create, update and delete
+
+The existing tools and fields remain supported. New writes return a revision
+and structured outcome in addition to the existing summary.
+
+- `mmap_declare`: create pages, layers, groups, lanes, nodes and edges. Existing
+  IDs are refused. Pass expectedRevision: "absent" to require a new page.
+- `mmap_update`: existing node fields, layer names/ranks, group labels/layers,
+  lane labels, complete laneOrder, map title/kind/context and edge patches.
+  An edge patch identifies from/to, with optional label, newFrom and newTo.
+  A null label clears it. A laneOrder contains every lane exactly once.
+- `mmap_remove`: existing per-resource deletion and cascades. Use deletePage:
+  true to delete the targeted page, including the default page. Inbound submap
+  references are refused unless references: "keep" is explicit. Unlink nodes
+  first when the references should disappear. This form cannot include edits
+  or legacy pages batches.
+
+Optional fields are unchanged when omitted and removed when set to null where
+the schema permits. context and sources are replaced as whole values. Moving
+a group does not silently move members: include their intended node moves in
+the same update or transaction. Normal single-field changes keep the old graph
+constraints; use a batch for changes that require a coordinated final graph.
+
+Every graph writer in the current MCP, HTTP viewer and watcher uses a cooperative
+cross-process project lock. MCP expectedRevision is compared inside that lock
+before loading the proposed changes into the saved map. `CONFLICT` requires a
+fresh read and reconsideration of the edit. `BUSY` means another transaction is
+active; retry after it completes. There is no background lock polling. Locks are
+released on normal completion/error; a confirmed dead PID can be recovered.
+An incomplete owner file after an abrupt crash is refused for manual inspection,
+not guessed stale from its age.
+
+Low-level library saveMapFile, hand edits, and older running processes do not
+participate in this contract. Restart MCP processes and native watchers after
+upgrading. Opening a Web surface upgrades services that lack format-2 support;
+existing tabs must reconnect with the newly returned URL. Atomic file
+replacement alone does not make a caller's stale read/modify/write safe.
+
+Legacy `mmap_remove {pages:[...]}` remains a separately documented batch of file
+deletions, with explicit partial success and historical reference behavior. It
+does not accept expectedRevision; use per-page deletePage for checked deletion.
+It is not a multi-page transaction.
+
+## One-page mixed transactions
+
+`mmap_batch` accepts page, expectedRevision and 1–100 ordered operations. Each
+operation is `{op: "declare" | "update" | "remove", data: {...}}`, with the
+same per-page fields as that tool. Per-operation page, expectedRevision and
+page deletion are excluded. Changes are drafted, the final graph is validated,
+and the page is saved once; a refusal preserves the original file bytes.
+
+```json
+{
+  "page":"payments",
+  "expectedRevision":"<revision returned by mmap_read>",
+  "operations":[
+    {"op":"remove","data":{"edges":[{"from":"api","to":"old-store"}]}},
+    {"op":"declare","data":{"nodes":[{"id":"new-store","label":"Store","layer":"base"}]}},
+    {"op":"declare","data":{"edges":[{"from":"api","to":"new-store"}]}},
+    {"op":"update","data":{"context":{"summary":"Payment services","next":"Verify the new store contract"}}}
+  ]
+}
+```
+
+Machine-readable error codes include NOT_FOUND, INVALID_STORE, REFUSED,
+CONFLICT, BUSY, INVALID_CURSOR, INVALID_ARGUMENT, REFERENCED and SAVE_FAILED.
+Malformed schema inputs remain MCP invalid-argument errors. Read calls do not
+open panels or create page files.
+
+## Checkpoints and source changes
+
+Map context has optional summary and next fields (up to 2,000 characters each).
+Save concise decisions and next actions, rather than copying the conversation.
+Nodes can hold up to 100 sources: `{path: "src/store.ts", sha256: "..."}`.
+Paths are project-relative, forward-slash paths with no traversal. SHA256 is
+optional so sources can be linked before verification.
+
+`mmap_read {resource:"changes", page, id}` hashes only the selected node's
+listed files, reports currentSha256 and unchanged/changed/unknown node state,
+and identifies affected consumers. Missing files count as changed. Missing
+baselines, inaccessible files, files over 8 MiB and paths resolving outside
+the project remain unverified. There is no whole-repository source scan and
+no automatic status change. After verification, copy the current hashes into
+sources[].sha256 with a revision-checked update.
+
+Classic maps continue to serialize as format 1. Maps containing context or
+source references serialize as format 2; this runtime reads both. Older runtimes
+must refuse format 2 instead of silently dropping its new fields. Removing all
+extension fields allows serialization as format 1 again. Both formats preserve
+the same graph, statuses and existing evidence.
+
+## Project identity
+
+Without an explicit MELLOS_MAPPING_CWD or CLAUDE_PROJECT_DIR, the server walks
+up from cwd to the nearest existing map store or Git root. An explicit override
+stays explicit. The mmap command and watcher use the same resolver. Nested
+repositories and worktrees are boundaries; separate branches are not silently
+redirected to a shared writable graph. Carry maps through Git or deliberate
+workspace setup when a new worktree needs them, and recheck source baselines.
+
+Codex CLI and App skills both start by reading existing pages. MCP initialization
+also advertises the restore workflow, including for MCP-only installations.
+Viewer selection follows host capabilities; the CLI does not try to use a
+desktop panel tool. After context compaction, repeat the lightweight page/context
+read, then load only the affected resources.

package/lib/domain/context.d.ts

@@ -0,0 +1,11 @@
+/** Optional portable provenance; no host paths or I/O in the map format. */
+export interface SourceRef {
+    readonly path: string;
+    readonly sha256?: string | undefined;
+}
+export interface MapContext {
+    readonly summary?: string | undefined;
+    readonly next?: string | undefined;
+}
+export declare function sourceError(raw: unknown): string | undefined;
+export declare function contextError(raw: unknown): string | undefined;

package/lib/domain/context.js

@@ -0,0 +1,27 @@
+export function sourceError(raw) {
+    if (!Array.isArray(raw) || raw.length > 100)
+        return 'sources must be an array of at most 100 file references';
+    for (const item of raw) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return 'source must be an object';
+        const s = item;
+        if (Object.keys(s).some(k => k !== 'path' && k !== 'sha256'))
+            return 'unknown source field';
+        if (typeof s.path !== 'string' || s.path.length > 1024 || !s.path || /[\u0000-\u001f\u007f-\u009f\\:]/.test(s.path) || s.path.startsWith('/') || s.path.split('/').some(p => !p || p === '.' || p === '..'))
+            return 'source path must be relative to the project, with forward slashes and no traversal';
+        if (s.sha256 !== undefined && (typeof s.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(s.sha256)))
+            return 'source sha256 must be a lowercase SHA256 hash';
+    }
+    return undefined;
+}
+export function contextError(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return 'context must be an object';
+    for (const [key, value] of Object.entries(raw)) {
+        if (key !== 'summary' && key !== 'next')
+            return 'unknown context field';
+        if (typeof value !== 'string' || value.length > 2000 || /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/.test(value))
+            return 'context fields must be text of at most 2000 characters';
+    }
+    return undefined;
+}

package/lib/domain/text.js

@@ -1,9 +1,15 @@
+import { contextError, sourceError } from './context.js';
 // Explicit ranges also work in the JSON Schema published by the MCP adapter.
 export const NO_CONTROLS = /^[^\u0000-\u001f\u007f-\u009f]*$/;
 export const NO_CONTROLS_TEXT = 'one line of text; control characters (ESC, newline, tab) are not allowed';
 export const NO_CONTROLS_BUT_BREAKS = /^[^\u0000-\u0008\u000b-\u001f\u007f-\u009f]*$/;
 export const NO_CONTROLS_BUT_BREAKS_TEXT = 'text with optional newlines (\\n) and tabs; other control characters (ESC, BEL, CR) are not allowed';
 export function mapTextError(map) {
+    if (map.context !== undefined) {
+        const error = contextError(map.context);
+        if (error)
+            return error;
+    }
     const check = (field, value, multiline = false) => value === undefined || (multiline ? NO_CONTROLS_BUT_BREAKS : NO_CONTROLS).test(value)
         ? undefined : `${field}: ${multiline ? NO_CONTROLS_BUT_BREAKS_TEXT : NO_CONTROLS_TEXT}`;
     let error = check('title', map.title);
@@ -22,6 +28,11 @@ export function mapTextError(map) {
         }
     }
     for (const [i, node] of map.nodes.entries()) {
+        if (node.sources !== undefined) {
+            const error = sourceError(node.sources);
+            if (error)
+                return `nodes[${i}]: ${error}`;
+        }
         for (const name of ['label', 'evidence', 'detail']) {
             // Version-1 files and document exports also support multiline evidence.
             // MCP keeps its narrower one-line evidence input for concise updates.

package/lib/domain/types.d.ts

@@ -171,7 +171,9 @@ export interface MapLane {
     readonly label: string;
 }
 /** A unit of work living in exactly one band. */
+export type { SourceRef, MapContext } from './context.js';
 export interface MapNode {
+    readonly sources?: readonly import('./context.js').SourceRef[];
     readonly id: NodeId;
     readonly label: string;
     readonly layer: LayerId;
@@ -198,6 +200,7 @@ export interface DepEdge {
 }
 /** The whole map. A plain immutable value — operations return new maps. */
 export interface MellosMap {
+    readonly context?: import('./context.js').MapContext;
     readonly title?: string;
     /** Presentation intent; absent means 'dev' (the progress ledger). */
     readonly kind?: MapKind;

package/lib/store/format.js

@@ -22,6 +22,7 @@
  */
 import { declareGroup, declareLane, declareLayer, declareNode, linkNodes, setKind, setTitle, updateNode } from '../domain/ops.js';
 import { mapTextError } from '../domain/text.js';
+import { sourceError, contextError } from '../domain/context.js';
 import { EMPTY_MAP, ID_RULE, ID_RULE_TEXT, describeMapError, err, makeGroupId, makeLaneId, makeLayerId, makeMapKind, makeNodeId, makeNodeKind, makeNodeStatus, makeRank, makeSubmapRef, ok, } from '../domain/types.js';
 /** On-disk format version. Bump only with a documented migration. */
 export const STATE_FILE_VERSION = 1;
@@ -99,8 +100,8 @@ function optionalString(rec, key, where, path) {
 export function parseMap(raw, path) {
     if (!isRecord(raw))
         return err({ kind: 'bad-shape', path, detail: 'root is not an object' });
-    if (raw['version'] !== STATE_FILE_VERSION) {
-        return err({ kind: 'bad-shape', path, detail: `version is ${String(raw['version'])}, expected ${STATE_FILE_VERSION}` });
+    if (raw['version'] !== STATE_FILE_VERSION && raw['version'] !== 2) {
+        return err({ kind: 'bad-shape', path, detail: `version is ${String(raw['version'])}, expected ${STATE_FILE_VERSION} or 2` });
     }
     const layers = arrayField(raw, 'layers', path, 'required');
     if (!layers.ok)
@@ -118,6 +119,12 @@ export function parseMap(raw, path) {
     if (!groups.ok)
         return groups;
     let map = EMPTY_MAP;
+    if (raw['context'] !== undefined) {
+        const error = contextError(raw['context']);
+        if (error)
+            return err({ kind: 'bad-shape', path, detail: error });
+        map = { ...map, context: raw['context'] };
+    }
     const title = optionalString(raw, 'title', 'map', path);
     if (!title.ok)
         return title;
@@ -292,6 +299,12 @@ export function parseMap(raw, path) {
                 return err({ kind: 'invariant-violation', path, violation: updated.error });
             map = updated.value;
         }
+        if (rawNode['sources'] !== undefined) {
+            const error = sourceError(rawNode['sources']);
+            if (error)
+                return err({ kind: 'bad-shape', path, detail: `${where}: ${error}` });
+            map = { ...map, nodes: map.nodes.map(n => n.id === id.value ? { ...n, sources: rawNode['sources'] } : n) };
+        }
     }
     for (const [i, rawEdge] of edges.value.entries()) {
         const where = `edges[${i}]`;
@@ -323,7 +336,9 @@ export function parseMap(raw, path) {
 /** Serialize a map into the on-disk shape. Inverse of parseMap for valid maps (F1). */
 export function serializeMap(map) {
     const body = {
-        version: STATE_FILE_VERSION,
+        // Older runtimes must refuse maps with provenance rather than silently erasing it.
+        version: map.context !== undefined || map.nodes.some(n => n.sources !== undefined) ? 2 : STATE_FILE_VERSION,
+        ...(map.context !== undefined ? { context: map.context } : {}),
         ...(map.title !== undefined ? { title: map.title } : {}),
         ...(map.kind !== undefined ? { kind: map.kind } : {}),
         layers: map.layers,

package/lib/store/project.d.ts

@@ -0,0 +1,2 @@
+/** Nearest existing store or Git root; never cross a nested repository/worktree boundary. */
+export declare function resolveProjectDirectory(cwd: string, stopAt?: readonly string[]): string;

package/lib/store/project.js

@@ -0,0 +1,29 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+/** Nearest existing store or Git root; never cross a nested repository/worktree boundary. */
+export function resolveProjectDirectory(cwd, stopAt = [homedir(), tmpdir()]) {
+    let start = resolve(cwd);
+    try {
+        start = realpathSync(start);
+    }
+    catch { /* Explicit test/manual paths may not exist yet. */ }
+    let dir = start;
+    const boundaries = new Set(stopAt.map(path => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    } }));
+    while (true) {
+        // A user's global .mellos directory is not an ancestor project's store.
+        if (dir !== start && boundaries.has(dir))
+            return start;
+        if (existsSync(join(dir, '.git')) || existsSync(join(dir, '.mellos', 'map.json')) || existsSync(join(dir, '.mellos', 'pages')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return start;
+        dir = parent;
+    }
+}

package/lib/store/store.d.ts

@@ -16,10 +16,13 @@
  * The concurrency model P2 buys, stated plainly:
  *   - Several writers may target one project at once. Each save is atomic and
  *     lands whole, so a reader never sees half a map — but there is NO
- *     lost-update protection: two saves of the same page race, and the last
+ *     lost-update protection in this low-level save API: two saves race, and the last
  *     rename wins, silently discarding what the other writer computed from an
  *     older read. Pages are the isolation unit (one effort = one page); two
  *     sessions that must not clobber each other belong on two pages.
+ *     Current MCP/viewer writers additionally use transaction.ts to lock the
+ *     complete read/modify/write operation, with optional revision checks.
+ *     Direct library saves and older processes do not acquire that lock.
  *   - The temp file carries the writer's pid and a random suffix, so
  *     concurrent writers never share one and never install each other's
  *     half-written content.
@@ -47,3 +50,5 @@ export { VIEWERS_DIR_NAME, VIEWER_FILE_VERSION, VIEWER_HEARTBEAT_MS, VIEWER_STAL
 export { CONFIG_FILE_NAME, CONFIG_FILE_VERSION, configFilePath, userConfigFilePath, MAPPING_POLICIES, type MappingPolicy, type InvalidPolicy, makeMappingPolicy, describeMappingPolicy, loadMappingPolicy, saveMappingPolicy, POLICY_SCOPES, type PolicyScope, type MappingPolicyScopes, effectiveMappingPolicy } from './policy.js';
 export { LEGACY_STATE_FILE_RELATIVE_PATH, migrateLegacyStore } from './migration.js';
 export { loadMapFile, saveMapFile } from './maps.js';
+export { withStoreLock, revisionOf, assertRevision, LedgerError } from './transaction.js';
+export { resolveProjectDirectory } from './project.js';

package/lib/store/store.js

@@ -16,10 +16,13 @@
  * The concurrency model P2 buys, stated plainly:
  *   - Several writers may target one project at once. Each save is atomic and
  *     lands whole, so a reader never sees half a map — but there is NO
- *     lost-update protection: two saves of the same page race, and the last
+ *     lost-update protection in this low-level save API: two saves race, and the last
  *     rename wins, silently discarding what the other writer computed from an
  *     older read. Pages are the isolation unit (one effort = one page); two
  *     sessions that must not clobber each other belong on two pages.
+ *     Current MCP/viewer writers additionally use transaction.ts to lock the
+ *     complete read/modify/write operation, with optional revision checks.
+ *     Direct library saves and older processes do not acquire that lock.
  *   - The temp file carries the writer's pid and a random suffix, so
  *     concurrent writers never share one and never install each other's
  *     half-written content.
@@ -48,3 +51,5 @@ export { VIEWERS_DIR_NAME, VIEWER_FILE_VERSION, VIEWER_HEARTBEAT_MS, VIEWER_STAL
 export { CONFIG_FILE_NAME, CONFIG_FILE_VERSION, configFilePath, userConfigFilePath, MAPPING_POLICIES, makeMappingPolicy, describeMappingPolicy, loadMappingPolicy, saveMappingPolicy, POLICY_SCOPES, effectiveMappingPolicy } from './policy.js';
 export { LEGACY_STATE_FILE_RELATIVE_PATH, migrateLegacyStore } from './migration.js';
 export { loadMapFile, saveMapFile } from './maps.js';
+export { withStoreLock, revisionOf, assertRevision, LedgerError } from './transaction.js';
+export { resolveProjectDirectory } from './project.js';

package/lib/store/transaction.d.ts

@@ -0,0 +1,12 @@
+import type { MellosMap } from '../domain/types.js';
+export declare class LedgerError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare const revisionOf: (map: MellosMap) => string;
+export declare function assertRevision(actual: string, expected?: string): void;
+/** A named page and the default page share the same project lock. */
+export declare function storeDirectory(file: string): string;
+/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
+export declare function withStoreLock<T>(file: string, action: () => T): T;

package/lib/store/transaction.js

@@ -0,0 +1,91 @@
+/** Cooperative, cross-process transactions for MCP and HTTP writers. */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { serializeMap } from './format.js';
+export class LedgerError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export const revisionOf = (map) => createHash('sha256').update(serializeMap(map)).digest('hex');
+export function assertRevision(actual, expected) {
+    if (expected !== undefined && expected !== actual)
+        throw new LedgerError('CONFLICT', 'Map changed; read the current revision before retrying.', { expectedRevision: expected, actualRevision: actual });
+}
+/** A named page and the default page share the same project lock. */
+export function storeDirectory(file) {
+    const dir = dirname(file);
+    return dir.endsWith('/pages') || dir.endsWith('\\pages') ? dirname(dir) : dir;
+}
+function deadOwner(lock) {
+    try {
+        const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0)
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return false;
+        }
+        catch (e) {
+            return e.code === 'ESRCH';
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
+export function withStoreLock(file, action) {
+    const dir = storeDirectory(file);
+    mkdirSync(dir, { recursive: true });
+    const lock = join(dir, '.write-lock');
+    const owner = join(lock, 'owner.json');
+    const token = randomUUID();
+    try {
+        mkdirSync(lock);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // Reapers serialize inside the old directory and recheck its owner after acquiring.
+        // Missing/invalid owners are deliberately not reclaimed on an age heuristic.
+        if (!deadOwner(lock))
+            throw new LedgerError('BUSY', `Another writer owns ${lock}; retry after it completes. An orphan without owner metadata needs manual inspection.`);
+        try {
+            mkdirSync(join(lock, '.reap'));
+        }
+        catch {
+            throw new LedgerError('BUSY', 'Another process is recovering the writer lock.');
+        }
+        if (!deadOwner(lock)) {
+            rmSync(join(lock, '.reap'), { recursive: true, force: true });
+            throw new LedgerError('BUSY', 'Writer ownership changed.');
+        }
+        rmSync(lock, { recursive: true });
+        try {
+            mkdirSync(lock);
+        }
+        catch {
+            throw new LedgerError('BUSY', 'Another writer acquired the recovered lock.');
+        }
+    }
+    let initialized = false;
+    try {
+        writeFileSync(owner, JSON.stringify({ pid: process.pid, token }), { flag: 'wx' });
+        initialized = true;
+        return action();
+    }
+    finally {
+        // Only remove the directory still owned by this invocation.
+        try {
+            if (!initialized || JSON.parse(readFileSync(owner, 'utf8')).token === token)
+                rmSync(lock, { recursive: true });
+        }
+        catch { /* A cleanup error must not misreport a successfully committed map as unsaved. */ }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "mcpName": "io.github.GuangminJu/mellos-mapping",
   "description": "A live layered dependency map for bottom-up development — MCP server + terminal pane. Ghost the design first, then light nodes up from the bottom as they are built and verified.",
   "type": "module",
@@ -70,6 +70,7 @@
     "lib",
     "README.zh-CN.md",
     "docs/codex.md",
+    "docs/map-api.md",
     "scripts/codex-register.mjs",
     "scripts/codex-cli.mjs",
     "scripts/install-mmap-command.mjs",
@@ -92,9 +93,10 @@
     "check:release": "node scripts/check-release.mjs",
     "check:package": "node scripts/check-package-surface.mjs",
     "check:codex": "node scripts/check-codex-package.mjs",
+    "check:reuse": "node scripts/check-reuse.mjs",
     "benchmark:render": "node scripts/benchmark-render.mjs",
     "prepack": "npm run build",
-    "verify": "npm run typecheck && npm run test && npm run build && npm run check:package && npm run check:codex && npm run check:release"
+    "verify": "npm run typecheck && npm run test && npm run build && npm run check:reuse && npm run check:package && npm run check:codex && npm run check:release"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/scripts/codex-register.mjs

@@ -42,7 +42,7 @@ if (launchedAsEntry(import.meta.url)) {
     const installed = registerServer(dirname(dirname(fileURLToPath(import.meta.url))));
     console.log(`mellos-mapping MCP registered with Codex: ${installed.nodePath} ${installed.serverPath}`);
     console.log('State files resolve to each session’s working directory (.mellos/map.json).');
-    console.log('Start a new Codex conversation to load the skills and six mmap tools.');
+    console.log('Start a new Codex conversation to load the skills and eight mmap tools.');
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;

package/scripts/mmap.mjs

@@ -170,7 +170,7 @@ async function main() {
     console.error(parsed.error);
     process.exit(1);
   }
-  const candidates = storeSearchPath(process.cwd());
+  const candidates = [store.resolveProjectDirectory(process.cwd())];
   const marker = storeMarkerOf(store.STATE_FILE_RELATIVE_PATH);
   const project = nearestProject(candidates, candidates.map((dir) => existsSync(join(dir, marker))));
   const cfg = { ...parsed.value, projectDir: project.root };