archstrict 0.0.0 → 0.2.0

package/.agents/hooks/hooks.json

@@ -0,0 +1,29 @@
+{
+  "description": "archstrict - runs simulate before a file edit and check right after, returning any violation into the agent's own context",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v node >/dev/null 2>&1 && exec node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use.mjs\" || exit 0",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v node >/dev/null 2>&1 && exec node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use.mjs\" || exit 0",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/.agents/hooks/post-tool-use.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// Responsibility: the PostToolUse hook. Runs the edited project's own
+// installed `archstrict check <file>` right after Edit/Write/MultiEdit and
+// feeds any violation back into the agent's context via
+// hookSpecificOutput.additionalContext - the same moment a human editor's
+// red squiggly would appear, per code.claude.com/docs/en/hooks.
+// Boundary: no rule logic here - this only shells out to the project's own
+// `archstrict` binary and reshapes its JSON. It never runs this
+// repository's own dist/cli.js: the hook ships to OTHER projects, each
+// with its own installed archstrict and its own archstrict.config.ts.
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+function readStdin() {
+  return JSON.parse(readFileSync(0, "utf8"));
+}
+
+// Every path writes exactly one line of JSON to stdout and exits 0 - a
+// hook that fails loudly would block the edit it's only meant to comment
+// on. `additionalContext` omitted (not merely empty) when there is
+// nothing to say: an empty string is still a context entry Claude reads.
+function emit(additionalContext) {
+  const output =
+    additionalContext === undefined
+      ? {}
+      : { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext } };
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+function main() {
+  let input;
+  try {
+    input = readStdin();
+  } catch {
+    emit();
+    return;
+  }
+
+  const editTools = new Set(["Edit", "Write", "MultiEdit"]);
+  if (!editTools.has(input.tool_name)) {
+    emit();
+    return;
+  }
+
+  const filePath = input.tool_input?.file_path;
+  if (typeof filePath !== "string" || !/\.(ts|tsx|mts|cts)$/.test(filePath)) {
+    emit();
+    return;
+  }
+
+  // The edited project's own cwd, not this plugin's own install
+  // location: check <file> resolves archstrict.config.ts from cwd, and a
+  // project checked with this hook is never this repository itself.
+  const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
+  const binPath = join(cwd, "node_modules", ".bin", "archstrict");
+  if (!existsSync(binPath)) {
+    // Not an error: most edits happen in files or projects with no
+    // archstrict installed at all. Said once, not raised as a failure -
+    // the hook's job is to add context when there is real feedback to
+    // add, not to insist a project adopt this tool.
+    emit();
+    return;
+  }
+
+  let stdout;
+  try {
+    stdout = execFileSync(binPath, ["check", filePath, "--json"], { cwd, encoding: "utf8" });
+  } catch (error) {
+    // check exits 1 exactly when violations exist (module-graph.ts's own
+    // documented contract) - that is real data on stderr's sibling
+    // stdout, not a hook failure. Only a stdout-less failure (the binary
+    // itself couldn't run) is reported as broken.
+    const execError = /** @type {{ stdout?: unknown; message: string }} */ (error);
+    if (typeof execError.stdout !== "string" || execError.stdout.length === 0) {
+      emit(`archstrict: check did not run (${execError.message}).`);
+      return;
+    }
+    stdout = execError.stdout;
+  }
+
+  const result = JSON.parse(stdout);
+  // A config or missing-file error (a required field absent, an
+  // unsupported edges shape) reports as { error, do } instead of a
+  // real CheckResult, exit 1, no stdout-less failure - so the branch
+  // above never catches it. Surfaced, not silently ignored: the project
+  // has archstrict installed but something about its own setup is broken,
+  // which the agent editing it needs to know, the same as a real
+  // violation would. `do` is the command to run; older binaries that
+  // omit it still surface the error text.
+  if (typeof result.error === "string") {
+    const doText = typeof result.do === "string" && result.do.length > 0 ? `\ndo: ${result.do}` : "";
+    emit(`archstrict: check did not run (${result.error}).${doText}`);
+    return;
+  }
+  if (result.violations.length === 0) {
+    emit();
+    return;
+  }
+
+  const lines = result.violations.map(
+    (v) => `[${v.rule}] ${v.path}:${v.line}:${v.column}\n  ${v.evidence}\n  because: ${v.because}\n  do: ${v.do}`,
+  );
+  emit(`archstrict found ${result.violations.length} violation(s) in ${filePath}:\n${lines.join("\n")}`);
+}
+
+main();

package/.agents/hooks/pre-tool-use.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// Responsibility: the PreToolUse hook. Before an Edit/Write/MultiEdit
+// actually touches disk, this builds the file text the tool call would
+// produce and runs the edited project's own installed
+// `archstrict simulate --json` against that one change, so the agent
+// hears about a new violation before the write happens instead of after
+// (the PostToolUse hook's own moment). Per code.claude.com/docs/en/hooks,
+// PreToolUse returns its decision inside hookSpecificOutput:
+// permissionDecision ("allow"/"deny"/"ask"/"defer") plus
+// permissionDecisionReason, or additionalContext alongside "allow".
+// Boundary: no rule logic here - this only shells out to the project's own
+// `archstrict` binary and reshapes its JSON, mirroring post-tool-use.mjs.
+// It never runs this repository's own dist/cli.js: the hook ships to OTHER
+// projects, each with its own installed archstrict.
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+// 10s covers simulate's own measured cost (about twice `check <file>`,
+// which reads the edge cache) on a real project; configurable because a
+// large monorepo's cold run can exceed it. A hook that stalls the tool
+// call for longer than the agent's patience defeats its own purpose.
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_SHOWN_VIOLATIONS = 5;
+
+function readStdin() {
+  return JSON.parse(readFileSync(0, "utf8"));
+}
+
+function emit(decision) {
+  const output =
+    decision === undefined
+      ? {}
+      : { hookSpecificOutput: { hookEventName: "PreToolUse", ...decision } };
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+// Applies one old_string -> new_string replacement the same way Edit and
+// MultiEdit do. Returns undefined (not a thrown error) when old_string
+// isn't found: the caller stays silent rather than guessing at the tool's
+// own error text, since the tool itself will report that failure.
+function applyReplacement(text, oldString, newString, replaceAll) {
+  if (typeof oldString !== "string" || typeof newString !== "string") return undefined;
+  if (!text.includes(oldString)) return undefined;
+  return replaceAll ? text.split(oldString).join(newString) : text.replace(oldString, newString);
+}
+
+// Builds the file text the tool call would produce, without writing
+// anything. Returns undefined when the input can't be built (a missing
+// old_string, a file that doesn't exist yet for Edit/MultiEdit, or a
+// malformed tool_input) - every such case stays silent per design, since
+// the tool call itself will surface its own failure.
+function proposedContent(toolName, toolInput, filePath) {
+  if (toolName === "Write") {
+    return typeof toolInput.content === "string" ? toolInput.content : undefined;
+  }
+  if (!existsSync(filePath)) return undefined;
+  const current = readFileSync(filePath, "utf8");
+  if (toolName === "Edit") {
+    return applyReplacement(current, toolInput.old_string, toolInput.new_string, toolInput.replace_all === true);
+  }
+  if (toolName === "MultiEdit") {
+    if (!Array.isArray(toolInput.edits)) return undefined;
+    let text = current;
+    for (const edit of toolInput.edits) {
+      const next = applyReplacement(text, edit?.old_string, edit?.new_string, edit?.replace_all === true);
+      if (next === undefined) return undefined;
+      text = next;
+    }
+    return text;
+  }
+  return undefined;
+}
+
+// Matches check.ts's own formatConfigPointerLines (`config-pointer.ts`'s
+// ConfigPointers shape) - duplicated here, not imported, because this hook
+// ships to other projects and only shells out to their installed
+// archstrict; it never depends on this repository's own src.
+function formatConfigPointerLines(config) {
+  const pointers = Array.isArray(config) ? config : [config];
+  return pointers.map(p => `  config: ${p.path}:${p.line}:${p.column} ${p.pointer} (${p.role})`);
+}
+
+function formatViolation(v) {
+  return [
+    `[${v.rule}] ${v.path}:${v.line}:${v.column}`,
+    `  ${v.evidence}`,
+    `  because: ${v.because}`,
+    ...formatConfigPointerLines(v.config),
+    `  do: ${v.do}`,
+  ].join("\n");
+}
+
+function formatAdded(added, filePath) {
+  const shown = added.slice(0, MAX_SHOWN_VIOLATIONS).map(formatViolation);
+  const rest = added.length - shown.length;
+  const restLine = rest > 0 ? `\n...and ${rest} more.` : "";
+  return `archstrict: this edit would add ${added.length} violation(s) in ${filePath}:\n${shown.join("\n")}${restLine}`;
+}
+
+function main() {
+  let input;
+  try {
+    input = readStdin();
+  } catch {
+    emit();
+    return;
+  }
+
+  const editTools = new Set(["Edit", "Write", "MultiEdit"]);
+  if (!editTools.has(input.tool_name)) {
+    emit();
+    return;
+  }
+
+  const toolInput = input.tool_input;
+  const filePath = toolInput?.file_path;
+  if (typeof filePath !== "string" || !/\.(ts|tsx|mts|cts)$/.test(filePath)) {
+    emit();
+    return;
+  }
+
+  const content = proposedContent(input.tool_name, toolInput, filePath);
+  if (content === undefined) {
+    emit();
+    return;
+  }
+
+  // The edited project's own cwd, matching the PostToolUse hook's own
+  // resolution: never this plugin's own install location.
+  const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
+  const binPath = join(cwd, "node_modules", ".bin", "archstrict");
+  if (!existsSync(binPath)) {
+    emit();
+    return;
+  }
+
+  const timeoutMs = Number(process.env.ARCHSTRICT_PRETOOLUSE_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+  const stdinBody = JSON.stringify({ changes: [{ path: filePath, content }] });
+
+  let stdout;
+  try {
+    stdout = execFileSync(binPath, ["simulate", "--json"], { cwd, encoding: "utf8", input: stdinBody, timeout: timeoutMs });
+  } catch (error) {
+    // simulate exits 1 both when `added` is nonempty (real data, read from
+    // stdout below) and on an input/config error ({ error, do } json) - a
+    // timeout or a crash leaves no stdout at all. Unlike the PostToolUse
+    // hook, a config error here stays silent rather than being reported:
+    // this hook runs before every edit, so a broken project config would
+    // otherwise interrupt every tool call instead of the one edit that
+    // actually caused it.
+    const execError = error;
+    if (typeof execError.stdout !== "string" || execError.stdout.length === 0) {
+      emit();
+      return;
+    }
+    stdout = execError.stdout;
+  }
+
+  let result;
+  try {
+    result = JSON.parse(stdout);
+  } catch {
+    emit();
+    return;
+  }
+  if (typeof result.error === "string" || !Array.isArray(result.added) || result.added.length === 0) {
+    emit();
+    return;
+  }
+
+  const resolvedLine = result.resolved?.length > 0 ? `\narchstrict: this edit would also resolve ${result.resolved.length} violation(s).` : "";
+  const text = `${formatAdded(result.added, filePath)}${resolvedLine}`;
+
+  if (process.env.ARCHSTRICT_PRETOOLUSE === "deny") {
+    emit({ permissionDecision: "deny", permissionDecisionReason: text });
+    return;
+  }
+  emit({ permissionDecision: "allow", additionalContext: text });
+}
+
+main();

package/.agents/mcp/server.mjs

@@ -0,0 +1,71 @@
+// Responsibility: connect the consumer's installed server or an empty MCP fallback.
+// Boundary: Node built-ins only; the installed package owns architecture queries.
+// Plugin distribution supplies files without its own npm installation, so npm packages
+// such as the SDK may not resolve here. Use built-ins until delegation reaches
+// the consuming project's installed archstrict package, where its SDK dependency resolves.
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
+
+// Match LATEST_PROTOCOL_VERSION in the pinned SDK 1.30.0. This dependency-free
+// wrapper cannot import the SDK to compute the value dynamically.
+const PROTOCOL_VERSION = "2025-11-25";
+
+// Observations across many live Claude Code MCP processes consistently found both cwd
+// and CLAUDE_PROJECT_DIR set to the session's project root. Prefer the explicit
+// environment signal over a potentially inherited cwd; retain cwd as the fallback.
+const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const require = createRequire(join(root, "package.json"));
+let mcpServerPath;
+// createRequire anchors Node's synchronous resolution to the consumer. Its clean failure
+// detects absence while respecting node_modules layouts, symlinks, and workspaces.
+// An existsSync check on a guessed path would not follow those resolution rules.
+try { mcpServerPath = require.resolve("archstrict/dist/mcp-server.js"); }
+catch { mcpServerPath = undefined; }
+
+let imported;
+if (mcpServerPath !== undefined) {
+  // Import in this process to avoid a second Node process for each session.
+  // A child server would need a full MCP client proxy here to inspect its tools
+  // and provide a clean empty fallback. Import failures can reach that fallback directly.
+  try { imported = await import(pathToFileURL(mcpServerPath).href); }
+  catch { imported = undefined; }
+}
+// Older installations can resolve and import successfully yet export only createArchstrictMcpServer.
+// Those successes do not establish this newer entry point. Check its shape before
+// an unconditional call to a missing function would throw a TypeError.
+if (typeof imported?.startArchstrictMcpServer === "function") {
+  await imported.startArchstrictMcpServer(root);
+// Missing, broken, and incompatible installations all lack usable architecture queries.
+// One stub gives clients the same connected, empty result for all three states;
+// separate fallbacks would falsely suggest different degrees of usable connection.
+} else {
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", chunk => {
+    buffer += chunk;
+    let end;
+    while ((end = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, end);
+      buffer = buffer.slice(end + 1);
+      let message;
+      try { message = JSON.parse(line); } catch { continue; }
+      // JSON-RPC and MCP notifications have no id and must receive no response.
+      // A reply would be an unsolicited message that violates the client's protocol expectations.
+      if (message === null || typeof message !== "object" || !Object.hasOwn(message, "id")) continue;
+      const { id, method } = message;
+      let result;
+      switch (method) {
+        case "initialize":
+          result = { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: "archstrict", version: "0.0.0" } };
+          break;
+        case "tools/list": result = { tools: [] }; break;
+        case "ping": result = {}; break;
+        default:
+          process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found" } }) + "\n");
+          continue;
+      }
+      process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+    }
+  });
+}

