archstrict 0.0.0 → 0.1.0

package/docs/calibrated-rules-design.md

@@ -0,0 +1,124 @@
+archstrict provides the built-in `config-meaning` assessment through `archstrict check --prove`. Jev chooses whether a rule's shape agrees with or contradicts its `because` text. A contradiction produces a finding when confidence reaches 0.7. A lower confidence produces an `undecided` result. A consistent choice produces no finding. This check is advisory and cannot enter todo. The general, user-authored `calibrated: [...]` array remains a design only. Neither `check` nor `rules <path>` reads that array. Adding it to a real config has no effect.
+
+# Calibrated rules
+
+archstrict reports the class of evidence for each result.
+The report keeps the three tiers distinct.
+This design adds an optional tier that uses Jev from TypeSafe AI.
+
+| Tier | What the result establishes |
+| --- | --- |
+| Proven | Existing structural rules produce deterministic results that a consumer can replay. |
+| Calibrated | A trained probability describes accuracy across many cases. It never guarantees correctness for one case. |
+| Explored | An agent inspects the code and records the date. The result has no repeatability guarantee. |
+
+This document defines only the calibrated tier.
+The explored tier belongs to separate future work and stays outside this design.
+
+Do not use a calibrated score to rank, annotate, or change the weight of a proven violation.
+Such a score invites a consumer to discount a real violation.
+The calibrated tier produces separate results with explicit labels and leaves deterministic results unchanged.
+
+## 1. Config location
+
+The new `calibrated` field contains an array of rule entries at the top level of the config.
+It sits beside `edges` and `declaredModules`; it never sits inside `edges`.
+
+Each entry has the shape `{ tags | glob, ask, criteria, at, because }`.
+The `at` field is optional.
+Each entry selects files with either `tags` or `glob`, never both.
+These alternatives follow the existing approach to file selection through classification.
+
+| Field | Purpose |
+| --- | --- |
+| `tags` | Select the files through their tags. |
+| `glob` | Select the files through a path pattern. |
+| `ask` | State the question that Jev assesses for each selected file. |
+| `criteria` | State the criteria for that assessment. |
+| `at` | Set the optional confidence threshold for a violation. |
+| `because` | State why the rule exists. |
+
+Every entry requires `because`, as other root-level rules require a reason.
+
+## 2. Activation
+
+The tier requires the `TYPESAFE_API_KEY` environment variable before it evaluates rules.
+When the key is absent, `check` reports every configured calibrated rule as an individual, named `skipped` entry.
+Each skipped entry carries the rule id, its configured `because`, and the reason `TYPESAFE_API_KEY is absent`.
+The report must retain these entries rather than omit them.
+
+This reuses the principle of rule 4, `empty-rule-set`: a rule that checks nothing must not look like a pass.
+
+The built-in `config-meaning` check is a deliberate, stricter exception to this general activation rule.
+It also requires `--prove` as explicit permission for each invocation.
+A routine CI or pre-commit check must not make paid requests because an unrelated tool has set the same credential.
+Without `--prove`, this check produces no assessment and makes no request.
+With `--prove`, a missing key or a failed batch produces one `skipped` entry for the whole batch.
+A contradiction with confidence below 0.7 produces an `undecided` entry with the rule's own `because` text.
+Its evidence includes the returned confidence and probabilities, but it has no `confidence` field.
+A contradiction at or above 0.7 produces a finding with a `confidence` field.
+All three outcomes carry `tier: "calibrated"`; they remain advisory and cannot enter todo, including in modules marked `strict`.
+The general field, threshold, and todo design below applies to future user-authored rules.
+
+An exhaustive allow list does not require a semantic assessment.
+Static config validation alone cannot establish the set of real values, but the dependency graph supplies those values.
+A deterministic graph check can detect an exhaustive allow list; the claim that static analysis cannot catch this case was incorrect.
+The built-in assessment instead checks whether the configured shape contradicts its own reason.
+
+## 3. Violation shape
+
+Each calibrated result carries the required fields `rule`, `path`, `line`, `column`, `evidence`, `because`, `config`, and `do`.
+The `config` field identifies the assessed edge-rule entry as structured data.
+It also carries two fields that deterministic violations do not carry:
+
+| Field | Value |
+| --- | --- |
+| `confidence` | The model's own calibrated number, from 0 to 1. |
+| `tier` | The literal string `"calibrated"`. |
+
+A consumer can filter or sort results by `tier` without parsing text to identify their class of evidence.
+A confidence value describes the calibrated result alone; it never modifies a deterministic violation.
+
+## 4. Threshold and exit code
+
+The report includes every calibrated result, including those that cannot affect the exit code.
+The rule's own `at` field determines whether its result can block a check.
+
+| Config and confidence | Report and todo | Effect on `check` |
+| --- | --- | --- |
+| `at` is absent | Report every result with `tier: "calibrated"`. Each result is eligible for todo. | Advisory only. The result never affects the exit code. |
+| `at` is present and `confidence >= at` | Report the result as a violation, subject to the existing todo rules. | Treat it like a deterministic violation for the exit code and the hard gate in a `strict` module. |
+| `at` is present and `confidence < at` | Report the result as information. | The result does not block the check or affect its exit code. |
+
+The design requires two independent choices.
+The API key enables evaluation; the `at` field permits a result to block a check.
+The advisory default does not grant that second permission.
+
+## 5. Todo eligibility and identity
+
+Calibrated results are eligible for todo under the existing rules for module debt.
+The fingerprint hashes `rule`, `path`, and a hash of the `ask` text itself.
+It never includes `confidence`.
+This identity freezes the question, not the answer that the model returns.
+
+A model update can change a score without changing that identity.
+A score change alone must not unfreeze or refreeze existing debt.
+A change to the `ask` text changes the identity because it changes the question.
+
+This reuses the existing pattern for the `type-leak` fingerprint.
+That fingerprint removes the mutable `referenced by` suffix from the evidence before it computes the hash.
+Both fingerprints exclude details that can vary while the debt stays the same.
+
+## 6. Interaction with strict modules
+
+Apply the threshold and exit behavior in decision 4 to modules marked `strict`.
+That table defines the interaction; this tier adds no separate condition for those modules.
+
+## 7. Projection through `rules <path>`
+
+When a calibrated rule's `tags` or `glob` matches the queried path, `rules <path>` shows it in a new section.
+The section shows the rule's `ask` text and its configured `at` threshold, if present.
+It never shows a score because a query before an edit does not evaluate the future code.
+
+This projection gives an agent the question before the agent writes a line.
+It follows the same principle as the existing `allowDeny`, `order`, and `point` projections.

