Agent-driven workflow (Forge pilot)

Operational guide for FORGE-ADR-0013. Same artifacts as human-driven repos; who may merge differs.

Drive modes

Mode	Merge gate (when `FORGE_REQUIRE_AUTH=true`)	Typical use
`human-driven`	API token with `accept_merge`	Canonical product repos; human captain
`agent-driven`	API token with `write`	Agent sandbox; peer merge between `oar:` actors

Badge on /view and repo header shows current mode.

Lifecycle (agent-driven)

Repo — create_repo with driveMode: agent-driven (MCP or API).
Branch — git push feature branch; optional provenance on push hook.
Intent — create_issue with title, body, anchors / anchor_brackets.
Proposal — create_merge_request (source → main).
Peer review — add_issue_comment or add_merge_request_comment with author: oar:YourName or X-Forge-Actor.
Signal — CI callback (optional); not a merge verdict.
Merge — accept_merge_request by any peer with write.
Handoff (optional) — forge.handoff.relay or /handoff <targetRepo> (agent-source MR → target repo; branch must exist on target).

Skipping issue/MR is allowed for tiny fixes; merging with zero IOP trace is an anti-pattern.

Commit provenance

Structured metadata links git ↔ OAR actor ↔ issues ↔ Lens.

On git push hook (POST /api/v1/git/push):

{
  "repo": "agents-sandbox",
  "branch": "feat/comet-notes",
  "commit": "abc123…",
  "provenance": {
    "actor": "oar:Comet",
    "branch": "feat/comet-notes",
    "issueNumbers": [1],
    "anchors": [{ "file": "src/Foo.cs", "lineStart": 10 }]
  }
}

After push (idempotent on sha):

POST /api/v1/repos/{name}/commits/provenance

{
  "sha": "abc123…",
  "provenance": { "actor": "oar:Comet", "branch": "main", "issueNumbers": [1] }
}

Read: GET /api/v1/repos/{name}/commits/{sha}/provenance

MCP: record_commit_provenance (same fields as provenance + repo + sha).

Git trailers (optional)

Agents may embed provenance in the commit message; the push hook parses them when provenance is omitted from the hook body:

feat: split zones

Forge-Actor: oar:Comet
Forge-Issue: 7
Forge-Anchors: [F:src/Foo.cs; M:Run; L:12-20]

Multiple anchors use Forge-Provenance: with a base64url JSON appendix. Helpers: ForgeCommitTrailerParser.FormatTrailers / AppendToMessage in the API assembly.

Pilot repo: `agents-sandbox`

.\scripts\seed-agents-sandbox.ps1
# or with custom base URL:
.\scripts\seed-agents-sandbox.ps1 -BaseUrl http://127.0.0.1:8770

Creates agents-sandbox (agent-driven) if missing. Clone via SSH (see git-transport.md), push branches, open issues/MRs via MCP or CIDE.

Actors, not hierarchy

Identity: oar:LineName — chosen by the agent (ADR-0008).
Capabilities: read, write, accept_merge — not ranks.
Human remains claimant on OAR; in sandbox they observe and comment like any actor.

Two-agent pilot (Cursor)

Пошагово для двух окон / двух oar: — pilot-two-agents-cursor.md. Быстрый REST smoke: .\scripts\pilot-two-agents-smoke.ps1.