[CLI] META-247 — land the ratified neutral package architecture

.github/workflows/ci.yml

@@ -31,23 +31,32 @@ jobs:
       - name: Architecture guard red tests
         run: node scripts/check-architecture.test.mjs
 
-      - name: Typecheck all packages
-        run: pnpm -r typecheck
-
+      # Build precedes typecheck. `agents-audit` consumes @workspacejson/cli's
+      # emitted declarations, so on a clean checkout those must exist before tsc
+      # can resolve them. pnpm builds in topological order, so the neutral
+      # package is built first.
       - name: Build all packages
         run: pnpm -r build
 
+      - name: Typecheck all packages
+        run: pnpm -r typecheck
+
       - name: Run tests
         run: pnpm -r test
 
       - name: Verify package tarballs
         run: pnpm run release:verify-packs
 
-      # This repository owns and exports agents-audit only. @workspacejson/spec
-      # and @workspacejson/rules are consumed as released dependencies and are
-      # verified by workspacejson/standard, not here.
+      # This repository owns @workspacejson/cli and agents-audit.
+      # @workspacejson/spec and @workspacejson/rules are consumed as released
+      # dependencies and are verified by workspacejson/standard, not here.
       - name: Validate package exports
-        run: node -e "import('agents-audit')"
+        run: |
+          node -e "import('@workspacejson/cli')"
+          node -e "import('agents-audit')"
+
+      - name: Run the neutral producer on this repo
+        run: node packages/cli/dist/cli.js generate --check || true
 
       - name: Run agents-audit on this repo
-        run: node packages/agents-audit/dist/cli.js scan . --fail-on error
+        run: node packages/agents-audit-compat/dist/cli.js scan . --fail-on error

AGENTS.md

@@ -1,8 +1,9 @@
 # Workspace Notes
 
-- This repository holds two distinct CLI packages. `./packages/agents-audit/` is the published `agents-audit` package and contains the real workspace.json generator (`./packages/agents-audit/src/generate.ts`). `./packages/cli/` is the private `@workspacejson/cli` DataHub/dbt join shim and is not the generator.
-- Keep package entry points aligned with `./packages/agents-audit/src/index.ts` and `./packages/cli/src/index.ts`.
-- Review changes against `./packages/agents-audit/src/cli.ts` before release.
+- This repository holds three packages. `./packages/cli/` is `@workspacejson/cli`, the neutral workspace.json producer — generation lives in `./packages/cli/src/producer/` and command routing in `./packages/cli/src/commands/`. `./packages/agents-audit-compat/` is the published `agents-audit` compatibility package. `./packages/datahub-adapter/` is a private DataHub/dbt adapter staged here pending extraction to `workspacejson/datahub-agent`.
+- Keep package entry points aligned with `./packages/cli/src/index.ts` and `./packages/agents-audit-compat/src/index.ts`.
+- `agents-audit` is a frozen compatibility bridge. Do not add features to it; both binaries route through `./packages/cli/src/commands/generate.ts` so they cannot drift.
 - `@workspacejson/spec` and `@workspacejson/rules` are consumed as released packages from `workspacejson/standard`; never vendor, copy or workspace-link them here.
 - Keep workspace metadata in `./CHANGELOG.md` and `./README.md` current.
 - Workspace layout is defined in `./pnpm-workspace.yaml`; repository boundaries are defined in `./OWNERSHIP.md` and enforced by `./scripts/check-architecture.mjs`.
+- Compatibility is gated by the parity harnesses in `./migration/`. Run them before changing anything `agents-audit` exposes.

CONTRIBUTING.md

@@ -7,21 +7,24 @@ released packages — do not vendor or edit them here.
 ## Before You Start
 
 - Read `AGENTS.md` and `OWNERSHIP.md` at the repo root
