From 06539885cc10d8664ac7e99174a4736f5d8a6a5f Mon Sep 17 00:00:00 2001 From: Qwynn Marcelle Date: Sun, 26 Jul 2026 10:20:23 -0400 Subject: [PATCH] docs: record the META-236 vendor-notice change, and fix stale paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit META-247's ruling required the vendor-notice change to carry "its own evidence AND announcement". The evidence landed — parity receipt, a recorded entry in migration/parity-expected-differences.txt, a separate commit — but the announcement did not. agents-audit's [Unreleased] section had the two META-157 items and nothing for META-236. Added to packages/agents-audit-compat/CHANGELOG.md: - the `scan` output change, stating plainly that exit codes are unchanged and `scan --json` is byte-identical, so machine-readable consumers are unaffected; - the added `renderMissingArtifactNotice` export, and that `renderVrekoUpsell` remains exported and unchanged — additive, nothing removed. Four stale references found while sweeping for others. One was a real break: 1. scripts/verify-published.mjs read ../packages/agents-audit/package.json for the release version. That path stopped existing in META-247, so the script threw on startup. It is only invoked from the disabled release path, so it was latent — but it would have failed the META-243 cutover at exactly the wrong moment. Repointed; it now runs, installs agents-audit@0.4.4 from the registry and verifies the binary. 2. .gitignore ignored packages/agents-audit/.tmp-*/ — the producer conformance tests that create those directories moved to packages/cli, so their temp dirs were no longer ignored and could have been committed. Generalised to packages/*/.tmp-*/. 3. .github/pull_request_template.md pointed contributors at packages/agents-audit/dist/cli.js. Repointed, and the parity harness added to the checklist for changes to anything agents-audit exposes. 4. Red-test fixture paths in check-architecture.test.mjs named a package that no longer exists. Functionally harmless — they write into a scratch copy — but they should read as the current layout. Also: packages/cli declared CHANGELOG.md in its `files` list but had no such file, so the packed tarball silently shipped without the changelog it claims. Added one, stating up front that the package has never been published and must not be documented as installable until META-243. The root CHANGELOG linked to ./packages/agents-audit/CHANGELOG.md — a dead link since META-247 — and had no repository-level entry for the architecture change at all. Both fixed. Verification typecheck 3/3 · build 3/3 · tests 82 (32 + 44 + 6) architecture guard pass · red tests 19/19 release:verify-packs pass · release:verify-published now runs (was throwing) parity: runtime, pack and shim all exit 0 --- .github/pull_request_template.md | 3 +- .gitignore | 2 +- CHANGELOG.md | 23 +++++++++++++- packages/agents-audit-compat/CHANGELOG.md | 2 ++ packages/cli/CHANGELOG.md | 37 +++++++++++++++++++++++ scripts/check-architecture.test.mjs | 6 ++-- scripts/verify-published.mjs | 2 +- 7 files changed, 68 insertions(+), 7 deletions(-) create mode 100644 packages/cli/CHANGELOG.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b114a38..6abbf45 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -7,7 +7,8 @@ Describe what changed and why. - [ ] `pnpm -r typecheck` - [ ] `pnpm -r test` - [ ] `pnpm -r build` -- [ ] `node packages/agents-audit/dist/cli.js scan . --fail-on error` +- [ ] `node packages/agents-audit-compat/dist/cli.js scan . --fail-on error` +- [ ] `bash migration/parity-agents-audit-runtime.sh` (required if anything `agents-audit` exposes changed) ## Notes diff --git a/.gitignore b/.gitignore index 5289304..f4f915b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,7 @@ node_modules/ dist/ packages/*/dist/ packages/*/node_modules/ -packages/agents-audit/.tmp-*/ +packages/*/.tmp-*/ .DS_Store coverage/ *.log diff --git a/CHANGELOG.md b/CHANGELOG.md index 89d0860..0ed5fa2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,12 +3,33 @@ This file records **repository-level** history for the CLI repository. Package release notes live with their packages: -* [`packages/agents-audit/CHANGELOG.md`](./packages/agents-audit/CHANGELOG.md) — `agents-audit` +* [`packages/cli/CHANGELOG.md`](./packages/cli/CHANGELOG.md) — `@workspacejson/cli` +* [`packages/agents-audit-compat/CHANGELOG.md`](./packages/agents-audit-compat/CHANGELOG.md) — `agents-audit` ## [Unreleased] ### Changed +- **Restructured to the ratified neutral architecture (META-236 → META-247).** + `packages/cli/` is now `@workspacejson/cli`, the neutral producer with binary + `workspacejson`. `packages/agents-audit/` became + `packages/agents-audit-compat/`, a frozen compatibility bridge that keeps the + `agents-audit` package name, binary, commands and all nine public exports and + delegates generation to the neutral package. The migrated DataHub/dbt adapter + moved to `packages/datahub-adapter/` and is staged pending extraction to + `workspacejson/datahub-agent` (META-248) — it is not durable architecture + here. Compatibility was proven by the parity harnesses; the only behavioral + difference is the ratified vendor-notice change, recorded in + `migration/parity-expected-differences.txt`. +- **The CLI now compiles against real standard-owned types (META-244).** A + handwritten `declare module '@workspacejson/spec'` in `types/ambient.d.ts` + shadowed the published declarations and hid the entire v0.4 contract — + `WorkspaceJsonV4`, `validateV4`, `CoChangeEntry`, `FragilityEntry` — from this + repository's compiler. Removed, with a guard rejecting reintroduction. +- **Parity harnesses are now executable gates, enforced in CI.** They previously + exited 0 regardless of result. They now fail when the set of differences + changes in either direction — a new difference, or a ratified one silently + disappearing. - Repository created by history-preserving extraction from `workspace-json/agents-audit@e47eb1b8556c4f361db9a78190a2f36b400756e8` (META-240). No package was renamed, no public command changed, and no package diff --git a/packages/agents-audit-compat/CHANGELOG.md b/packages/agents-audit-compat/CHANGELOG.md index 09de684..8d4daa5 100644 --- a/packages/agents-audit-compat/CHANGELOG.md +++ b/packages/agents-audit-compat/CHANGELOG.md @@ -4,6 +4,8 @@ ### Patch Changes +- **Changed:** `scan` no longer prints a vendor notice when `.agents/workspace.json` is missing or stale. It now names the command that actually fixes the problem — `agents-audit generate` — and still reports the same validation errors. Ratified in META-236: vendor promotion never enters the neutral producer, and is removed or made opt-in in this compatibility package. Exit codes are unchanged and `scan --json` output is byte-identical, so nothing consuming machine-readable output is affected. Human-readable `scan` output does change; this is recorded as an intentional difference in `migration/parity-expected-differences.txt` and enforced by the CI parity gate. +- **Added:** `renderMissingArtifactNotice`, the neutral replacement used by `scan`. `renderVrekoUpsell` remains exported and unchanged for API compatibility — it is simply no longer called by the CLI, so callers who want it can still invoke it. This export set is additive; no historical export was removed. - `generate --check --dry-run` now fires the drift gate (exit 1, "manual evidence is untouched") instead of the dry-run branch silently winning and exiting 0; the JSON projection is still printed under `--dry-run`. Deferred from 0.4.4 (META-157) because it changes exit-code semantics; landed here as its own reviewed change with regression tests watched red against the pre-change CLI. - `generate` now surfaces `invalidFileMoved` (result data that has existed since 0.4.3 but was never displayed): when a previous `.agents/workspace.json` was invalid and moved aside, the CLI prints where it was relocated to and that its manual evidence could not be recovered. diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md new file mode 100644 index 0000000..0804bff --- /dev/null +++ b/packages/cli/CHANGELOG.md @@ -0,0 +1,37 @@ +# Changelog — `@workspacejson/cli` + +## [Unreleased] + +**This package has never been published.** It is not on npm, and must not be +documented as installable until the coordinated publish-authority cutover +(META-243). The working public command today is `npx agents-audit generate`, +which runs this same producer implementation. + +### Added + +- Initial package: the neutral workspace.json producer, binary `workspacejson`. + Created in META-247 from the implementation ratified in META-236. +- `src/producer/` — deterministic generation, repository scanning, + reconciliation, manual-evidence preservation, atomic writes and drift + detection. Harvested from `agents-audit`'s `generate.ts`, which had no + dependency on the audit product and moved wholesale. +- `src/commands/` — public command routing. `agents-audit` invokes the same + `runGenerate` implementation, so the two binaries cannot drift apart during + the compatibility window. +- `generateWorkspaceJson` accepts a caller-supplied `producer` identity, written + to `generated.by`. It defaults to this package; `agents-audit` passes its + historical identity so its artifacts remain byte-identical. `generated.by` is + excluded from the material projection, so this never affects drift detection. +- `generateWorkspaceJson` accepts a caller-supplied `commandName`, used in + refusal and remediation messages. Previously these hardcoded `agents-audit`, + which would have told a `workspacejson` user to run a different tool. + +### Notes + +- Config-file support is deliberately absent. `agents-audit` reads + `.agentsauditrc`, an audit-shaped name the neutral producer should not + inherit; naming a neutral config file is a public-surface decision left to the + OSS polish work (META-245). +- Contracts come from `workspacejson/standard` as released packages + (`@workspacejson/spec`, `@workspacejson/rules`), pinned to exact versions. + This package implements the contract; it does not define it. diff --git a/scripts/check-architecture.test.mjs b/scripts/check-architecture.test.mjs index 9897f6d..d113f36 100644 --- a/scripts/check-architecture.test.mjs +++ b/scripts/check-architecture.test.mjs @@ -21,7 +21,7 @@ const cases = [ { name: "clean-room: @marcelle-labs import", expect: "clean-room", - mutate: (root) => write(join(root, "packages/agents-audit/src/violation.ts"), + mutate: (root) => write(join(root, "packages/agents-audit-compat/src/violation.ts"), `import { thing } from '@marcelle-labs/private-core';\nexport const x = thing;\n`), }, { @@ -33,13 +33,13 @@ const cases = [ { name: "clean-room: workspace.vreko.json assumption", expect: "clean-room", - mutate: (root) => write(join(root, "packages/agents-audit/src/violation.ts"), + mutate: (root) => write(join(root, "packages/agents-audit-compat/src/violation.ts"), `export const sidecar = '.agents/workspace.vreko.json';\n`), }, { name: "copied-schema: normative schema copied into the CLI repo", expect: "copied-schema", - mutate: (root) => write(join(root, "packages/agents-audit/schema/v1.json"), JSON.stringify({ + mutate: (root) => write(join(root, "packages/agents-audit-compat/schema/v1.json"), JSON.stringify({ $schema: "https://json-schema.org/draft/2020-12/schema", $id: "https://workspacejson.dev/schema/v1.json", title: "workspace.json", diff --git a/scripts/verify-published.mjs b/scripts/verify-published.mjs index d06823a..77f4484 100644 --- a/scripts/verify-published.mjs +++ b/scripts/verify-published.mjs @@ -15,7 +15,7 @@ import { spawnSync } from "node:child_process"; // @workspacejson/cli is deliberately absent: it is `private: true` and must not // appear on the registry. scripts/check-architecture.mjs is what asserts that. const version = process.env.WORKSPACEJSON_RELEASE_VERSION - ?? JSON.parse(readFileSync(new URL("../packages/agents-audit/package.json", import.meta.url), "utf8")).version; + ?? JSON.parse(readFileSync(new URL("../packages/agents-audit-compat/package.json", import.meta.url), "utf8")).version; const packages = [ { name: "agents-audit", check: ["npx", "--no-install", "agents-audit", "--help"] }, ];