Software Delivery OS

Jentrix models the whole software-delivery pipeline — idea → spec → Work Order → branch → pull request → CI → review → merge → preview deploy → production deploy → monitor → incident/outcome — as a durable delivery graph over your real execution systems: GitHub + GitHub Actions + Vercel.

Jentrix observes and governs; it never builds, tests, or deploys. GitHub, Actions, Vercel, and external agent runners do the work. Jentrix ingests their signals as first-class records and evidence, gates the risky boundaries (push, merge, deploy, rollback, credential grants), and measures the outcome — records, not fires.

This guide is the map. The deep dives live in their own pages:

• GitHub sync — connecting the App, the PR/CI ingestion contract, loop prevention.
• Agent workflows — the delivery template family, merge/deploy gates, the reviewer-reacts-to-CI loop.
• Policy engine / Credential broker — how the gated boundaries are enforced and credentialed.

The delivery graph

A workspace-scoped graph hangs off the pull request (the unit of change) and resolves to a repo through the existing GitHubRepoLink (repo ↔ board, strictly 1:1). It reuses the loose-id convention of the rest of the platform — real relations only for workspace/task ownership.

Archiving a task or unlinking a PR never deletes the delivery audit trail.

Pull request + CI sync

Once a connected GitHub installation is upgraded to the delivery scopes, inbound pull_request, pull_request_review, check_run/check_suite, status, and workflow_run/workflow_job events project into the graph.

• PR → task matching is deterministic: a Jentrix task key (STK-123) in the head branch name, then the PR title, then the body — and the resolved task must belong to the PR's repo→board. A board-valid hit lands matched; anything else is kept as an orphan (never dropped) and can be adopted later from the delivery panel or via link_task_to_pr.
• Evidence is two-step. Webhooks only signal that a run finished; logs and test reports are fetched from the Actions API in a second step, run through redactSecrets, size-capped, and stored as artifacts on the PR/CiRun/task.
• Loop guards mirror Issue sync: source-tagging (source: "github" / "vercel" / "ci" never echoes out), content-hash equality (lastSyncedHash), delivery-id/event-id dedup, and last-writer-wins on updated_at. A Jentrix-authored PR update never re-triggers an inbound write.

Everything degrades gracefully: an un-upgraded install keeps syncing Issues with zero errors, and the whole layer is provider-optional (no GitHub/Vercel env ⇒ silent no-op).

Deployments + release-control mode

Vercel deployment webhooks route through a VercelProjectLink (Vercel team + project id ↔ repo/board + environment mapping + signing secret + owning workspace) into Deployment/Release records. Preview deploys are recorded as observability with no gate. A generic POST /api/ci/ingest (HMAC + its own signed timestamp) feeds the same models from non-GitHub/Vercel runners.

The production boundary is governed once, per the project environment's release-control mode:

• gate_before_merge (default) — the merge gate is the production boundary. Approving it merges the PR through a brokered repo:merge credential; the Vercel deploy that follows is observed and recorded (no deploy credential).
• gate_at_promotion — Vercel is configured not to auto-promote, and a separate deploy gate authorizes the Vercel promotion through a brokered deploy:production credential.

Rollback is gated and brokered in both modes, recorded as a Deployment that references the one it reverts.

Gated boundaries

Push, merge, deploy, and rollback are the highest-risk actions in the pipeline. Each goes through the Policy Engine → a human approval gate (for merge/deploy) → a WorkLease → a short-lived, scoped, single-use brokered credential. Agents never hold a standing raw repo or cloud token — the GitHub App's Contents:write is mediated by repo:push / repo:merge grants, never handed out raw, and the standing sync token is scoped to exclude contents-write.

The task delivery panel + Control Tower queues

The task detail panel shows a delivery section — linked PRs, their CI conclusion, deploy state, and evidence — with deep links out to GitHub and Vercel, updated live over the delivery.pr_linked / delivery.check_failed / delivery.ci_updated / delivery.deploy_updated board events. Cards show a CI/PR status pill.

Delivery exceptions surface in eight self-healing Control Tower queues, each with an explainable reason and deep links, resolving through the existing resolution + ledger path:

Failing checks · Stale PRs · Blocked merges · Missing evidence · Deploy failures · Release approvals · Rollback needed · Flaky tests.

The Rollback needed queue carries a governed rollback action that dispatches an admin-gated, release:rollback-brokered, leased rollbackDeployment.

Agent delivery workflows

Five delivery templates (feature, bugfix, ci_failure_triage, release_candidate, hotfix) drive the pipeline on the existing plan → review → execute → review Agent Job loop. The executor opens a real branch/PR through the governed write path; the reviewer turn reacts to real CI evidence; the loop pauses at the merge gate (and, under gate_at_promotion, a deploy gate). Start one with request_delivery_workflow; a failing check can auto-launch a ci_failure_triage loop via the check.failed automation trigger. See Agent workflows for the full state machine and turn discipline.