-- Know which of the two CLI packages you are changing:
-  - `packages/agents-audit/` — published `agents-audit`, contains the real generator
-  - `packages/cli/` — private `@workspacejson/cli`, the DataHub/dbt join shim
+- Know which package you are changing:
+  - `packages/cli/` — `@workspacejson/cli`, the neutral producer (`src/producer/`) and its commands (`src/commands/`)
+  - `packages/agents-audit-compat/` — published `agents-audit`, a **frozen** compatibility bridge; do not add features to it
+  - `packages/datahub-adapter/` — private DataHub/dbt adapter, staged here pending extraction to `workspacejson/datahub-agent`; do not build on it
 - Keep changes within the owning package when possible
 - Avoid changing package entrypoints unless the public surface changes
 
 ## Common Commands
 
 ```bash
 pnpm install
-pnpm typecheck
+pnpm build          # must precede typecheck on a clean checkout: agents-audit
+pnpm typecheck      # consumes @workspacejson/cli's emitted declarations
 pnpm test
-pnpm build
 pnpm run check:architecture
-node packages/agents-audit/dist/cli.js scan .
+node scripts/check-architecture.test.mjs
+node packages/agents-audit-compat/dist/cli.js scan .
+node packages/cli/dist/cli.js generate --check
 ```
 
 ## Change Expectations

OWNERSHIP.md

@@ -1,70 +1,112 @@
 # Ownership — `workspacejson/cli`
 
-Machine-checked by `scripts/check-architecture.mjs`, run in CI. This document
-states the intent; the script is what enforces it.
+Machine-checked by `scripts/check-architecture.mjs`, run in CI with red tests in
+`scripts/check-architecture.test.mjs`. This document states the intent; the
+script is what enforces it.
+
+## Packages
+
+| Directory | Package | Distribution | Role |
+| -- | -- | -- | -- |
+| `packages/cli/` | `@workspacejson/cli` | public, **not yet published** | the neutral workspace.json producer and its `workspacejson` binary |
+| `packages/agents-audit-compat/` | `agents-audit` | public, published `0.4.4` | frozen compatibility bridge for the historical `agents-audit` command and API |
+| `packages/datahub-adapter/` | `@workspacejson/datahub-adapter` | **private, never published** | **migration staging only** — see below |
 
 ## Owns
 
-* Producer and audit CLI implementation (`packages/agents-audit/`)
-* Repository scanning, deterministic generation and reconciliation of
-  `.agents/workspace.json`
-* Manual-evidence preservation, drift detection and atomic-write behavior
-* The DataHub/dbt adapter package (`packages/cli/`)
+* The neutral producer: deterministic generation, repository scanning,
+  reconciliation, manual-evidence preservation, atomic writes, drift detection
+  (`packages/cli/src/producer/`)
+* Public command routing and CLI UX (`packages/cli/src/commands/`)
+* The historical `agents-audit` audit behavior and its compatibility surface
 * CLI package distribution and the CLI release workflow
 
 ## Consumes
 
 * Released public contracts from `workspacejson/standard`:
-  `@workspacejson/spec`, `@workspacejson/rules` — pinned to registry-backed
+  `@workspacejson/spec`, `@workspacejson/rules` — pinned to exact registry
   versions, never workspace links or sibling checkouts
 
 ## Must never define
 
-* The normative schema or specification text — that is `workspacejson/standard`
-* MCP, Codex, VS Code or other editor/host integration behavior — that is
+* The normative schema or specification text — `workspacejson/standard`
+* MCP, Codex, VS Code or other editor/host integration behavior —
   `workspacejson/integrations`
-* Site content as a source of truth — that is `workspacejson/site`
+* Site content as a source of truth — `workspacejson/site`
+* **DataHub-specific consumption, joining, orchestration or evaluation** —
+  `workspacejson/datahub-agent`
 * Private product behavior of any kind
 
