[MIGRATION] META-240 — extract producer and DataHub shim into workspacejson/cli

[qmarcelle]

Extracts the CLI slice of the four-repository migration into workspacejson/cli, with history preserved and parity proven separately for each of the two CLI packages.

Linear: META-240 (child of META-237, gated on META-238). Ledger: Four-repository migration ledger.

Move first. Prove parity. Transfer authority later. Redesign second.

---

Frozen source

repository:  workspace-json/agents-audit  (public)
branch:      main
SHA:         e47eb1b8556c4f361db9a78190a2f36b400756e8
head commit: merge of PR #23 — feat(agents-audit): land deferred generate display behaviors (META-157)

Re-measured with git rev-parse HEAD against a clean clone. Not inherited from the earlier note — it happened to match.

META-138 contamination gate re-run (not assumed from its Done state), across --all --full-history: .vreko-swarm, agents-workspace-cannon-repo, vreko-gtm-strategy.md, vreko-architecture.md, launch-posture.md, workspace.vreko.json, and -S'@marcelle-labs' all return nothing. Clean.

Extraction method

git filter-repo path filter, then a reconstructed repository root. 124 commits → 51 commits; full old→new mapping committed at migration/commit-map.txt (133 entries, 53 preserved / 79 dropped). Exact command in migration/PROVENANCE.md.

Fidelity verified before any reconstruction — extracted trees are byte-identical to the frozen source:

packages/agents-audit  3266ed425e6f5ad29a50c8b13759518955b4c473  IDENTICAL
packages/cli           fcd97c028c70639d89f23bbc78db0e396f2abaad  IDENTICAL
types                  80ee90072829feade3d84742502f215f8ce2893c  IDENTICAL

Excluded-path leak check: 0 commits for packages/spec, packages/rules, docs/, assets/, .planning/, .agents/, pnpm-lock.yaml, root README.md/CHANGELOG.md/AGENTS.md.

This PR's base (main) is the raw extraction; the diff is exactly the repository-root reconstruction.

Current → target paths

