From 439e9c262266beb75bfbbbe872508fec9ec5efb5 Mon Sep 17 00:00:00 2001 From: Jake Ruesink Date: Sun, 9 Aug 2026 20:58:07 -0500 Subject: [PATCH 1/2] feat(drift): add --artifacts-dir, and say where the default actually lands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `audit` took `--artifacts-dir`; `drift` only took `--output`, so there was no way to place the report short of naming the exact file. One correction to the diagnosis, and it matters for the workaround: the default does not write into the target repo. It writes into `process.cwd()` — `./docs/audits/artifacts/-/drift-report.md` relative to wherever you are standing. Verified: run from /tmp against packages/vision and the report lands in /tmp, with nothing written to vision at all. That is why lc-classic-starter got littered — the run happened from inside it. The same command from anvil's directory litters anvil instead, which is the worse failure because the artifacts look like they belong there. So the flag alone would not have closed it. The usage text said "Default output: docs/audits/artifacts/..." with no frame, which reads as relative to the repo being scanned. Both the CLI help and the docs now say relative to your current directory, not to the audited repo. `--output` still wins over `--artifacts-dir`, and the audit's own invocation is unaffected because it already passes `--output` explicitly. Co-Authored-By: Claude Opus 5 (1M context) --- bin/anvil.ts | 12 ++++++--- docs-site/src/content/docs/reference/cli.md | 3 +++ scripts/cli-target-contract.test.ts | 27 +++++++++++++++++++++ scripts/drift-detect.ts | 25 +++++++++++++++---- 4 files changed, 59 insertions(+), 8 deletions(-) diff --git a/bin/anvil.ts b/bin/anvil.ts index 5cab4d3..188a565 100755 --- a/bin/anvil.ts +++ b/bin/anvil.ts @@ -45,9 +45,15 @@ const SUBCOMMAND_HELP: Record = { " --ai-timeout-ms Timeout for AI synthesis calls in milliseconds\n" + " --force-stage-b Run Stage B scoring even when Stage A fails", drift: - "Usage: anvil drift --target [--skip-dirs dir1,dir2,...] [--output ]\n" + - " anvil drift [--skip-dirs dir1,dir2,...] [--output ]\n\n" + - "Default output: docs/audits/artifacts/-/drift-report.md", + "Usage: anvil drift --target [--skip-dirs dir1,dir2,...] [--artifacts-dir ] [--output ]\n" + + " anvil drift [--skip-dirs dir1,dir2,...] [--artifacts-dir ] [--output ]\n\n" + + "Options:\n" + + " --target Path to the repo to scan (required)\n" + + " --skip-dirs Comma-separated directory names to exclude from scanning\n" + + " --artifacts-dir Write the report into this directory\n" + + " --output Write the report to this exact path\n\n" + + "Default output: ./docs/audits/artifacts/-/drift-report.md,\n" + + "relative to your CURRENT DIRECTORY — not to the repo being scanned.", bootstrap: "Usage: anvil bootstrap --target [--output ]\n" + " anvil bootstrap [--output ]", diff --git a/docs-site/src/content/docs/reference/cli.md b/docs-site/src/content/docs/reference/cli.md index 944aeab..6c37cdb 100644 --- a/docs-site/src/content/docs/reference/cli.md +++ b/docs-site/src/content/docs/reference/cli.md @@ -47,6 +47,9 @@ anvil drift --target ./my-repo [options] | `--target ` | Path to the repo to scan (required) | | `--output ` | Write report to a specific path | | `--skip-dirs ` | Comma-separated directory names to exclude from scanning | +| `--artifacts-dir ` | Write the report into this directory | + +The report defaults to `./docs/audits/artifacts/-/drift-report.md`, **relative to your current directory — not to the repo being scanned**. Run it from inside a target repo and the report lands in that repo; pass `--artifacts-dir` or `--output` to put it somewhere deliberate. Checks path existence, glob pattern resolution, broken symlinks, validation dates, and command availability. The positional form `anvil drift ./my-repo` remains supported for compatibility. diff --git a/scripts/cli-target-contract.test.ts b/scripts/cli-target-contract.test.ts index 700cd5c..a9ab2da 100644 --- a/scripts/cli-target-contract.test.ts +++ b/scripts/cli-target-contract.test.ts @@ -17,11 +17,13 @@ test("drift accepts --target while preserving the positional form", () => { projectPath: "./repo", extraSkipDirs: [], outputFile: "drift.md", + artifactsDir: null, }); expect(parseDriftArgs(["bun", "drift", "./repo"])).toEqual({ projectPath: "./repo", extraSkipDirs: [], outputFile: null, + artifactsDir: null, }); }); @@ -41,3 +43,28 @@ test("bootstrap accepts --target while preserving the positional form", () => { outputFile: null, }); }); + +test("drift accepts --artifacts-dir, and --output still wins", () => { + // audit already had --artifacts-dir; drift only had --output, so the default + // landed in whatever directory you happened to be standing in. + expect( + parseDriftArgs(["bun", "drift", "./repo", "--artifacts-dir", "/tmp/out"]), + ).toEqual({ + projectPath: "./repo", + extraSkipDirs: [], + outputFile: null, + artifactsDir: "/tmp/out", + }); + + const both = parseDriftArgs([ + "bun", + "drift", + "./repo", + "--artifacts-dir", + "/tmp/out", + "--output", + "/tmp/exact.md", + ]); + expect(both.outputFile).toBe("/tmp/exact.md"); + expect(both.artifactsDir).toBe("/tmp/out"); +}); diff --git a/scripts/drift-detect.ts b/scripts/drift-detect.ts index 6ccc7b9..7622a5b 100644 --- a/scripts/drift-detect.ts +++ b/scripts/drift-detect.ts @@ -150,9 +150,10 @@ function defaultReportOutputPath(projectRoot: string): string { export function usageAndExit(): never { console.error( - "Usage: anvil drift --target [--skip-dirs dir1,dir2,...] [--output ]\n" + - " anvil drift [--skip-dirs dir1,dir2,...] [--output ]\n" + - "Default output: docs/audits/artifacts/-/drift-report.md", + "Usage: anvil drift --target [--skip-dirs dir1,dir2,...] [--artifacts-dir ] [--output ]\n" + + " anvil drift [--skip-dirs dir1,dir2,...] [--artifacts-dir ] [--output ]\n" + + "Default output: ./docs/audits/artifacts/-/drift-report.md,\n" + + "relative to YOUR CURRENT DIRECTORY — not to the audited repo.", ); process.exit(1); } @@ -161,6 +162,7 @@ export type ParsedArgs = { projectPath: string; extraSkipDirs: string[]; outputFile: string | null; + artifactsDir: string | null; }; export type IgnoreMatcher = { @@ -172,6 +174,7 @@ export function parseArgs(argv: string[]): ParsedArgs { let projectPath: string | null = null; let extraSkipDirs: string[] = []; let outputFile: string | null = null; + let artifactsDir: string | null = null; for (let i = 2; i < argv.length; i++) { const arg = argv[i]; @@ -196,6 +199,14 @@ export function parseArgs(argv: string[]): ParsedArgs { .map((d) => d.trim()) .filter(Boolean); i++; + } else if (arg === "--artifacts-dir") { + const val = argv[i + 1]; + if (!val || val.startsWith("--")) { + console.error("--artifacts-dir requires a directory path"); + process.exit(1); + } + artifactsDir = val; + i++; } else if (arg === "--output") { const val = argv[i + 1]; if (!val || val.startsWith("--")) { @@ -216,7 +227,7 @@ export function parseArgs(argv: string[]): ParsedArgs { usageAndExit(); } - return { projectPath, extraSkipDirs, outputFile }; + return { projectPath, extraSkipDirs, outputFile, artifactsDir }; } export function collectFiles(root: string): string[] { @@ -1486,7 +1497,11 @@ export function main(): void { return (a.line ?? 0) - (b.line ?? 0); }); - const outputPath = args.outputFile ?? defaultReportOutputPath(projectRoot); + const outputPath = + args.outputFile ?? + (args.artifactsDir + ? join(resolve(args.artifactsDir), "drift-report.md") + : defaultReportOutputPath(projectRoot)); mkdirSync(dirname(outputPath), { recursive: true }); const report = buildReport( projectRoot, From b02e2afd3313c1e4eadee8679fa3c6100ab98a8d Mon Sep 17 00:00:00 2001 From: Jake Ruesink Date: Sun, 9 Aug 2026 20:58:47 -0500 Subject: [PATCH 2/2] chore: bump 0.1.0-alpha.19 Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 8 ++++---- docs-site/public/llms-full.txt | 2 +- docs-site/src/content/docs/reference/cli.md | 2 +- docs/byok-trust-model.md | 2 +- docs/first-user-proof-packet.md | 6 +++--- docs/first-user-proof.md | 4 ++-- docs/getting-started.md | 6 +++--- docs/proofs/current-outside-tester-send-packet.md | 14 +++++++------- package.json | 2 +- 9 files changed, 23 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 48e0b70..511f296 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ Relative `--target` paths resolve from your current shell cwd. If you are alread Choose the lane that matches your setup before your first run. -If you are collecting the outside-user proof, stay on the exact pinned version and launcher from [First User Proof](docs/first-user-proof.md) instead of switching to the unpinned examples in this README. The current pinned `0.1.0-alpha.18` proof packet uses one repo-root `bunx` command with `--ci --output ./anvil-audit.md` so the saved report comes back from the first run. +If you are collecting the outside-user proof, stay on the exact pinned version and launcher from [First User Proof](docs/first-user-proof.md) instead of switching to the unpinned examples in this README. The current pinned `0.1.0-alpha.19` proof packet uses one repo-root `bunx` command with `--ci --output ./anvil-audit.md` so the saved report comes back from the first run. ### Local-only first pass (no provider required) @@ -151,7 +151,7 @@ bun run ./bin/anvil.ts --version Verified on the current alpha packet: - `--help` prints the four shipped entry commands: `audit`, `drift`, `bootstrap`, `mine-pr` -- `--version` prints `0.1.0-alpha.18` +- `--version` prints `0.1.0-alpha.19` Why you might choose this lane: @@ -173,10 +173,10 @@ For first-run setup and CI/lint guidance, see: Lambda Curry maintains this project with internal automation behind it, but that machinery is secondary to the public product path above. -- **Status:** Report as Decision Tool shipped; current charter follow-through is to collect outside-Lambda-Curry first-run proof on pinned `0.1.0-alpha.18` +- **Status:** Report as Decision Tool shipped; current charter follow-through is to collect outside-Lambda-Curry first-run proof on pinned `0.1.0-alpha.19` - **Verification posture:** CI artifact (audit report) + downstream observed impact in rule quality - **Current checked-in self-audit:** `docs/audits/anvil-audit-2026-08-08.md` reports `98/100` Structural Lint, `35/35` Guardrail Readiness, `0` issues, and `0` remediation tasks on current `main` -- **Current proof packet:** `docs/proofs/current-outside-tester-send-packet.md` keeps the external proof lane on one canonical repo-root command that saves `./anvil-audit.md`; the pinned packet stays on `@lambdacurry/anvil@0.1.0-alpha.18` +- **Current proof packet:** `docs/proofs/current-outside-tester-send-packet.md` keeps the external proof lane on one canonical repo-root command that saves `./anvil-audit.md`; the pinned packet stays on `@lambdacurry/anvil@0.1.0-alpha.19` Anvil is not primarily a UI project. Its real proof surface is whether downstream outputs and consumers reflect the intended rule behavior correctly. diff --git a/docs-site/public/llms-full.txt b/docs-site/public/llms-full.txt index fc19156..58c0e00 100644 --- a/docs-site/public/llms-full.txt +++ b/docs-site/public/llms-full.txt @@ -745,7 +745,7 @@ anvil audit --target ./my-repo [options] Relative `--target` paths resolve from your current shell cwd. -If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.18` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias. +If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.19` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias. ## `anvil drift` diff --git a/docs-site/src/content/docs/reference/cli.md b/docs-site/src/content/docs/reference/cli.md index 6c37cdb..05cc8d9 100644 --- a/docs-site/src/content/docs/reference/cli.md +++ b/docs-site/src/content/docs/reference/cli.md @@ -32,7 +32,7 @@ anvil audit --target ./my-repo [options] Relative `--target` paths resolve from your current shell cwd. -If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.18` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias. +If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.19` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias. ## `anvil drift` diff --git a/docs/byok-trust-model.md b/docs/byok-trust-model.md index a3249fe..e26cb30 100644 --- a/docs/byok-trust-model.md +++ b/docs/byok-trust-model.md @@ -18,7 +18,7 @@ By default, Anvil scans your repo locally, then expects a working AI provider fo If you want the privacy-first path, run: -> **Current alpha note:** The published `0.1.0-alpha.18` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`. Packaged relative `--target` and `--output` paths still resolve from your shell cwd, so normal repo-relative first-run commands are honest when you use the unpinned command (it tracks the latest published build). +> **Current alpha note:** The published `0.1.0-alpha.19` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`. Packaged relative `--target` and `--output` paths still resolve from your shell cwd, so normal repo-relative first-run commands are honest when you use the unpinned command (it tracks the latest published build). ```bash # zero-install diff --git a/docs/first-user-proof-packet.md b/docs/first-user-proof-packet.md index 40e8e71..9b6dc72 100644 --- a/docs/first-user-proof-packet.md +++ b/docs/first-user-proof-packet.md @@ -20,7 +20,7 @@ Send back whether it worked first try, the first useful fix the report pointed t bunx @lambdacurry/anvil@ audit --target . --ci --output ./anvil-audit.md ``` -Replace `` with the specific published build you want validated. The current `0.1.0-alpha.18` proof packet sends only the repo-root saved-report command above so the artifact comes back from the same first run without asking the tester to choose between layouts. +Replace `` with the specific published build you want validated. The current `0.1.0-alpha.19` proof packet sends only the repo-root saved-report command above so the artifact comes back from the same first run without asking the tester to choose between layouts. Helpful docs: - Getting started: https://lambda-curry.github.io/anvil/getting-started/first-audit @@ -54,7 +54,7 @@ Before sending the note above, make sure: ## 3. Exact command blocks to send -Pick one install path and one shell layout, then send only that exact command so the tester is not choosing between multiple moving parts. For the current `0.1.0-alpha.18` packet, the canonical layout is Bun zero-install from the target repo root. +Pick one install path and one shell layout, then send only that exact command so the tester is not choosing between multiple moving parts. For the current `0.1.0-alpha.19` packet, the canonical layout is Bun zero-install from the target repo root. Replace `` before you send anything. Do not use the floating `@alpha` tag in the external proof packet. @@ -128,7 +128,7 @@ bun run verify:first-user-proof -- docs/proofs/YYYY-MM-DD--first-user-pr ``` The validator returns a deterministic `counts` / `does-not-count` result and names the missing proof fields or contract mismatches directly. -For the current pinned `0.1.0-alpha.18` proof lane, that includes checking that the retained audit command keeps the packet's `--ci` spelling. +For the current pinned `0.1.0-alpha.19` proof lane, that includes checking that the retained audit command keeps the packet's `--ci` spelling. When the packet keeps a local report artifact, it also requires `Saved report path or screenshot link` to match the retained audit command's `--output` path. Save one small packet with these fields: diff --git a/docs/first-user-proof.md b/docs/first-user-proof.md index a58098a..1a7c2d3 100644 --- a/docs/first-user-proof.md +++ b/docs/first-user-proof.md @@ -15,7 +15,7 @@ Capture one real outside-Lambda-Curry run that proves: Do this only after the exact published version you want to validate is live, and before Milestone 3 is called complete. -Do not send this packet with the floating `@alpha` tag. Replace `` in the command below with the specific published build you are validating, for example `0.1.0-alpha.18`. +Do not send this packet with the floating `@alpha` tag. Replace `` in the command below with the specific published build you are validating, for example `0.1.0-alpha.19`. ## Suggested tester profile @@ -115,7 +115,7 @@ bun run verify:first-user-proof -- docs/proofs/YYYY-MM-DD--first-user-pr ``` That validator checks the outside-tester status, pinned CLI version, first-try success, returned artifact, and other minimum packet fields, then returns `counts` or `does-not-count` with explicit reasons. -For the current pinned `0.1.0-alpha.18` proof lane, it requires the retained audit command to keep the exact `--ci` spelling from the packet. +For the current pinned `0.1.0-alpha.19` proof lane, it requires the retained audit command to keep the exact `--ci` spelling from the packet. ## Done signal for Milestone 3 gate diff --git a/docs/getting-started.md b/docs/getting-started.md index fd80a1b..bf1f04a 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -64,7 +64,7 @@ anvil --version What you should see in the current alpha: - `--help` lists the four shipped commands: `audit`, `drift`, `bootstrap`, `mine-pr` -- `--version` prints `0.1.0-alpha.18` +- `--version` prints `0.1.0-alpha.19` If you are validating Anvil from a cloned checkout instead of a global install, run: @@ -125,7 +125,7 @@ Top 5 improvements: ## Save the report to a file -> **Current alpha note:** The published `0.1.0-alpha.18` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`, while the packaged CLI still resolves relative `--target` and `--output` paths from your shell cwd on `bunx`, `npx`, and Bun global install. Normal relative-path examples are honest when you use the unpinned command (it tracks the latest published build). +> **Current alpha note:** The published `0.1.0-alpha.19` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`, while the packaged CLI still resolves relative `--target` and `--output` paths from your shell cwd on `bunx`, `npx`, and Bun global install. Normal relative-path examples are honest when you use the unpinned command (it tracks the latest published build). ```bash # zero-install with bunx @@ -235,7 +235,7 @@ anvil audit \ `--ci` keeps discovery, drift detection, coverage scoring, and markdown output local. The report headline becomes `Structural Lint Score`, and the improvement section is generated from repo-local heuristics instead of a provider. -`--no-ai` still works as a deprecated compatibility alias for the same mode. The current external first-user proof packet stays pinned to `0.1.0-alpha.18` and uses `--ci` for the local-only lane. +`--no-ai` still works as a deprecated compatibility alias for the same mode. The current external first-user proof packet stays pinned to `0.1.0-alpha.19` and uses `--ci` for the local-only lane. Privacy-first example artifact from the same example target: diff --git a/docs/proofs/current-outside-tester-send-packet.md b/docs/proofs/current-outside-tester-send-packet.md index 214a31b..909f9ff 100644 --- a/docs/proofs/current-outside-tester-send-packet.md +++ b/docs/proofs/current-outside-tester-send-packet.md @@ -2,7 +2,7 @@ Use this packet to route one outside-Lambda-Curry tester through Anvil's remaining Milestone 3 proof lane. -This packet stays pinned to `@lambdacurry/anvil@0.1.0-alpha.18`. Do not swap the tester onto the floating `@alpha` tag. +This packet stays pinned to `@lambdacurry/anvil@0.1.0-alpha.19`. Do not swap the tester onto the floating `@alpha` tag. ## Three-line opener @@ -15,7 +15,7 @@ Send back whether it worked first try, the first useful fix the report pointed t ## Exact command to send ```bash -bunx @lambdacurry/anvil@0.1.0-alpha.18 audit --target . --ci --output ./anvil-audit.md +bunx @lambdacurry/anvil@0.1.0-alpha.19 audit --target . --ci --output ./anvil-audit.md ``` Send this as the only command. It assumes the tester is already in the target repo root, guarantees the saved report path, and keeps the local-only flag aligned with current public docs. @@ -27,7 +27,7 @@ Could you try one first-run Anvil audit on a real repo of yours? Paste the single command below from that repo's root; it saves `./anvil-audit.md`, stays local, and does not require an AI provider. ```bash -bunx @lambdacurry/anvil@0.1.0-alpha.18 audit --target . --ci --output ./anvil-audit.md +bunx @lambdacurry/anvil@0.1.0-alpha.19 audit --target . --ci --output ./anvil-audit.md ``` Helpful docs: @@ -39,7 +39,7 @@ What I'd love back: 1. Whether the exact command worked on the first try 2. If it did not, what failed first 3. If you changed the launcher or command, what you used instead - - If you switched to global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@0.1.0-alpha.18` line and the `anvil audit ...` line together in `Exact command`. + - If you switched to global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@0.1.0-alpha.19` line and the `anvil audit ...` line together in `Exact command`. 4. Whether you ran it from the repo root or somewhere else 5. The first useful fix the report pointed to, if any 6. Anything that felt confusing, too internal, or too hand-wavy @@ -47,7 +47,7 @@ What I'd love back: - If you send back the saved report path itself, keep `./anvil-audit.md`, the exact path the retained command wrote with `--output`. If you want one extra cross-check, this should print the same pinned version: -`bunx @lambdacurry/anvil@0.1.0-alpha.18 --version` +`bunx @lambdacurry/anvil@0.1.0-alpha.19 --version` If you changed launchers before the successful run, use the matching `--version` command from that same install path instead of mixing launchers in the saved packet. Do not append `anvil --version` to a `bunx` or `npx` proof packet. @@ -57,7 +57,7 @@ Count this as Milestone 3 proof only if all of these are true: - the tester is outside Lambda Curry - the tester completes a successful first run on a real repo -- the retained audit command keeps the pinned `0.1.0-alpha.18` local-only `--ci` spelling +- the retained audit command keeps the pinned `0.1.0-alpha.19` local-only `--ci` spelling - the exact command and returned artifact are retained in a saved proof packet - any rough edge found is captured as follow-up work @@ -79,7 +79,7 @@ bun run verify:first-user-proof -- docs/proofs/YYYY-MM-DD--first-user-pr ``` Run that verifier from an Anvil repo checkout or an unpacked published Anvil package root; the verifier now ships with the same proof-doc bundle. -It keys validation off the saved packet's `Pinned CLI version`, so this retained `0.1.0-alpha.18` packet can still be checked after current `main` advances to a later package version. +It keys validation off the saved packet's `Pinned CLI version`, so this retained `0.1.0-alpha.19` packet can still be checked after current `main` advances to a later package version. Historical note: the original dated retained packet for this same pinned proof lane remains at `docs/proofs/2026-05-23-alpha4-outside-tester-send-packet.md`. diff --git a/package.json b/package.json index b53b8d2..9b121c1 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@lambdacurry/anvil", - "version": "0.1.0-alpha.18", + "version": "0.1.0-alpha.19", "description": "AI rules + engineering guardrails audit engine for AI-assisted codebases", "keywords": [ "agents",