package/docs/init-singleton-modules.md

@@ -0,0 +1,128 @@
+# init declares one module per directory or loose file
+
+`archstrict init [dir]` walks the project with check's own file-eligibility
+rule and declares one module per top-level directory that holds an
+analyzed source file (`.ts`, `.tsx`, `.mts`, or `.cts`), and one
+single-file module per loose top-level file of one of those extensions -
+both inside the opened container (`src/` by default) and at the
+project root. Every file the first `check` analyzes then belongs to
+exactly one declared module, by construction. The first check therefore
+reports 0 `uncovered-module` and 0 `empty-rule-set` violations, on any
+project shape.
+
+## The problem this replaces
+
+Before this change, `init` declared a module for each directory under a
+fixed glob (`src/*`) and excluded every loose top-level `.ts` file with a
+literal `exclude: ["*.ts"]`. Two real shapes broke that:
+
+- A directory with no `src/` at all, or a `src/` holding no directories
+  (only loose files) - `init` had nothing to declare, or refused.
+- A directory alongside `src/` at the project root, or a loose file
+  directly inside `src/` itself - each showed up as its own
+  `uncovered-module` violation on the very first `check`, which `todo`
+  can never freeze away (an `uncovered-module` violation has no module
+  directory to freeze it into). A project in this shape stayed at exit 1
+  permanently unless a person hand-wrote an `exclude` entry for those
+  files before running `todo` for the first time.
+
+## The decision
+
+Each analyzed file becomes its own module (a directory module for a
+directory's files, a single-file module - `surface` naming the file
+itself - for a loose file), never a shared catch-all covering every loose
+file at once. Two ideas were rejected:
+
+- **Printing an inventory of directories, with loose files left
+  uncovered.** This reproduces the exact trap above: the first check
+  still reports `uncovered-module`, and it still can't be frozen.
+- **One catch-all module for every loose file at once
+  (`{ name: "loose", glob: "src/*.ts" }`).** Its own public surface is
+  every one of those files' own exports at once - a degenerate shape with
+  no real public/private distinction inside it. `init` also never writes
+  a glob whose base is the project root (`**`, `*.ts`): such a module's
+  directory is the whole project.
+
+A directory module carries no per-entry `surface` of its own - the
+project's own top-level default applies, or a real `package.json`
+`exports` map at that directory's own root, when it has one. Setting a
+per-entry `surface` would turn that derivation off for every directory
+`init` ever declares.
+
+## Naming
+
+A group's name is its on-disk name (the directory's name, or the file's
+name including its extension) - one directory cannot hold a file and
+another directory of the same name, so this alone never collides at the
+same level. A group below the project root whose on-disk name is already
+taken (by a top-level entry of the same name) instead takes its own
+project-relative path as its name: a root `cli.ts` and a container's own
+`cli.ts` become `"cli.ts"` and, say, `"src/cli.ts"`.
+
+## Everything the walk excludes
+
+`init` writes an `exclude` covering: its own two files
+(`archstrict.config.ts`, `archstrict.types.ts`); every hidden directory,
+at any depth (`.git`, a tool's own state directory) - the same thing
+`tsc`'s own default `include` already skips; a fixed list of common
+non-source directory names (`test`, `tests`, `example`, `examples`,
+`spike`, `build`, `coverage`, `fixtures`, `e2e`, `tmp`), each added only when a
+real directory of that name exists on disk; and a colocated test file's own
+naming convention (`*.test.ts`, `*.spec.tsx`, and every other suffix/analyzed-
+extension pair, plus a `__tests__/` directory), each added only when a real
+analyzed file already matches it. A container named on the command line is
+never treated as noise, even when its own name is on the directory list.
+The two hidden-directory patterns are the same on every machine (a
+committed config never names a directory that exists on only one
+machine); a directory or test file a project decided is real source keeps
+its own exclude entry removed by hand - the config comment names the
+reason (a test file imports across modules as a fixture, and boundary
+rules read production code) right beside the pattern it excluded.
+
+## Zero-directory and zero-candidate cases
+
+A container holding only loose files (no directories at all) still
+declares one module per file; `init` prints one extra line, naming the
+alternative (checking the whole container as one module instead) without
+writing it - that shape stays a hand-edit, since a `do:` line names one
+action, not a menu.
+
+A project with no analyzed source file anywhere - under the seeded
+exclude - has nothing for `init` to declare. It writes neither file and
+exits 1, naming what's missing.
+
+## Re-run
+
+`init` never touches an existing `archstrict.config.ts`. A re-run only
+re-reads it and rewrites `archstrict.types.ts` (the `ModuleName` union)
+from its own `declaredModules` names - never from a fresh walk. A
+directory argument on a re-run is still validated (the same syntax rules
+apply), then ignored: it only ever chose a container for a config `init`
+is about to write.
+
+## What stays out of this change
+
+A re-run does not yet print the paste-ready `declare:`/`exclude:` lines
+for a file that has since fallen outside every declared module (only the
+`ModuleName` regeneration lands here); rule 3's own suggested fix text and
+`check`'s own footer are unchanged for the same reason.
+
+`init --json` and `recommend`'s own directory argument landed in a later
+change: `recommend [dir]` without a config now runs this same walk in
+memory (no file is written) instead of a single-level modules-glob
+discovery, so its own proposed globs always agree with what `init` would
+write for the same tree. `init --json` reports one object on success
+(`configPath`, `typesPath`, `configWritten`, `opened`, `moduleNames`,
+`hiddenDirs`, `noiseDirs`, `testFileExcludes`, `uncovered`, `notes`, `do`)
+and `{ error, do }`
+on failure, the same convention `check --json` and `todo --json` already
+follow. A later change removed the old single-level discovery path
+entirely, once no user-facing command called it anymore: `declaredModules`
+is now the only way a module is ever bounded.
+
+Rule 6 (type-leak) can still report a finding for a singleton file whose
+own export structurally exposes another module's own internal
+declaration - this is this project's own currently-implemented reading of
+that rule, unrelated to this change and unaffected by it: declaring more,
+smaller modules only means more module boundaries between files for that
+existing rule to evaluate, not a new rule or a new finding class.

package/docs/maintenance.md

@@ -0,0 +1,82 @@
+# Maintenance
+
+## Checks
+
+Run the main checks before a release or after a code change:
+
+```sh
+npm run build
+npm run typecheck
+npm test
+```
+
+Run the dogfood scenario and the oracle comparisons separately:
+
+```sh
+npm run dogfood:nukadoko
+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>
+```
+
+`dogfood:nukadoko` runs the built CLI's full init/check/todo/edit/check round trip against a real,
+unrelated published `src/` copied into a disposable scratch directory. The two oracle scripts
+re-run the Prisma and VS Code boundary-config comparisons through the real, built CLI against a
+scratch copy of a local clone, converting each project's own real config with the existing
+`scripts/convert-*` converters. Neither writes into the clone itself. See
+[AGENTS.md](../AGENTS.md)'s Commands section for what each requires (a local clone, `pnpm install`
+for the Prisma one) and what each prints.
+
+`npm run ci:ts7-probe` measures which of the operations rule 6 needs work on whatever typescript 7
+happens to be installed. It never fails; an unsupported operation is the measurement, not an error.
+archstrict itself always analyzes with its own pinned `typescript` dependency, independent of this
+probe.
+
+## Dependencies and Node.js
+
+Do not add a dependency without the owner's approval. Pin every dependency to an exact version.
+Wait at least seven days after a version is released before adding it, and check that no newer
+security release replaces it. Prefer language-official packages, then vendor packages, and avoid
+single-maintainer packages.
+
+archstrict analyzes with `typescript` pinned at `6.0.3`. CI (`.github/workflows/ci.yml`) runs the
+main job on Node.js 22 and separately probes typescript 7 (`ci:ts7-probe`) without changing the
+pinned dependency. The publish workflow (`.github/workflows/publish.yml`) requires Node.js 24.10
+and npm 11.5.1 or newer before it runs `npm publish`. `package.json` currently declares no
+`engines` field; adding one, and which Node.js versions it should name, is the owner's call.
+
+## Add a rule or a verb
+
+Preserve the violation contract when you add a rule:
+
+- A violation carries a rule id, `path:line:col`, the evidence, a `because` reason, and a `do:`
+  command that runs, in both text and JSON output.
+- A violation's text never uses the words "strict" or "typed" - a name must not mislead about what
+  fixes it.
+- Text output stays bounded: past a fixed count, print grouped counts with one example per group
+  and a `do:` that reruns just that group. JSON output stays complete; only text output cuts.
+- Point new prose at the config field that caused the violation, the same way an existing rule's
+  `because` reason does, so an agent can find the one line to change.
+
+Preserve the same contract when you add a verb:
+
+- Support both a text and a `--json` mode, with the same field names and order the existing verbs
+  use for the same concept (`do`, `error`, a per-item `path`).
+- A config or missing-file failure throws so `main` in `src/cli.ts` catches it and prints
+  `{ "error": "<message>", "do": "<command>" }` (or the text equivalent) - do not print a partial
+  result and a stack trace instead.
+- Add the verb to `AGENTS.md`'s Commands section and to the CLI usage line in `src/cli.ts`.
+- Add example-based tests for exact text and JSON output, and Hegel property tests for any round
+  trip, invariant, or ordering rule the verb introduces.
+
+## Triage a bug report
+
+Ask for the project's `archstrict.config.ts`, the `archstrict check --json` output, and the
+project's `archstrict.todo.json` if one exists. The config shows which module, tag, and edge rules
+apply; the JSON output shows every violation with its rule id and evidence; the todo file shows
+which of those are already frozen debt rather than new failures.
+
+Reproduce the report by running `archstrict check` against a copy of the project, or against a
+minimal fixture that keeps the same module and edge shape. Compare the text and `--json` output
+against what the report describes. Add the fixture as a test case when it contains no sensitive
+paths or names, then add an example test for the exact output and a property test for the broken
+invariant, when one exists.