Delivery outcomes (DORA + agent-native)

The daily outcomes cron rolls up two buckets per workspace over a trailing 90-day window, surfaced on the workspace Delivery dashboard (/<workspace>/dashboards/delivery) and the project Metrics tab:

• DORA — lead time for change, deployment frequency, change-failure rate, MTTR.
• Agent-native — PR-review turnaround, CI-fix loop count, human-edit rate on agent PRs, and delivery-approval burden.

The rollup is pure aggregation over the delivery graph (unit-tested against seed-shaped fixtures) and is idempotent for a given window.

Releases + incidents

/<workspace>/releases manages lightweight Release records — notes, a rollback plan, included PRs (resolved to their GitHub links), and a DRAFT → READY → DEPLOYED status, emitting release.ready / release.deployed. A failed production deploy (error state) auto-opens an M6 Incident linked to the offending deployment (idempotent — one incident per failed deploy); a regression can also open an incident from a release manually.

The auto-escalation opens an incident and corrective work, always. Before opening, it resolves the lifecycle identifiers from the delivery graph — the Work Item (the deploy's task, or its PR's task, or the task the correlated execution is anchored on), the execution (the harness run owning the PR's head branch, else the run anchored on the Work Item), and the affected EXECUTOR run — and then:

• opens the incident linked to the deployment (the idempotency key), with the Work Item on its blast radius and every identifier on the opening timeline entry. Incident.runId binds the newest EXECUTOR AgentRun of the correlated execution where one resolves; where none does, a typed reason (no_correlated_execution / no_executor_run) is recorded instead. A run is never fabricated and no other role is substituted — a validator run is read-only by definition and is excluded by name;
• opens a REQUIRED corrective Work Item and attaches it as the incident's follow-up. This is unconditional: board resolution walks a total chain (deployment board → Work Item's board → Vercel project link → GitHub repo link → the software-company BUGS binding → a find-or-create "Delivery Incidents" BUGS board), so a deployment with no board and no task — a shape the model permits — still gets corrective work. The follow-up claim is written inside the task's own create transaction and fenced by a partial unique index, so a replayed webhook or a concurrent escalation produces neither a duplicate nor an orphan task;
• refuses an escalation that can name no correlation at all. A standalone, uncorrelated incident is an abandoned path, so it is declined and logged rather than written; the refusal is re-checked in the ops core (openDeliveryIncident) so it holds for any caller on this path.

If the process dies between the two commits, the cron sweep re-derives the postcondition from durable state: any unresolved auto delivery incident carrying no required corrective follow-up has one created on the next pass (deliveryIncidentsRepaired in the sweep summary). Convergence, not best-effort.

Until that corrective work carries a disposition, the correlated execution cannot reach a clean acceptance verdict — see completion coupling.

Playbook mining

Once delivery loops start completing, the daily outcomes cron also mines playbook drafts from them. It clusters the AgentJobs that reached DONE over the trailing 90 days by template + board kind, and for each recurring pattern (at least two successful runs) upserts a playbook draft pre-filled with:

• the tool surface the template drives (the M7 loop tools plus the delivery tools the template implies),
• proposed eval cases derived from the template (PR opened, CI green, loop converged), and
• the supporting AgentRun ids as evidence.

Drafts are deduped by (workspace, template + board kind), so re-mining refreshes evidence without resetting a reviewer's verdict, and a pattern a reviewer already rejected or promoted is never re-surfaced. Nothing is enabled automatically: a draft must be reviewed and then promoted by an admin behind the policy + eval coverage gate before it becomes a usable playbook.

The same daily cron mines completed harness runs through the same machinery (clustered by branch strategy + board kind) — see Harness playbook mining.

MCP surface

Delivery reads (read scope): list_delivery_items, get_pull_request, list_ci_runs, get_ci_run. Delivery writes: link_task_to_pr (adopt an orphan PR onto a task) and request_delivery_workflow (start a delivery loop bound to a repo/PR). Merge and deploy approvals stay UI-first (Control Tower / job page) — there is deliberately no MCP path for an agent to approve its own merge or deploy.

Security recap

• Inbound webhooks: HMAC verify + provider-native replay/dedup (GitHub X-GitHub-Delivery, Vercel/generic event-id; generic ingest carries its own signed timestamp) + payload size limits + a provider/source allowlist + redactSecrets over every stored log/artifact.
• Push/merge/deploy/rollback are policy-gated, leased, and brokered — never a standing raw token; credentials are short-lived, scoped, and single-use.
• Every delivery mutation follows the existing authorization and activity attribution; agent actions carry their source badge.