docs(architecture): define effective capability at consuming boundaries

[andrexibiza]

What does this PR do?

Defines the cross-cutting rule that configured intent cannot impersonate current effective capability.

The new contract separates the full capability lifecycle:

configured
  -> resolvable
  -> authenticated
  -> policy-admitted
  -> currently effective
  -> exercised
  -> settled

It requires the component that owns the side effect to obtain or revalidate an exact, scope-bound proof at the consuming boundary and to consume it atomically with the effect. It also keeps optional absence, denial, ambiguity, unavailability, and staleness distinct, and preserves the separate settlement obligation after an operation is exercised.

This is deliberately a semantic contract rather than a premature universal runtime class. Existing subsystem owners retain their native proof types and implementation topology.

Related Issue

Composes the existing architecture owners rather than opening or closing a duplicate umbrella:

• [Architecture] Make observable state proof-carrying from source to side effect #90866 — proof-carrying state composition
• [Architecture] Make qualified identity monotonic across Hermes subsystem boundaries #90142 — qualified identity
• [Architecture] Proof scope must equal mutation scope #90144 — proof/mutation scope
• [Architecture]: recovery and teardown must be fenced by durable generation identity #90145 — generation fencing
• [Architecture]: make false success a first-class defect class with typed completion proofs #90049 — typed completion and settlement
• [Architecture] Treat built artifacts and real protocol peers as part of the system under test #90150 — delivered artifact and real-peer realization
• [Architecture] GitHub automation has split authority: metadata writes succeed while repository-object writes fail #90200 / fix(github): preflight repository-object authority #90230 — operation-specific GitHub authority
• [Architecture / Publication] Task Completion Verification — exact-object completion as the sixth Hermes law #91230 — exact-object task completion
• fix(gateway): canonical routing identity — claimant-generation object not published #89252 — current credential claimant/generation
• feat(update): add deployment-plan admission with fail-closed legacy guard #91316 — deployment-plan physical consumption

Concrete evidence: #91695, #91720, and #91828.

Type of Change

• 📝 Documentation update

Changes Made

• docs/effective-capability-contract.md
  • defines the normative state model and consuming-boundary rules;
  • specifies exact proof dimensions, atomicity, and typed verdicts;
  • provides an adversarial acceptance matrix and review checklist;
  • maps the contract onto the surviving architecture and implementation owners.
• docs/ADR.md
  • records the proposed architecture decision;
  • links the detailed contract;
  • captures consequences for mutation authority, degraded legacy paths, and boundary-level tests.

How to Test

1. Confirm the branch is based directly on current upstream main at b6bcb3e791c673e63974029bbab40cc9326803ff.
2. Confirm the diff is limited to docs/ADR.md and docs/effective-capability-contract.md.
3. Confirm the relative ADR link resolves to the new contract and the issue/PR interlocks resolve in GitHub.
4. Review the acceptance matrix against the concrete behavior in fix(browser): live Developer Mode revocation + restart-safe artifact TTL #91695, feat(nix): wait for the backend bind target before it starts #91720, fix(desktop): stop missing plugin entries from flooding IPC logs #91828, fix(gateway): canonical routing identity — claimant-generation object not published #89252, and feat(update): add deployment-plan admission with fail-closed legacy guard #91316.

No runtime, configuration, schema, dependency, or generated artifact changes are present.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched open and merged PRs/issues and found adjacent implementations, not an existing cross-cutting contract
• My PR contains only changes related to this architecture decision
• Tests are N/A: documentation-only, with no executable surface changed
• Platform testing is N/A: the contract is platform-independent

Documentation & Housekeeping

• Relevant documentation is the entire change
• cli-config.yaml.example is N/A; no config keys changed
• CONTRIBUTING.md and AGENTS.md are unchanged; no contributor workflow is changed
• Cross-platform impact is explicitly included in the subsystem-neutral contract
• Tool descriptions/schemas are N/A; no model tool behavior changed

Architecture issue receipts

• #90866 — canonical Pattern 5 composition
• #90144 — capability proof scope
• #90145 — generation-bound validity
• #90049 — exercise versus settlement
• #90150 — realized artifact and peer capability
• #90200 — operation-specific GitHub authority
• #91230 — exact-object completion interlock
• #89252 — current claimant adoption
• #91316 — physical deployment-plan adoption

Exact object

• Base: b6bcb3e791c673e63974029bbab40cc9326803ff
• Head: 3a4e1ba23be41ff81045fabc51f5955be3e292fc
• Topology: two commits, two documentation files, 281 additions, zero deletions

[andrexibiza]

Exact-head verification snapshot

Verified against PR head 3a4e1ba23be41ff81045fabc51f5955be3e292fc:

• upstream main remains b6bcb3e791c673e63974029bbab40cc9326803ff;
• merge base equals that exact upstream object;
• branch is 2 commits ahead / 0 behind;
• changed path set is exactly docs/ADR.md and docs/effective-capability-contract.md;
• diff is 281 additions / 0 deletions;
• GitHub currently reports the PR mergeable;
• Docker Build, Test, and Publish — success;
• Nix flake check — success;
• CI — queued at this snapshot.

No runtime, generated artifact, dependency, schema, or configuration surface is changed.

[andrexibiza]

Closure receipt at exact current head 3a4e1ba23be41ff81045fabc51f5955be3e292fc: CI 32537542893, Docker 32537542514, and Nix 32537542515 all completed successfully. Review-thread census is empty. No status is inherited from the base or adjacent PRs; this receipt is bound to the submitted object.

[Enough1122]

AI code review — automated review for reference, author can ignore or act on any point.

Docs-only ADR + contract (docs/ADR.md, docs/effective-capability-contract.md). The core distinction — configured intent selects candidates, consuming boundaries prove authority — is sound, and the explicit choice to keep it semantic ("not a requirement that every subsystem import one universal EffectiveCapabilityProof class") avoids turning the contract into speculative runtime infrastructure, which is the right call for this repo.

Suggestions:

1. Evidence citations point at open PRs. "Concrete evidence already demonstrates the rule" cites fix(browser): live Developer Mode revocation + restart-safe artifact TTL #91695, feat(nix): wait for the backend bind target before it starts #91720, fix(desktop): stop missing plugin entries from flooding IPC logs #91828 (and the ADR context references refactor(bot-mode): add shadow control-plane contracts #91917) — several are unmerged/open at posting time. If any of those get reworked or closed, the ADR's evidence base dangles silently. Either mark them as pending/proposed or cite merged commits only.

2. One worked walkthrough would help adoption. The seven-state progression (configured -> ... -> settled) plus six failure verdicts is a lot to hold abstractly. Walking a single real path end-to-end (e.g. browser-control Developer Mode revocation through all seven states, including where it regresses mid-flight) would give implementers a reference translation. The acceptance matrix is close to this, but scenario-table rows ≠ one continuous trace.

3. Discoverability: repo-root docs/ADR.md isn't part of the Docusaurus tree under website/docs/. If that's deliberate (internal-only ADRs), fine — otherwise a cross-link from the developer guide helps external contributors find the contract they're being reviewed against.

The non-goals section (no speculative probing, no process-global registry, recovery may obtain fresh proofs) is well scoped.