package/docs/releasing.md

@@ -0,0 +1,55 @@
+# Releasing
+
+archstrict stays on 0.x versions for now. A release has three parts: the npm package, a git tag,
+and the skill and plugin.
+
+Pushing a `v*` tag runs `.github/workflows/publish.yml`. The workflow checks out
+the tagged commit, runs the release checks, and runs `npm publish`. npm authenticates with GitHub
+Actions OIDC through the Trusted Publisher. The repository stores no `NPM_TOKEN`, and the workflow
+uses no long-lived npm secret. The GitHub Environment `publish` is the human gate. Required
+reviewers approve the job before it can publish.
+
+Every `uses:` value in a workflow must use a full 40-hex commit SHA. Add the action version in a
+trailing comment, for example `uses: actions/checkout@<40-hex> # vX.Y.Z`. A tag ref does not meet
+this requirement.
+
+## Trusted publisher
+
+Create the npm Trusted Publisher with these case-sensitive fields:
+
+- Organization or user: `meganemura`
+- Repository: `archstrict`
+- Workflow filename: `publish.yml`
+- Environment name: `publish`
+- Allowed action: `npm publish`
+
+Create the GitHub Environment `publish` and add the required reviewers. A private repository
+cannot hold an environment with required reviewers, so this step waits until the repository
+becomes public. The deployment approval appears after a `v*` tag starts the workflow and the job
+enters that environment.
+
+The `repository.url` field in `package.json` points at this GitHub repository. npm checks that URL
+against the workflow repository. After the first successful publish, require two-factor
+authentication for the package and disallow token publishing. The Trusted Publisher will continue
+to work.
+
+## Each version
+
+1. Replace `(unreleased)` in `CHANGELOG.md` with the release date. Set the same version in
+   `package.json` and `package-lock.json`.
+2. Run `npm run build`, `npm run typecheck`, and `npm test`.
+3. Run `npm pack --dry-run`. Read its file list. It must contain `dist/`, `docs/`, `skills/`, both
+   READMEs, the changelog, `AGENTS.md`, `llms.txt`, `.agents/`, and the license. It must not contain
+   `test/` or `.claude-team/`.
+4. Commit the release as `chore: release 0.x.0`. Tag it as `v0.x.0`. The tag without `v` must equal
+   the `package.json` version. Push the commit and tag. The tag push starts the workflow.
+5. Approve the `publish` environment for that Actions run. The workflow runs `npm ci`, the build,
+   typecheck, and tests before `npm publish`. `prepublishOnly` repeats those checks.
+6. Extract only that version's notes. `--notes-file CHANGELOG.md` would include every version.
+   Use `awk '/^## 0.x.0/{in_version=1;next} /^## /{in_version=0} in_version' CHANGELOG.md > notes.md`.
+   Then run `gh release create v0.x.0 --title v0.x.0 --notes-file notes.md`.
+7. Install or update the skill and plugin for the agents that use this repository, following
+   whatever install path Claude Code and the agent's own tooling document for a plugin repository
+   at that time; this repository names no fixed install command for that step.
+
+The owner performs the commit, tag, push, environment approval, release creation, and npm publish.

