@marver-design/marver 0.20.0 → 0.22.0

package/templates/playbooks/reorganize-context/eval.md

@@ -0,0 +1,93 @@
+# Context eval - can a fresh agent answer from the repo alone?
+
+The reorganization is judged by one thing: a fresh agent, with no memory and no chat history,
+answering real questions about the product correctly and cheaply. Run it **before** and **after**,
+the same way both times.
+
+This file is the protocol and the questions. The **answer key is a separate file**
+(`answer-key-<project>.md`) and never enters the worktree the agent reads.
+
+## Isolation - check before each pass
+
+- The agent runs in the worktree (`../<repo>-context`), a fresh process per question.
+- No agent memory for that path: Claude Code keys memory by project path, so
+  `~/.claude/projects/<worktree-slug>/memory/` must not exist. Codex keeps none by default.
+- No hook injects project context for that path (a vault feed keyed by path, a knowledge inbox).
+- The answer key, the reorg notes kept outside the worktree, and earlier pass results are not in
+  the worktree. Before the first pass, `context/` does not exist yet.
+- **A clean profile.** Global instructions also count as injected context: Claude Code loads
+  `~/.claude/CLAUDE.md`, Codex loads its global `AGENTS.md`. Launch with an empty config home and
+  only credentials in it - Claude Code: `CLAUDE_CONFIG_DIR=<empty dir>` with an API key; Codex:
+  `CODEX_HOME=<dir holding only auth>`. Confirm from the transcript's first event that no user or
+  global instruction file was loaded.
+  - *Learned on the first run:* without an API key, Claude Code cannot run clean - `--bare` needs one,
+    and a plain run loads the auto-memory that worktrees of one repository share. Codex with a
+    `CODEX_HOME` holding a copy of `auth.json` works; check `codex features list` shows `memories`
+    off, and keep each pass's session rollouts out of that home before the next pass. Copy the auth
+    only when its `last_refresh` is recent, and delete the copy after.
+- **Read-only.** Claude Code with read tools only (`--allowedTools Read,Grep,Glob`); Codex with
+  `--sandbox read-only`.
+- Same CLI, same model, same prompt, both passes.
+
+## The prompt
+
+> Answer this question using only files in this repository: <question>. Give the answer, the
+> files you used, and your confidence. If the repository cannot settle it, say "cannot tell" and
+> why. Do not run the app, query a database, call an API, or read outside this directory.
+
+## The measurement - one metric, per question
+
+Run each question as its own invocation with a machine-readable transcript (Claude Code:
+`claude -p "<prompt>" --output-format stream-json --verbose`; Codex: `codex exec --json`). From the
+transcript record:
+
+- **result** - correct / partial / wrong / cannot-tell, judged against the answer key;
+- **confident wrong** - a wrong answer given with high confidence, counted separately;
+- **bytes read** - the summed size of every tool result returned to the agent (file reads, searches,
+  listings). Measure what the model saw, not what the command printed: Codex truncates long output
+  (each result carries its `original_token_count`), so read the session rollout's tool outputs, not
+  `exec --json`'s `aggregated_output`. Record the session's **input tokens** beside it;
+- **tool calls**;
+- **out of bounds** - any read outside the worktree. One voids that answer.
+
+"Cannot tell" with the right reason counts as correct where the key says the repository genuinely
+does not hold the answer.
+
+## Pass
+
+- no confident wrong answer after;
+- more correct answers after than before - or, if the before pass was already perfect, equal;
+- fewer total bytes read after.
+
+A capable agent may already answer everything before - the first run's before pass was 16 / 16 at
+medium effort, the traps notwithstanding. Then the pass is decided on cost, and a weaker or cheaper
+profile is worth a second pair of passes to see whether the reorganization moves correctness.
+
+## The six kinds of question
+
+Write 10-16, at least one of each, from Phase 2 evidence, with the key signed off by the human where
+Phase 8 asked:
+
+1. **Shipped** - is X available, where, for whom, since when?
+2. **Behaviour** - how does surface Y work today?
+3. **Interfaces** - what runs behind action Z: jobs, mails, data written?
+4. **Why** - why was decision N taken, and does it still apply?
+5. **Next** - what is being built next, and what counts as done?
+6. **Receipts** - what did someone say about T, and where is it recorded?
+
+Include **traps**: questions where a stale spec, a design frame, or a wrong instruction gives a
+confident wrong answer today. They are the point.
+
+## Your project's questions
+
+Write them before the before pass, from Phase 2's evidence, and keep the key out of the worktree:
+
+| # | Kind | Question | Trap |
+|---|---|---|---|
+
+## Report format
+
+| # | Before: result | Before: bytes / calls | After: result | After: bytes / calls |
+|---|---|---|---|---|
+
+Write the before column before Phase 1 begins - not from memory afterwards.

