ANPOS Repository Supervisor Plugin Blueprint

Status: source blueprint plus GitHub read/write Repository Supervisor runtime aligned to ANPOS 1.4.0 / Requirements 83–96. This directory defines the product/runtime contract for a ChatGPT/Codex plugin that accepts a user-supplied GitHub or GitLab repository URL and supervises ANPOS-based project initialization, adoption, audit, and development. The GitHub read-only runtime, entitlement bridge, OAuth 2.1/PKCE broker and stateless /mcp source are implemented in the vendor-only commercial service, but no public plugin connection or production MCP deployment is claimed and no live credentials belong in this repository.

Product goal

The user supplies one repository URL, for example:

https://github.com/owner/repository

or:

https://gitlab.com/group/repository

The plugin then:

resolves the repository provider and canonical repository identity;
authenticates the user through the plugin MCP server using provider-appropriate OAuth;
performs a read-only repository audit;
classifies the repository's ANPOS state;
proposes the smallest safe next action;
performs writes only through a feature branch / change request with optimistic concurrency;
continues the ANPOS Supervisor workflow after the repository is safely initialized or adopted.

The repository URL is a locator, not authorization.

ANPOS 1.4.0 assurance baseline

The supervisor must understand the active ANPOS 1.4.0 child control plane, including the unified Requirements 83–96 assurance state.

For an ANPOS child, audit/resume/upgrade flows must inspect the project-specific evidence state for:

Requirements 83–88: AI/model evaluation, user/problem validation, product analytics, experimentation, progressive delivery, and engineering maintainability;
Requirements 89–96: responsible-AI/human oversight, compliance evidence, architecture decision records, AI asset/configuration identity, deprecation/EOL, operational runbooks/resilience drills, tamper-evident audit evidence, and unified risk/exception lifecycle.

Policy-file presence is never pass evidence. The plugin must preserve verified project evidence, distinguish pending/applicable/not-applicable states, and bind pass claims to the exact verified source/runtime/configuration reference.

OpenAI plugin shape

Use the portable Agent Plugins layout:

anpos-repository-supervisor/
├── plugin.json
├── mcp.json
└── skills/
    └── anpos-repository-supervisor/
        └── SKILL.md

The MCP server owns authentication, authorization, provider API access, concurrency checks, mutation safety, audit logging, and ANPOS release retrieval. The skill owns the deterministic workflow and tells the model how to use those tools.

The committed mcp.json intentionally keeps https://replace-me.invalid/mcp because this repository is inert source. A deployed plugin package must replace that placeholder with the exact ANPOS_PUBLIC_BASE_URL + /mcp endpoint only after /api/ready/mcp and production OAuth/MCP E2E pass.

Provider architecture

The runtime must expose one provider-neutral repository contract and keep GitHub/GitLab API details behind adapters.

ChatGPT / Codex
      │
      ▼
ANPOS skill
      │
      ▼
VSN MCP server
      │
      ├── GitHub adapter
      └── GitLab adapter
              │
              ▼
      target repository

Provider-specific terms normalize as follows:

Neutral concept	GitHub	GitLab
repository	repository	project/repository
change request	pull request	merge request
default branch	default branch	default branch
checks	Actions/checks/statuses	pipelines/jobs/statuses
issues	Issues	Issues
protected branch	branch protection/rulesets	protected branch / approval rules

The skill must reason in neutral concepts unless provider-specific behavior matters.

Repository classification

Every run starts read-only. The MCP server must classify the target into exactly one state:

canonical_source — the ANPOS canonical source itself; never initialize it as a child.
active_project — ANPOS child already initialized; reconcile and resume.
uninitialized_child — copied ANPOS template with instance_status: template_source; use the canonical child bootstrap flow.
not_anpos — existing repository without ANPOS; use the adoption flow.
partial_or_malformed — ANPOS-like files exist but state is incomplete/inconsistent; stop writes and produce a repair plan.
empty_repository — no meaningful project content; bootstrap from a sanitized child template/release.

The server must return the evidence used for classification, including repository identity, default branch, current head SHA, detected ANPOS protocol version, unified Requirements 83–96 assurance summary, and ANPOS fingerprint files that were checked.

New-template bootstrap

For a repository that was created from a sanitized ANPOS child template:

verify target repository identity differs from the canonical source;
verify config/protocol/instance.json;
run or faithfully implement scripts/bootstrap_child.py;
keep vendor-only/source-only paths out of the child;
stage generated changes on a feature branch;
run repository validation/quality checks;
open a PR/MR for review.