Source (at frozen SHA)	Target	Action
packages/agents-audit/**	packages/agents-audit/**	copy, history-preserved
packages/cli/**	packages/cli/**	copy, history-preserved
scripts/verify-package-tarball.mjs	same	adapt — sibling packing
scripts/verify-published.mjs	same	adapt — CLI-owned only
scripts/verify-npm-publish-access.mjs	same	copy
types/ambient.d.ts	same	copy, byte-identical
tsconfig.base.json	same	adapt — drop rules path alias
pnpm-workspace.yaml, .npmrc, .gitignore, .changeset/README.md, .github/ISSUE_TEMPLATE/**, .github/pull_request_template.md, CODE_OF_CONDUCT.md	same	copy
package.json, README.md, CHANGELOG.md, AGENTS.md, CONTRIBUTING.md, SECURITY.md, .changeset/config.json, .github/workflows/*	same	rebuild/adapt as CLI-owned
packages/spec/**, packages/rules/**	—	exclude → META-239
docs/audits/**, .planning/**, assets/**, .agents/workspace.json, pnpm-lock.yaml	—	exclude

The two CLI packages remain distinct

This is the load-bearing constraint of META-240, and nothing here merges, renames, or republishes either package.

Directory	Package	State	Actual responsibility
packages/agents-audit/	agents-audit@0.4.4	public	AGENTS.md audit and the real workspace.json generator (src/cli.ts, src/generate.ts). Bin agents-audit.
packages/cli/	@workspacejson/cli@0.0.1	private: true, registry E404	dbt/DataHub path normalization + fileIndex join. Bin declared workspacejson. Not the generator.

Verified mechanically: packages/cli contains no generateWorkspaceJson reference and depends on neither agents-audit nor @workspacejson/rules.

Parity — agents-audit

Packed artifact

File inventory identical to both the old candidate and the published agents-audit@0.4.4 tarball (9 entries).

Semantic manifest comparison against the published tarball — 18 of 21 keys byte-identical:

IDENTICAL  name version bin main module types exports files engines type
           publishConfig author description homepage keywords license scripts
           dependencies                    <-- runtime dependency VALUES EQUAL
DIFFERS    repository.url  -> workspacejson/cli      (intentional, ledger-required)
           bugs.url        -> workspacejson/cli      (intentional, ledger-required)
           devDependencies -> +@types/node 22.19.17  (intentional, see below)

@workspacejson/spec and @workspacejson/rules resolve to "0.4.4" in the new packed manifest — exactly what pnpm pack already wrote into the published tarball from workspace:*. The pin changes the committed source, not the packed bytes.

old candidate sha256  eadb10210956f838632f20d6f56a4102ecc0a44f12d56e054bd4334ed92976f6
new candidate sha256  379dd1eee282d8822c91a47d882e5aaaea74ac33d3c34c3f7fc4b699aefb377c
published 0.4.4       c7d302901f7df8b4890eeb0b925ae40b8b90868c49aa87a5b6df52f3ae08df2c

Tarball hashes differ because manifests differ by the three intentional fields above; the file inventory is identical.

Registry integrity independently re-verified by download and re-hash — 3/3 match dist.integrity for agents-audit, @workspacejson/spec, @workspacejson/rules @ 0.4.4.

Runtime — 29/29, both sides installed from packed tarballs, identical fixtures

Receipt: migration/parity-agents-audit-runtime.txt, harness: migration/parity-agents-audit-runtime.sh.

Command surface — exit code and normalized output identical old vs new:
--help, --version, scan ., scan . --json, generate --dry-run, generate --check, generate, generate --force, unknown-flag rejection.

Load-bearing behaviors were perturbed, not merely exercised:

Perturbation	Expected	old	new
corrupt JSON artifact, no --force	exit 1, refuses	✅	✅
schema-invalid artifact, no --force	exit 1, refuses	✅	✅
invalid artifact under --check	exit 1, "manual evidence is untouched"	✅	✅
--force over invalid artifact	exit 0, moves aside workspace.json.invalid.<ts>	✅	✅
hand-authored manual.fragileFiles + regenerate	survives verbatim	✅	✅
--dry-run	writes nothing	✅	✅
--check	writes nothing	✅	✅
dbt project outside git root	exit 2	✅	✅

Generated artifacts byte-identical excluding volatile timestamps; producer stamp {name: agents-audit, version: 0.4.4} on both. Public import surface identical (9 exports).

Full suite: 63 tests, 11 files (source control: 62 — the +1 is the package-metadata suite going from 3 cases to 4, fully accounted for).

Parity — private DataHub shim, proven separately

Receipt: migration/parity-datahub-shim.txt, harness: migration/parity-datahub-shim.mjs. 35/35. A green producer result is not evidence about this package, so it shares nothing with the run above.

Covers: package identity/privacy, canonical/computeProjectPrefix/normalizeModelPath, multi-project dbt discovery (with node_modules correctly ignored), manifest extraction, join against generated.fileIndex, legacy top-level fileIndex fallback, and the zero-join non-zero exit.

Perturbed: dropping the project prefix collapses the same nested join from 2/2 to 0/2 — the exact silent failure this shim exists to surface; a partial fileIndex yields 1/2 rather than all-or-nothing; a dbt project outside the git root exits 2.

Package tests: 6/6 both sides.

Intentional differences

1. repository.url / bugs.url → workspacejson/cli. Required by the ledger's parity criteria.
2. @types/node added to packages/agents-audit devDependencies. Not cosmetic — a genuine defect the split exposed. The monorepo resolved @workspacejson/rules to source via the tsconfig.base.json path alias, which transitively pulled @types/node into the program and silently supplied node:crypto, fs.realpathSync, and fs/promises.{rename,unlink}. Against the published rules declarations that leak disappears and the DTS build fails. The type environment is now declared rather than inherited by accident. types/ambient.d.ts is unchanged from the frozen source (verified byte-identical) — I did not paper over it by editing the ambient stub.
3. tsconfig.base.json drops the @workspacejson/rules → packages/rules/src/index.ts alias (that directory is standard-owned now).
4. verify-package-tarball.mjs no longer packs ../rules / ../spec off disk; it resolves them as a consumer would, with WORKSPACEJSON_STANDARD_TARBALLS for pre-publication candidates. Its fixed-group assertion became an exact-pin assertion, since this repo does not own that group.
5. verify-published.mjs verifies only agents-audit.
6. package-metadata.test.ts drops packages/spec / packages/rules assertions (they move under META-239) and gains assertions that the shim stays private and standard deps stay pinned.
7. .changeset/config.json — fixed group emptied, @workspacejson/cli ignored.
8. Root README/CHANGELOG/AGENTS/CONTRIBUTING/SECURITY rewritten as CLI-owned.

Clean-room and boundary guards

scripts/check-architecture.mjs, run in CI, with 13 red tests in scripts/check-architecture.test.mjs. Every guard class was observed rejecting a deliberate violation, plus a baseline case asserting the unmodified repo passes:

PASS  baseline: unmodified repository is accepted
PASS  rejected — clean-room: @marcelle-labs import
PASS  rejected — clean-room: private Vreko source import
PASS  rejected — clean-room: workspace.vreko.json assumption
PASS  rejected — copied-schema: normative schema copied into the CLI repo
PASS  rejected — repository-boundary: host-integration code in the CLI repo
PASS  rejected — repository-boundary: standard package redefined here
PASS  rejected — local-dependency: committed sibling-checkout path
PASS  rejected — local-dependency: workspace link in a published package
PASS  rejected — unpinned-standard-dependency: floating range on a standard package
PASS  rejected — private-package-publication: @workspacejson/cli loses private:true
PASS  rejected — foreign-publish: workflow publishing a standard-owned package
PASS  rejected — private-package-publication: workflow publishing the private shim

13 passed, 0 failed

Ownership documented in OWNERSHIP.md.

One thing I did not silently accept

types/ambient.d.ts carries a hand-written declare module '@workspacejson/spec' restating that package's TypeScript surface, and ambient declarations shadow the real node_modules types. It is not a clean-room violation (not @marcelle-labs, not Vreko, not the normative schema/v1.json), and migrating it unchanged is what parity requires — so it moved verbatim. But it is a duplicated view of a standard-owned contract living in this repo. Logged on META-236/META-165; the published tarballs do ship real declarations, so the follow-up is viable.

Publishing remains disabled

• .github/workflows/release.yml has no enabled trigger, requests contents: read only, holds no credential, and contains no publish step at all — not a conditional one.
• workspacejson/cli has no repository secrets (verified: empty secret and variable lists). It is mechanically incapable of publishing.
• workspace-json/agents-audit retains NPM_TOKEN and remains the sole publisher of agents-audit.
• Nothing was published. No dist-tag, package name, or registry state changed.
• @workspacejson/cli remains private: true and absent from npm.

Rollback

Rollback ref	workspace-json/agents-audit@e47eb1b8556c4f361db9a78190a2f36b400756e8
Procedure	Abandon this repository. The frozen SHA still contains both packages, still builds them, and still holds sole publish authority. No registry state changed, so rollback needs no republish and no consumer action.

The source repository was not modified. No reverse-merge machinery exists.

Deferred — explicitly not done here

• META-236 — neutral producer package and command identity. agents-audit is not converted to a bridge; @workspacejson/cli is not renamed, published, or broadened.
• META-195 — producer fileIndex / frameworkManifest enrichment.
• META-235 — version / specVersion dual emission.
• META-243 — publish-authority cutover, secret revocation, old-repository lock.

Verification run locally

pnpm install                    ok
pnpm run check:architecture     ok (61 files, 3 manifests)
node scripts/check-architecture.test.mjs   13/13
pnpm -r typecheck               ok (2/2 packages)
pnpm -r build                   ok (2/2 packages)
pnpm -r test                    63 + 6 tests passing
pnpm run release:verify-packs   ok — real `generate` smoke test resolving
                                spec/rules from the registry
agents-audit scan . --fail-on error   exit 0, 100/100 (A)
old-vs-new agents-audit parity  29/29
DataHub shim parity             35/35

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.