+## `packages/datahub-adapter/` is staging, not architecture
+
+This package is **not durable CLI architecture**. It is the DataHub/dbt adapter
+migrated intact from the `agents-audit` monorepo, parked here only because
+META-240 had to preserve it somewhere while its permanent owner was decided.
+
+It is a **consumer** adapter — it reads an existing `.agents/workspace.json` and
+joins dbt models against `generated.fileIndex`. That is DataHub consumer logic,
+not neutral producer logic, and it belongs to `workspacejson/datahub-agent`.
+
+Until it is extracted:
+
+* it stays `private: true` and is never published;
+* the neutral CLI **must not depend on it** — the dependency direction is
+  one-way and the guard enforces it;
+* it is not polished, documented or advertised as a CLI-owned package;
+* it does not appear in the durable CLI package map.
+
+Its 35/35 parity harness (`migration/parity-datahub-shim.mjs`) travels with it
+and must pass against the DataHub-owned candidate after extraction.
+
+**Do not confuse this adapter with a hypothetical `workspacejson signals
+datahub` producer surface.** They run in opposite directions: this adapter
+consumes the artifact; a signals surface would produce DataHub-specific
+evidence. No such producer surface is admitted, and none may be added without an
+explicit ADR-002 Gate A ruling.
+
 ## Dependency direction
 
 ```text
 workspacejson/standard
         ↓
-workspacejson/cli       workspacejson/integrations
-        \                    /
+workspacejson/cli ──→ agents-audit (compat)
+        ↑
+        │  (consumes released contracts and the public CLI interface)
+workspacejson/integrations      workspacejson/datahub-agent
+        \                              /
               workspacejson/site
 ```
 
-This repository depends **downstream only**. It must never be imported by
-`workspacejson/standard`.
+Within this repository: `agents-audit` depends on `@workspacejson/cli`. Never
+the reverse. `@workspacejson/datahub-adapter` depends on neither.
 
 ## Clean-room boundary
 
-No code in this repository may import, copy, require or assume:
+No code here may import, copy, require or assume:
 
 ```text
 @marcelle-labs/*
 private Vreko source
 workspace.vreko.json
 ```
 
-Proprietary repositories may consume released Apache-2.0 `@workspacejson/*`
-packages. The reverse direction is prohibited.
+Additionally, `packages/cli/` must contain **no** vendor- or host-specific
+content at all — no DataHub, dbt or Vreko logic, by filename or by content.
+Guard: `neutral-producer-purity`.
 
 ## Publish authority
 
 | Package | Publishable from here | Current authority |
 | -- | -- | -- |
-| `agents-audit` | Metadata says yes; **workflow disabled** | `workspace-json/agents-audit` until META-243 |
-| `@workspacejson/cli` | **No** — `private: true`, must not be published | none (unpublished by design) |
-| `@workspacejson/spec` | **Never** — not owned here | `workspacejson/standard` |
-| `@workspacejson/rules` | **Never** — not owned here | `workspacejson/standard` |
+| `agents-audit` | metadata says yes; **workflow disabled** | `workspace-json/agents-audit` until META-243 |
+| `@workspacejson/cli` | metadata says yes; **workflow disabled, never published** | none yet — META-243 |
+| `@workspacejson/datahub-adapter` | **No** — private, and leaving this repository | none |
+| `@workspacejson/spec`, `@workspacejson/rules` | **Never** — not owned here | `workspacejson/standard` |
 
-This repository holds no publish-capable secret. Authority transfer is
-META-243's job, not this repository's.
+This repository holds no publish-capable secret.
 
 ## Migration source and provenance
 
 Extracted from `workspace-json/agents-audit@e47eb1b8556c4f361db9a78190a2f36b400756e8`
-on 2026-07-26 under META-240. See [`migration/PROVENANCE.md`](./migration/PROVENANCE.md).
+on 2026-07-26 under META-240; restructured to the ratified architecture under
+META-247. See [`migration/PROVENANCE.md`](./migration/PROVENANCE.md).

README.md

@@ -1,77 +1,70 @@
 # workspacejson/cli
 
-CLI distribution for the **workspace.json** standard: repository scanning,
-deterministic generation and reconciliation of `.agents/workspace.json`, and
-CLI-side adapters.
+CLI distribution for the **workspace.json** standard: repository scanning and
+deterministic generation of `.agents/workspace.json`.
 
 This repository owns the *producer implementation and its executables*. It does
