Skip to content

About

core-methodologies

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

Surgical DevOps

Accelerator Conformance License: MIT

A deterministic operational boundary for probabilistic AI engineering agents.

Português: README_PT-BR.md

Surgical DevOps is an open-source development orchestrator that keeps AI models outside the operational trust boundary. Models may reason, explain, and propose. Human authority, scope, execution, evidence, mutation, and failure handling remain governed by deterministic contracts.

The project does not claim to make a language model deterministic. It makes the operational system around the model explicit, bounded, auditable, and fail-closed.

Current qualified baseline

Evidence Value
Release line Surgical AI Control Plane product v0.1.0-beta.1 on Surgical DevOps v2.6.0-rc.6
Qualified architectural parent ecc87210f0ab3aee93064bba917d859e7028e706
Historical release-candidate baseline 24f0f1946eb795b3464b2846953e191755b9c8c3; preserved for the rc.6 evidence chain
Historical exact-ref qualification Accelerator Conformance 34860826996; Ubuntu, macOS, and Windows: PASS
Historical main-push qualification Accelerator Conformance 34862373028; same SHA and native matrix: PASS
Review binding policy RUNTIME_EXACT_SHA_EVIDENCE; CI produces the exact SHA/run/artifact tuple
Product qualification Exact feature-branch SHA, native runs, and artifact hashes are recorded by CI; no public release is authorized
Active normative protocols BH-SEP v2.4 + BH-SDP v2.4; containment integrated in RAW

The complete trail, including runs that failed before the green baseline, is in Engineering Evidence. Independent reviewers can start with the External Engineering Review Package.

Why this project exists

AI engineering tools are probabilistic, but filesystem writes, process execution, Git state, credentials, and production mutation require deterministic authority:

Human objective
      |
      v
Probabilistic cognition (no operational authority)
      |
      v
Deterministic admission and authority contracts
      |
      v
Canonical Orchestrator
      |
      v
Governed adapter -> bound evidence or fail-closed result

The AI provider never becomes an authority provider. A useful answer, a plan, or a confident model output does not authorize a physical operation.

Core invariants

  • Human sovereignty: critical authority originates from verified human intent.
  • Intent is not authority: natural language does not create capabilities.
  • Inspect first: mutation requires declarative inspection and bounded scope.
  • PATCH by default: minimal changes take precedence over broad rewrites.
  • Exact grants: operations bind action, target, workspace, lifecycle, risk, and identity.
  • No direct model execution: cognitive providers receive no filesystem, shell, process, network, credential, or mutation authority.
  • Durable mutation state: locking, journal, commit authority, recovery, and replay remain explicit.
  • Fail-closed: missing, invalid, expired, ambiguous, or unqualified evidence cannot become success.

Platform qualification

Platform Qualified mechanism Evidence status
Linux Bubblewrap deny-default containment and POSIX primitives Historical exact-ref baseline: PASS; final EER-1 artifact pending authorized CI
macOS Seatbelt deny-default profile applied by fixed native helper Historical exact-ref baseline: PASS; final EER-1 artifact pending authorized CI
Windows Fixed Win32 security/durability helper and governed adapters Historical exact-ref baseline: PASS; final EER-1 artifact pending authorized CI

These mechanisms are not presented as identical sandboxes. They are different native implementations evaluated against common bounded contracts. See Engineering Evidence.

Governed AI and interaction modes

  • NATURAL: outcome-oriented language and progressive disclosure.
  • ENGINEER: natural language with relevant technical evidence.
  • EXPERT: deterministic command-oriented control.

NATURAL may automatically discover and activate only a qualified local Ollama model already installed behind the canonical loopback transport; it never downloads a model. External providers are explicit opt-in only, and an explicit human selection is never silently replaced. No selection grants operational authority. Providers are replaceable and remain outside operational authority. Broad analyses in NATURAL mode cross human authorization, bind a deterministic physical workspace session, open a governed discovery index, inspect sensitive content before provider exposure, evaluate micro-reads against a bounded task envelope, and record an audit without content.

For advanced repository engineering, OpenAI Codex is the recommended reference agent and the closest target to the complete conversational development loop. This recommendation grants no privileged authority and claims no universal comparative superiority. See the bilingual AI provider selection guide.

ENGINEER mode adds an immutable proposal bound to the observed READ_FILE target and the actual BEFORE SHA-256. The flow must stop at HUMAN_AUTHORITY_REQUIRED; physical mutation remains a separate explicit R3 operation.

Quick start

Declared runtime: Node.js >=24.18.0.

Install the supplied beta artifact; no development source checkout is required:

npm install -g ./surgical-dev-ops-2.6.0-rc.6.tgz
surgical init --profile developer
surgical doctor
surgical start
surgical demo

See the customer documentation for repository onboarding, authority, evidence, recovery, upgrade, and removal.

To run the governed Codex SDK integration with the same command on Linux, macOS, and Windows:

npm run start:codex

This path uses the local Codex authentication already configured on the machine. Codex remains cognitive-only and read-only; physical mutations continue through the governed Surgical DevOps adapters.

The compatibility executable surgical is also provided. To run the suite:

On first launch in a human terminal, bilingual onboarding selects one of the three experiences provided by the same installation: NATURAL, ENGINEER, or EXPERT. To redo the interface preference:

surgical-devops --configure

To use a profile only for the current invocation, without changing the saved preference:

surgical-devops --interaction NATURAL
surgical-devops --interaction ENGINEER
surgical-devops --interaction EXPERT

To select the complete human-facing language only for the current invocation, without rewriting the saved preference:

surgical-devops --language pt-BR
surgical-devops --language en

The preference contains no operational authority. All profiles use the same Orchestrator and the same BH-SEP/BH-SDP, R3, journal, Manifest CAS, and anti-replay contracts.

To run the suite:

npm ci
npm test

Normative protocols and immutable RAW artifacts

Protocol versions are independent from the Surgical DevOps software release; v2.6.0-rc.6 identifies the Surgical runtime, while product v0.1.0-beta.1 identifies the customer surface and BH-SEP and BH-SDP v2.3 govern the current runtime.

v2.2 — historical and preserved

v2.3 — historical and preserved

Derived joint copy of v2.3

v2.4 — current containment-integrated RAW

The active protected profile is BH-SEP v2.4 + BH-SDP v2.4 with containment integrated directly into the normative RAW. v2.3 remains immutable historical evidence.

Historical v2.3 BH-CONTAINMENT operational profile

The historical v2.3 protected profile is BH-SEP v2.3 + BH-SDP v2.3 + BH-CONTAINMENT. It remains preserved as immutable historical evidence and must not be used as a less restrictive fallback for the active v2.4 contained profile.

Future versions must use new versioned paths and must not overwrite or redirect the original RAW artifacts. See Protocol Preservation and ADR-018.

Architecture and evidence

What green CI does not claim

  • It is not proof of absolute security.
  • It does not make probabilistic model reasoning deterministic.
  • It does not claim universal durability against physical power loss.
  • POWER_LOSS_VALIDATED remains false until specific physical qualification.
  • Strict pathname CAS remains unqualified according to ADR-009.
  • Windows, Linux, and macOS do not have identical isolation primitives.
  • External adversarial review remains a separate qualification.
  • The reproducible external challenge is available at docs/review/TRY_TO_BREAK_IT.md.

Unsupported claims remain unqualified rather than becoming green.

Contributing and license

Read CONTRIBUTING.md. Changes must preserve the authority model, bilingual parity, stable RAW artifacts, and fail-closed behavior.

MIT © 2026 Thales Rangel.

About

core-methodologies

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages