Planning material — fictional examples, no production behavior
AI Consulting Planning Showcase

Governed AI Sprint Delivery Orchestrator Implementation Plan

Status

Approved implementation direction — execute incrementally with reviewed infrastructure and repository changes.

M2 runtime and operator control checkpoint — 2026-08-17

Milestone 2’s durable infrastructure, operator control, and protected deployment safeguards are complete. Orchestrator Epic E1 #46 is closed after all durable-infrastructure child issues merged to main:

  1. Aurora PostgreSQL and migrations (#60): Private Aurora PostgreSQL Serverless v2 writer in isolated subnets with backups, parameterized deletion protection, migration execution task definitions, and cold-resume handling.
  2. SQS and DynamoDB runtime coordination (#61): Encrypted SQS FIFO command/callback queues with dead-letter queue redrive, and a DynamoDB runtime coordination table for delivery deduplication, worker wake generations, and status projections.
  3. Scale-to-zero ECS Fargate workers (#62): Inert worker service with 0–2 capacity, immutable commit-SHA image pinning, least-privilege execution/task roles, durable leases, and graceful drain.

Operator control (Epic E2 #47) and safe operations (Epic E3 #48) children are also complete:

Live deployment validation proved the complete lifecycle in AWS:

The next ordered work is now M3 — Live Planning and Execution, beginning with live model and GitHub provider integration (Epic E1 #49), LangGraph workflow runtime (Epic E2 #50), and usage/diagnostics (Epic E3 #51).

M1 completion checkpoint — 2026-08-10

Milestone 1’s authority and repository safeguards are complete. Orchestrator Epic E3 #45 is closed after both separated-identity children merged with human review. PR #90 defined strict automation-identities/v1 contracts, exact role permission and operation ceilings, fail-closed authorization/protection preflight, and three role-specific empty secret containers. Protected Terraform run 31351272293 applied the non-destructive secret/IAM changes.

PR #91 pinned the reviewer and merger App/installation IDs, portal-only audience, permission snapshots, distinct secret ARNs, trusted diagnostic, and sanitized provisioning evidence. A disposable client-portal PR #133 proved one exact-head COMMENTED review by the reviewer bot and was closed without merging. The merger proof minted a portal-constrained token but invoked no merge endpoint. Independent rotation drills proved both replacement keys, revoked both old keys, observed HTTP 401 for both revoked credentials, and removed obsolete AWS staging labels without exposing values.

This checkpoint does not enable a reviewer/merger runtime consumer, automated review, automatic merge, release, or deployment. GitHub permissions remain platform ceilings beneath application policy, and later execution slices still require their own approved plans and human review.

The next ordered work is now M2 — AWS Runtime and Operator Control, beginning with Epic E1 #46 and its durable-infrastructure children. M3-M5 remain gated by the milestone sequence; completing M1 does not authorize infrastructure apply or deployment for M2.

Delivery progress checkpoint — 2026-08-09

Milestone 1 Epic E1, the autonomous-run contract and governance slice, is implemented and merged. Orchestrator PR #88 added immutable, fingerprinted automatic-run authorization, fail-closed drift evaluation, authorization-bound merge states, and durable PostgreSQL persistence. PR #89 added the autonomous-delivery threat model, separated authority matrix, and containment/recovery policy. Both required CI and human review before merge.

Client-portal Epic E2 #111 is also complete. PR #130 published the passing history-aware publication audit, and PR #131 added the proprietary notice and private vulnerability-reporting policy. The repository is now public with private vulnerability reporting, squash-only merging, one independent approval, stale-review dismissal, resolved conversations, administrator enforcement, strict GitHub Actions CI Gate, and force-push/deletion prevention. A disposable-branch exercise verified the break-glass disable-and-restore procedure without weakening main.

The next ordered work remains M1, not M2: orchestrator Epic E3 #45 must define and provision the separated builder, reviewer, and merger identities. M2 remains blocked on completion of all M1 safeguards.

MVP definition and backlog checkpoint — 2026-08-07

The minimum viable product is now a complete, AWS-hosted autonomous delivery run through one frozen and human-authorized manifest of the client portal’s open Phase 1 issues. The operator first resolves every material decision, approves every final marked plan, and authorizes the exact issue identities, plan fingerprints, default-branch SHA, policy version, and automatic merge mode. After that checkpoint, the orchestrator may plan execution order, dispatch builds, review exact pull-request revisions, request at most two repairs, independently approve passing revisions, and enable squash auto-merge without a per-pull-request human gate.

Automatic merge is enabled only after the client portal becomes public and protected main enforces pull requests, one independent approval, stale-review dismissal, resolved conversations, and the strict CI Gate. Build publishing, review approval, and merge enablement use three distinct least-privilege identities. Any plan, head, base, check, review, identity, policy, protection, or authorization drift fails closed. Independent work may continue after one branch blocks, but the MVP succeeds only when every manifest issue is merged and closed.

The candidate manifest is portal issues #74-#80, #82-#83, and #105-#110. Closed split parents #81 and #84 are excluded. The actual manifest is frozen only after decisions on #76, #78, and #79 are resolved, the six split children have approved plans, and stale dependency references are normalized.

The implementation sequence is maintained as matching GitHub milestones and epic/child issue hierarchies:

  1. M1 — Authority and Repository Safeguards (contract epic #44, identity epic #45, and portal-publication epic #111).
  2. M2 — AWS Runtime and Operator Control (infrastructure #46, operator control #47, and safe operations #48).
  3. M3 — Live Planning and Execution (providers #49, orchestration #50, and usage/diagnostics #51).
  4. M4 — Review, Repair, and Automatic Merge (portal adapter #112, review/repair #52, and automatic merge #53).
  5. M5 — Portal Backlog Completion (readiness #54 and backlog run #55).

Each epic is a non-authorizing tracker. Its child issues are the smallest planned implementation or explicitly human-operated units and retain the repository’s normal marked-plan, non-default-branch, pull-request, validation, and review requirements. This checkpoint supersedes the earlier sequence’s human-merge MVP boundary and two-target pilot requirement. Consulting-site rollout, client distribution, goal decomposition, dynamic backlog discovery, and unattended production deployment remain post-MVP.

Implementation checkpoint — 2026-08-01

Implementation is active in the private todd-brunia/ai-delivery-orchestrator repository. The repository foundation and the following reviewed slices have merged to main:

The current validation baseline is 42 unit/static-policy tests and 15 real-PostgreSQL integration tests, plus lint, type checking, production build, Docker build and runtime smoke test, dependency audit, secret scan, Compose validation, and credential-free Terraform formatting and validation in CI. The local PostgreSQL service can be stopped without deleting its named volume.

This checkpoint does not mean Phase 1 or Phase 2 is complete. The current code has no public HTTP/Lambda endpoint, GitHub App credentials or API calls, real model integration, LangGraph runtime or checkpoints, reconciliation loop, operator API, applied AWS resources, or target-repository installation. The provider composition rejects real-provider mode and cannot mutate another repository. The Terraform foundation is configuration only: no AWS plan or apply has run, no AWS variables are configured, and no cloud cost was created.

This is the current pause point. When implementation resumes, first decide whether to execute the separately authorized human bootstrap operation or continue defining unapplied Phase 1 infrastructure. Secrets contracts, observability, budgets, the Bruno smoke-test foundation, and application control-plane resources remain pending. HTTP/Lambda ingress, LangGraph workflow execution, and canonical GitHub refetch remain separate later slices.

This plan defines the first implementation slice of the broader autonomous goal-to-deployment delivery pipeline. It creates a reusable AWS-hosted orchestrator that coordinates an explicit list of GitHub issues. It does not yet generate epics from a business goal or select issues from filter criteria.

The first installation is ai-consulting-client-portal, which will become public only after the separately reviewed publication audit and proprietary notice changes. ai-consulting-site is a post-MVP second target.

After the internal pilot proves the operating model, the implementation must also support a client-owned deployment path. A client should be able to fork a client-distributable release of ai-delivery-orchestrator into its own GitHub organization and use the fork’s Terraform and documented workflows to provision an isolated deployment in an AWS account it controls. This is a portability and productization requirement, not authorization to publish the current private/proprietary repository or provision client infrastructure.

Initial outcome

Create a private implementation repository named ai-delivery-orchestrator containing:

The first workflow, sprint-delivery/v1, accepts one repository plus an explicit list of issue numbers. It determines dependencies and conflict risk, authorizes eligible plans, schedules safe work, reviews pull requests, attempts bounded repairs, and either waits for human merge or, for a separately authorized immutable run, enables guarded squash auto-merge.

Architecture

GitHub App webhooks             Bruno with AWS SigV4
          |                              |
          +---------- API Gateway -------+
                            |
                     Ingress/API Lambda
                       |           |
                 SQS FIFO      DynamoDB
                       |       status projection
                       v
              ECS Fargate worker service
                 desired count 0-2
                       |
                    LangGraph
                   /         \
          GitHub/OpenAI    Aurora PostgreSQL
                            checkpoints + audit

Runtime responsibilities

Use open-source LangGraph.js directly with @langchain/langgraph-checkpoint-postgres; do not adopt the licensed LangGraph Agent Server. Keep the domain state machine independent of LangGraph checkpoint formats so another runtime can replace LangGraph later.

AWS infrastructure

Deploy the pilot in us-east-1 with Terraform.

Always-available control plane

Scale-to-zero compute

PostgreSQL

Aurora is authoritative. DynamoDB is only the durable inbox, deduplication store, wake coordinator, and read projection.

Credentials and deployment

Store the GitHub App private key, GitHub webhook secret, and OpenAI API key in Secrets Manager. Use short-lived GitHub App installation tokens for GitHub calls. Do not expose GitHub publishing credentials to model execution.

Use versioned S3 Terraform state with native locking. GitHub Actions assumes AWS roles through OIDC; do not create long-lived AWS deployment keys.

CI/CD behavior:

Client-owned fork and provisioning

The post-pilot distribution model is one fork per client organization and one or more client-owned AWS environments. The supported path must not depend on consultancy-owned AWS accounts, Terraform state, GitHub Apps, deployment roles, secrets, or a centrally operated control plane.

Before describing the repository as client-self-provisionable:

Client forks may carry local policy and target-repository configuration, but clients should receive upstream security and compatibility updates as reviewable pull requests pinned to immutable releases. A future managed multi-client service remains a separate product requiring its own tenant, privacy, threat, support, and incident-response design.

Implementation repository design

Use Node.js 22, TypeScript, npm workspaces, LangGraph.js, the official OpenAI JavaScript SDK and Responses API, AWS SDK v3, Octokit, PostgreSQL, and Zod.

Organize the code around:

Persist workflow definition/version, sprint run, work item, dependency edge, conflict domain, plan fingerprint, feasibility decision, attempt, GitHub artifact, review, transition, lease, retry, cost, and provenance records. Every external mutation uses a transactional outbox and idempotency key.

OpenAI credential routing, request correlation, and cost ownership follow the OpenAI usage attribution and project strategy: target-application model work is charged to that target’s OpenAI project, independent execution stages use separate project-scoped credentials, and the orchestrator project is not a default bucket for work it merely coordinates.

Do not retain raw model reasoning. Retain the structured decision, evidence references, model and policy versions, usage, and hashes of reviewed artifacts.

Public interfaces

Operator API

All /v1/* routes require API Gateway AWS IAM authorization. Bruno signs requests with temporary AWS credentials using SigV4.

Provide:

Run creation requires an Idempotency-Key header and this v1 body:

{
  "repository": "todd-brunia/ai-consulting-client-portal",
  "issueNumbers": [81, 82, 83],
  "mergePolicy": "human"
}

Reject duplicates, closed issues, pull request numbers, inaccessible issues, and cross-repository lists. The issue list is immutable after acceptance. mergePolicy: "automatic" is represented in the versioned contract but must be rejected until the automated-merge phase is enabled.

Queued commands return 202 Accepted. Reads include projectionAsOf so Bruno users can identify stale projections. Cancellation prevents future automation but does not close issues, abandon pull requests, or reverse completed merges.

Repository adapter

Add .github/ai-delivery-orchestrator.yml to each target. Version 1 declares:

Reject unknown fields, unsupported versions, missing labels, and configurations that weaken mandatory controls.

GitHub App

Create a new orchestrator GitHub App, separate from both repositories’ current build-publisher Apps, and install it only on the portal and site repositories.

Initial repository permissions are:

Subscribe to issue, pull request, pull request review, check run/suite, workflow run, installation, and repository-selection events. Do not grant source-write or merge permission in v1.

Webhook processing must validate the exact raw request body against X-Hub-Signature-256, deduplicate X-GitHub-Delivery, respond promptly, enqueue a normalized event, and refetch canonical GitHub state before acting. A scheduled reconciliation loop repairs missed or delayed events.

Sprint workflow

States

Run states:

accepted -> collecting_plans -> analyzing -> active
         -> waiting_for_human -> paused -> completed

Recovery outcomes are blocked, failed, cancelled, and superseded.

Work-item states:

discovered
  -> awaiting_plan
  -> feasibility_review
  -> human_plan_approval_required | ready_to_build
  -> build_dispatched
  -> building
  -> pr_open
  -> checks_pending
  -> reviewing
  -> fixing
  -> ready_for_human_review
  -> merged

Every transition records actor, policy version, evidence, idempotency key, and time, and uses optimistic concurrency plus a durable lease.

Plan collection and authorization

  1. Validate and record every issue’s immutable GitHub identity.
  2. Apply needs-planning when an issue has no marked plan and no conflicting state, allowing the existing repository workflow to plan it.
  3. On plan-ready, fingerprint the issue, marked plan, trusted amendments, adapter configuration, and default-branch SHA.
  4. Use GPT-5.6 Terra at medium reasoning effort to return a schema-validated dependency graph, conflict domains, likely paths, feasibility result, risk classification, required evidence, and unresolved decisions.
  5. Detect cycles, open external dependencies, conflicting paths, and invalid or low-confidence output deterministically. Uncertainty forces serialization or human review rather than optimistic parallelism.
  6. Store feasibility findings privately; do not post them as issue comments.
  7. For ordinary feasible work, apply approved-for-build, refetch and verify the plan fingerprint, then apply approved-for-ai-build.
  8. Require human approved-for-build for security, authentication, secrets, infrastructure, destructive data, billing, workflow-policy, and external communication changes. After human approval, the orchestrator applies only approved-for-ai-build.
  9. For infeasible or ambiguous plans, remove plan-ready, apply needs-decision, expose the reason through the operator API, and stop that dependency branch.

The deterministic policy may make a work item more restrictive than the model suggests; model output may never weaken repository risk policy.

Scheduling and builds

Add narrowly scoped repair and sync dispatch stages to both repositories:

Pull request review and completion

  1. Correlate the draft pull request to its issue, plan fingerprint, automation marker, branch, base SHA, and head SHA.
  2. Wait for the repository-configured required checks.
  3. Review the exact diff with GPT-5.6 Sol at high reasoning effort and validate findings against a strict path, line, severity, evidence, and recommendation schema.
  4. If actionable findings exist, submit a GitHub REQUEST_CHANGES review and dispatch repair.
  5. Permit at most two review/fix cycles for a head lineage. After two failed cycles, apply blocked and require human attention.
  6. When the review passes, submit a non-approving automated review summary, convert the draft to ready for review and apply preview-ready to the issue. Human-mode runs wait for review and merge; automatic-mode runs require an independent current approval and every exact-head merge-policy check before the separate merger identity may enable squash auto-merge.
  7. On merge, verify the merged SHA, mark the item merged, synchronize stale parallel branches, and release newly unblocked work.
  8. On close without merge, force-push, plan mutation, check regression, or branch mismatch, stop and reconcile rather than continuing silently.

Delivery sequence

Phase 1 — Repository and platform foundation

Phase 2 — Dry-run orchestration

Phase 3 — Client portal pilot

Phase 4 — Consulting site rollout

Phase 5 — Client-owned deployment portability

Phase 6 — Post-MVP expansion

After the frozen portal backlog completes, evaluate consulting-site rollout, additional repositories, client-owned distribution, goal decomposition, and whether evidence supports any broader plan-approval policy. Automatic merge does not imply automatic release or deployment, and it remains bound to exact human-approved plans, protected repositories, separated identities, current checks and reviews, and emergency disablement.

Test and acceptance plan

Pilot acceptance requires:

Assumptions and explicit boundaries