readfirst 0.7.0 → 0.9.0

package/README.md

@@ -15,11 +15,16 @@ No server, no account, no model calls. It reads your git checkout and `.readfirs
 Any language; needs Node 20+ for `npx`.
 
 ```sh
-npx readfirst init --agent   # first map from your folders, checks from your scripts, plus the line for CLAUDE.md / AGENTS.md
+npx readfirst init --agent --ci   # first map from your folders, checks from your scripts, the line for CLAUDE.md / AGENTS.md,
+                                  # and the GitHub Action that comments on PRs and keeps the map in step
 npx readfirst prompt         # a brief for your coding agent to fill in titles, checks, risks and rules
 npx readfirst check          # every tracked file is in exactly one group (or ignored); rules point at real files
 ```
 
+In a monorepo, each workspace package with its own `package.json` becomes a group with its own checks
+(`pnpm --filter @acme/db test`, `yarn workspace …`, `npm test -w …`), so `verify` runs that package's tests, not the
+whole repository's, and its description becomes the group's title.
+
 Commit `.readfirst/map.json`. From then on:
 
 ```sh
@@ -50,6 +55,18 @@ npx readfirst hook --install
 adds a hook to `.claude/settings.json`. Before each Edit or Write, Claude Code gets the rules, risks and checks for that
 file as context, once per file per session. Nothing to remember, and the edit is never blocked.
 
+Want the checks enforced, not just suggested?
+
+```sh
+npx readfirst hook --install --verify
+```
+
+also adds a Stop hook: before Claude Code finishes its turn, it runs the map's checks for the files it edited in that
+session. If one fails, Claude Code cannot finish yet and gets the failure to fix. It gets one try per turn, so a check
+it cannot fix never traps the session. It runs only check commands that the map on your main branch already lists: a
+command someone's branch adds or changes is named, not run, until it is merged (`npx readfirst verify` runs it when you
+choose to).
+
 ### See the map
 
 ```sh
@@ -121,10 +138,29 @@ lists what `npx readfirst fix` would change.
 | `fail-on-map-problems` | `true` | `false` reports map problems without failing |
 | `strict` | `false` | `true` also fails on new files that are only placed by their neighbours |
 | `comment` | `true` | `false` writes only the job summary |
+| `auto-fix` | `false` | `true` commits what `readfirst fix` settles (new files placed by their neighbours) to the PR branch |
 | `limit` | `30` | most tests and users listed per section |
 
 On a PR from a fork, the token is read-only. The list then goes to the job summary instead of a comment.
 
+### Keep the map in step without thinking about it
+
+```yaml
+permissions:
+  contents: write        # for auto-fix
+  pull-requests: write
+# ...
+      - uses: jeonghun917/readfirst@v0
+        with:
+          auto-fix: true
+```
+
+With `auto-fix`, when a PR adds files next to ones the map already places, the Action writes them into the map and
+commits that to the PR branch. That is the mechanical part `npx readfirst fix` does, nothing else: new risks and
+rules stay for a person. It skips PRs from forks, and it skips the commit if the branch's map changed since the run
+started, so a push is never overwritten. A commit made with the default `GITHUB_TOKEN` does not start new workflow
+runs. If your branch protection requires checks, pass a GitHub App or personal token as `token`.
+
 ## The map
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "mcpName": "io.github.jeonghun917/readfirst",
   "description": "What to read and check before you (or your AI agent) change a file: project rules, risks and tests tied to code.",
   "type": "module",

package/src/action.mjs

@@ -30,12 +30,14 @@ async function pages(fetchImpl, env, path) {
   return all;
 }
 
-export function commentBody({ list, problems, removed, commit, fixes = [], settled = [] }) {
+export function commentBody({ list, problems, removed, commit, fixes = [], settled = [], committed = null }) {
   const parts = [MARKER, '## readfirst', ''];
   if (problems.length) {
     parts.push(`> [!WARNING]\n> \`${MAP_PATH}\` no longer matches the code (${problems.length} problem${problems.length > 1 ? 's' : ''}). Run \`npx readfirst check\` and fix the map in this PR.`, '');
     parts.push(...problems.slice(0, 20).map((p) => `- ${p}`), ...(problems.length > 20 ? [`- …and ${problems.length - 20} more`] : []), '');
     if (fixes.length) parts.push('`npx readfirst fix` would make these changes:', ...fixes.slice(0, 10).map((f) => `- ${f}`), ...(fixes.length > 10 ? [`- …and ${fixes.length - 10} more`] : []), '');
+  } else if (committed) {
+    parts.push(`<details><summary>readfirst placed ${settled.length} new file(s) in the map and committed it to this branch (${committed.slice(0, 7)})</summary>`, '', ...settled.slice(0, 20).map((f) => `- ${f}`), ...(settled.length > 20 ? [`- …and ${settled.length - 20} more`] : []), '', 'Pull before your next push.', '</details>', '');
   } else if (settled.length) {
     parts.push(`<details><summary>New files placed by their neighbours (${settled.length})</summary>`, '', ...settled.slice(0, 20).map((f) => `- ${f}`), ...(settled.length > 20 ? [`- …and ${settled.length - 20} more`] : []), '', '`npx readfirst fix` writes this into the map; nothing to do for this PR.', '</details>', '');
   }