package/docs/rules-edge-cache.md

@@ -0,0 +1,50 @@
+# Persistent graph cache
+
+`check`, `check <file>`, `todo`, `rules`, `recommend`, `fix`'s own baseline, and `search` all build
+their module graph through one cached path. It reads and writes
+`node_modules/.cache/archstrict/edges.json` (a header) plus a fixed 64 shard files under
+`node_modules/.cache/archstrict/edges/` in the analyzed project - a file's own shard is a stable
+hash of its own project-relative path. `simulate` never reads or writes this cache; it keeps its
+own in-memory overlay instead.
+
+A build rewrites only the shards whose own files actually changed, never the whole cache: a touch
+or a one-file edit rewrites one shard plus the header. A shard that is missing, unreadable, or
+whose bytes no longer match the header's own recorded hash for it makes only that shard's own
+files a cache miss (re-walked and re-resolved); it is never an error, and it never discards the
+rest of the cache.
+
+The cache stores one entry per analyzed file, keyed by its absolute path: that file's own
+syntactic import list (never its AST), its resolved specifiers, and the compiler options and
+package.json "type" it was parsed under. A file whose own mtime, size, effective compiler
+options, and implied module format all still match is not reparsed; only a changed or new file is
+reparsed, and only that one file.
+
+Resolutions are reused outright while nothing that can affect a resolution answer has moved:
+the analyzed file set, every package.json outside node_modules, the nearest lockfile, every
+resolvable file outside node_modules (any extension a specifier could resolve to, whether
+analyzed, excluded, or in dist/), every distinct effective compiler-options object, and the
+node_modules package set on the path resolution actually walks (see below). The moment any of
+these moves, every specifier is re-resolved project-wide from each file's own already-cached
+import list - never a reparse of any file whose own mtime and size are unchanged.
+
+The node_modules dependency set covers every node_modules directory this build meets: each
+ancestor of the project root's own, all the way up to the filesystem root (the same distance
+TypeScript's own resolver walks for a bare specifier, regardless of where a lockfile sits), and
+every one the project's own tree walk meets while descending (a workspace member's own
+node_modules, e.g. `packages/app/node_modules`), without ever descending into node_modules
+itself. Each one records its own top-level package names and their package.json's own mtime,
+read after following a symlink; a dot-prefixed entry (`.cache`, `.bin`, `.vite`, pnpm's own
+`.pnpm` store) is never counted as a package name, so this cache's own
+`node_modules/.cache/archstrict` does not move its own fingerprint. This covers a package
+installed or removed with no lockfile edit, and a symlinked workspace package's own `exports`
+edit. It does not cover an edit made directly to an already-installed package's own file, leaving
+its package.json untouched - nothing this cache reads changes for that edit, and deleting
+`node_modules/.cache/archstrict` is the only way to force a rebuild for it.
+
+The reparse gate is mtime and size, not a content hash: an edit that keeps the exact same byte
+size and whose mtime is restored (or never advances) is not detected either.
+
+A package version mismatch, a change to this project's own built code (module-graph.js,
+edge-cache.js), or a different installed typescript version drops the whole cache. A malformed
+cache file is a silent miss, not an error; writes are atomic (a temporary file, then a rename),
+and a failed write leaves the fresh analysis result usable regardless.

