@massu/core 1.4.0 → 1.5.1

package/dist/hooks/user-prompt.js

@@ -292,6 +292,18 @@ var WatchConfigSchema = z.object({
   max_watched_files: z.number().int().positive().default(1e4),
   paths_full_root_opt_in: z.boolean().default(false)
 }).passthrough().optional();
+var AdapterLocalPathSchema = z.string().refine((s) => !/^([A-Za-z]:[\\/]|[\\/])/.test(s), {
+  message: "absolute paths are rejected; adapters.local entries must be relative to the massu.config.yaml directory"
+}).refine((s) => !s.split(/[\\/]/).includes(".."), {
+  message: "parent-directory traversal (`..`) is rejected; adapters.local entries must stay inside the project tree"
+}).transform((s) => s.split(/[\\/]/).filter((part) => part !== "" && part !== ".").join("/"));
+var AdaptersConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  local: z.array(AdapterLocalPathSchema).default([])
+}).passthrough().optional();
+var TelemetryConfigSchema = z.object({
+  adapters: z.boolean().default(false)
+}).passthrough().optional();
 var LSPConfigSchema = z.object({
   enabled: z.boolean().default(false),
   servers: z.array(z.object({
@@ -347,6 +359,10 @@ var RawConfigSchema = z.object({
   detected: DetectedConfigSchema,
   // Plan 3a: file-watcher daemon tunables
   watch: WatchConfigSchema,
+  // Plan 3c: third-party adapter registry kill-switch + signing override + local-path opt-in.
+  adapters: AdaptersConfigSchema,
+  // Plan 3c: anonymous adapter-discovery telemetry opt-in (default off).
+  telemetry: TelemetryConfigSchema,
   // Plan 3b Phase 4: optional LSP enrichment of AST adapter results.
   lsp: LSPConfigSchema.optional()
 }).passthrough();
@@ -458,6 +474,8 @@ Hint: run \`massu config refresh\` to regenerate a valid config or fix the liste
     detection: parsed.detection,
     detected: parsed.detected,
     watch: parsed.watch,
+    adapters: parsed.adapters,
+    telemetry: parsed.telemetry,
     lsp: parsed.lsp
   };
   if (!_config.cloud?.apiKey && process.env.MASSU_API_KEY) {

package/docs/AUTHORING-ADAPTERS.md

@@ -0,0 +1,207 @@
+# Authoring a Massu Adapter
+
+> Plan 3c gap-31 deliverable. Documents the adapter authoring workflow for
+> third-party `@massu/adapter-*` packages and project-local TypeScript
+> adapters listed in `massu.config.yaml > adapters.local`.
+
+## Quickstart
+
+```bash
+mkdir my-adapter && cd my-adapter
+npm init -y
+npm install --save-peer @massu/core
+```
+
+Edit `package.json`:
+
+```json
+{
+  "name": "@your-org/adapter-yourframework",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "massu-adapter": true,
+  "massu-adapter-api-version": "1",
+  "peerDependencies": { "@massu/core": ">=1.5.0 <2.0.0" }
+}
+```
+
+Create `src/index.ts`:
+
+```typescript
+import { defineAdapter, type CodebaseAdapter } from '@massu/core/adapter';
+
+export default defineAdapter({
+  id: 'your-framework',
+  languages: ['typescript'],
+
+  matches(signals) {
+    return Boolean(
+      signals.packageJson?.dependencies?.['your-framework'] ??
+      signals.packageJson?.devDependencies?.['your-framework'],
+    );
+  },
+
+  async introspect(files, rootDir) {
+    // Run Tree-sitter queries, walk ASTs, sample files…
+    // The runner has already pre-read `files`; do NOT re-read from disk inside introspect.
+    return {
+      conventions: {
+        router: 'your-framework',
+        // …whatever fields your framework's variant template consumes
+      },
+      provenance: [
+        // Each field's provenance: where in the codebase + which query found it.
+        { field: 'router', value: 'src/main.ts:12', query: 'package.json dependency' },
+      ],
+      confidence: 'high', // 'high' | 'medium' | 'low' | 'none'
+    };
+  },
+});
+```
+
+Build + publish:
+
+```bash
+npm run build
+npm pack          # smoke-test the tarball
+npm publish --access public
+```
+
+## The contract
+
+Every adapter package's default export MUST conform to `CodebaseAdapter`:
+
+```typescript
+interface CodebaseAdapter {
+  id: string;                                   // stable kebab-case id
+  languages: TreeSitterLanguage[];              // languages this adapter consumes
+  matches(signals: DetectionSignals): boolean;  // cheap signal check, NO file IO
+  introspect(files: SourceFile[], rootDir: string): Promise<AdapterResult>;
+}
+```
+
+`defineAdapter` is a no-op identity function at runtime; it exists so adapter
+authors get IDE autocomplete + compile-time type errors for missing or
+mistyped fields. Use it instead of `const adapter: CodebaseAdapter = { ... }`
+for cleaner author ergonomics.
+
+### `matches(signals)` rules
+
+- Cheap: NO file IO, NO async work, NO network. Returns `boolean` synchronously.
+- Idempotent: same `signals` input → same return.
+- The runner builds `signals` once per project scan and passes the same
+  reference to every adapter; do NOT mutate.
+
+### `introspect(files, rootDir)` rules
+
+- May be slow + async. The runner isolates failures (a thrown error in
+  one adapter does NOT abort the whole scan; the runner records it under
+  `MergedAdapterOutput.errored`).
+- `files` is pre-read by the runner. Re-reading from disk inside
+  `introspect` defeats the runner's sampling discipline + breaks tests.
+- Return per-field `provenance` so consumers can trace where each
+  convention came from. `confidence` is per-adapter for v1; field-level
+  confidence is reserved for a future major version.
+
+## Three trust classes
+
+The Massu adapter loader classifies every adapter into exactly one of three
+trust classes. Pick the right one for your adapter:
+
+| Class | When to use | Verification |
+|---|---|---|
+| **CORE-BUNDLED** | You contributed your adapter to `@massu/core` itself. | Inherits trust from `@massu/core`'s npm provenance. No per-load signature check. |
+| **REGISTRY-VERIFIED** | You publish `@your-org/adapter-yourframework` separately on npm. | Manifest at `https://registry.massu.ai/adapters/manifest.json` lists the package + per-version sha256. Loader verifies the Ed25519 manifest signature + per-package sha256 before loading. |
+| **LOCAL-EXPLICIT** | You have a project-internal TypeScript adapter that should NOT be published. | Listed in `massu.config.yaml > adapters.local` (POSIX-relative path). Loader checks the `~/.massu/adapters-local-fingerprint.json` sentinel — operator must run `massu adapters add-local <path>` to acknowledge each entry. |
+
+Choose REGISTRY-VERIFIED for any community-contributed adapter. The
+`@your-org/` prefix is up to you; the loader accepts any package whose
+`package.json` declares `"massu-adapter": true` and whose name matches a
+manifest entry.
+
+## Submitting a REGISTRY-VERIFIED adapter
+
+Adapter packages are added to the signed registry manifest by the Massu
+maintainer (`ethankowen-73`) via PR review. The flow:
+
+1. Author your package per the Quickstart above.
+2. Publish to npm: `npm publish --access public`.
+3. Open a PR against `https://github.com/massu-ai/massu` proposing the
+   manifest entry. The PR body should include:
+   - Package name + version
+   - sha256 of the published tarball (from `npm view <pkg>@<version> dist.shasum`)
+   - Brief description of what the adapter detects
+4. The maintainer reviews the package source, audits the introspect
+   logic for resource use + secrets handling, verifies the sha256 matches
+   the npm tarball, signs the updated manifest with the registry
+   Ed25519 key, and deploys to `https://registry.massu.ai`.
+
+Until the manifest is updated + redeployed, the loader will refuse your
+adapter with a "not in the signed registry manifest" error. There is no
+unsigned-loading bypass — the prior `allow_unsigned` config flag was
+removed in CR-9 audit C2 because it was a tripwire: parsed but never
+consulted by any callsite, creating a footgun for future contributors
+who might wire it incorrectly. Authors who want to test their adapter
+locally before the manifest is updated should use the LOCAL-EXPLICIT
+class instead (path entry in `adapters.local`), which is the supported
+operator-acknowledged loading path for in-development adapters.
+
+## LOCAL-EXPLICIT adapter authoring
+
+For project-internal adapters that you do not want to publish, list the
+TS file path under `adapters.local`:
+
+```yaml
+adapters:
+  local:
+    - adapters/internal-thing.ts
+```
+
+Then run:
+
+```bash
+npx massu adapters add-local adapters/internal-thing.ts
+```
+
+The CLI:
+1. Validates the path (rejects absolute paths + parent traversal; normalizes to POSIX).
+2. Appends to `massu.config.yaml > adapters.local` preserving comments.
+3. Updates `~/.massu/adapters-local-fingerprint.json` so the loader
+   recognizes the new entry as operator-acknowledged.
+
+To remove:
+
+```bash
+npx massu adapters remove-local adapters/internal-thing.ts
+```
+
+If you edit `massu.config.yaml > adapters.local` directly (instead of
+via the CLI), the loader will refuse to load any local adapter on the
+next run — it cannot tell whether the change was operator-intentional
+or a malicious postinstall script. To re-acknowledge the current state:
+
+```bash
+npx massu adapters resync-local-fingerprint
+```
+
+This is the only-supported escape hatch for "I edited the yaml directly
+and I trust the result."
+
+## Stability commitment
+
+Every export in `@massu/core/adapter` is part of the SemVer-stable surface.
+Breaking changes to `CodebaseAdapter` (renamed fields, removed methods)
+require a major version bump of `@massu/core` AND adapter packages
+declaring `"massu-adapter-api-version": "1"` will be refused at startup
+under the new major. This is intentional — the contract change requires
+adapter authors to opt-in to the new shape.
+
+Additive changes (new optional fields on result types, new
+TreeSitterLanguage enum entries) are minor-version compatible.
+
+## See also
+
+- [`SECURITY.md`](./SECURITY.md) — signing model, key rotation, supply-chain risks
+- [`@massu/core/adapter`](../src/adapter.ts) — the SDK source
+- Plan 3c (internal): adapter registry + supply-chain security architecture

package/docs/SECURITY.md

@@ -0,0 +1,250 @@
+# Security Model
+
+> Plan 3c gap-29, gap-47, gap-54, gap-61 deliverable. Documents the
+> Massu adapter trust model: signing, verification, key rotation, three
+> trust classes, and the supply-chain risks the design mitigates.
+
+## Threat model
+
+Massu adapters run **unsandboxed** inside the host Node process. An
+adapter that's compromised at install or load time can do anything the
+host process can do — read environment variables, write files, make
+outbound HTTP requests, etc. Sandboxing (Node `vm.Context` isolation
+or worker-thread separation with a defined adapter API surface) is a
+deferred 40h+ scope; for the foreseeable future, mitigations are
+**signature/sha-pinning + revocation**, not isolation.
+
+The supply-chain attack surface is the largest in the entire Plan 3
+series. The defenses are layered:
+
+1. **Three-class trust model** — every adapter classifies into exactly
+   one origin (CORE-BUNDLED / REGISTRY-VERIFIED / LOCAL-EXPLICIT).
+   Anything that doesn't classify refuses to load.
+2. **Signed manifest** — REGISTRY-VERIFIED adapters appear in a
+   per-release Ed25519-signed manifest at
+   `https://registry.massu.ai/adapters/manifest.json`. The signature
+   is verified against a public key bundled inside `@massu/core`.
+3. **Per-package sha256** — each manifest entry pins a sha256 of the
+   adapter's published tarball. Tampering with the unpacked package
+   in `node_modules` is detected at load time (gap-37 follow-up).
+4. **Postinstall-poisoning fingerprint** — `adapters.local` mutations
+   require an operator-CLI sentinel file. A malicious postinstall script
+   that mutates `massu.config.yaml > adapters.local` is detected at
+   startup; the loader refuses all local adapters until the operator
+   re-acknowledges via `massu adapters resync-local-fingerprint`.
+5. **Strict cache schema** — cached manifest at
+   `~/.massu/adapter-manifest.json` parses through Zod; corrupted or
+   unknown-shape entries are dropped without disclosing why.
+6. **Telemetry strictness** — the optional adapter-discovery telemetry
+   (off by default) emits ONLY four allowlisted fields, enforced at
+   write AND replay time by a `.strict()` Zod schema. PII keys are
+   rejected at write time, never persisted.
+
+## Three trust classes
+
+| Class | Trust derives from | Verification path |
+|---|---|---|
+| **CORE-BUNDLED** | `@massu/core`'s own npm publish + `prepublish-check.sh` audit + your `npm install @massu/core` choice | Skips signature verification (this IS the trusted baseline) |
+| **REGISTRY-VERIFIED** | The signed `manifest.json` at registry.massu.ai | Manifest sig + per-package sha256 + `signing_key_id` rotation drift detection |
+| **LOCAL-EXPLICIT** | The operator's per-path opt-in via `adapters.local` | `~/.massu/adapters-local-fingerprint.json` sentinel must match current config + be sourced from `cli` or `cli-resync` |
+
+The loader REFUSES to load any adapter that doesn't classify into exactly
+one class. Multi-class collisions (an id matching CORE-BUNDLED and
+LOCAL-EXPLICIT simultaneously) also refuse with a clear stderr warning
+naming all the matching classes.
+
+## Manifest signing
+
+The registry manifest envelope at
+`https://registry.massu.ai/adapters/manifest.json` has the following
+structure:
+
+```json
+{
+  "manifest":             { "manifest_schema_version": 1, "issued_at": "...", "adapters": [...] },
+  "manifest_b64":         "<base64 of the EXACT bytes that were signed>",
+  "signature":            "<base64 Ed25519 signature>",
+  "manifest_sha256":      "<sha256 hex of manifest_b64-decoded bytes>",
+  "signed_at":            "<ISO8601>",
+  "signing_key_id":       "<sha256 hex of the public key>"
+}
+```
+
+The `manifest_b64` field is required: it carries the byte-for-byte
+input that `nacl.sign.detached(msg, priv)` was invoked over. The
+verifier base64-decodes it, computes sha256, compares to
+`manifest_sha256`, JSON-parses, deep-equals against `manifest`,
+runs `nacl.sign.detached.verify` against the bundled public key, and
+verifies that `signing_key_id == sha256(bundled-pubkey)`. Any step
+failing → refuse the manifest. (The cache + the live registry both
+ship the same envelope shape.)
+
+## Adapter signing model
+
+For v1, **a single registry signing key signs the entire manifest**,
+including entries for `@massu/`-org-published adapter packages
+(rails, phoenix, aspnet, spring, go-chi) AND community contributions.
+The `signing_key_id` field is in the per-entry shape but always equals
+the same single registry key for v1; the field is reserved for a future
+federated model where individual adapter publishers countersign their
+own entries (deferred to a future major version).
+
+Implication for community contributors: a third-party developer
+publishing `@your-org/adapter-foo` on npm CANNOT have their package
+added to the signed manifest without the Massu maintainer's review +
+signature. The PR-to-manifest flow is documented in
+[`AUTHORING-ADAPTERS.md`](./AUTHORING-ADAPTERS.md) under "Submitting a
+REGISTRY-VERIFIED adapter."
+
+The maintainer (`ethankowen-73`) holds the signing key in macOS
+Keychain at `massu/registry/signing/private`. A backup maintainer
+documented in this file's "Succession" section below is the single-
+point-of-failure mitigation.
+
+## Key rotation
+
+The Ed25519 keypair is rotated annually OR on suspected compromise.
+Rotation procedure:
+
+1. Generate a new keypair via `tweetnacl` (operator-only, store private
+   in macOS Keychain replacing the prior entry).
+2. Update `packages/core/security/registry-pubkey.{pem,b64,env}` with
+   the new public key bytes in all 3 formats (PEM-wrapped, raw base64,
+   env-var format).
+3. Append the new RAW-bytes sha256 to `KNOWN_PUBKEY_FINGERPRINTS` in
+   `scripts/bundle-pubkey.mjs` (DO NOT remove the old entry — rotation
+   grace window).
+4. Run `bash scripts/bundle-pubkey.mjs` to regenerate
+   `packages/core/src/security/registry-pubkey.generated.ts`.
+5. Sign a transition manifest **countersigned by both old AND new keys**
+   so consumers running pre-rotation `@massu/core` can still verify
+   under the old key during the grace window. (The Phase 5 verifier
+   accepts manifests countersigned by ANY entry in the `KNOWN_PUBKEY_FINGERPRINTS`
+   allowlist during the rotation grace window.)
+6. Ship a new `@massu/core` minor release bundling the new pubkey;
+   document the rotation in the release CHANGELOG.
+7. Old-key-only verification remains accepted until the NEXT minor
+   release after rotation, at which point old-key entries are removed
+   from `KNOWN_PUBKEY_FINGERPRINTS`.
+
+The cached manifest at `~/.massu/adapter-manifest.json` records the
+`bundled_pubkey_fingerprint` of the @massu/core that wrote the cache.
+On read, if the cache's fingerprint != currently-running @massu/core's
+bundled pubkey fingerprint, the cache is treated as STALE-DUE-TO-ROTATION
+and the loader forces a fresh fetch from the registry. This catches the
+upgrade case where an operator runs `npm install -g @massu/core@latest`
+mid-rotation and would otherwise hold a manifest signed under the old
+key.
+
+## Postinstall-poisoning defense
+
+`adapters.local` listings bypass the registry-signed allowlist (operators
+opt-in per-path). To prevent malicious npm postinstall scripts from
+mutating `adapters.local` to inject attacker-controlled paths, the
+loader checks a sentinel file at `~/.massu/adapters-local-fingerprint.json`:
+
+```json
+{
+  "fingerprint": "<sha256 hex of canonical-stringified sorted adapters.local array>",
+  "source":      "cli" | "cli-resync",
+  "ts":          "<ISO8601>"
+}
+```
+
+Any time the operator runs `massu adapters add-local <path>`, `massu adapters
+remove-local <path>`, or `massu adapters resync-local-fingerprint`, the
+sentinel is updated with `source: "cli"` (or `cli-resync`). At loader
+startup, the current `massu.config.yaml > adapters.local` content's
+fingerprint is compared to the sentinel:
+
+- **Match** → proceed to load LOCAL-EXPLICIT adapters.
+- **Drift OR sentinel absent** → REFUSE all LOCAL-EXPLICIT adapters
+  with a stderr warning naming the divergence + pointing the operator
+  at `massu adapters resync-local-fingerprint`.
+
+A malicious postinstall script could, in principle, also mutate the
+sentinel. Mitigations:
+
+- The sentinel is mode `0o600` (owner-only). A postinstall script running
+  as the same user CAN write to it, but doing so requires advance
+  knowledge of the file format AND the canonical-fingerprint scheme. The
+  schema is `.strict()`, so any unknown-key write is rejected at
+  read time (treated as "no sentinel").
+- A future hardening (gap-32 follow-up) could require a HMAC over the
+  sentinel using a key only the CLI knows, but the CLI is itself
+  operator-installed, so HMAC keys would need to derive from operator
+  state outside the npm tree.
+
+## Telemetry posture
+
+Telemetry is **off by default**. Enable via:
+
+```yaml
+telemetry:
+  adapters: true
+```
+
+When enabled, the adapter-discovery writer emits ONE JSONL line per
+discovery event matching this schema (`.strict()` so unknown keys are
+rejected):
+
+```typescript
+{
+  adapter_id: string;     // canonical id (e.g. "@massu/adapter-rails")
+  count:      number;     // discovery events observed in this batch
+  version:    string;     // adapter version when known
+  ts:         string;     // ISO8601
+}
+```
+
+Specifically:
+
+- File paths are NEVER sent.
+- Symbol names are NEVER sent.
+- Source code content is NEVER sent.
+- Project names are NEVER sent.
+- Operator identity is NEVER sent.
+
+The transport is HTTPS POST to `https://telemetry.massu.ai/adapter-discovery`
+through the same allowlisted fetcher (`packages/core/src/security/fetcher.ts`)
+that the registry uses. Pending events buffer at
+`~/.massu/telemetry-pending.jsonl` (mode `0o600`) when the endpoint is
+unreachable, with a 1MB / 1000-entry hard cap. Replay re-validates every
+entry against the same `.strict()` schema before sending; entries that
+fail re-validation are dropped without sending. Disabling telemetry
+mid-flight stops both new records AND any pending replay.
+
+## Succession
+
+The npm `@massu` org is currently owned by `ethankowen-73`. Backup
+maintainer assignment (open action — required before Phase 9
+publish per the canonical plan): a second account must hold
+`Maintainer` role on the `@massu` org so deprecate / unpublish capability
+is not single-point-of-failure on holiday or illness. Verify via
+`npm org ls @massu` showing ≥2 maintainers before the next minor
+release ships.
+
+## Reporting a vulnerability
+
+If you discover a supply-chain or signing-flow vulnerability in
+`@massu/core` or any registry-listed adapter, do NOT open a public
+GitHub issue. Email `security@massu.ai` with the details (mailbox
+provisioning is an open action — required before Phase 9 publish
+per the canonical plan). The maintainer will:
+
+1. Acknowledge within 48h.
+2. Investigate + reproduce.
+3. Issue a CVE if confirmed.
+4. Publish a patched `@massu/core` release with `npm deprecate` on the
+   affected versions.
+5. Add the affected adapter to the manifest's `unpublished: true` list
+   if applicable, so all consumers refuse to load on next refresh.
+
+## See also
+
+- [`AUTHORING-ADAPTERS.md`](./AUTHORING-ADAPTERS.md) — how to write a
+  conformant adapter
+- `packages/core/src/security/` — the verifier, fetcher, atomic-write,
+  fingerprint, and cache modules implementing this model
+- Plan 3c (internal): full architectural background + threat-model
+  decisions

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@massu/core",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "type": "module",
   "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 72 total), 55+ workflow commands, 11 agents, 20+ patterns",
   "main": "src/server.ts",
+  "exports": {
+    ".": "./src/server.ts",
+    "./adapter": "./src/adapter.ts"
+  },
   "bin": {
     "massu": "./dist/cli.js"
   },
@@ -13,7 +17,7 @@
     "build": "tsc --noEmit && npm run build:cli && npm run build:hooks",
     "build:cli": "esbuild --bundle --platform=node --format=esm --outfile=dist/cli.js src/cli.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --banner:js='#!/usr/bin/env node\nimport{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
     "build:hooks": "esbuild --bundle --platform=node --format=esm --outdir=dist/hooks src/hooks/*.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --banner:js='import{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
-    "prepublishOnly": "bash ../../scripts/prepublish-check.sh && npm run build",
+    "prepublishOnly": "bash ../../scripts/prepublish-check.sh && node ../../scripts/bundle-pubkey.mjs && npm run build",
     "bench:watch": "tsx test/perf/watch-benchmark.ts"
   },
   "dependencies": {
@@ -26,7 +30,7 @@
     "tar": "^7.4.3",
     "tweetnacl": "^1.0.3",
     "vscode-languageserver-protocol": "^3.17.5",
-    "web-tree-sitter": "^0.26.8",
+    "web-tree-sitter": "~0.25.10",
     "yaml": "^2.4.0",
     "zod": "^3.23.0"
   },

package/src/adapter.ts

@@ -0,0 +1,90 @@
+/**
+ * `@massu/core/adapter` — public adapter authoring SDK (Plan 3c gap-31, gap-35).
+ *
+ * Adapter authors import from this subpath ONLY; everything inside @massu/core
+ * outside this entry point is implementation detail subject to change without
+ * a major version bump. The contract surface here is part of the SemVer-
+ * stable API.
+ *
+ * Usage (adapter package author):
+ *
+ *   import { defineAdapter, type CodebaseAdapter } from '@massu/core/adapter';
+ *
+ *   export default defineAdapter({
+ *     id: 'rails-active-record',
+ *     languages: ['ruby'],
+ *     matches(signals) {
+ *       return Boolean(signals.gemfile?.includes('rails'));
+ *     },
+ *     async introspect(files, rootDir) {
+ *       // Tree-sitter queries, AST walks, file sampling…
+ *       return {
+ *         conventions: { router: 'rails' },
+ *         provenance: [{ field: 'router', value: 'config/routes.rb:1', query: 'gemfile' }],
+ *         confidence: 'high',
+ *       };
+ *     },
+ *   });
+ *
+ * Then in the adapter package's package.json:
+ *   {
+ *     "name": "@massu/adapter-rails",
+ *     "version": "0.1.0",
+ *     "main": "dist/index.js",
+ *     "type": "module",
+ *     "massu-adapter": true,
+ *     "massu-adapter-api-version": "1",
+ *     "peerDependencies": { "@massu/core": ">=1.5.0 <2.0.0" }
+ *   }
+ *
+ * The adapter loader (Plan 3b runner.ts) does
+ *   const mod = await import(`<package-dir>/${main}`);
+ *   const adapter = (mod.default ?? mod) as CodebaseAdapter;
+ * and dispatches matches() + introspect() accordingly.
+ *
+ * defineAdapter is a NO-OP at runtime — it's an identity function that
+ * exists for compile-time type narrowing (so adapter authors get IDE
+ * autocomplete + type errors for missing fields). The factory's only job
+ * is to anchor the type contract; it does NOT validate at runtime, register
+ * anywhere, or mutate state. Runtime validation happens at the loader
+ * (Plan 3b runner.ts) which checks the dispatched object shape before
+ * invoking matches/introspect.
+ *
+ * Stability: every export here is part of @massu/core's public SemVer
+ * surface. Breaking changes to the CodebaseAdapter shape (renamed fields,
+ * removed methods) require a major version bump per the
+ * massu-adapter-api-version contract. Adapter packages declare
+ * `"massu-adapter-api-version": "1"` so the loader refuses incompatible
+ * majors at startup.
+ */
+
+export {
+  // The contract every adapter package must implement.
+  type CodebaseAdapter,
+  // Inputs the runner provides to matches() / introspect().
+  type DetectionSignals,
+  type SourceFile,
+  type TreeSitterLanguage,
+  // Output shapes from introspect() + the runner's merge step.
+  type AdapterResult,
+  type Provenance,
+  type AdapterResolved,
+  type MergedAdapterOutput,
+} from './detect/adapters/types.js';
+
+import type { CodebaseAdapter } from './detect/adapters/types.js';
+
+/**
+ * Identity factory — narrows the input's type to `CodebaseAdapter` so
+ * authors get compile-time checking + IDE autocomplete for missing /
+ * mistyped fields. Runtime: returns the input unchanged. Use this in
+ * place of an inline `const adapter: CodebaseAdapter = { ... }`
+ * annotation.
+ *
+ * Returning the input (instead of `void`) means adapter packages can do
+ * `export default defineAdapter({ ... })` and the loader's
+ * `mod.default` destructuring just works.
+ */
+export function defineAdapter(spec: CodebaseAdapter): CodebaseAdapter {
+  return spec;
+}

package/src/cli.ts

@@ -73,6 +73,12 @@ async function main(): Promise<void> {
       await handleConfigSubcommand(args.slice(1));
       break;
     }
+    case 'adapters': {
+      const { handleAdaptersSubcommand } = await import('./commands/adapters.ts');
+      const result = await handleAdaptersSubcommand(args.slice(1));
+      process.exit(result.exitCode);
+      return;
+    }
     case '--help':
     case '-h': {
       printHelp();
@@ -162,6 +168,7 @@ Commands:
   refresh-log [N]   Show the last N watcher auto-refresh events
   validate-config   Validate massu.config.yaml (alias: config validate)
   config <sub>      Config lifecycle: refresh | validate | upgrade | doctor | check-drift
+  adapters <sub>    Third-party adapter registry: list | refresh | search | add-local | remove-local | install | resign
 
 Options:
   --help, -h        Show this help message