@@ -72,13 +74,16 @@ export async function runAction({ env = process.env, fetchImpl = fetch, root = e
   }
   const repo = env.GITHUB_REPOSITORY;
   const changed = await pages(fetchImpl, env, `/repos/${repo}/pulls/${pr.number}/files`);
+  const committed = (env['INPUT_AUTO-FIX'] ?? env.INPUT_AUTO_FIX ?? 'false') === 'true' && settled.length
+    ? await commitFix({ fetchImpl, env, repo, pr, raw, fixed: map, settled, log })
+    : null;
   const removed = changed.filter((f) => f.status === 'removed').map((f) => f.filename);
   const targets = changed.filter((f) => f.status !== 'removed').map((f) => f.filename);
   // A broken map still gets a comment (the problems), but no read list from it.
   const list = targets.length && !problems.length
     ? readList({ map, files, imports: importEdges(files, readText(root)), targets, commit: pr.head?.sha ?? null, limit: Number(env.INPUT_LIMIT || 30) })
     : null;
-  const body = commentBody({ list, problems, removed, commit: pr.head?.sha ?? null, fixes, settled });
+  const body = commentBody({ list, problems, removed, commit: pr.head?.sha ?? null, fixes, settled, committed });
   summary(body);
 
   if ((env.INPUT_COMMENT ?? 'true') !== 'false') {
@@ -95,7 +100,39 @@ export async function runAction({ env = process.env, fetchImpl = fetch, root = e
     }
   }
   if (problems.length) log(`${MAP_PATH} has ${problems.length} problem(s):\n- ${problems.join('\n- ')}`);
-  return { ok: !(problems.length && failOnProblems), problems, list, body };
+  return { ok: !(problems.length && failOnProblems), problems, list, body, committed };
+}
+
+// auto-fix: write what `readfirst fix` settles (new files placed by their neighbours, patterns for deleted files) into
+// the map on the PR's branch, as one commit through the contents API. Only the mechanical part, never anything a person
+// has to decide; only on a branch of this repository; only when the branch's map is the one this run read, so a push in
+// between is never overwritten. Returns the new commit's sha, or null with a warning.
+async function commitFix({ fetchImpl, env, repo, pr, raw, fixed, settled, log }) {
+  if (pr.head?.repo?.full_name !== repo || !pr.head?.ref) {
+    log('::warning::readfirst auto-fix: this PR comes from a fork, so the map update stays a suggestion in the comment.');
+    return null;
+  }
+  const path = MAP_PATH.split('/').map(encodeURIComponent).join('/');
+  try {
+    const now = await api(fetchImpl, env, 'GET', `/repos/${repo}/contents/${path}?ref=${encodeURIComponent(pr.head.ref)}`);
+    let onBranch = null;
+    try { onBranch = JSON.parse(Buffer.from(now.content ?? '', 'base64').toString('utf8')); } catch { onBranch = null; }
+    if (JSON.stringify(onBranch) !== JSON.stringify(raw)) {
+      log('::warning::readfirst auto-fix: the map on the branch differs from the one this run read (a newer push, or the base changed it); nothing committed.');
+      return null;
+    }
+    const res = await api(fetchImpl, env, 'PUT', `/repos/${repo}/contents/${path}`, {
+      message: `readfirst fix: place ${settled.length} new file(s) in the map`,
+      content: Buffer.from(`${JSON.stringify(fixed, null, 2)}\n`, 'utf8').toString('base64'),
+      sha: now.sha,
+      branch: pr.head.ref,
+    });
+    log(`readfirst auto-fix: committed the map update to ${pr.head.ref}`);
+    return res?.commit?.sha ?? 'committed';
+  } catch (e) {
+    log(`::warning::readfirst auto-fix could not commit (${/: 403 /u.test(e.message) ? 'the token needs contents: write' : e.message.slice(0, 200)}); the comment says what \`npx readfirst fix\` would change.`);
+    return null;
+  }
 }
 
 if (process.argv[1]?.endsWith('/src/action.mjs')) {

package/src/cli.mjs

@@ -1,5 +1,5 @@
 // readfirst: what to read and check before changing a file.
-//   readfirst init [--agent]       write a first .readfirst/map.json from the file tree (and the agent-notes line)
+//   readfirst init [--agent] [--ci] write a first .readfirst/map.json from the file tree (and the agent-notes line, the Action)
 //   readfirst prompt               the brief for a coding agent to fill in titles, checks, risks and rules
 //   readfirst prompt --labels <lang>  the brief for personal labels (a translation and plain notes) for the view
 //   readfirst check                the map covers every tracked file and is well formed
@@ -8,15 +8,16 @@
 //   readfirst diff [--base <ref>]  the read list for the files changed since <ref> (default: origin/main, else main)
 //   readfirst verify [--base <ref>] run the checks the read list names for the changed files; exit 1 if one fails
 //   readfirst hook [--install]     a Claude Code PreToolUse hook: the read list for the file an Edit or Write is about to change
+//                                  (--install --verify also adds a Stop hook, `hook --stop`, that runs verify before Claude Code finishes)
 //   readfirst mcp                  an MCP server on stdio: read_list, changed_read_list and check_map as tools for any agent
 //   readfirst view [--out <file>]  the map as a city in one HTML page (default .readfirst/local/view.html)
 // Options: --root <dir> (default: the current git repository), --json, --limit <n>.
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { basename, isAbsolute, join, relative } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 import { importEdges } from './imports.mjs';
-import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems, settleMap } from './map.mjs';
+import { MAP_PATH, assertMap, draftChecks, draftMap, fixMap, mapProblems, settleMap } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
 import { keepLocal, labelsBrief, LOCAL_DIR, readLabels } from './labels.mjs';
 import { viewData } from './view.mjs';
@@ -26,20 +27,22 @@ import { emptyList, readList, toMarkdown } from './readlist.mjs';
 
 const HELP = `readfirst — what to read and check before changing a file
 
-  readfirst init [--agent]       write a first ${MAP_PATH} from the file tree
+  readfirst init [--agent] [--ci] write a first ${MAP_PATH} from the file tree
   readfirst prompt               brief for your coding agent to fill in the map
   readfirst check [--strict]     check the map covers every tracked file (new files beside placed ones pass; --strict fails on them)
   readfirst fix                  place new files, drop patterns for deleted ones
   readfirst read <file>...       read list for files you are about to change
   readfirst diff [--base <ref>]  read list for files changed since <ref>
   readfirst verify [--base <ref>]  run the checks for the files changed since <ref> (--dry-run lists them)
-  readfirst hook [--install]     Claude Code hook: the read list before each edit (--install adds it to .claude/settings.json)
+  readfirst hook [--install]     Claude Code hook: the read list before each edit (--install adds it to .claude/settings.json;
+                                 --install --verify also runs the checks for edited files before Claude Code finishes)
   readfirst view [--out <file>]  the map as a city in one HTML page
   readfirst mcp                  MCP server on stdio for Cursor, Codex, Windsurf and other agents
   readfirst prompt --labels <lang>  brief for your agent to write personal labels for the view (e.g. ko, en)
 
 Options: --root <dir>, --json, --limit <n>, --timeout <s> (verify, per check; default 900), --force (init: replace the map),
-         --agent (init: add the read-first line to CLAUDE.md / AGENTS.md / .cursorrules)`;
+         --agent (init: add the read-first line to CLAUDE.md / AGENTS.md / .cursorrules),
+         --ci (init: add .github/workflows/readfirst.yml, the Action with auto-fix)`;
 
 function parse(argv) {
   const args = { _: [], json: false };
@@ -51,6 +54,9 @@ function parse(argv) {
     else if (a === '--install') args.install = true;
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--strict') args.strict = true;
+    else if (a === '--verify') args.verify = true;
+    else if (a === '--ci') args.ci = true;
+    else if (a === '--stop') args.stop = true;
     else if (a === '-h' || a === '--help') args.help = true;
     else if (a.startsWith('--')) { const v = argv[++i]; if (v === undefined) throw new Error(`${a} needs a value`); args[a.slice(2)] = v; }
     else args._.push(a);
@@ -164,6 +170,9 @@ export function brief(list) {
   return lines;
 }
 
+// Which files the PreToolUse hook has seen in a session: the Stop hook verifies those.
+const seenFile = (stateDir, session) => join(stateDir, `readfirst-hook-${String(session ?? 'none').replace(/[^\w-]/gu, '')}.json`);
+
 // Claude Code PreToolUse hook. Reads the hook's JSON on stdin; for an Edit, Write or MultiEdit of a file the map covers,
 // prints the read list as additionalContext, once per file per session. Never blocks the edit: any problem means no output.
 export function runHook(input, { now = Date.now(), stateDir = tmpdir() } = {}) {
@@ -175,7 +184,7 @@ export function runHook(input, { now = Date.now(), stateDir = tmpdir() } = {}) {
     const root = git(cwd, 'rev-parse', '--show-toplevel').trim();
     const path = (isAbsolute(file) ? relative(root, file) : file).replace(/\\/gu, '/');
     if (path.startsWith('..') || path === MAP_PATH || !existsSync(join(root, MAP_PATH))) return null;
-    const seenAt = join(stateDir, `readfirst-hook-${String(event.session_id ?? 'none').replace(/[^\w-]/gu, '')}.json`);
+    const seenAt = seenFile(stateDir, event.session_id);
     let seen = {};
     try { seen = JSON.parse(readFileSync(seenAt, 'utf8')); } catch { seen = {}; }
     if (seen[path] && now - seen[path] < 6 * 3600_000) return null;
@@ -195,17 +204,106 @@ export function runHook(input, { now = Date.now(), stateDir = tmpdir() } = {}) {
   }
 }
 
+// The check commands of the map as the base branch has it. The Stop hook runs a command without anyone asking, so it
+// runs only these: a command a branch adds or changes in the map is repository content nobody has merged yet.
+function trustedRuns(root) {
+  try {
+    const { ref } = changedFiles(root);
+    const since = git(root, 'merge-base', ref, 'HEAD').trim();
+    const map = JSON.parse(git(root, 'show', `${since}:${MAP_PATH}`));
+    return new Set([...(map.groups ?? []), ...(map.rules ?? [])].flatMap((x) => (x.checks ?? []).map((c) => c.run)));
+  } catch {
+    return new Set();
+  }
+}
+
+// Claude Code Stop hook (opt-in, `hook --install --verify`): before Claude Code ends its turn, run the map's checks for the
+// files it edited in this session that are still changed. A failing check blocks the stop once, with the failure as the
+// reason, so the agent fixes it; on the second stop of the same turn it lets go, so a check it cannot fix never traps
+// the session. Only commands the base branch's map already lists run; others are named for `readfirst verify`, which
+// someone runs on purpose. Nothing edited, nothing changed or no checks: no output.
+export function runStopHook(input, { stateDir = tmpdir(), timeout = 600 } = {}) {
+  let event;
+  try { event = JSON.parse(input); } catch { return null; }
+  if (event.stop_hook_active) return null;
+  try {
+    const root = git(event.cwd ?? process.cwd(), 'rev-parse', '--show-toplevel').trim();
+    if (!existsSync(join(root, MAP_PATH))) return null;
+    let seen = {};
+    try { seen = JSON.parse(readFileSync(seenFile(stateDir, event.session_id), 'utf8')); } catch { return null; }
+    const dirty = new Set(git(root, 'status', '--porcelain', '-z', '--untracked-files=all').split('\0').filter(Boolean).map((l) => l.slice(3)));
+    let changed = [];
+    try { changed = changedFiles(root).files; } catch { /* no base branch: the working tree is enough */ }
+    const targets = Object.keys(seen).filter((f) => dirty.has(f) || changed.includes(f)).sort();
+    if (!targets.length) return null;
+    const files = repoFiles(root);
+    const map = readMapFile(root);
+    if (mapProblems(map, files, { placement: false }).length) return null;
+    const list = readList({ map, files, imports: importEdges(files, readText(root)), targets, limit: 1 });
+    if (!list.checks.length) return null;
+    const trusted = trustedRuns(root);
+    const skipped = list.checks.filter((c) => !trusted.has(c.run)).map((c) => c.run);
+    const result = verifyChecks(root, list.checks.filter((c) => trusted.has(c.run)), { timeout });
+    const failed = result.filter((c) => c.status !== 'pass');
+    const notRun = skipped.length ? ` Not run, because the base branch's map does not list them yet: ${skipped.map((r) => `\`${r}\``).join(', ')}; run \`npx readfirst verify\` to run them on purpose.` : '';
+    if (!failed.length) return JSON.stringify({ systemMessage: `readfirst verify: ${result.length} check(s) passed for ${targets.length} edited file(s).${notRun}` });
+    const reason = [
+      `readfirst verify: ${failed.length} of ${result.length} check(s) the map lists for the files you edited failed. Fix them before you finish.${notRun}`,
+      ...failed.map((c) => `\n--- ${c.run} (${c.status}${c.code != null ? `, exit ${c.code}` : ''})${c.why ? ` covers ${c.why}` : ''}; last lines:\n${c.output ?? ''}`),
+    ].join('\n');
+    return JSON.stringify({ decision: 'block', reason });
+  } catch {
+    return null;
+  }
+}
+
+export const WORKFLOW_PATH = '.github/workflows/readfirst.yml';
+// The Action as `init --ci` writes it: on each PR, the read-list comment, and new files placed in the map on the PR's
+// branch (auto-fix). Never over a workflow that is already there.
+export function writeWorkflow(root) {
+  const at = join(root, WORKFLOW_PATH);
+  if (existsSync(at)) return false;
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, [
+    '# readfirst: one comment per PR with the rules, risks and checks for the files it changes,',
+    '# and new files placed in .readfirst/map.json on the PR branch (auto-fix). https://github.com/jeonghun917/readfirst',
+    'name: readfirst',
+    'on: pull_request',
+    'permissions:',
+    '  contents: write       # auto-fix commits the map update to the PR branch',
+    '  pull-requests: write  # the comment',
+    'jobs:',
+    '  readfirst:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0',
+    '      - uses: jeonghun917/readfirst@v0',
+    '        with:',
+    '          auto-fix: true',
+    '',
+  ].join('\n'));
+  return true;
+}
+
 export const HOOK_COMMAND = 'npx --yes readfirst hook';