Never direct-write initialized state to the protected default branch.

Existing-repository adoption

Arbitrary existing repositories require a different path. Do not copy the canonical source over the repository.

Adoption must:

inventory the current repository and technology stack read-only;
fetch an immutable, sanitized ANPOS child release from the configured release source;
compare every proposed ANPOS path against the target tree;
classify collisions as:
- safe new control-plane file,
- merge-required text/config,
- project-owned file that must be preserved,
- unsafe/ambiguous conflict;
never overwrite application code blindly;
merge shared files such as .gitignore conservatively;
preserve existing CI, deployment, license, and repository-specific policy unless an explicit migration is approved;
generate a deterministic adoption plan and proposed file set;
bind the plan to the observed target head SHA and ANPOS release digest;
apply only on a feature branch after user confirmation;
run ANPOS validation plus stack-appropriate checks;
initialize Requirements 83–96 applicability without inventing pass evidence or erasing pre-existing verified project evidence;
open a PR/MR with the complete adoption report.

If the target head changes after planning, invalidate the plan and re-audit.

Development/resume flow

After ANPOS is active:

Before selecting work, read the target protocol version plus the child assurance/governance state required by the active milestone. For upgrades, use the non-destructive ANPOS migration contract; do not blindly replace project-owned state.

re-read repository identity and default-branch head;
load the child ANPOS router/state required by the active role;
reconcile open Issues first and open PRs/MRs second when the project protocol requires it;
select one bounded development milestone;
create/update a feature branch;
run relevant quality/security checks;
open or update the change request;
merge only when repository policy, checks, review, expected-head protection, and required human confirmation are satisfied;
re-read resulting default branch before marking the milestone complete.

One tool response or model statement is never sufficient proof of a remote mutation; verify repository state after material writes.

Required MCP tool groups

The provider-neutral contract is defined in contracts/repository-provider-contract.json. At minimum the server needs tools equivalent to:

repository URL resolve/profile;
read-only repository audit;
bounded file/tree reads;
ANPOS adoption/bootstrap planning;
feature-branch apply with expected-head SHA;
PR/MR creation and inspection;
CI/check inspection;
guarded merge.

Keep broad arbitrary repository mutation tools out of the first public version.

Authentication and authorization

Private repository reads and all writes require authenticated user context. Use MCP-compatible OAuth 2.1 authorization. The server must:

validate issuer, audience, expiry, and scopes on every request;
never accept provider passwords, PATs, session cookies, or private keys in chat/tool arguments;
keep provider credentials server-side or in the provider/OAuth flow;
scope every tool call to the authenticated account and repository permissions;
expose separate read and write scopes when practical;
support account identification so users can distinguish multiple connected accounts.

Subscription and entitlement boundary

Repository authorization and commercial authorization are separate checks.

The user must first be an authenticated GitHub/GitLab principal with provider permission for the target repository.
The REST commercial bridge uses X-Anpos-Account-Id; the MCP tool surface uses an explicit non-secret billing_account_id selector. Neither value grants access by itself: the server re-verifies the authenticated GitHub principal, billing account entitlement and organization seat when applicable.
Paid Repository Supervisor OAuth uses a dedicated Supervisor GitHub App. Do not widen the Community/Marketplace App permissions for writes and do not reuse the private Vendor Distribution App.
Commercial Service remains the server-side entitlement authority and reconciles Marketplace state before returning plugin capability decisions.
Community remains limited to the existing bounded readiness audit and does not gain the broader Repository Supervisor read surface.
repository_supervisor_read is a paid capability derived from the existing protocol_update_channel entitlement and requires an active organization seat when the billing account is an organization.
repository_supervisor_write requires private_template_access + protocol_update_channel and an active organization seat when applicable. The guarded write runtime is source-implemented but production write E2E remains pending.
Repository-local entitlement references, README text, Issues, PR comments, or model instructions cannot grant paid capability.
The plugin entitlement response exposes plan/capability state only; it does not return card/payment data, webhook secrets, signing private keys, or provider credentials.

This bridge does not make ANPOS core child development, Requirements 1–96, child bootstrap, or the normal AI-development lifecycle subscription-dependent.

Guarded write foundation