package/docs/todo-single-file-migration.md

@@ -0,0 +1,58 @@
+# Migrating from the per-module todo layout
+
+**Remove all of the following after the first release** - the migration
+only matters for a project that adopted archstrict before the single-file
+`archstrict.todo.json` existed:
+
+- this file
+- `src/todo-migration.ts` and `test/todo-migration.test.ts`, whole
+- in `src/verbs/check.ts`: `readCurrentTodo`'s own `legacy`/`migrationNote`
+  branches (fold `readCurrentTodo` back down to reading only
+  `readTodoFile`), and the `migrationNote` plumbing into `result.notes`
+- in `src/verbs/todo.ts`: `freezeOrPrune`'s own `legacy` branch and its
+  call to `deleteLegacyTodoFiles`
+- in `src/todo-store.ts`'s `readTodoFile`: the `{ entries: [...] }`,
+  no-`schemaVersion` fallback that returns `undefined` instead of throwing
+  `malformed` - once nothing on the old layout exists to collide with the
+  new file's own path, an object without `schemaVersion` is just malformed
+
+## The old layout
+
+Before this change, frozen debt lived in one file per module:
+`archstrict.todo.json` inside a directory module's own directory, or
+`<file>.archstrict.todo.json` beside a single-file module (there is no
+directory to hold a sibling file). A project-root marker file,
+`.archstrict-todo-initialized`, recorded that `archstrict todo` had run at
+all, since a project with zero freezable violations wrote no per-module
+file on its first run and file-existence alone couldn't tell "first run,
+genuinely clean" apart from "a later run."
+
+On a 31-module project, that put 24 todo files scattered among the source
+files, and a re-architecture created and removed a todo file with every
+module it added or split.
+
+## The new layout
+
+One file at the project root, `archstrict.todo.json`, with a schema
+version and entries grouped by module name. Its own existence now means
+"the first run happened" - a project with no debt after its first run
+still gets the file, with an empty module map, so the ratchet's own state
+stays visible on disk. `.archstrict-todo-initialized` no longer exists.
+
+## What migrates, and when
+
+`archstrict todo` folds the old layout in automatically, the first time it
+runs after this change ships: it reads every legacy per-module file and
+the marker (if any), treats the result as a normal prune pass (never a
+fresh first run, since the debt was already frozen under the old layout),
+writes the new single file, then deletes every old file it read. A module
+whose own glob covers the project root itself (`"**"`) has its legacy
+per-module path collide with the new file's own path; that file is read,
+then overwritten in place with the new, schema-versioned shape - never
+queued for deletion, which would otherwise erase the migration in the same
+run that produced it.
+
+`archstrict check` reads the old layout too, until someone actually runs
+`archstrict todo` - so an adopted project already covered by the old
+layout keeps passing `check` across the upgrade, with a note in the report
+pointing at `archstrict todo` to migrate.

