reanimator 0.1.0

data/README.md

@@ -0,0 +1,483 @@
+# Reanimator
+
+**Turn repository intent into a verified, low-friction stewardship contract.**
+
+An [Autogenetica](https://autogenetica.ai) system for self-maintaining software.
+
+> The first successful Reanimator run should prove something useful without
+> changing a single line of code.
+
+Reanimator reads a repository, infers what *healthy* means for it, and proves
+that health **read-only** — before any coding agent or write permission is ever
+involved. It classifies lifecycle intent, discovers a vitality contract from
+evidence, resolves an effective policy against a non-bypassable safety floor,
+and produces a proof-of-life baseline.
+
+This gem implements the read-only foundation of the
+[Onboarding & Configuration Specification](#specification-coverage): delivery
+slices 1–2 (inventory & intent, discovery & baseline) plus the canonical schema
+and effective-policy resolver. It is the "trustworthy heartbeat" the spec says
+to ship before building an autonomous surgeon.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "reanimator"
+```
+
+```console
+$ bundle install
+# or, standalone:
+$ gem install reanimator
+```
+
+Requires Ruby >= 3.3.
+
+## The onboarding path, on the command line
+
+Every command is **read-only by default** and maps to an onboarding stage.
+
+### 1. Classify before acting — `inventory`
+
+```console
+$ reanimator inventory ~/src/*
+Portfolio inventory — 12 repositories
+Recommended for onboarding: agentic, claude_memory, eliza
+
+Active original repositories → suggest maintain:
+  - agentic — Active original repository with recognizable structure.
+Forks → suggest upstream:
+  - langchainrb — The repository is a fork; defaulting to upstream observation.
+```
+
+Reanimator never preselects every repository — it recommends a small,
+high-confidence set that can reach a useful baseline quickly.
+
+### 2. Find proof before asking for policy — `discover`
+
+```console
+$ reanimator discover
+Suggested profile: ruby-gem (high) — A gemspec indicates a published gem.
+
+ecosystem:
+  [high] Packaged and released as a Ruby gem.  ← widget.gemspec (file_present)
+commands:
+  [high] Tests run with RSpec.  ← .rspec (command_inference): bundle exec rspec
+support matrix:
+  [medium] Declared Ruby support: >= 3.1.0.  ← widget.gemspec (version_pin): >= 3.1.0
+```
+
+Every discovered fact carries its **provenance and confidence**, so the tool can
+always answer *"Why does Reanimator believe this?"*
+
+### 3. Review the effective contract — `contract`
+
+```console
+$ reanimator contract
+Effective contract — codenamev/widget
+Intent:   maintain (provisional)
+Profile:  ruby-gem (inferred) — A published Ruby gem: resolves, tests, lints, and builds.
+Autonomy: observe=automatic  diagnose=automatic  repair=disabled  submit=disabled  merge=disabled
+
+Security posture: balanced
+  Approved package-registry network, hosted agents allowed, patch submission permitted, no major automatic repair.
+  Required: none
+  Advisory: dependency review, secret scanning, security policy
+
+Criteria (* = required):
+  * tests: Test suite passes. — bundle exec rspec
+    security-dependency-review: Dependency risk is reviewed automatically. — security_evidence
+  ...
+Protected paths (elevated review to change):
+  - .reanimator.yml
+  - .github/workflows/**
+```
+
+Export a minimal, round-trippable `.reanimator.yml`:
+
+```console
+$ reanimator contract --export
+version: 1
+intent: maintain
+profile: ruby-gem
+```
+
+### 4. Measure a proof-of-life baseline — `baseline`
+
+Read-only by default (native checks run; commands are *planned*):
+
+```console
+$ reanimator baseline
+State:   UNPROVEN — A claim exists but sufficient executable evidence is absent or stale.
+Mode:    read-only (planned)
+```
+
+Opt in to bounded execution to actually prove life:
+
+```console
+$ reanimator baseline --execute
+State:   ALIVE — All due obligations have fresh passing evidence and no unapproved blocking risk.
+Mode:    executed (bounded, read-only)
+Verified Vitality Rate: 100% (3/3 required)
+  ✓* tests: Test suite passes. — bundle exec rspec (1.69s)
+  ✓* build: Gem builds. — gem build widget.gemspec (0.32s)
+
+NO SOURCE CHANGES WERE MADE
+```
+
+Other formats: `--format check` (the GitHub Check surface) and `--format json`.
+
+### 5. Prove an agent is ready — `agents` and `commission`
+
+The agent is a replaceable life-force adapter: a repair provider is *commissioned*
+against a disposable fixture and graded independently — **without any repository
+write**.
+
+```console
+$ reanimator agents
+Coding agents:
+  ✓ local (available) [plan, patch, repository_edit, sandbox_exec]
+  ◦ codex (unavailable) [...] — No credentials found (set OPENAI_ACCESS_TOKEN); connect the codex provider first.
+
+$ reanimator commission
+Commissioning — local
+Readiness: READY
+Objective: arithmetic (at risk → alive)
+Cost: $0.00  Latency: 0.001s  Tools: repository_edit, patch  Network: none
+A connected profile is proven ready. NO REPOSITORY WRITES WERE REQUIRED.
+```
+
+The agent proposes a **patch as data**; the harness applies it to a separate,
+clean copy and grades it with Reanimator's own evaluators. A patch that reaches
+for a protected or verifier path is refused — the anti-gaming rule, enforced.
+
+### 6. Bounded repair — `repair`
+
+A repair is found, applied in an isolated workspace, and **re-verified
+independently** before anything is proposed. The result is a *draft PR
+artifact* — never a write, never a submission.
+
+```console
+$ reanimator repair            # on a healthy repo
+Outcome:  NO-OP (healthy)
+
+$ reanimator repair            # repair not yet enabled in the contract
+Outcome:  ESCALATION
+Reason:   Repair is not enabled for patch_dependency (max autonomy diagnose); enable repair to proceed.
+
+$ reanimator repair            # repair enabled, a fixable failure present
+Outcome:  DRAFT PR (proposed, not submitted)
+Evidence: at_risk → alive
+Proposed draft PR:
+  branch: reanimator/repair-arithmetic-901cec8a
+  title:  Fix: add(2, 2) equals 4.
+NO SOURCE WAS WRITTEN TO THE REPOSITORY.
+```
+
+Every outcome is recorded as an immutable run-ledger entry (`no_op`, `report`,
+`draft_pr`, `escalation`, `safe_stop`). Submitting a proposed change to GitHub is
+a deliberate, separate step — not something repair does on its own.
+
+### Repository families — `families` and `gates`
+
+Related projects are a compatibility graph, not isolated targets. Families are
+inferred from portfolio structure (a project and its `-examples` suite,
+`-example-*` deployment samples, `-docs`, or a `<host>-<project>` plugin):
+
+```console
+$ reanimator families ~/src/*
+Repository families — 2 families (4 repositories that must stay alive together)
+
+agentic:
+  - agentic (library)
+  - agentic-examples (compatibility suite)
+  edge: agentic -> agentic-examples (compatibility suite)
+  gate: agentic requires its own proof command in agentic-examples
+```
+
+`gates` proves each edge by running the downstream member's own check — read-only,
+bounded, in a disposable copy, so an upstream change triggers downstream checks
+**without opening anything downstream**. A failure names the exact edge:
+
+```console
+$ reanimator gates ~/src/* --execute
+Family gates — slimer
+  ✗ slimer -> slimer-example-docker (deployment example) — bin/smoke failed.
+BROKEN EDGE: slimer -> slimer-example-docker (deployment example)
+```
+
+A repository can also declare its membership (`family: {id:, role:}`), and a full
+section 10 family policy with explicit `members:` and `gates:` is parsed as-is.
+Declaration always wins over inference.
+
+### Configuration drift — `drift`
+
+A contract is only trustworthy while it still describes the repository. Drift
+detection compares what a repository resolved to when you recorded it against
+what its evidence resolves to now, and sorts every difference by one question:
+**is less being proven than before?**
+
+```console
+$ reanimator drift                       # what am I required to prove right now?
+Contract snapshot — codenamev/widget
+Intent:   maintain   Profile: ruby-gem   Security: balanced posture
+Proves:   4 criteria (2 required)
+Evidence: runtimes 3.3, 3.4 · security gates dependabot
+
+Nothing was written. Record this with `reanimator drift --record` so later drift has something to be measured against.
+
+$ reanimator drift --record
+Recorded contract snapshot for codenamev/widget → .reanimator-snapshot.json
+
+$ reanimator drift                       # now there is something to compare against
+Configuration drift — codenamev/widget
+
+Policy changes (review required) — 2
+  ! supported runtime removed: 3.2
+    The runtime matrix narrowed: a version that used to be exercised no longer is.
+  ! security control removed: dependabot
+    A security gate was removed; it is no longer part of the proof.
+
+Benign changes — 1
+  · criterion tests command: bundle exec rspec → bin/rspec
+    The same obligation is proven by a differently spelled command.
+
+REVIEW REQUIRED: 2 policy changes — less is being proven than before.
+
+Intended? Re-record with: reanimator drift --record
+```
+
+A renamed test command is benign — the obligation did not move, only its
+spelling. A narrowed matrix or a removed gate is a policy change nobody
+necessarily decided on, so it is never buried in the benign list. The command
+exits non-zero on policy drift, so CI can gate on it (and says how to accept
+drift you meant). The snapshot captures
+*discovered* evidence too — drift that never touches `.reanimator.yml` is
+still caught.
+
+The snapshot lives **in the repository**, committed as
+`.reanimator-snapshot.json` beside `.reanimator.yml`. That is deliberate:
+the contract and the record of what it last required are the same kind of
+thing, and keeping both under review means a policy change arrives as a diff in
+a pull request rather than as state hidden inside a tool.
+
+#### Across a portfolio
+
+Pass several paths and drift becomes a triage list. Each repository is compared
+against its own snapshot, and one unreadable member never stops the rest:
+
+```console
+$ reanimator drift ~/src/*
+REANIMATOR DRIFT
+Portfolio: portfolio
+Mode: read-only
+
+REVIEW REQUIRED — 1 repository
+  codenamev/widget
+    1 policy change
+      ! security control removed: dependabot
+        A security gate was removed; it is no longer part of the proof.
+
+CHANGED, BENIGN — 1 repository
+  codenamev/doodad
+    · criterion tests command: bundle exec rake spec → bundle exec rspec
+
+UNCHANGED — 3 repositories
+  codenamev/gadget
+  codenamev/gizmo
+  codenamev/thing
+
+NOT RECORDED — 1 repository
+  codenamev/fresh
+    nothing to compare against yet
+
+REVIEW REQUIRED: 1 policy change across 1 repository — less is being proven than before.
+Intended? Re-record with: reanimator drift --record
+
+NO FILES WERE WRITTEN. NO SOURCE CHANGES WERE MADE.
+```
+
+For repositories you cannot commit a file into, `--snapshots DIR` keeps them
+side by side keyed by repository instead:
+
+```console
+$ reanimator drift ~/src/* --snapshots ~/.reanimator/snapshots --record
+```
+
+Three outcomes are deliberately distinct. A repository with **nothing
+recorded** is named, not counted as fine, and does not fail the gate — a first
+run has nothing to compare against. A repository whose snapshot **cannot be
+read** does fail it: "we could not tell" is not "nothing changed", and
+corrupting a snapshot must never be a way to pass. Benign change never fails
+it at all.
+
+### Security posture — what it actually binds
+
+The posture is a named decision with consequences, not a label. It decides how
+much security evidence a repository has to show; the project's shape does not.
+
+```yaml
+# .reanimator.yml
+version: 1
+intent: maintain
+profile: ruby-gem
+security:
+  posture: strict      # strict | balanced | local | custom
+```
+
+| Posture | Blocks without evidence | Reported, not blocking |
+| --- | --- | --- |
+| `strict` (default for private repositories) | security policy, dependency review, secret scanning | static analysis, ownership |
+| `balanced` (default for public repositories) | — | dependency review, secret scanning, security policy |
+| `local` | secret scanning | dependency review |
+| `custom` | — | — |
+
+Controls are named by **obligation, not by tool**: "dependency risk is reviewed"
+is satisfied by Dependabot, `bundler-audit`, or `actions/dependency-review-action`
+alike, so a repository that already solved the problem its own way is credited
+rather than asked to adopt ours. A control with no evidence is reported as
+*missing evidence* with the remedy attached — never as a silent pass:
+
+```console
+  •  security-secret-scanning: Committed secrets are scanned for.
+     — No secret scanning found. Add gitleaks or trufflehog to CI.
+  ✓  security-policy: A security policy says how to report a vulnerability.
+     — A security policy is published (SECURITY.md).
+```
+
+Under `strict` and `local` those gaps are blocking, so a repository with no
+security evidence is **Unproven**, not Alive. When the gap is a deliberate,
+tracked decision, accept it with a waiver rather than weakening the posture.
+
+`custom` implies nothing in either direction: "no hidden relaxation from a
+preset" means Reanimator adds no control you did not ask for, either.
+
+### Accepted risk — waivers
+
+Sometimes a known failure is a deliberate, tracked decision, not a gap. A waiver
+records it as **accepted risk** — visible, attributable, and kept out of the
+vitality rate — without pretending it passed:
+
+```yaml
+# .reanimator.yml
+version: 1
+intent: maintain
+profile: ruby-gem
+waivers:
+  - target: boot                       # the acceptance-criterion id
+    reason: "hardware-only smoke; tracked in OPS-7"
+    expires: 2030-01-01                # optional; past this it fails closed
+```
+
+The baseline then reports `boot` under "Accepted risk (waived)" instead of as a
+blocker, and the repository can be **Alive** with the risk shown separately. An
+expired waiver stops applying and the obligation is blocking again.
+
+### Resolved autonomy — `permissions`
+
+```console
+$ reanimator permissions
+Permissions — codenamev/widget (autonomy: observe=automatic diagnose=automatic repair=disabled …)
+  Patch dependency update: max=diagnose | observe=auto diagnose=auto repair=off submit=off merge=off …
+  CI or verifier modification: max=diagnose | … [elevated review]
+```
+
+Task-class defaults (section 11) are intersected with the repository's *enabled*
+autonomy and the safety floor: with repair/submit opt-in and off, everything
+clamps to diagnose; merge is always off in v1.
+
+### The portfolio baseline (Appendix A)
+
+```console
+$ reanimator portfolio ~/src/* --name codenamev
+REANIMATOR BASELINE
+Portfolio: codenamev
+Mode: read-only
+
+ALIVE
+  agentic
+UNPROVEN
+  ups
+    - Boot smoke against /up needs a running service; not established in a read-only baseline.
+
+NO SOURCE CHANGES WERE MADE
+No coding agent was required.
+```
+
+## Library API
+
+The CLI is a thin shell over a plain Ruby API — the same "80% path" in one call:
+
+```ruby
+require "reanimator"
+
+Reanimator.inventory(paths)          #=> Reanimator::Portfolio
+Reanimator.discover(path)            #=> Reanimator::DiscoveryResult
+Reanimator.contract(path)            #=> Reanimator::EffectiveContract
+Reanimator.baseline(path, execute: true) #=> Reanimator::Baseline
+Reanimator.snapshot(path)            #=> Reanimator::ContractSnapshot
+Reanimator.drift(path, since: file)  #=> Reanimator::DriftReport
+Reanimator.portfolio_drift(paths)    #=> Reanimator::PortfolioDrift
+
+baseline = Reanimator.baseline(".")
+baseline.state.to_sym                  #=> :unproven
+baseline.verified_vitality_rate        #=> 0.0
+baseline.to_h                          # fully serializable
+```
+
+## Core model
+
+The nouns that stay stable while implementations evolve (spec section 02):
+
+| Concept | Class |
+| --- | --- |
+| Lifecycle intent | `LifecycleIntent` (maintain, monitor, preserve, incubate, retire, upstream, ignore) |
+| Vitality profile | `VitalityProfile` / `Profiles` (ruby-gem, ruby-cli, rails-app, rails-legacy, …) |
+| Discovered fact | `DiscoveredFact` (+ `Provenance`, `Confidence`) |
+| Effective contract | `EffectiveContract` (+ `EffectivePolicyResolver`, `SafetyFloor`) |
+| Baseline | `Baseline` (+ `BaselineRunner`, `Evaluators`, `ProofOfLife`) |
+| Repository state | `RepositoryState` (alive, at risk, needs you, recovering, unproven, sleeping, diverged, retired) |
+
+Two rules are **enforced**, not just documented:
+
+- An owner-declared contract wins over inference.
+- Neither a declaration nor discovery may loosen the safety floor — merge stays
+  off in v1, verifier and contract paths stay protected, and a task that
+  modifies the rules of proof cannot use them to approve itself.
+
+## Specification coverage
+
+| Spec area | Status |
+| --- | --- |
+| 01–02 Model, goals, constraints | ✅ Implemented |
+| 04–05 Portfolio intake, lifecycle intent | ✅ `Portfolio`, `Classifier`, `Cohort` |
+| 06 Discovery by confirmation & drift | ✅ `Detectors::*`, provenance, confidence, `DriftDetector`, `PortfolioDrift` |
+| 07 Configuration & precedence | ✅ `EffectivePolicyResolver`, `SafetyFloor` |
+| 09 Acceptance criteria, verifier isolation & waivers | ✅ `AcceptanceCriterion`, `Evaluators`, `Waiver` (accepted risk) |
+| 14–15 Baseline & proof-of-life | ✅ `BaselineRunner`, `ProofOfLife`, `Reports` |
+| 08 Agent connections, commissioning, routing | ✅ `Agents::*`, `Commissioning`, `Routing::Router` |
+| 11 Autonomy ladder & permission model | ✅ `AutonomyLevel`, `TaskClass`, `PermissionModel` |
+| 13 / 17 Bounded repair & run ledger | ✅ `RepairRun`, `Obligation`, `ProposedChange`, `Run` (no writes) |
+| 18 MVP slices 1–4 | ✅ Inventory→baseline→commissioning→bounded repair |
+| 10 Repository families & compatibility graphs | ✅ `Relationship`, `Family`, `FamilyInference`, `Family::GateRunner` |
+| 12 Security controls | ✅ `SecurityControl`, `SecurityPosture#obligations`, `Evaluators::SecurityEvidence` (network egress still advisory) |
+| Draft-PR *submission* to GitHub | ⏳ Deliberate opt-in; artifact is ready, the write is not wired |
+| GitHub App, web UI | ⏳ Explicitly later (spec sections 03, 18) |
+
+See [`.architecture/decisions`](.architecture/decisions) for the reasoning
+behind key choices.
+
+## Development
+
+```console
+$ bin/setup          # install dependencies
+$ bundle exec rake   # run specs and StandardRB
+$ bin/console        # an IRB session with the gem loaded
+```
+
+Releases are manual and credential-free — see [RELEASING.md](RELEASING.md).
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+Security is part of Reanimator's design, not a hidden settings page. The tool
+treats repository content, issues, logs, pull requests, and external
+documentation as **untrusted input**, and treats coding-agent responses as
+**untrusted proposals** until they are independently evaluated.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately to **v@codenamev.com** rather
+than opening a public issue. Include a description, reproduction steps, and the
+affected version. You will receive an acknowledgement, and a coordinated fix and
+disclosure timeline.
+
+## Design guarantees relevant to security
+
+- **Read-only by default.** Inventory, classification, discovery, and baseline
+  require no write permission and never modify repository source.
+- **Disposable-workspace execution.** When checks execute, they run inside a
+  throwaway copy of the repository, never the original working tree, so a build
+  or test cannot mutate the real checkout (no stray artifacts).
+- **Bounded execution.** Any executed check is opt-in (per run and globally) and
+  runs under a hard wall-clock bound that terminates the entire process group,
+  so a spawned child cannot outlive the bound.
+- **Known limitation.** Execution is not yet OS-sandboxed — network egress, user,
+  and resource isolation (spec section 12) are planned but not implemented. Treat
+  `--execute` on untrusted repositories accordingly; it is off by default.
+- **Non-bypassable safety floor.** No configuration layer may loosen verifier
+  isolation, remove protected paths (`.reanimator.yml`, workflows, CODEOWNERS),
+  or enable automatic merge in v1.
+- **Anti-gaming.** A task that modifies the rules of proof cannot use those
+  modified rules to approve itself.

data/exe/reanimator

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "reanimator"
+
+Reanimator::CLI.start(ARGV)

data/lib/reanimator/acceptance_criterion.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A single statement that must remain true for a repository, together with
+  # how it is proven (specification section 09). The acting agent may attempt
+  # the work but may never grade itself, so a criterion names an *evaluator*
+  # rather than trusting a self-reported result.
+  class AcceptanceCriterion
+    # Effect on review and autonomy. Changes to verifier definitions, security
+    # posture, protected paths, or merge authority are :elevated and receive
+    # extra scrutiny even when technically allowed.
+    RISK_CLASSES = %i[low normal elevated].freeze
+
+    # @return [Symbol] stable identity used in reports and history
+    attr_reader :id
+    # @return [String] human-readable statement of what must remain true
+    attr_reader :claim
+    # @return [Symbol] native evaluator name, GitHub check, or :command
+    attr_reader :evaluator
+    # @return [String, nil] the command to run when evaluator is :command
+    attr_reader :run
+    # @return [String, nil] target for evaluators that need one (e.g. /up)
+    attr_reader :target
+    # @return [Boolean] whether failure blocks advancement
+    attr_reader :required
+    # @return [Hash] supported environment, paths, services, or family scope
+    attr_reader :scope
+    # @return [String, nil] how recently evidence must have been produced
+    attr_reader :freshness
+    # @return [String] who may change or waive the criterion
+    attr_reader :owner
+    # @return [Symbol] one of {RISK_CLASSES}
+    attr_reader :risk_class
+    # @return [Provenance, nil] where this criterion came from, when discovered
+    attr_reader :provenance
+
+    def initialize(id:, claim:, evaluator:, run: nil, target: nil, required: true,
+      scope: {}, freshness: nil, owner: "repository", risk_class: :normal, provenance: nil)
+      @id = id.to_sym
+      @claim = claim
+      @evaluator = evaluator.to_sym
+      @run = run
+      @target = target
+      @required = required
+      @scope = scope
+      @freshness = freshness
+      @owner = owner
+      @risk_class = risk_class.to_sym
+      unless RISK_CLASSES.include?(@risk_class)
+        raise UnknownError, "Unknown risk class #{risk_class.inspect}. Known: #{RISK_CLASSES.join(", ")}."
+      end
+      @provenance = provenance
+    end
+
+    def required? = @required
+
+    # Verifier and contract-touching criteria carry elevated risk by policy.
+    def elevated? = risk_class == :elevated
+
+    def to_h
+      {
+        id: id,
+        claim: claim,
+        evaluator: evaluator,
+        run: run,
+        target: target,
+        required: required,
+        scope: scope,
+        freshness: freshness,
+        owner: owner,
+        risk_class: risk_class
+      }.compact
+    end
+  end
+end

data/lib/reanimator/agent_connection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A credentialed provider integration available to an account or organization
+  # (specification section 08 credential model). Credentials are connected at
+  # the account level and **never committed to a repository** - this object
+  # holds only a *reference* to where the secret lives (an environment variable
+  # name), plus the policy envelope the connection operates within: which
+  # repositories it may touch, its code-egress posture, its budget, models, and
+  # execution mode.
+  class AgentConnection
+    # Code-egress postures a connection can declare.
+    EGRESS = %i[none approved_providers any].freeze
+    EXECUTION_MODES = %i[hosted local].freeze
+
+    attr_reader :provider, :display_name, :credentials_ref, :permitted_repositories,
+      :code_egress, :max_cost_usd, :models, :tools, :execution_mode
+
+    def initialize(provider:, credentials_ref: nil, display_name: nil, permitted_repositories: ["*"],
+      code_egress: :approved_providers, max_cost_usd: 8.0, models: [], tools: [], execution_mode: :hosted)
+      @provider = provider.to_sym
+      @display_name = display_name || @provider.to_s
+      @credentials_ref = credentials_ref
+      @permitted_repositories = Array(permitted_repositories)
+      @code_egress = code_egress.to_sym
+      @max_cost_usd = max_cost_usd
+      @models = Array(models)
+      @tools = Array(tools)
+      @execution_mode = execution_mode.to_sym
+      validate!
+    end
+
+    # A local, self-hosted connection: no credentials, no egress, code and
+    # execution stay on user-controlled runners (section 12 "local" posture).
+    def self.local(**overrides)
+      new(provider: :local, code_egress: :none, execution_mode: :local,
+        display_name: "Local rule-based agent", **overrides)
+    end
+
+    def local? = execution_mode == :local || provider == :local
+
+    # Whether this connection is permitted to act on a repository full name.
+    def permits?(full_name)
+      permitted_repositories.any? { |glob| File.fnmatch?(glob, full_name.to_s, File::FNM_PATHNAME) }
+    end
+
+    def to_h
+      {
+        provider: provider, display_name: display_name, credentials_ref: credentials_ref,
+        permitted_repositories: permitted_repositories, code_egress: code_egress,
+        max_cost_usd: max_cost_usd, models: models, execution_mode: execution_mode
+      }
+    end
+
+    private
+
+    def validate!
+      raise UnknownError, "Unknown code_egress #{code_egress.inspect}." unless EGRESS.include?(code_egress)
+      raise UnknownError, "Unknown execution_mode #{execution_mode.inspect}." unless EXECUTION_MODES.include?(execution_mode)
+    end
+  end
+end