-// Adds the hook to the project's .claude/settings.json, keeping everything already there.
-export function installHook(root) {
+export const STOP_HOOK_COMMAND = 'npx --yes readfirst hook --stop';
+// Adds the hook to the project's .claude/settings.json, keeping everything already there. With verify, also the Stop
+// hook that runs the checks before Claude Code finishes.
+export function installHook(root, { verify = false } = {}) {
   const at = join(root, '.claude', 'settings.json');
   let settings = {};
   if (existsSync(at)) {
     try { settings = JSON.parse(readFileSync(at, 'utf8')); } catch { throw new Error('.claude/settings.json is not valid JSON; fix it first'); }
   }
   const pre = ((settings.hooks ??= {}).PreToolUse ??= []);
-  if (pre.some((m) => (m.hooks ?? []).some((h) => /readfirst hook/u.test(h.command ?? '')))) return false;
-  pre.push({ matcher: 'Edit|Write|MultiEdit', hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 15 }] });
+  const has = (list) => list.some((m) => (m.hooks ?? []).some((h) => /readfirst hook/u.test(h.command ?? '')));
+  let added = false;
+  if (!has(pre)) { pre.push({ matcher: 'Edit|Write|MultiEdit', hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 15 }] }); added = true; }
+  if (verify) {
+    const stop = (settings.hooks.Stop ??= []);
+    if (!has(stop)) { stop.push({ hooks: [{ type: 'command', command: STOP_HOOK_COMMAND, timeout: 1800 }] }); added = true; }
+  }
+  if (!added) return false;
   mkdirSync(join(root, '.claude'), { recursive: true });
   writeFileSync(at, `${JSON.stringify(settings, null, 2)}\n`);
   return true;
@@ -216,7 +314,7 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
   const [cmd, ...rest] = args._;
   if (args.help || !cmd) { io.out(`${HELP}\n`); return cmd || args.help ? 0 : 2; }
   if (cmd === 'hook' && !args.install) {
-    const out = runHook(stdin());
+    const out = args.stop ? runStopHook(stdin()) : runHook(stdin());
     if (out) io.out(`${out}\n`);
     return 0;
   }
@@ -247,14 +345,21 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     const map = draftMap(files, readText(root));
     mkdirSync(join(root, '.readfirst'), { recursive: true });
     writeFileSync(at, `${JSON.stringify(map, null, 2)}\n`);
-    const checks = map.groups.find((g) => g.checks.length)?.checks ?? [];
-    io.out(`wrote ${MAP_PATH}: ${map.groups.length} group${map.groups.length === 1 ? "" : "s"}${checks.length ? `, checks found: ${checks.map((c) => c.run).join(', ')}` : ''}.\n`);
+    const repoChecks = draftChecks(files, readText(root)).map((c) => c.run);
+    const scoped = map.groups.filter((g) => g.checks.length && g.checks.some((c) => !repoChecks.includes(c.run))).length;
+    io.out(`wrote ${MAP_PATH}: ${map.groups.length} group${map.groups.length === 1 ? '' : 's'}${repoChecks.length ? `, checks found: ${repoChecks.join(', ')}` : ''}${scoped ? `; ${scoped} workspace package${scoped === 1 ? '' : 's'} got ${scoped === 1 ? 'its' : 'their'} own checks` : ''}.\n`);
     if (args.agent) {
       const wrote = addAgentLine(root);
       io.out(wrote.length ? `added the read-first line to ${wrote.join(', ')}.\n` : 'your agent notes already mention readfirst.\n');
-      io.out('Using Claude Code? `readfirst hook --install` hands it the read list automatically before each edit.\n');
     }