package/llms.txt

@@ -0,0 +1,19 @@
+# archstrict
+
+TypeScript module-boundary checker. A module is one directory, or one file, named in `archstrict.config.ts`. It shows the rest of the codebase one public-surface file; every other file inside it is private. Known violations freeze into one project-root `archstrict.todo.json`, grouped by module name, that can only shrink.
+
+It is not a type checker. It does not compile TypeScript, format code, or lint style.
+
+Agent skill: [skills/archstrict/SKILL.md](skills/archstrict/SKILL.md)
+
+Installed package: `node_modules/archstrict/skills/archstrict/SKILL.md` (this file sits beside it at `node_modules/archstrict/llms.txt`).
+
+## Commands
+
+- `archstrict init [dir] [--json]` — declare one module per top-level directory holding `.ts` and one per loose top-level `.ts` file, so the first `check` covers every file by construction; write `archstrict.types.ts` and, if missing, `archstrict.config.ts` (`schemaVersion: 1`)
+- `archstrict check [file] [--json] [--rule <id>] [--module <name>] [--frozen]` — report violations for the whole project; a file argument only scopes the report. Up to 20 violations print in full; more print grouped counts with one example each, plus a `do:` per group. `--rule`/`--module` narrow the printed and JSON violations (repeatable); the exit code reflects the filtered set once a filter is given. `--frozen` also includes todo-matched violations, marked `frozen: true` and exempt from the exit code, so a re-architecting agent can read a module's frozen debt through the same filters instead of opening its todo JSON by hand
+- `archstrict todo [--json]` — freeze current freezable violations on the first run, then only prune
+- `archstrict recommend [dir] [--json]` — `patternProposals`: at most 5 detected boundary patterns (layered order, app over library, leaf/pure kernel, external package confined to one area, test code kept out of production, public-entry-only, host/plugin inversion, feature isolation around a shared kernel), ranked by how strongly the real edges support each, with evidence, a pasteable config fragment, and how many violations adopting it would add today; `surfaceProposals`: for each surface-less module, a ranked list of the files other modules actually import from it and the smallest ranked prefix covering at least 80% of those imports, offered as a `surface` value alongside adding a barrel file or freezing the module private
+- `archstrict hotspots [--since <git ref or date>] [--json]` — combine Git change frequency and co-change with module fan-in, fan-out, frozen debt, and active violations
+
+A config or missing-file failure prints a `do:` line naming the command to run. With `--json` that failure is `{ "error": "<message>", "do": "<command>" }`.