package/dist/boards-BmxcT3Lc.mjs

@@ -1,290 +0,0 @@
-import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { join, sep } from "node:path";
-import { createHash } from "node:crypto";
-//#region src/server/hash.ts
-/** sha256 hex of a string - the CAS token for board files, the registry, the manifest. */
-const hash = (s) => createHash("sha256").update(s).digest("hex");
-//#endregion
-//#region src/shared/board-tree.ts
-/**
-* Board folders - the pure tree shared by the sidebar, the dev API, the build and the
-* tests. Files are the truth: a board says which folder it sits in (`folder` on the
-* board file, ranked among its siblings by `order`), and `design/boards/_folders.json`
-* says which folders exist and where they rank at the root. One level only: folders
-* hold boards, never folders. `all-scenes` never enters the tree - callers pin it last.
-*/
-/** The on-disk name grammar shared by boards and folders (a board name is a filename). */
-const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
-const isBoardName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
-/** The folder registry beside the boards - underscore = infrastructure, never a board. */
-const FOLDERS_FILE = "_folders.json";
-/** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
-*  off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
-const isBoardFile = (f) => f.endsWith(".json") && isBoardName(f.slice(0, -5));
-const readDescription = (v) => {
-	if (typeof v !== "string") return void 0;
-	return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
-};
-const readTitle = (v) => {
-	if (typeof v !== "string") return void 0;
-	return Array.from(v.replace(/[\u0000-\u001f\u007f]/g, " ").trim().replace(/\s+/g, " ")).slice(0, 120).join("").trim() || void 0;
-};
-const rank = (o) => typeof o === "number" && Number.isFinite(o) ? o : Infinity;
-/** A folder's title and description, present only when set. */
-const folderExtras = (it) => ({
-	...it.title ? { title: it.title } : {},
-	...it.description ? { description: it.description } : {}
-});
-/** The registry file's shape. Returns the rows, or a string naming what is wrong - a
-*  malformed registry is an ERROR the human must fix (silently reading it as empty would
-*  let the next drag overwrite their folders), while a missing file is simply no folders. */
-function parseFolders(raw) {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "expected an object";
-	const { version, folders } = raw;
-	if (version !== void 0 && version !== 1) return `unsupported version ${String(version)}`;
-	if (!Array.isArray(folders)) return "expected a \"folders\" array";
-	const out = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const f of folders) {
-		const name = f?.name;
-		if (!isBoardName(name)) return "a folder needs a name - lowercase letters, numbers and dashes";
-		if (seen.has(name)) return `folder "${name}" is listed twice`;
-		seen.add(name);
-		const o = f.order;
-		const t = readTitle(f.title);
-		const d = readDescription(f.description);
-		out.push({
-			name,
-			...typeof o === "number" && Number.isFinite(o) ? { order: o } : {},
-			...t ? { title: t } : {},
-			...d ? { description: d } : {}
-		});
-	}
-	return out;
-}
-/** Sidebar order from the files. Root: boards with no folder + every folder (registered
-*  or implied by a board), ranked by `order` then kind (board before folder) then name.
-*  Inside a folder: its boards by `order` then name. Unranked sorts after ranked. A folder's
-*  title and description ride on its item (they live in the registry a tree write rewrites);
-*  a board's title stays with its row - it lives in the board's own file. */
-function buildTree(boards, folders) {
-	const folderOrder = /* @__PURE__ */ new Map();
-	const folderMeta = /* @__PURE__ */ new Map();
-	for (const f of folders) if (isBoardName(f.name) && !folderOrder.has(f.name)) {
-		folderOrder.set(f.name, f.order);
-		folderMeta.set(f.name, folderExtras(f));
-	}
-	const members = /* @__PURE__ */ new Map();
-	const rootBoards = [];
-	for (const b of boards) {
-		if (!isBoardName(b.name) || b.name === "all-scenes") continue;
-		const folder = isBoardName(b.folder) ? b.folder : void 0;
-		if (!folder) {
-			rootBoards.push(b);
-			continue;
-		}
-		if (!folderOrder.has(folder)) folderOrder.set(folder, void 0);
-		const list = members.get(folder) ?? [];
-		list.push(b);
-		members.set(folder, list);
-	}
-	const byRank = (a, b) => rank(a.order) - rank(b.order) || a.name.localeCompare(b.name);
-	const root = [...rootBoards.map((b) => ({
-		item: {
-			kind: "board",
-			name: b.name
-		},
-		order: b.order
-	})), ...[...folderOrder].map(([name, order]) => ({
-		item: {
-			kind: "folder",
-			name,
-			boards: (members.get(name) ?? []).sort(byRank).map((b) => b.name),
-			...folderMeta.get(name) ?? {}
-		},
-		order
-	}))];
-	root.sort((a, b) => rank(a.order) - rank(b.order) || (a.item.kind === b.item.kind ? 0 : a.item.kind === "board" ? -1 : 1) || a.item.name.localeCompare(b.item.name));
-	return root.map((r) => r.item);
-}
-/** Every board in reading order - the order the switchers and the landing pick use. */
-function flatten(tree) {
-	const out = [];
-	for (const it of tree) if (it.kind === "board") out.push(it.name);
-	else out.push(...it.boards);
-	return out;
-}
-function validateWire(wire) {
-	if (!Array.isArray(wire)) return "invalid tree";
-	const boards = /* @__PURE__ */ new Set(), folders = /* @__PURE__ */ new Set();
-	const board = (n) => {
-		if (!isBoardName(n) || n === "all-scenes") return "invalid board name in tree";
-		if (boards.has(n)) return `board "${n}" appears twice`;
-		boards.add(n);
-		return null;
-	};
-	for (const w of wire) {
-		if (typeof w === "string") {
-			const e = board(w);
-			if (e) return e;
-			continue;
-		}
-		if (!w || typeof w !== "object" || Array.isArray(w)) return "invalid tree item";
-		const { folder, boards: kids, title, description } = w;
-		if (!isBoardName(folder)) return "invalid folder name in tree";
-		if (title !== void 0 && (typeof title !== "string" || Array.from(title).length > 120)) return "invalid folder title";
-		if (description !== void 0 && (typeof description !== "string" || description.length > 300)) return "invalid folder description";
-		if (folders.has(folder)) return `folder "${folder}" appears twice`;
-		folders.add(folder);
-		if (!Array.isArray(kids)) return "invalid folder in tree";
-		for (const k of kids) {
-			const e = board(k);
-			if (e) return e;
-		}
-	}
-	if (boards.size > 200 || folders.size > 50) return "tree too large";
-	return null;
-}
-//#endregion
-//#region src/server/boards.ts
-/**
-* Reading design/boards/ safely - the one enumerator the dev API, the build and the tests
-* share. Only REGULAR files on the board-name grammar count as boards (a symlink, dangling or
-* live, could read or publish JSON from outside the project - it is skipped, and reported so
-* the build can fail closed). The folder registry is read the same way: absent = no folders,
-* malformed = an error the human must fix, never a silently empty registry.
-*/
-/** Does realpath(dir) stay inside realpath(root)? A symlinked design/boards can't escape. */
-function underRoot(root, dir) {
-	try {
-		const rr = realpathSync(root);
-		const rd = realpathSync(dir);
-		return rd === rr || rd.startsWith(rr + sep);
-	} catch {
-		return false;
-	}
-}
-/** Is design/boards a directory we may read and write? It must not be a symlink at all (a
-*  link to the repo root would list package.json as a board and let a tree write rewrite
-*  it; a link outside would publish foreign JSON) and must resolve inside the root. Absent
-*  is fine (no boards yet). Returns the error, or null. */
-function checkBoardsDir(root, boardsDir) {
-	return checkRealDirs(root, [[join(boardsDir, ".."), "design"], [boardsDir, "design/boards"]]);
-}
-/** Every EXISTING path in `dirs` (root-down order) must be a real directory inside the root -
-*  a symlinked `design` with no boards dir yet would otherwise be followed by the mkdir that
-*  creates it; a symlinked `design/scenes` would let a brief write land outside the project.
-*  An absent one ends the walk (nothing beneath it exists either). Returns the error, or null. */
-function checkRealDirs(root, dirs) {
-	for (const [p, label] of dirs) {
-		try {
-			if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
-		} catch {
-			return null;
-		}
-		if (!underRoot(root, p)) return `${label} escapes the project`;
-	}
-	return null;
-}
-/** A regular file (lstat: a symlink is never followed, a dangling one is not "absent"). */
-const isRegularFile = (p) => {
-	try {
-		return lstatSync(p).isFile();
-	} catch {
-		return false;
-	}
-};
-/** Is there ANY node at p (a dangling symlink counts)? */
-const nodeExists = (p) => {
-	try {
-		lstatSync(p);
-		return true;
-	} catch {
-		return false;
-	}
-};
-/** Every board file: name, raw content, hash, and its JSON (null when malformed). `skipped`
-*  names the entries that looked like boards but were not regular files. */
-function listBoardFiles(boardsDir) {
-	const boards = [], skipped = [];
-	if (!existsSync(boardsDir)) return {
-		boards,
-		skipped
-	};
-	for (const f of readdirSync(boardsDir)) {
-		if (!isBoardFile(f)) continue;
-		const file = join(boardsDir, f);
-		if (!isRegularFile(file)) {
-			skipped.push(f);
-			continue;
-		}
-		const content = readFileSync(file, "utf8");
-		let json = null;
-		try {
-			json = JSON.parse(content);
-		} catch {}
-		boards.push({
-			name: f.slice(0, -5),
-			file,
-			content,
-			sha256: hash(content),
-			json
-		});
-	}
-	return {
-		boards,
-		skipped
-	};
-}
-/** The author-owned sidebar fields off a board's JSON, leniently: rank, folder, the title
-*  humans see, the sentence agents read. */
-function boardFields(json, validName) {
-	const o = json;
-	const title = readTitle(o?.title);
-	const description = readDescription(o?.description);
-	return {
-		...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
-		...validName(o?.folder) ? { folder: o.folder } : {},
-		...title ? { title } : {},
-		...description ? { description } : {}
-	};
-}
-/** The folder registry. `sha256` is the CAS token a tree write must echo (null = "there was
-*  no file"), so a write can never silently replace a registry it never saw. */
-function readRegistry(boardsDir) {
-	const p = join(boardsDir, FOLDERS_FILE);
-	if (!nodeExists(p)) return {
-		state: "absent",
-		folders: [],
-		sha256: null
-	};
-	if (!isRegularFile(p)) return {
-		state: "malformed",
-		error: `design/boards/${FOLDERS_FILE} must be a regular file, not a symlink`,
-		sha256: null
-	};
-	const content = readFileSync(p, "utf8");
-	let raw;
-	try {
-		raw = JSON.parse(content);
-	} catch {
-		return {
-			state: "malformed",
-			error: `design/boards/${FOLDERS_FILE} is not valid JSON - fix the file`,
-			sha256: hash(content)
-		};
-	}
-	const parsed = parseFolders(raw);
-	if (typeof parsed === "string") return {
-		state: "malformed",
-		error: `design/boards/${FOLDERS_FILE}: ${parsed}`,
-		sha256: hash(content)
-	};
-	return {
-		state: "ok",
-		folders: parsed,
-		sha256: hash(content)
-	};
-}
-//#endregion
-export { listBoardFiles as a, BOARD_NAME as c, flatten as d, isBoardName as f, hash as g, validateWire as h, isRegularFile as i, FOLDERS_FILE as l, readTitle as m, checkBoardsDir as n, nodeExists as o, readDescription as p, checkRealDirs as r, readRegistry as s, boardFields as t, buildTree as u };