-    io.out(`Next: run \`readfirst prompt\` and give the brief to your coding agent, or fill in titles, checks, risks and rules by hand.${args.agent ? '' : '\nTip: `readfirst init --agent` also adds the one line your coding agent needs to CLAUDE.md or AGENTS.md.'}\n`);
+    if (args.ci) io.out(writeWorkflow(root) ? `wrote ${WORKFLOW_PATH}: a PR comment with the read list, and new files placed in the map on the PR branch.\n` : `${WORKFLOW_PATH} already exists; left as it is.\n`);
+    const next = [
+      'run `readfirst prompt` and give the brief to your coding agent (or fill in titles, risks and rules by hand)',
+      ...(args.agent ? [] : ['`readfirst init --agent` would add the one line your agent needs to CLAUDE.md or AGENTS.md']),
+      'Claude Code: `readfirst hook --install` gives it the read list before each edit (`--verify` also runs the checks before it finishes)',
+      ...(args.ci ? [] : ['`readfirst init --ci` would add the GitHub Action that comments on PRs and keeps the map in step']),
+    ];
+    io.out(`Next:\n${next.map((n) => `- ${n}`).join('\n')}\n`);
     return 0;
   }
   if (cmd === 'prompt') {
@@ -294,7 +399,9 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     return problems.length ? 1 : 0;
   }
   if (cmd === 'hook') {
-    io.out(installHook(root) ? 'added the readfirst hook to .claude/settings.json: Claude Code now sees the read list before each edit.\n' : '.claude/settings.json already has the readfirst hook.\n');
+    io.out(installHook(root, { verify: args.verify })
+      ? `added the readfirst hook to .claude/settings.json: Claude Code now sees the read list before each edit${args.verify ? ', and cannot finish while a check for a file it edited fails (it gets one try to fix it)' : ''}.\n`
+      : '.claude/settings.json already has the readfirst hook.\n');
     return 0;
   }
   if (cmd === 'fix') {

package/src/imports.mjs

@@ -1,7 +1,8 @@
-// Which tracked file imports which, read from the code. Only imports that resolve to a tracked file count: packages and
-// unresolved specifiers are left out. JavaScript/TypeScript (import, export from, import(), require) and Python
-// (import a.b, from a.b import c, relative from . imports) are read here; Go, Rust, Elixir, C#, Java/Kotlin, Ruby and
-// PHP in langs.mjs.
+// Which tracked file imports which, read from the code. Only imports that resolve to a tracked file count: packages from
+// outside the repository and unresolved specifiers are left out. JavaScript/TypeScript (import, export from, import(),
+// require; relative paths, the repository's own workspace packages and tsconfig/jsconfig "paths" aliases) and Python
+// (import a.b, from a.b import c, relative from . imports, and "a.b.c" strings that name a module of the repository,
+// as hooks and settings do) are read here; Go, Rust, Elixir, C#, Java/Kotlin, Ruby and PHP in langs.mjs.
 import { posix } from 'node:path';
 import { moreEdges } from './langs.mjs';
 
@@ -13,6 +14,87 @@ const PY_IMPORT = /^[ \t]*(?:from[ \t]+(\.*[\w.]*)[ \t]+import[ \t]+(\([^)]*\)|[
 const JS_EXT = ['', '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.mts', '.vue', '.svelte', '/index.js', '/index.ts', '/index.tsx', '/index.mjs'];
 
 const lineAt = (body, index) => body.slice(0, index).split('\n').length;
+const dirOf = (f) => (posix.dirname(f) === '.' ? '' : posix.dirname(f));
+const within = (dir, file) => dir === '' || file.startsWith(`${dir}/`);
+
+// tsconfig.json allows comments and trailing commas.
+export function parseJsonc(text) {
+  if (text === null || text === undefined) return null;
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"') {
+      const end = text.slice(i).match(/^"(?:[^"\\\n]|\\.)*"/u);
+      if (!end) return null;
+      out += end[0]; i += end[0].length - 1;
+    } else if (c === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      out += '\n';
+    } else if (c === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      if (close < 0) return null;
+      i = close + 1;
+    } else out += c;
+  }
+  try { return JSON.parse(out.replace(/,(\s*[}\]])/gu, '$1')); } catch { return null; }
+}
+
+// Bare specifiers that point back into the repository: a workspace package by the name in its package.json
+// ("@acme/db", "@acme/db/schema"), or a "paths" alias from the tsconfig/jsconfig that covers the importing file ("@/lib/x").
+function jsResolver(files, tracked, read) {
+  const jsCandidates = (base) => [...JS_EXT.map((e) => base + e), base.replace(/\.(m|c)?js$/u, '.$1ts'), base.replace(/\.js$/u, '.tsx')];
+  const firstTracked = (bases) => {
+    for (const b of bases) {
+      const hit = jsCandidates(posix.normalize(b)).find((c) => tracked.has(c));
+      if (hit) return hit;
+    }
+    return undefined;
+  };
+  const pkgs = [];
+  for (const f of files) {
+    if (!/(?:^|\/)package\.json$/u.test(f) || f.includes('node_modules/')) continue;
+    let j;
+    try { j = JSON.parse(read(f) ?? ''); } catch { continue; }
+    if (typeof j?.name !== 'string' || !j.name || dirOf(f) === '') continue;
+    const dot = typeof j.exports === 'string' ? j.exports : j.exports?.['.'];
+    const exp = typeof dot === 'string' ? [dot] : dot && typeof dot === 'object' ? ['types', 'import', 'default', 'require'].map((k) => dot[k]).filter((v) => typeof v === 'string') : [];
+    // An entry pointing at build output (dist/index.js) is read as the source next to it (src/index.ts).
+    const entries = [j.source, ...exp, j.types, j.typings, j.module, j.main].filter((v) => typeof v === 'string')
+      .flatMap((e) => [e, e.replace(/^\.?\/?(?:dist|build|lib|out)\//u, 'src/').replace(/\.d\.ts$/u, '.ts')]);
+    pkgs.push({ name: j.name, dir: dirOf(f), entries: [...entries, 'src/index', 'index'] });
+  }
+  pkgs.sort((a, b) => b.name.length - a.name.length);
+  const aliases = [];
+  for (const f of files) {
+    if (!/(?:^|\/)(?:tsconfig|jsconfig)(?:\.[\w-]+)?\.json$/u.test(f) || f.includes('node_modules/')) continue;
+    const opts = parseJsonc(read(f))?.compilerOptions;
+    if (!opts?.paths || typeof opts.paths !== 'object') continue;
+    const base = posix.join(dirOf(f), opts.baseUrl ?? '.');
+    for (const [pattern, targets] of Object.entries(opts.paths)) {
+      if (Array.isArray(targets)) aliases.push({ scope: dirOf(f), pattern, targets: targets.filter((t) => typeof t === 'string').map((t) => posix.join(base, t)) });
+    }
+  }
+  // The nearest config wins, as it would for the compiler.
+  aliases.sort((a, b) => b.scope.length - a.scope.length);
+  return (from, spec) => {
+    for (const a of aliases) {
+      if (!within(a.scope, from)) continue;
+      const star = a.pattern.indexOf('*');
+      let rest = null;
+      if (star < 0) rest = spec === a.pattern ? '' : null;
+      else if (spec.startsWith(a.pattern.slice(0, star)) && spec.endsWith(a.pattern.slice(star + 1))) rest = spec.slice(star, spec.length - (a.pattern.length - star - 1));
+      if (rest === null) continue;
+      const hit = firstTracked(a.targets.map((t) => t.replace('*', rest)));
+      if (hit) return hit;
+    }
+    const pkg = pkgs.find((p) => spec === p.name || spec.startsWith(`${p.name}/`));
+    if (!pkg) return undefined;
+    const sub = spec.slice(pkg.name.length + 1);
+    return sub
+      ? firstTracked([posix.join(pkg.dir, sub), posix.join(pkg.dir, 'src', sub)])
+      : firstTracked(pkg.entries.map((e) => posix.join(pkg.dir, e.replace(/\.(?:m|c)?js$|\.tsx?$/u, ''))));
+  };
+}
 
 export function importEdges(files, read) {
   const tracked = new Set(files);
@@ -27,13 +109,19 @@ export function importEdges(files, read) {
     const base = posix.join(baseDir, ...dotted.split('.').filter(Boolean));
     return [`${base}.py`, `${base}/__init__.py`].find((c) => tracked.has(c));
   };
+  let bare = null;
   for (const from of [...files].sort()) {
     if (JS.test(from)) {
       const body = read(from);
       if (body === null) continue;
       for (const m of body.matchAll(JS_IMPORT)) {
         const spec = (m[1] ?? m[2] ?? m[3]).split('?')[0];
-        if (!spec.startsWith('.')) continue;
+        if (!spec.startsWith('.')) {
+          if (spec.startsWith('node:') || /^[a-z]+:/u.test(spec)) continue;
+          bare ??= jsResolver(files, tracked, read);
+          add(from, bare(from, spec), lineAt(body, m.index));
+          continue;
+        }
         const base = posix.normalize(posix.join(posix.dirname(from), spec));
         // TypeScript sources import "./x.js" for the file "./x.ts".
         const candidates = [...JS_EXT.map((e) => base + e), base.replace(/\.(m|c)?js$/u, '.$1ts'), base.replace(/\.js$/u, '.tsx')];
@@ -64,6 +152,33 @@ export function importEdges(files, read) {
       }
     }
   }
+  dottedEdges(files, tracked, read, pyModule, add);
   moreEdges([...files].sort(), read, add);
   return out;
 }
+
+// Python projects name code by dotted path in strings: Frappe hooks.py ("app.module.function"), frappe.call from
+// JavaScript, Django settings and urls, Celery task names. A string counts when its first part is a top-level Python
+// package of the repository and the longest leading part names one of its modules.
+function dottedEdges(files, tracked, read, pyModule, add) {
+  const top = new Map();
+  for (const f of files) {
+    const m = f.match(/^(?:(src)\/)?([A-Za-z_]\w*)\/__init__\.py$/u);
+    if (m) top.set(m[2], m[1] ?? '');
+  }
+  if (!top.size) return;
+  const DOTTED = /["'`]([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)+)["'`]/gu;
+  for (const from of files) {
+    if (!/\.(?:py|m?js|tsx?|json)$/u.test(from) || from.includes('node_modules/')) continue;
+    const body = read(from);
+    if (body === null || body.length > 2_000_000) continue;
+    for (const m of body.matchAll(DOTTED)) {
+      const parts = m[1].split('.');
+      if (!top.has(parts[0])) continue;
+      for (let n = parts.length; n >= 2; n--) {
+        const to = pyModule(parts.slice(0, n).join('.'), top.get(parts[0]));
+        if (to) { add(from, to, lineAt(body, m.index)); break; }
+      }
+    }
+  }
+}

package/src/map.mjs

@@ -160,9 +160,44 @@ export function draftMap(files, read = () => null) {
     const hasNested = [...byFolder.values()].some((slot) => slot.pattern?.startsWith(`${root}/`) && slot.pattern !== `${root}/**`);
     if (covered && hasNested) covered.files = covered.files.filter((p) => p !== `${root}/**`).concat(loose);
   }
+  // A folder that is a workspace package of its own (packages/db/package.json) gets that package's checks, run through the
+  // package manager's workspace filter, so verify runs the package's tests instead of the whole repository's. Its title
+  // comes from the package's description when it has one.
+  for (const g of groups.values()) {
+    const dir = g.files.length === 1 && /^(.+)\/\*\*$/u.exec(g.files[0])?.[1];
+    if (!dir || !files.includes(`${dir}/package.json`)) continue;
+    let pkg;
+    try { pkg = JSON.parse(read(`${dir}/package.json`) ?? ''); } catch { continue; }
+    const checks = workspaceChecks(files, dir, pkg);
+    if (checks.length) g.checks = checks;
+    const about = typeof pkg?.description === 'string' ? pkg.description.trim().replace(/\s+/gu, ' ') : '';
+    if (about && g.title.startsWith('TODO:')) g.title = `${typeof pkg.name === 'string' ? `${pkg.name}: ` : ''}${about}`.slice(0, 200);
+  }
   return { format: MAP_FORMAT, groups: [...groups.values()].sort((a, b) => a.id.localeCompare(b.id)), rules: [], ignore: [...ignore].sort() };
 }
 
+const packageManager = (has) => (has.has('pnpm-lock.yaml') ? 'pnpm' : has.has('yarn.lock') ? 'yarn' : has.has('bun.lockb') || has.has('bun.lock') ? 'bun' : 'npm');
+const PLACEHOLDER = /no test specified/u;
+// The scripts worth running as checks, in order, with what each covers.
+const scriptChecks = (scripts, run) => [
+  ...(typeof scripts.test === 'string' && !PLACEHOLDER.test(scripts.test) ? [{ run: run('test'), why: 'the test suite' }] : []),
+  ...['typecheck', 'type-check', 'check-types', 'lint'].filter((n) => typeof scripts[n] === 'string').map((n) => ({ run: run(n), why: n === 'lint' ? 'lint rules' : 'types' })),
+];
+
+// One workspace package's own scripts, scoped to it: pnpm --filter, yarn workspace, bun --filter or npm -w.
+export function workspaceChecks(files, dir, pkg) {
+  const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  const name = typeof pkg?.name === 'string' && pkg.name ? pkg.name : null;
+  const pm = packageManager(new Set(files));
+  const run = (script) => {
+    if (pm === 'pnpm') return `pnpm --filter ${name ?? `./${dir}`} ${script === 'test' ? 'test' : `run ${script}`}`;
+    if (pm === 'yarn' && name) return `yarn workspace ${name} ${script === 'test' ? 'test' : `run ${script}`}`;
+    if (pm === 'bun' && name) return `bun --filter ${name} run ${script}`;
+    return script === 'test' ? `npm test -w ${dir}` : `npm run ${script} -w ${dir}`;
+  };
+  return scriptChecks(scripts, run).map((c) => ({ ...c, why: `${c.why} of ${name ?? dir}` }));
+}
+
 // Repairs the two ways a good map goes stale as code moves, without guessing at meaning:
 // - a tracked file in no group joins the group of its nearest neighbour (same folder, else the closest parent folder);
 //   a new folder whose files are all unplaced joins as "<folder>/**", a lone new file by its path;
@@ -244,11 +279,9 @@ export function draftChecks(files, read = () => null) {
   if (has.has('package.json')) {
     let scripts = {};
     try { scripts = JSON.parse(read('package.json') ?? '{}').scripts ?? {}; } catch { scripts = {}; }
-    const pm = has.has('pnpm-lock.yaml') ? 'pnpm' : has.has('yarn.lock') ? 'yarn' : has.has('bun.lockb') || has.has('bun.lock') ? 'bun' : 'npm';
+    const pm = packageManager(has);
     const run = (name) => (pm === 'npm' ? (name === 'test' ? 'npm test' : `npm run ${name}`) : `${pm} ${name === 'test' && pm !== 'bun' ? 'test' : `run ${name}`}`);
-    const placeholder = /no test specified/u;
-    if (typeof scripts.test === 'string' && !placeholder.test(scripts.test)) add(run('test'), 'the test suite');
-    for (const name of ['typecheck', 'type-check', 'check-types', 'lint']) if (typeof scripts[name] === 'string') add(run(name), name === 'lint' ? 'lint rules' : 'types');
+    for (const c of scriptChecks(scripts, run)) add(c.run, c.why);
   }
   const makefile = has.has('Makefile') ? read('Makefile') ?? '' : '';
   if (/^test:/mu.test(makefile)) add('make test', 'the test suite (Makefile)');