Agentic PR Control Plane v0: issue-scoped implementation, review gate, policy merge gate

[mdheller]

Intent

Define the v0 Agentic PR Control Plane for SocioProphet: a GitHub-native development operating system where issues become typed work orders, implementation agents produce bounded draft PRs, reviewer agents perform adversarial review, and policy gates own merge authority.

This is not a request to build a generic chat assistant. The target is the operating system around agentic development:

Issue -> Task Planner -> Repo Snapshot -> Sandbox Runner -> Patch Producer -> Diff Hygiene Gate -> CI Runner -> Review Agent -> PR Publisher -> Merge Gate -> Post-merge Ledger

Product lesson driving this issue

Recent Copilot-agent usage showed the correct split:

• A narrow issue produced useful, reviewable work when the scope was explicit.
• An overbroad or weakly gated task produced an unacceptable dependency/environment dump.

The v0 control plane must make the good path easy and the bad path structurally hard.

Scope

Create a repo-local specification and implementation plan for these control-plane services:

• taskd — turns GitHub issues into typed work orders.
• repod — snapshots repos, checks default branch freshness, computes branch divergence, and exposes safe file operations.
• sandboxd — runs implementation work in disposable environments with no persistent pollution.
• patchd — creates commits/draft PRs and refuses generated dependency trees unless policy explicitly allows them.
• reviewd — performs Codex-style adversarial review of changed files, tests, scope, claims, and hygiene.
• gated — enforces merge policy, expected head SHA, CI status, review status, and branch freshness.
• ledgerd — records actor, issue, branch, files changed, checks run, review result, and merge/block rationale.

Required design rule

No single agent may hold all three powers:

Implementation agent may propose.
Review agent may approve or request changes.
Policy gate may merge.

Expected deliverables

Keep this narrow. Expected changed files: 3 to 6, unless the PR justifies otherwise in the body.

Suggested deliverables:

1. A normative v0 spec under the existing docs/ surface.
2. A typed work-order schema or schema extension under the existing schemas/ surface, if that fits current repo conventions.
3. A minimal example work order or fixture showing issue intake -> draft PR -> review -> merge gate -> ledger record.
4. A short integration note mapping the v0 control plane to Policy Fabric / policy-fabric, prophet-platform, global-devsecops-intelligence, ontogenesis, and sociosphere.

Non-goals

• Do not implement a full production service in this issue.
• Do not add vendored dependencies, virtual environments, generated dependency trees, node_modules, build artifacts, binary blobs, or large generated output.
• Do not mutate unrelated product surfaces.
• Do not claim production readiness.
• Do not bypass Policy Fabric / policy-fabric ownership for merge and hygiene rules.

Acceptance criteria

• The spec states the agentic PR lifecycle and the service boundaries clearly.
• The spec distinguishes implementation, review, and merge authority.
• The work-order contract includes scope, expected files, non-goals, validation commands, review checklist, and allowed side effects.
• The draft PR output contract includes changed-file summary, validation evidence, known gaps, and self-critique.
• The design supports a pre-semantic diff hygiene gate before reviewer-agent time is consumed.
• The integration map names concrete owning repos and trust boundaries.
• The PR body includes validation commands run and current known gaps.
• The PR remains small and repo-local; any deviation from the expected file count is explicitly justified.

Validation expectations

Before opening the PR, run the repo's existing validation loop where available. At minimum:

git status --short
git diff --stat

If available in this repo, also run the standard AgentPlane checks such as:

scripts/doctor.sh

Reviewer checklist

• Scope matches this issue.
• No generated dependency tree or virtual environment is committed.
• No unrelated files are changed.
• The issue -> draft PR -> review -> gate -> ledger lifecycle is explicit.
• The policy-plane handoff is concrete enough to implement in Policy Fabric / policy-fabric.

Related work

Pair this with the Policy Fabric issue for Diff Hygiene Gate v0. That issue should own the enforceable pre-review checks for vendored environments, generated dependency trees, unrelated file mutations, stale branches, and overbroad PRs.

[mdheller]

Linked paired governance issue: SocioProphet/policy-fabric#44.

The Agentic PR Control Plane v0 should consume Diff Hygiene Gate v0 before semantic review and before merge-gate evaluation. AgentPlane owns issue-scoped task execution, draft PR production, evidence emission, and lifecycle shape; Policy Fabric owns enforceable pre-review hygiene rules and merge policy semantics.

[mdheller]

Triage — Agentic PR Control Plane v0: Design. Issue-scoped implementation → review gate → policy merge gate. Large scope; recommend scoping to a v0 stub.