package/package.json

@@ -1,12 +1,65 @@
 {
   "name": "archstrict",
-  "version": "0.0.0",
-  "description": "Reserved.",
+  "version": "0.1.0",
+  "description": "TypeScript module boundary checker: default-private module surfaces, layers, cycles, and a todo freeze that can only shrink.",
+  "keywords": [
+    "architecture",
+    "boundaries",
+    "typescript",
+    "lint",
+    "module",
+    "agent",
+    "claude-code"
+  ],
   "license": "MIT",
   "author": "meganemura",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meganemura/archstrict.git"
+  },
+  "homepage": "https://github.com/meganemura/archstrict#readme",
+  "bugs": {
+    "url": "https://github.com/meganemura/archstrict/issues"
+  },
   "type": "module",
+  "bin": {
+    "archstrict": "./dist/cli.js"
+  },
   "files": [
     "README.md",
-    "LICENSE"
-  ]
+    "README.ja.md",
+    "CHANGELOG.md",
+    "AGENTS.md",
+    "LICENSE",
+    "dist",
+    "docs",
+    "skills",
+    "llms.txt",
+    ".agents"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --testTimeout=60000",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "dogfood:nukadoko": "npm run build && nuka run features",
+    "ci:ts7-probe": "node scripts/probe-typescript7.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "@hegeldev/hegel": "0.4.5",
+    "@meganemura/depug": "0.1.3",
+    "@types/node": "26.5.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "nukadoko": "0.12.0",
+    "vitest": "5.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
 }