package/.agents/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "archstrict",
+  "version": "0.0.0",
+  "description": "TypeScript module boundary checking, in the sense of ArchUnit and archspec. A PostToolUse hook runs check right after a file edit and returns violations into the agent's own context, the same moment a human editor's red squiggly would.",
+  "author": {
+    "name": "meganemura"
+  },
+  "homepage": "https://github.com/meganemura/archstrict",
+  "repository": "https://github.com/meganemura/archstrict",
+  "license": "MIT",
+  "mcpServers": {
+    "archstrict": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs"]
+    }
+  },
+  "hooks": ["./hooks/hooks.json"],
+  "keywords": ["claude-code", "claude-code-plugin", "typescript", "architecture", "module-boundaries", "linting"]
+}

package/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md
+
+Context for agents that work in this repository.
+
+## What this is
+
+archstrict checks TypeScript module boundaries.
+It is not tsc, not ESLint, and not a type checker; it is architecture linting, in the sense of ArchUnit (Java) and archspec (Ruby).
+It is designed for a reader that starts from an empty context: a coding agent first, a human second.
+
+The shape, in one paragraph.
+A module is one directory, declared explicitly in config (`declaredModules`) rather than discovered by convention - a barrel `index.ts` is not evidence of an enforced boundary. A glob that names a single file is a module too: `surface` resolves against that file's parent.
+A module shows the rest of the codebase one file, named by the config's own `surface` field (default one entry per analyzed source extension: `index.ts`, `index.tsx`, `index.mts`, `index.cts`); anything a module does not export from that file is private, and an import that reaches past it into the module's internals is a violation.
+A module with no public-surface file present is entirely private: every external import into it is a violation.
+A module's surface file can also leak an internal type it never exported by name - a property, a return type, or a generic constraint that structurally reaches past the surface - which is its own violation, distinct from an import bypassing the surface from outside.
+A file can also carry tags (`classify`/`classifyByDirectoryName`, glob or ambient directory-name -> tag) independent of module membership, and a constraint engine (`edges`: `allowDeny`, `order`, `point`) checks edges between tags - the same domain/layer/plane shapes tools like dependency-cruiser and Nx's `depConstraints` express, generalized over tags instead of a fixed vocabulary.
+Shape (scope, exclude, classify, declaredModules, edges, the surface file name) lives in one root file, `archstrict.config.ts`, written as a plain TypeScript value; it is never scattered per module.
+A known cycle can be named as an exception (`ignoredCycles`), and a directory a project decided must hold no code at all can be declared with `mustBeEmpty` - see [skills/archstrict/references/rules.md](skills/archstrict/references/rules.md) for both.
+Known violations freeze into one project-root todo file, `archstrict.todo.json`, grouped by module name, that can only shrink; a module marked `strict` in config can never accumulate a todo entry, existing or new — any entry there is itself a violation.
+A violation report always carries a rule id, `path:line:col`, the evidence, the `because` reason, and a `do:` command — enough for an agent to fix its own mistake without asking.
+
+## Layout
+
+- `src/` is the library and CLI. The root `archstrict.config.ts` checks that tree: `core` is the analysis engine, `rules` and `verbs` are where a new rule or verb lands, and `cli`, `mcp`, and `check-options` sit above them. `archstrict.todo.json` is the ratchet. `skills/archstrict/` is the product skill shipped to consumers, not a second config.
+- `test/` is the Vitest suite; `features/` is the nukadoko (Gherkin) dogfood scenario.
+- `.agents/` is the canonical Claude Code plugin: the manifest, the PreToolUse and PostToolUse hooks, and the MCP server. `.claude-plugin/plugin.json` symlinks to `.agents/plugin.json`, and repo-root `hooks/` and `mcp/` symlink to `.agents/hooks` and `.agents/mcp`. `${CLAUDE_PLUGIN_ROOT}` is the directory that contains `.claude-plugin/`, so those plugin-root paths still resolve. `.claude-plugin/` stays a real directory holding only the manifest symlink: Claude loads `hooks/` from the plugin root, and a directory symlink onto `.agents/` would place `hooks/` and `mcp/` inside `.claude-plugin/`.
+- `skills/archstrict/` (and root `llms.txt`) is the agent-facing skill (`SKILL.md` plus `references/`).
+- `scripts/` holds standalone scripts (not part of the shipped library): the typescript 7 probe, two narrow config converters (Prisma's architecture.config.json, VS Code's code-layering table) to archstrict.config.ts's own shape, and the two runners that re-run the Prisma/VS Code oracle comparisons through the real CLI against a real clone (see Commands below). `.github/workflows/` is CI.
+- `.claude-team/` holds the task spec, the report, and their working artifacts. It is gitignored; do not reference it from committed content.
+
+## Visibility
+
+This repository is intended for public release.
+Write all committed text in English: code, comments, docs, commit messages.
+Do not reference private tools, private repositories, or internal working documents (including `.claude-team/`) in committed content.
+If you want to cite an internal document, write its substance in place instead.
+
+## Rules
+
+- Do not add dependencies without the owner's approval. Pin exact versions, at least 7 days past release. Prefer language-official packages, then vendor packages, and avoid single-maintainer packages.
+- Write tests with Hegel (`@hegeldev/hegel`, property-based) wherever a property exists: round trips, invariants, monotonicity. Example-based tests cover exact CLI output and JSON shape.
+- Comments say why: the constraint, or the alternative that was refused. Each module starts with its responsibility and its boundary.
+- Violation text never uses the words "strict" or "typed"; a name must not mislead about what fixes a violation.
+- A release, a `npm publish`, or a change of the repository's visibility is the owner's to run.
+
+## Commands
+
+For working on archstrict itself:
+
+- `npm run build` — compile `src/` to `dist/`. The CLI's own tests spawn the built `dist/cli.js`, so run this before `npm test` if `dist/` is missing or stale.
+- `node dist/cli.js check` — checks this repository against the root `archstrict.config.ts`. `node dist/cli.js todo` prunes `archstrict.todo.json` after the first run and does not add debt again.
+- `npm run typecheck` — `tsc --noEmit` over the whole project.
+- `npm test` — the Vitest suite.
+- `npm run dogfood:nukadoko` — a nukadoko (Gherkin) scenario that runs the built CLI's full init/check/todo/edit/check round trip against nukadoko's own published `src/` (a real, unrelated codebase with no public-surface convention), copied into a disposable scratch directory. Never modifies the real nukadoko package or a checkout of it.
+- `npm run ci:ts7-probe` — measures, against whatever typescript 7 happens to be installed, which of the operations rule 6 needs actually work on typescript 7's `./unstable/*` surface. Never fails: an unsupported operation is the measurement, not an error. archstrict itself always analyzes with its own pinned `typescript` dependency (6.0.3), independent of this. CI (`.github/workflows/ci.yml`) installs `typescript@7.0.2` (`--no-save`, never touching `package.json`) just for this job.
+- `node scripts/run-prisma-oracle.mjs <path-to-a-real-prisma/prisma-clone>` / `node scripts/run-vscode-oracle.mjs <path-to-a-real-microsoft/vscode-clone>` — re-run the Prisma/VS Code oracle comparisons through the real, built CLI (`dist/cli.js check --json`) against a scratch copy of the clone, converting its own real config (`architecture.config.json` / the `code-layering` ESLint rule's table) with the existing `scripts/convert-*` converters. Requires a local clone (`ghq get --shallow` or equivalent); the Prisma one also needs `pnpm install` run in it once, for its own real `node_modules`. Neither ever writes into the clone itself. Each prints a positive-control run (a rule deliberately forbidding something real and common) alongside the baseline, so a `0` in the baseline reads as a genuine pass, not the constraint engine silently seeing no edges at all.
+
+The CLI itself:
+
+- `archstrict init [dir] [--json]` — on a fresh project, declare one module per top-level directory holding TypeScript source (`.ts`, `.tsx`, `.mts`, `.cts`; default container `src/`, or the project root when it's absent or holds none) and one single-file module per loose top-level source file, so the first `check` covers every analyzed file by construction. That map is an inventory: group files that change together (`glob` may be an array of paths in one directory), split a directory that holds almost every file, then add `edges`. `archstrict recommend` names a mega-module and a file-per-module inventory in `mapNotes`. Write `archstrict.types.ts` (the module-name union type). Re-run any time; it never touches an existing `archstrict.config.ts`, only regenerates `archstrict.types.ts` from its own `declaredModules` names. `--json` prints one object (`configPath`, `typesPath`, `configWritten`, `opened`, `moduleNames`, `hiddenDirs`, `noiseDirs`, `testFileExcludes`, `uncovered`, `notes`, `do`), or `{ "error": "<message>", "do": "<command>" }` on failure, the same convention `check` and `todo` follow.
+- `archstrict check [file] [--json] [--rule <id>] [--module <name>] [--frozen]` — analyze the whole project and report violations. With a file argument, analysis still covers the whole project (resolving an edge needs it), but the report is scoped to that file's own violations. Text output prints every violation up to 20; past that it prints grouped counts (by rule, then by the module owning the todo) with one full example per group and a `do:` that reruns just that group, cut at a line-count cap with a count of the groups left out. `--rule`/`--module` are repeatable and filter both the text and `--json` output after analysis; the exit code reflects the filtered set once either is given. An unknown rule id or module name is an error listing the valid ones. `--frozen` includes todo-matched violations too, each marked `frozen: true` and still combinable with `--rule`/`--module`; the exit code ignores a frozen violation, so a project already covered by `archstrict todo` still exits 0. When most public-surface-bypass violations target modules with no surface file at all, the summary says so and offers freezing, naming a surface, or adding surface files as next steps.
+- `archstrict todo [--json]` — on a project's first run, freeze every current freezable violation into one project-root `archstrict.todo.json`, grouped by module name; on every later run, only prune entries that no longer match a current violation. Never adds after the first run. That file's own existence is the "first run happened" signal, replacing an earlier marker file; a project with no debt after its first run still gets the file, with an empty module map, so the ratchet stays visible. The first run refuses instead (exit 1, no file written) while any `uncovered-module` violation exists, since such a file can never be frozen and a later declared-and-covered version of it would then find freezing already closed forever; a later, prune-only run is unaffected. `--json` prints `{ firstRun, added, pruned }`, or `{ "error": "<message>" }` on a config error, the same convention `check` follows.
+
+- `archstrict hotspots [--since <git ref or date>] [--json]` — report commits, changed lines, fan-in, fan-out, frozen debt, active violations, and a commits-times-fan-in score per module. It also reports co-change counts and both directional shares for module pairs. Text output is limited to ten modules and ten pairs; JSON contains all results.
+
+- `archstrict simulate [--json] [--whole-project]` — preview proposed source or config changes without writing to disk. The default report is scoped to changed files; `--whole-project` reports the complete project delta. Read the JSON change set from stdin; see [simulation](skills/archstrict/references/simulate.md).
+
+## Claude Code plugin
+
+This repository is itself a Claude Code plugin (`.claude-plugin/plugin.json`, a symlink to `.agents/plugin.json`). It ships two hooks around every Edit/Write/MultiEdit, both shelling out to the edited project's own `node_modules/.bin/archstrict`, never to this repository's own build. Its `PreToolUse` hook (`.agents/hooks/pre-tool-use.mjs`, reached as `hooks/pre-tool-use.mjs`) runs before the write happens: it builds the file text the tool call would produce and previews it through that project's `archstrict simulate --json`, returning any added violation into the agent's own context so it can change course before the write lands, or denying the tool call outright when `ARCHSTRICT_PRETOOLUSE=deny` is set. Its `PostToolUse` hook (`.agents/hooks/post-tool-use.mjs`, reached as `hooks/post-tool-use.mjs`) runs the edited project's own installed `archstrict check <file>` right after the write and returns any violation into the agent's own context - the same moment a human editor's red squiggly would appear. Both say nothing when the edited project has no `archstrict` installed at all or the edited file has no violation; see [the hook reference](skills/archstrict/references/hook.md) for the full set of silent cases. The MCP server is `.agents/mcp/server.mjs`, reached as `${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs`. `npm pack` ships `.agents/` and drops the symlinks, so an installed package's hooks are `node_modules/archstrict/.agents/hooks/pre-tool-use.mjs` and `post-tool-use.mjs`.
+
+
+<!-- ARCHSTRICT_START -->
+## archstrict
+
+In projects with an `archstrict.config.ts` (module-boundary/architecture linting), run `archstrict rules <path>` BEFORE creating a file or adding an import - it reports the module, tags, and constraints that would govern that path, even before it exists. Run `archstrict check` after editing to confirm.
+
+The full rule reference (every rule's evidence/because/do shape, the config schema, the pre-edit query) is at `node_modules/archstrict/skills/archstrict/SKILL.md` when installed via npm - read it before configuring `archstrict.config.ts`, or when a violation's `do:` text alone isn't enough.
+
+If there is no `archstrict.config.ts`, skip archstrict entirely - it may not be installed here.
+<!-- ARCHSTRICT_END -->

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+The format follows Keep a Changelog, and the versions follow SemVer. Before 1.0, a minor version
+may change commands, flags, config, or output shape. The version entry will describe each change.
+
+## 0.2.0 (2026-10-01)
+
+### Added
+
+- This repository includes `.claude-plugin/marketplace.json`. Claude Code users can install the plugin with `/plugin marketplace add meganemura/archstrict` and `/plugin install archstrict@archstrict`.
+- `declaredModules[].glob` accepts an array of paths that share one directory, so a flat directory can name a multi-file seam without a directory move. Surface and friends resolve against that directory. The type-leak boundary is each listed file. Paths in two directories, and an empty array, are config errors.
+- `archstrict init` prints that the generated map is an inventory. A container of only files is told to group seams with a glob array. A directory that holds at least four fifths of the files (and at least eight) is named so it can be split before `archstrict todo`.
+- `archstrict recommend` adds `mapNotes` (`mega-module`, `file-per-module`). A surface proposal for the mega-module says to split it before freezing its bypasses.
+- `archstrict check` and `archstrict todo` name the case where one module holds most analyzed files and most public-surface bypasses, including bypasses a todo file already suppresses. The next command is to split that module before freezing more. `check <file>` leaves the note out.
+- While the config has no `edges` rule, a whole-project `check` prints one `summary:` line: the
+  config so far freezes today's import graph, not a target architecture. Its `do:` lines name
+  `archstrict recommend`, `archstrict hotspots`, and the rearchitect reference. `--json` carries
+  the same text as `nextSteps`. `check <file>` leaves it out.
+- A cycle between two modules now names the imports on each side and two moves in its `do:`:
+  extract the shared part into a leaf module both import, or pass the dependency in from the side
+  that owns it, and run `archstrict simulate` on the planned change first. A lopsided pair still
+  names its minority imports first. A cycle of three or more modules keeps the earlier text.
+- A `type-leak` `do:` now tells two cases apart. A type this module owns needs only a name on this
+  surface. A type owned by another module with no surface needs a surface on that module, or the
+  exposing export must leave this surface.
+
+### Changed
+
+- Every verb that walks the project (`init`, `check`, `todo`, `simulate`, `hotspots`, `recommend`)
+  now skips gitignored paths. archstrict reads the root and nested `.gitignore` files, the ones
+  above the project root, and the repository's `info/exclude` with git's own pattern rules, and
+  never runs git. A local scratch directory such as `tmp/` no longer floods `check` with
+  `uncovered-module` violations. A gitignored file stays resolvable as an import target. A config
+  that already declares a module inside a gitignored directory keeps analyzing that module; remove
+  the declaration to drop it.
+
+### Documentation
+
+- The skill, recommend reference, and re-architecture notes tell an adopter to treat `init` as an inventory, to split a mega-module before freezing it, to group a flat directory with a `glob` array, to install the skill once per user, and where a CLI and a graph helper sit.
+- The README (and its Japanese twin) has one Install section per host. Claude Code users add the
+  repository marketplace, then install `archstrict@archstrict` for the skill, edit hooks, and MCP
+  server. Other agents install the skill with `gh skill install`, add the `AGENTS.md` section with
+  `archstrict agents`, and run `archstrict check` in CI, since the edit hooks are Claude Code only.
+
+## 0.1.0 (2026-09-29)
+
+### Added
+
+- `archstrict init [dir] [--json]` declares one module per top-level directory holding TypeScript
+  source and one per loose top-level source file, so the first `check` covers every analyzed file
+  by construction, and writes `archstrict.types.ts`.
+- `archstrict check [file] [--json] [--rule <id>] [--module <name>] [--frozen]` reports module
+  boundary violations: a public-surface bypass, an import cycle, an uncovered module, an empty rule
+  set, a deprecated module edge whose count grew, a type leaked out of a surface, and a tag-boundary,
+  tag-order, or point-rule violation from the constraint engine. `--rule` and `--module` filter both
+  the text and JSON output; `--frozen` also reports todo-matched violations without affecting the
+  exit code.
+- `archstrict todo [--json]` freezes current violations into one project-root
+  `archstrict.todo.json`, grouped by module name, on the first run, then only prunes stale entries
+  afterward. A module marked `strict` in config can never accumulate a todo entry.
+- `archstrict rules <path> [--json]`, `archstrict search <query> [--json]`,
+  `archstrict recommend [dir] [--json]`, `archstrict fix [file] [--dry-run] [--json]`, and
+  `archstrict hotspots [--since <ref>] [--json]` describe a path's constraints, search declared
+  public surfaces, propose a boundary config from real edges, fix a surface bypass by adding a
+  re-export, and rank modules by Git change frequency, co-change, fan-in, fan-out, and frozen debt.
+- `archstrict simulate [--json] [--whole-project]` previews proposed source or config changes
+  against the full rule pipeline without writing to disk, reading the change set from stdin.
+- `archstrict.config.ts` declares a project's modules, their public-surface file name, tags
+  (`classify`/`classifyByDirectoryName`), edges between tags (`allowDeny`, `order`, `point`), known
+  cycle exceptions (`ignoredCycles`), and directories that must hold no code (`mustBeEmpty`).
+- A violation always carries a rule id, `path:line:col`, the evidence, a `because` reason, and a
+  `do:` command, in both text and JSON output.
+- A Claude Code plugin (`.agents/`): a `PreToolUse` hook previews an Edit, Write, or MultiEdit
+  through `simulate` before the write lands, a `PostToolUse` hook confirms the result through
+  `check` right after, and an MCP server exposes the same verbs as tools.
+- An agent skill (`skills/archstrict/SKILL.md` and its references) and `llms.txt` give a coding
+  agent the workflow and the rule reference without reading the source.