-not own the specification. The normative schema, rules and contracts live in
-[`workspacejson/standard`](https://github.com/workspacejson/standard); this
-repository consumes them as released packages.
+not own the specification — the normative schema, rules and contracts live in
+[`workspacejson/standard`](https://github.com/workspacejson/standard) and are
+consumed here as released packages.
 
-## The generator command today
+> **Status: pre-release.** The architecture below landed in META-247 and is the
+> ratified target shape, but nothing here is published yet and the public
+> documentation is deliberately unfinished. The working command today is
+> `npx agents-audit generate`.
 
-```bash
-npx agents-audit generate
-```
-
-That is the real, published, working command for producing
-`.agents/workspace.json`. It is implemented in
-[`packages/agents-audit/`](./packages/agents-audit/) and published to npm as
-[`agents-audit`](https://www.npmjs.com/package/agents-audit).
+## Packages
 
-```bash
-agents-audit scan .              # audit AGENTS.md hygiene
-agents-audit generate            # write .agents/workspace.json
-agents-audit generate --dry-run  # print the projection, write nothing
-agents-audit generate --check    # non-writing drift gate for CI
-agents-audit generate --force    # recover from an invalid existing artifact
-```
+| Directory | Package | Published? | Role |
+| -- | -- | -- | -- |
+| [`packages/cli/`](./packages/cli/) | `@workspacejson/cli` | **No — not yet on npm** | the neutral producer and its `workspacejson` binary |
+| [`packages/agents-audit-compat/`](./packages/agents-audit-compat/) | `agents-audit` | **Yes — `0.4.4`** | frozen compatibility bridge; preserves the historical command and API |
 
-## This repository contains two different CLI packages
+`packages/datahub-adapter/` also exists but is **not part of this repository's
+architecture** — it is a private DataHub/dbt adapter staged here pending
+extraction to `workspacejson/datahub-agent`, which owns DataHub consumption. See
+[`OWNERSHIP.md`](./OWNERSHIP.md).
 
-They are **not** the same tool, and one of them is not installable.
+## Generating the artifact
 
-| Directory | Package | Published? | What it actually does |
-| -- | -- | -- | -- |
-| [`packages/agents-audit/`](./packages/agents-audit/) | `agents-audit` | **Yes — public, `0.4.4`** | `AGENTS.md` audit **and the current workspace.json producer**. Binary: `agents-audit`. |
-| [`packages/cli/`](./packages/cli/) | `@workspacejson/cli` | **No — `private: true`, not on npm** | A DataHub/dbt adapter: normalizes dbt model paths to repository-root-relative keys and joins them against an existing `generated.fileIndex`. Binary declared as `workspacejson`, but the package is not distributed. |
+Today, the command that works is the compatibility one:
 
-### `packages/cli` is not the generator
+```bash
+npx agents-audit generate
+```
 
-The directory being named `cli` and the package being named
-`@workspacejson/cli` is misleading, and it has misled before. It contains no
-generation logic. It reads a `.agents/workspace.json` that something else
-already produced. If you are looking for the code that *writes* the artifact,
-it is `packages/agents-audit/src/generate.ts`.
+Once `@workspacejson/cli` is published, the neutral equivalent is:
 
-### Do not advertise `@workspacejson/cli` as installable
+```bash
+workspacejson generate            # write .agents/workspace.json
+workspacejson generate --dry-run  # print the projection, write nothing
+workspacejson generate --check    # non-writing drift gate for CI
+workspacejson generate --force    # recover from an invalid existing artifact
+```
 
-`npm install @workspacejson/cli` does not work and is expected not to work —
-the package is `private: true` and returns `E404` from the registry. Any
-documentation, extension text or integration guide that tells a user to install
-it is wrong.
+Both routes run **the same implementation** — `agents-audit` delegates to
+`@workspacejson/cli`, so the two binaries cannot drift apart during the
+compatibility window.
 
-## The future neutral CLI identity is undecided
+`agents-audit` additionally keeps its audit commands (`scan`, `version`) and all
+nine of its historical public exports.
 
-Whether a neutral producer package appears, whether `agents-audit` becomes a
-compatibility bridge or stays a distinct audit product, and what happens to the
-private DataHub shim are **open questions**, tracked in
-[META-236](https://linear.app/marcelle-labs/issue/META-236). Nothing in this
-repository should be read as having settled them. Until META-236 is ratified,
-the answer to "what does a cold user run?" is `npx agents-audit generate`.
+## Compatibility guarantee
 
-## Ownership boundaries
+`agents-audit` is a **frozen bridge**: its package name, binary, commands, exit
+codes, output and exported API are unchanged, and it gets no new features. The
+guarantee is enforced by executable parity harnesses in
+[`migration/`](./migration/), which run real packed candidates from before and
+after each change:
 
-| Repository | Owns |
-| -- | -- |
-| [`workspacejson/standard`](https://github.com/workspacejson/standard) | specification, JSON Schema, rules, ADRs, conformance fixtures — **contract authority** |
-| **`workspacejson/cli`** (this repo) | producer/audit CLI implementation, repository scanning, generation, CLI distribution |
-| [`workspacejson/integrations`](https://github.com/workspacejson/integrations) | MCP, Codex, VS Code, host adapters |
-| [`workspacejson/site`](https://github.com/workspacejson/site) | `workspacejson.dev` presentation and documentation assembly |
+```bash
+migration/parity-agents-audit-runtime.sh   # 29/29 producer behavior
+migration/parity-datahub-shim.mjs          # 35/35 adapter behavior
+```
 
-This repository contains **no** normative schema copy, **no** host-integration
-implementation, and **no** site implementation. See [`OWNERSHIP.md`](./OWNERSHIP.md).
+Removing the compatibility package is gated on downstream consumers — Buildomator,
+the VS Code extension, MCP installers and documentation — moving to the neutral
+command first.
 
 ## Development
 
@@ -80,26 +73,28 @@ pnpm install
 pnpm typecheck
 pnpm build
 pnpm test
-pnpm run check:architecture     # clean-room and repository-boundary guards
-pnpm run release:verify-packs   # packed-tarball verification for agents-audit
+pnpm run check:architecture                 # boundary and clean-room guards
+node scripts/check-architecture.test.mjs    # deliberate-violation red tests
+pnpm run release:verify-packs               # packed-tarball verification
 ```
 
 Requires Node.js >= 20.
 
 ## Publishing
 
-**Publishing from this repository is currently disabled.** The release workflow
-is non-authoritative and cannot publish: it holds no npm credential and exits
-before any publish step. `workspace-json/agents-audit` remains the sole publisher
-of `agents-audit` until the coordinated authority cutover in
-[META-243](https://linear.app/marcelle-labs/issue/META-243).
+**Publishing from this repository is disabled.** The release workflow has no
+enabled trigger, holds no npm credential and contains no publish step.
+`workspace-json/agents-audit` remains the sole publisher of `agents-audit` until
+the coordinated authority cutover in META-243.
+
+`@workspacejson/cli` has never been published. Do not document
+`npm install @workspacejson/cli` as if it works.
 
 ## Provenance
 
 Extracted with full history from
 `workspace-json/agents-audit@e47eb1b8556c4f361db9a78190a2f36b400756e8`.
-See [`migration/PROVENANCE.md`](./migration/PROVENANCE.md) for the extraction
-command, old→new commit mapping, included/excluded paths and rollback procedure.
+See [`migration/PROVENANCE.md`](./migration/PROVENANCE.md).
 
 ## License
 

migration/parity-agents-audit-pack.sh

@@ -4,7 +4,7 @@ set -uo pipefail
 
 SCRATCH="/private/tmp/claude-502/-Users-user1-dev-cli/ed967700-e9b4-4202-b983-6faf9cee9f6d/scratchpad"
 OLD="$SCRATCH/source-agents-audit/packages/agents-audit"
-NEW="$SCRATCH/cli-extract/packages/agents-audit"
+NEW="$SCRATCH/cli-extract/packages/agents-audit-compat"
 OUT="$SCRATCH/parity"
 mkdir -p "$OUT/old" "$OUT/new"