docs(adr): ADR-0020 — rescope SC-010 and authorize work toward the Backstage catalog adapter - #82
Merged
Merged
Conversation
…the Backstage catalog adapter Spike 009 recorded `blocked` with shortfall `envelope-or-scale-evidence-incomplete`. Under contracts/evidence-bundle-and-verdict.md §4 that forces `recommendation = null`, so nothing in the repository authorizes the catalog adapter, and spec.md's Output Recommendation says even a `go-explicit` would not have. The shortfall is narrower than its name. Scale evidence was captured for all three passes (T052/T056/T060, aggregated T061); only the envelope half fired. Both real-corpus passes fail-closed-rejected because both corpora are genuinely defective. SC-010 admits no passing implementation under FR-001's frozen inputs. community-plugins carries two fully admissible YAML documents both named `backstage-community-nexus-repository-manager`, so ADR-0012's `owned-paths-fail-closed-atomic` assertion requires the abort; SC-010 names that corpus non-fungibly. ADR-0015 established this while declining to benefit from it, and its Conditions of Acceptance 3 expressly permits a rescope subject to a separate record. This is that record. It rescopes SC-010 so a correct fail-closed rejection satisfies the criterion, and authorizes implementation work against ADR-0012's four-item production gate (lines 202-220) — of which gate 3, the reference oracle, is unmet. It does not authorize release: that is deferred to a later record gated on clause 5 plus ADR-0012 gates 3 and 4. Spike 009 stands unmodified; no checkbox is flipped and no verdict is rewritten. Reviewed adversarially from fresh contexts across two model lineages over three rounds. Every round found substantive defects and every finding was accepted; in two of three the defect was created by the previous round's correction. Round 3's reviews converged independently on the frontmatter assertion having missed round 2's fix. The record documents that non-convergence rather than claiming a clean bill. Status is `proposed`: an agent-drafted record cannot reach `accepted` without a named human ratifier, and the lint gate was observed failing on that rule before being trusted (ADR-0016). Also bumps the dogfood corpus count in packages/cli/test/lint.test.ts from 19 to 20, matching the established pattern for adding a record. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Caution The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased. |
There was a problem hiding this comment.
Pull request overview
Drafts ADR-0020 to rescope SC-010 and authorize Backstage adapter implementation work while retaining release gates.
Changes:
- Adds ADR-0020 with evidence, constraints, and action items.
- Updates the repository corpus-count test.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
docs/adr/0020-...md |
Records the proposed rescope and authorization. |
packages/cli/test/lint.test.ts |
Updates expected ADR count to 20. |
| ## Review history | ||
|
|
||
| Two independent adversarial reviews from fresh contexts, across two model | ||
| lineages, over two rounds before ratification. The second round was bounded to |
…s frozen expectations Round-4 adversarial review split PASS/FAIL across the two lineages. The FAIL prevailed on the merits, and its lead finding is the sharpest of the four rounds: clause 5 froze the accept corpus's expected paths and then never required anything to be compared against them. A populated, digest-verified envelope proves integrity, not correctness — a semantically wrong envelope carries a perfectly valid self-digest. The release gate could have been cleared by output that was simply wrong. That reproduced the exact defect this record was written to avoid: spike 009's own oracle was, on its evidence index's admission, "not an executed test harness", with expectations frozen and never diffed. Clause 5 now requires a post-output comparison of derived ownership against the frozen expectations at zero false positives and zero false negatives — the standard ADR-0012 already names as production-readiness evidence — as a step distinct from the pre-output freeze/audit, each recording its own hashes and PASS/FAIL. The same review found "at least one annotated entity ... a floor rather than a target" set no enforceable adequacy bar, so an audited single hand-picked descriptor still satisfied the letter. The defect is accepted; the proposed remedy of fixing an exact minimum count is not, because ADR-0012 requires production limits be ratified from evidence rather than guessed. The independent audit must instead record an explicit adequacy finding. The reviews disagreed on whether the frontmatter assertion had drifted from clause 5 again. The PASS found it "less detailed ... but asserts nothing the body denies"; the FAIL held that an assertion omitting the body's selection-basis and size controls is enforceable as written and therefore weaker than the clause it encodes. The FAIL was upheld: clause 8 designates that assertion as the rule a future CI gate compiles from. The drafting session had found the same omission independently before either review returned. The assertion now carries the selection basis, size, adequacy finding and post-output comparison. Also corrects the review history's own round count (it still read "two rounds") and adds the post-output comparison as its own action item. Four rounds, eight reviews, a substantive defect in every round — three of them in the accept-path gate, each created by the previous round's fix to it. Round 4's corrections are not themselves reviewed, and the record says so. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sets status: accepted and provenance.ratifiedBy: "@mbeacom", and adds the ratification banner following the ADR-0015/ADR-0019 convention. The banner records two things that are not otherwise checkable from the repository: 1. How ratification happened. The maintainer ratified by instruction during an agent session, delegating the mechanical edit rather than typing it. ratifiedBy names the deciding human, which is accurate, but the manner is recorded because this is the first record ratified that way and the repository cannot show it. 2. What was open at the time. Round 4's corrections had not been independently reviewed, and across four rounds and eight reviews every round found at least one substantive defect — three in the accept-path gate, each created by the previous round's fix to it. The earlier stated standard ("stop after round 3 if it is clean") was not met on its own terms, since round 3 was not clean; the maintainer overrode it deliberately. Ratifying on that basis is a judgement about where the remaining risk sits, not a claim the record is defect-free. The agent-accepted-requires-ratifier gate was observed failing on this record with ratifiedBy removed, and passing with it restored, so the rule is load-bearing here rather than assumed (ADR-0016). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
mbeacom
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
specs/009-catalog-binding-viability/— the Backstage catalog-binding spike — already executed and recordedblocked(blockedShortfall: "envelope-or-scale-evidence-incomplete"). Undercontracts/evidence-bundle-and-verdict.md§4 that forcesrecommendation = null, andspec.md's Output Recommendation says even ago-explicit"MUST NOT itself schedule, authorize, or scope apackages/adapters/catalog-backstageimplementation."So no artifact in the repository authorized the adapter. This record is that authorization — for the work, not the release.
Status:
accepted, ratified by @mbeacom on 2026-08-04.Why the
blockedverdict does not measure the generatorThe shortfall is narrower than its name. Scale evidence was captured for all three passes (T052/T056/T060
[X], aggregated T061); only the envelope half fired. Of three required passes, onlysyntheticproduced a populated envelope.SC-010 admits no passing implementation under FR-001's frozen inputs.
community-pluginscontainsnexus-repository-manager/catalog-info.yaml— two YAML documents, bothkind: Component, bothmetadata.name: backstage-community-nexus-repository-manager(44 chars, passesisValidObjectName). Both fully admissible, so ADR-0012'sowned-paths-fail-closed-atomicassertion requires the abort. SC-010 names that corpus non-fungibly.ADR-0015 established this while explicitly declining to benefit from it, and its Conditions of Acceptance 3 expressly permits a rescope "subject to a separate record." This is that record — it does not claim ADR-0015 required it.
What it decides
derivedPathPatternsordering and must be re-frozen. Release is deferred to a later record gated on clause 5 plus ADR-0012 gates 3 and 4.The gap it does not paper over
The reject path is proven on 194 real descriptors; the accept path only on synthetic input. Clause 5 makes that a release gate requiring two distinct steps: the accept corpus, its maintainer-authored
adrkit.io/owned-pathsoverlay, its expected paths and its recorded selection basis and size are frozen and independently audited before generator output; and after the run, derived ownership is diffed against those frozen expectations at zero false positives and zero false negatives. A digest proves integrity, not correctness.Also recorded honestly: zero of 156 real descriptors carry the annotation. Clause 5 gates technical compatibility only — adoption is entirely ungated, and the adapter could clear every gate here and release into zero demand.
Review
Adversarial review from fresh contexts, two model lineages, four rounds, eight reviews. Every round found at least one substantive defect; every finding was accepted.
Three of the four defects were in the accept-path gate, each created by the previous round's fix to it. The record documents this non-convergence in its own Review history rather than claiming a clean bill, and states plainly that round 4's corrections are themselves unreviewed at ratification.
Checks
bun test857 pass / 0 fail ·typecheckclean ·check:deps→core-has-no-adapter-deps: ok·adr lint→ 20 records, 0 errors, 0 warnings.Per ADR-0016,
agent-accepted-requires-ratifierwas observed failing on this record withratifiedByremoved and passing with it restored, so the ratification gate is load-bearing rather than assumed.The one non-doc change is bumping the dogfood corpus count in
packages/cli/test/lint.test.tsfrom 19 → 20, matching the established pattern for adding a record.