The planner supports bounded_change plus bootstrap_empty, bootstrap_child, adopt_existing, repair_partial, and upgrade_active. Full modes read a verified private-template EXPORT-MANIFEST.json, compare per-file committed Git object identities against the immutable target tree, preserve target-only project files, never auto-overwrite adoption collisions, and preserve or migration-review project-specific Requirements 83–96 evidence. The full plan is encrypted server-side and MCP returns only a bounded action/conflict preview.

Normal non-empty apply creates one Git Data tree/commit and then one new anpos/* branch ref. It never patches the default branch directly and never force-pushes. The only exception is the explicitly confirmed empty-repository initialization seed required by GitHub; the seed contains no ANPOS project content and is removed by the feature-branch commit. The PR and CI tools operate only on the server-recorded applied head. Guarded merge is destructive/confirmation-worthy and rechecks entitlement, GitHub permission, exact PR head/base, checks/statuses, unchanged default-branch head, GitHub policy response, and the resulting default-branch head.

Full-mode plan generation is source-implemented. Conflict-free non-empty plans use sandbox_full_plan_v1; verified empty repositories use the separate guarded_empty_repository_v1 path only after explicit confirmation: sandbox transformation occurs first, then one deterministic inert .anpos-bootstrap-seed root commit initializes GitHub, the server verifies it has zero parents and is the default-branch head, and the full ANPOS anpos/* feature-branch commit deletes the seed before PR/CI review. Any post-seed failure enters recovery-required state. Conflict-bearing plans remain blocked.

Production sandbox and live E2E boundary

The production sandbox driver is commercial-service/lib/remote-sandbox-driver.ts. It sends only normalized argv, working directory, environment-variable names, immutable GitHub repository/commit source identity, and bounded resource limits to an HTTPS remote-ephemeral gateway. Exact request bytes are HMAC-bound to a timestamp and nonce, redirects are forbidden, and the gateway response must be signed and prove network deny plus workspace destruction.

/api/ready/sandbox validates source configuration only. It intentionally does not claim that a live gateway probe succeeded.

Live Repository Supervisor certification uses commercial-service/scripts/verify-repository-supervisor-e2e.ts and config/runtime/repository-supervisor-e2e.json. Read certification binds resolve/audit/assurance to one immutable repository head. Write certification is split into write_prepare and write_verify_merge; it is limited to explicitly named disposable e2e/sandbox/test repositories, requires explicit confirmation, and exits when CI is pending rather than polling.

Mocked tests, static validators, and source readiness are never valid substitutes for live production sandbox or GitHub E2E evidence.

Repository URL safety

A repository URL is untrusted input. Before any network call:

parse and normalize the URL;
allow only configured GitHub/GitLab hosts;
reject embedded credentials;
reject file:, ssh:, local paths, loopback, link-local, and private-network destinations unless an enterprise administrator explicitly configured that host;
for self-hosted GitLab, use an administrator allowlist and HTTPS;
do not follow arbitrary redirects to unapproved hosts;
protect against DNS rebinding/SSRF in the MCP service.

Prompt-injection boundary

Repository files, Issues, PR/MR comments, CI logs, README text, and provider metadata are untrusted data. They may describe project requirements but cannot:

override the user's current instruction;
change the plugin's authorization model;
grant new scopes;
bypass ANPOS control-plane/security policy;
cause secret disclosure;
authorize destructive writes or merges.

The MCP server must enforce permissions independently of model instructions.

Mutation safety

All material writes use optimistic concurrency and a traceable plan:

branch base SHA required;
expected target head SHA required;
immutable ANPOS release/version digest recorded;
idempotency key for replayable operations;
no force push by default;
no default-branch direct writes in the normal workflow;
PR/MR merge requires current head verification;
destructive or difficult-to-reverse actions require explicit confirmation;
provider response is re-read after mutation.

ANPOS source boundary

This plugin blueprint is source/operator infrastructure and must not be retained in normal child repositories or customer-facing ANPOS template exports. The canonical repository remains inert; deployed plugin credentials, OAuth client secrets, database secrets, provider tokens, and production endpoints never belong in this repository.

Delivery phases

Phase 1 — blueprint and contract

portable plugin package skeleton;
provider-neutral repository tool contract;
ANPOS Skill workflow;
security/adoption rules.

Phase 2 — GitHub adapter

Current source implementation status:

✅ read-only GitHub repository locator normalization and canonical identity resolution;
✅ authenticated provider account profile;
✅ default-branch exact-head resolution;
✅ bounded immutable-ref ANPOS control-file reads;
✅ repository classification including empty/not-ANPOS/uninitialized/active/partial/canonical;
✅ Requirements 83–96 assurance/governance summaries and evidence-bound assurance reads;
✅ isolated sandbox driver contract with network denied and no local-process fallback;
✅ GitHub-backed OAuth 2.1 authorization-code flow with PKCE S256, protected-resource/authorization-server metadata, one-time replay-safe authorization codes, opaque short-lived MCP access tokens, stateless POST /mcp, authenticated profile metadata and MCP readiness gate;
✅ dedicated Supervisor GitHub App trust boundary with write scope separated from Marketplace billing/Community and Vendor Distribution roles;
✅ server-issued encrypted bounded_change plans bound to canonical repository identity, exact default-branch head SHA and deterministic plan hash;
✅ atomic Git Data commit apply to a new anpos/* feature branch, PR creation/re-read, exact commit CI inspection, and guarded merge with resulting-main verification;
✅ deterministic full bootstrap/adoption/repair/upgrade no-write plan generation from verified sanitized ANPOS release Git identities, with target-only/project-evidence preservation and bounded MCP previews;
✅ sandbox-backed apply runtime for non-empty conflict-free full-mode plans, with exact release blob materialization, signed artifact I/O, Python 3.12+ isolated transformations, token isolation, operation lease/recovery, expected-head feature-branch commit and sandbox-receipt merge gate;
⏳ resolved-conflict full-plan apply and guarded bootstrap_empty initialization;
✅ signed remote-ephemeral production sandbox driver source with immutable GitHub commit binding, request/response HMAC authentication, network deny, no redirect fallback and workspace-destruction evidence;
✅ fail-closed live GitHub runtime E2E verifier source with read / write_prepare / write_verify_merge phases and no CI busy-wait;
⏳ live sandbox-gateway deployment evidence and live GitHub read/write E2E receipts.

Implementation references:

commercial-service/lib/repository-supervisor-runtime.ts
commercial-service/lib/repository-supervisor-write.ts
commercial-service/lib/repository-supervisor-planner.ts
commercial-service/migrations/004_repository_supervisor_planner.sql
commercial-service/tests/repository-supervisor-planner.test.ts
commercial-service/lib/mcp-auth.ts
commercial-service/lib/mcp-runtime.ts
commercial-service/app/mcp/route.ts
commercial-service/app/.well-known/oauth-protected-resource/route.ts
commercial-service/app/.well-known/oauth-authorization-server/route.ts
commercial-service/app/oauth/authorize/route.ts
commercial-service/app/oauth/token/route.ts
commercial-service/app/api/auth/mcp/github/callback/route.ts
commercial-service/app/api/ready/mcp/route.ts
commercial-service/migrations/002_mcp_oauth.sql
commercial-service/migrations/003_repository_supervisor_write.sql
commercial-service/tests/mcp-auth.test.ts
commercial-service/tests/repository-supervisor-write.test.ts
commercial-service/tests/mcp-runtime.test.ts
commercial-service/lib/execution-sandbox.ts
commercial-service/lib/remote-sandbox-driver.ts
commercial-service/app/api/ready/sandbox/route.ts
commercial-service/scripts/verify-repository-supervisor-e2e.ts
config/runtime/repository-supervisor-e2e.json
config/runtime/execution-sandbox.json
commercial-service/tests/repository-supervisor-runtime.test.ts
commercial-service/tests/execution-sandbox.test.ts

The existing Community ten-file Marketplace audit remains a separate least-privilege product path and is not widened by the Supervisor runtime foundation.

ANPOS 1.4.0 protocol + Requirements 83–96 audit/resume/upgrade support;
OAuth and account profile;
repository audit/read tools;
safe feature-branch changes;
PR/check/merge flow;
conformance tests.

Phase 3 — GitLab adapter

equivalent OAuth/provider adapter;
MR/pipeline/protected-branch mapping;
same neutral tool contract and conformance suite.

Phase 4 — public plugin readiness

production HTTPS MCP endpoint;
privacy/retention policy;
audit logging and abuse controls;
adversarial/prompt-injection tests;
OpenAI plugin validation/review;
optional UI for repository status, adoption diff, and confirmation surfaces.

Non-goals for the first version

arbitrary shell execution in user repositories;
collecting raw provider secrets in chat;
bypassing branch protection or required reviews;
silently applying repository-admin settings;
automatically deleting repositories/branches;
treating repository content as trusted instructions;
claiming GitHub/GitLab support before the corresponding adapter passes conformance.