package/dist/boards-PuVzw5Wp.mjs

@@ -1,62 +0,0 @@
-import { a as listBoardFiles, d as flatten, f as isBoardName, n as checkBoardsDir, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BmxcT3Lc.mjs";
-import { join } from "node:path";
-//#region src/cli/boards.ts
-/**
-* `marver boards` - the sidebar as the agent sees it: every folder and board in reading
-* order, from the files (no dev server needed). One call answers "what folders exist, what
-* is in them, what ranks where" before the agent writes `folder` on a board or edits
-* `design/boards/_folders.json`. `--json` gives the tree shape the shell uses.
-*/
-function boardsCommand(root, opts) {
-	const dir = join(root, "design", "boards");
-	const de = checkBoardsDir(root, dir);
-	if (de) throw new Error(de);
-	const { boards, skipped } = listBoardFiles(dir);
-	const reg = readRegistry(dir);
-	if (reg.state === "malformed") throw new Error(reg.error);
-	const rows = boards.map((b) => ({
-		name: b.name,
-		...boardFields(b.json, isBoardName)
-	}));
-	const tree = buildTree(rows, reg.folders);
-	const hasAll = boards.some((b) => b.name === "all-scenes");
-	if (opts.json) {
-		console.log(JSON.stringify({
-			tree,
-			boards: rows.filter((r) => r.name !== "all-scenes"),
-			landing: flatten(tree)[0] ?? (hasAll ? "all-scenes" : null),
-			registry: reg.state === "ok" ? "design/boards/_folders.json" : null
-		}, null, 2));
-		return;
-	}
-	if (!tree.length && !hasAll) {
-		console.log("no boards yet - design/boards/ is empty");
-		return;
-	}
-	const order = (n) => {
-		const o = rows.find((r) => r.name === n)?.order;
-		return o === void 0 ? "" : `  order ${o}`;
-	};
-	const title = (t) => t ? `  "${t}"` : "";
-	const desc = (d) => d ? `  - ${d}` : "";
-	const boardLine = (n) => {
-		const r = rows.find((x) => x.name === n);
-		return `${n}${title(r?.title)}${order(n)}${desc(r?.description)}`;
-	};
-	for (const it of tree) {
-		if (it.kind === "board") {
-			console.log(boardLine(it.name));
-			continue;
-		}
-		console.log(`${it.name}/${title(it.title)}  (folder, ${it.boards.length} board${it.boards.length === 1 ? "" : "s"}${reg.folders.some((f) => f.name === it.name) ? "" : ", implied by its boards - not in _folders.json"})${desc(it.description)}`);
-		for (const b of it.boards) console.log(`  ${boardLine(b)}`);
-		if (!it.boards.length) console.log("  (empty)");
-	}
-	if (hasAll) console.log("all-scenes  (auto, always last)");
-	const landing = flatten(tree)[0];
-	if (landing) console.log(`\nlanding board: ${landing}`);
-	console.log(`registry: ${reg.state === "ok" ? "design/boards/_folders.json" : "none (no empty or ranked folders yet)"}`);
-	if (skipped.length) console.log(`skipped (not regular files): ${skipped.join(", ")}`);
-}
-//#endregion
-export { boardsCommand };