diff --git a/README.md b/README.md index a6e807f..cd883c4 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.15` 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.16` 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.15` +- `--version` prints `0.1.0-alpha.16` 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.15` +- **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.16` - **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.15` +- **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.16` 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 be8873a..39c1481 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.15` 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.16` 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 0b78456..642b30f 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.15` 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.16` 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 1635ade..a85caea 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.15` 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.16` 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 0c98e68..1adc17c 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.15` 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.16` 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.15` 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.16` 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.15` proof lane, that includes checking that the retained audit command keeps the packet's `--ci` spelling. +For the current pinned `0.1.0-alpha.16` 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 7237f62..4623bc3 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.15`. +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.16`. ## 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.15` 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.16` 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 60f5a6e..47dbbc1 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.15` +- `--version` prints `0.1.0-alpha.16` 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.15` 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.16` 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.15` 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.16` 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 bcadc5d..7573e5a 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.15`. Do not swap the tester onto the floating `@alpha` tag. +This packet stays pinned to `@lambdacurry/anvil@0.1.0-alpha.16`. 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.15 audit --target . --ci --output ./anvil-audit.md +bunx @lambdacurry/anvil@0.1.0-alpha.16 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.15 audit --target . --ci --output ./anvil-audit.md +bunx @lambdacurry/anvil@0.1.0-alpha.16 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.15` 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.16` 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.15 --version` +`bunx @lambdacurry/anvil@0.1.0-alpha.16 --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.15` local-only `--ci` spelling +- the retained audit command keeps the pinned `0.1.0-alpha.16` 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.15` 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.16` 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 a0ff9e7..b723b73 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@lambdacurry/anvil", - "version": "0.1.0-alpha.15", + "version": "0.1.0-alpha.16", "description": "AI rules + engineering guardrails audit engine for AI-assisted codebases", "keywords": [ "agents", diff --git a/scripts/governance-metadata-scoping.test.ts b/scripts/governance-metadata-scoping.test.ts index d3e89cf..d589479 100644 --- a/scripts/governance-metadata-scoping.test.ts +++ b/scripts/governance-metadata-scoping.test.ts @@ -200,3 +200,13 @@ test("a file we have committed to is still ours to date", () => { expect(dateCheck(files)?.status).toBe("fail"); }); + +test("no governance files at all still scores zero, unlike all-exempt", () => { + // The other half of the emptiness split, and previously covered only + // indirectly by a golden fixture. A missing surface is Governance Surface's + // failure to report; it must not be laundered into a date-hygiene pass. + const check = dateCheck([]); + + expect(check?.status).toBe("fail"); + expect(check?.detail).toContain("0%"); +}); diff --git a/scripts/lib/git-state.ts b/scripts/lib/git-state.ts index 5e99469..07689e7 100644 --- a/scripts/lib/git-state.ts +++ b/scripts/lib/git-state.ts @@ -34,6 +34,8 @@ export const READ_ONLY_GIT_COMMANDS: Readonly> = Object.freeze({ "cat-file": {}, "check-ignore": {}, + // Reports which commits already have an equivalent upstream. Read-only. + cherry: {}, config: { subVerbs: ["--get", "--get-all", "--list"] }, diff: {}, "for-each-ref": {}, @@ -269,6 +271,15 @@ export type BranchInfo = { isDefault: boolean; /** Null when the branch shares no merge base with the default branch. */ aheadOfDefault: number | null; + /** + * Commits ahead of the default that have NO equivalent patch there. + * + * Ahead-of-default counts merged work as unmerged forever once the merge + * rewrote SHAs, which rebase and squash merges both do. `git cherry` compares + * patch ids instead, so a rebase-merged branch reads as zero. Null when the + * comparison could not run. + */ + unappliedCommits: number | null; behindDefault: number | null; /** Total commits on each side; meaningful when histories are unrelated. */ totalCommits: number; @@ -835,6 +846,7 @@ function collectBranches( let aheadOfDefault: number | null = null; let behindDefault: number | null = null; + let unappliedCommits: number | null = null; let sharesHistoryWithDefault = true; if (!isDefault && defaultRef) { @@ -849,10 +861,22 @@ function collectBranches( behindDefault = counts.left; aheadOfDefault = counts.right; } + if ((aheadOfDefault ?? 0) > 0) { + // `+` marks a commit with no equivalent patch on the default branch. + const cherry = git(["-C", repoRoot, "cherry", defaultRef, name]); + if (cherry.ok) { + unappliedCommits = lines(cherry.stdout).filter((line) => + line.startsWith("+"), + ).length; + } + } else { + unappliedCommits = 0; + } } } else if (isDefault) { aheadOfDefault = 0; behindDefault = 0; + unappliedCommits = 0; } let aheadOfUpstream: number | null = null; @@ -873,6 +897,7 @@ function collectBranches( isDefault, aheadOfDefault, behindDefault, + unappliedCommits, totalCommits, sharesHistoryWithDefault, aheadOfUpstream, diff --git a/scripts/lib/repo-audit.ts b/scripts/lib/repo-audit.ts index 0ac7d87..5d1217a 100644 --- a/scripts/lib/repo-audit.ts +++ b/scripts/lib/repo-audit.ts @@ -254,15 +254,25 @@ function evaluateBranches(state: GitState): Finding[] { totalCommits: branch.totalCommits, }, }); - } else if (!branch.isDefault && (branch.aheadOfDefault ?? 0) > 0) { + } else if ( + !branch.isDefault && + (branch.aheadOfDefault ?? 0) > 0 && + // Ahead-of-default calls merged work unmerged forever once the merge + // rewrote SHAs, which rebase and squash merges both do. Anvil's own repo + // reported eight such branches, seven of them fully merged. Patch-id + // equivalence is what separates them. + branch.unappliedCommits !== 0 + ) { + const unapplied = branch.unappliedCommits ?? branch.aheadOfDefault; findings.push({ code: FINDING_CODES.branchNotOnDefault, severity: "low", subject: branchLabel(branch), - message: `Branch \`${branch.name}\` has ${branch.aheadOfDefault} commit(s) not reachable from \`${state.defaultBranch.name}\` (and is ${branch.behindDefault} behind).`, + message: `Branch \`${branch.name}\` has ${unapplied} commit(s) with no equivalent on \`${state.defaultBranch.name}\` (and is ${branch.behindDefault} behind).`, details: { branch: branch.name, ahead: branch.aheadOfDefault, + unapplied: branch.unappliedCommits, behind: branch.behindDefault, defaultBranch: state.defaultBranch.name, }, diff --git a/scripts/repo-audit.test.ts b/scripts/repo-audit.test.ts index da881b9..551947a 100644 --- a/scripts/repo-audit.test.ts +++ b/scripts/repo-audit.test.ts @@ -520,3 +520,43 @@ test("summary.passed tracks the configured threshold", () => { buildReport(state, findings, { failOn: "medium" }).summary.passed, ).toBe(false); }); + +test("a rebase-merged branch is not reported as unmerged", () => { + // Anvil's own repo reported eight branches as not-on-default; seven were + // fully merged. A rebase or squash merge rewrites SHAs, so ancestry calls the + // work unmerged forever while its patches sit on main. + const { root } = makeRepoWithRemote(); + gitOrThrow(root, ["checkout", "--quiet", "-b", "feature"]); + const sha = commitFile(root, "feature.txt", "work\n", "feat: the work"); + gitOrThrow(root, ["checkout", "--quiet", "main"]); + // Move main first, so replaying the patch lands it under a NEW sha — without + // this the cherry-pick reproduces the identical commit and nothing diverges. + commitFile(root, "unrelated.txt", "other\n", "chore: unrelated"); + gitOrThrow(root, ["cherry-pick", sha]); + + const state = collectGitState({ repoRoot: root }); + const feature = state.branches.find((b) => b.name === "feature"); + + expect(feature?.aheadOfDefault).toBeGreaterThan(0); + expect(feature?.unappliedCommits).toBe(0); + expect(evaluateFindings(state, STALE).map((f) => f.code)).not.toContain( + FINDING_CODES.branchNotOnDefault, + ); +}); + +test("a genuinely unmerged branch is still reported", () => { + // The guard against silencing the check entirely. + const { root } = makeRepoWithRemote(); + gitOrThrow(root, ["checkout", "--quiet", "-b", "feature"]); + commitFile(root, "feature.txt", "work\n", "feat: never landed"); + gitOrThrow(root, ["checkout", "--quiet", "main"]); + + const state = collectGitState({ repoRoot: root }); + const feature = state.branches.find((b) => b.name === "feature"); + + expect(feature?.unappliedCommits).toBe(1); + const finding = evaluateFindings(state, STALE).find( + (f) => f.code === FINDING_CODES.branchNotOnDefault, + ); + expect(finding?.message).toContain("no equivalent on"); +});