SDLC Playbook: The Agentic Shape Up

§ 1.Core Philosophy #

This framework sets our standard for high-velocity R&D through intent-based governance. We use Trunk-Based Development on main to keep integration and learning continuous. Delivery follows the Basecamp Shape Up cadence: 6-week work cycles followed by 2-week cool-downs. Governance is anchored by Signed Tags — the primary, immutable evidence of both technical peer review and functional validation.

Build Cycle 6 weeks · fixed appetite

Cool-down 2 weeks

W1W2W3W4W5W6W7W8

§ 2.The Artifact Library #Evidence as Code

The audit trail lives in the repository and in automated pipeline logs, so every release is cryptographically linked to its authorization.

§ 2.1Traceability Contract #

Every production release must satisfy a deterministic evidence chain.

Traditional workflow (new code deployment):

Snapshot workflow (promoting deployed state):

See Appendix A for snapshot-based releases.

Linkage rules

• Every commit message must reference a Bet Record ID (bet:<slug>).
• An rc- tag points to exactly one commit on main, but a Bet Record may produce many rc- tags before one is signed.
• Every signed- tag must reference: the rc- tag it promotes (if applicable), the Bet Record ID, and the pipeline run ID.
• Every Ledger entry must include: commit hash, signed- tag, Approver identity, and links to the pipeline log and Bet Record.

Enforcement. CI rejects rc- tags whose commit lacks a Bet Record ID, and signed- tags missing any required reference. Broken chains never reach production — they fail at the gate, not in review.

§ 2.2Revocation #

A signed- tag is immutable, but its trust is not. If post-release analysis invalidates an authorization, the Approver appends a Revocation Entry to the Release Ledger citing the original tag, the reason, and the remediating signed- tag (if any). The original tag remains in history as evidence of what was authorized; the Ledger is the source of truth for what is currently trusted.

---

§ 3.The Triple-Guardrail Controls #

C1Independent Verification #

Mend.io runs in block mode within the pipeline for every rc- tag. This gate stops vulnerable code from progressing to sign-off.

C2Agent Config Shield #

The .agent-config.json file (which defines model versions and system prompts) is protected by CODEOWNERS and branch protection. Any change requires a review signature from an identity outside the developer group.

C3The Signed Handshake #Four-Eyes Principle

Production promotion requires a signed- tag from an identity other than the requester.

§ 3.1Control Responsibility Matrix #

Principle. Machines validate consistency and policy. Humans validate intent and correctness. The Agent never signs.

---

§ 4.The "Professional Handshake" SOP #Formally: Release Authorization Protocol

A three-step procedure that converts a commit on main into a release-grade, signed artifact.

§ 4.1Cool-down Protocol #Hotfix Path

Urgent patches bypass the 6-week rhythm but retain the same controls:

1. Branch from main, tag rc-hotfix-v* — triggers C1 (Mend.io scan).
2. Apply the C3 Signed Handshake — the Approver signs signed-hotfix-v*.
3. Record in the Release Ledger with a "Hotfix" justification and a link to the incident or vulnerability that motivated it.

The Appetite is not extended. Hotfix work consumes cool-down capacity.

---

§ 5.FAQ: Governance & Methodology #

---

§ 6.Glossary #

---

APPENDIX Snapshot-Based Release Workflow #

A.1Understanding the Monorepo Release Model #

In our monorepo setup:

• Multiple apps (app1, app2, app3) are built from commits on the main branch
• Each commit triggers CI pipeline runs that produce Docker images with sequential tags (build numbers: 22, 33, 44, etc.)
• Not every app rebuilds on every commit — only apps with changed code get new images
• The highest Docker tag across all deployed apps indicates the latest commit in the deployment

Key principle: Because this is a monorepo, all apps deployed at or before commit X will have Docker tags ≤ the tag of the app built from commit X.

A.2Discovery Phase: Finding What's Deployed #

Before creating a release, you must discover the current deployment state.

For Product Managers (Non-Technical)

Check the UI footer on each app, or use the discovery script:

node scripts/release-tagger.js --discover

For Developers

Option 1: Query health endpoints (if implemented):

curl https://app1.yourcompany.com/health
curl https://app2.yourcompany.com/health
curl https://app3.yourcompany.com/health

Option 2: Check environment variables on the host

Option 3: Use automated discovery script

Example Discovery Output

Querying apps...
✓ app1: commit 43jdfd342, docker tag 33
✓ app2: commit 3289h3292, docker tag 44  ← HIGHEST
✓ app3: commit v04343432, docker tag 22

Latest commit identified: 3289h3292 (docker tag 44)

The commit with the highest Docker tag is your release candidate.

A.3Creating a Signed Release #

Once you've identified the latest commit, follow these steps:

Step 1: Verify the Commit in Git

# Ensure the commit exists on main branch
git log --oneline | grep 3289h3292

# Verify it's on main
git branch --contains 3289h3292

Step 2: Choose Your Tag Format

The signed-* prefix is required. Choose a suffix based on your release cadence:

Naming rules:

• Prefix must be signed- (pipeline trigger contract)
• Use hyphens, not underscores: signed-2025-q1 ✅, signed_2025_q1 ❌
• Lowercase only: signed-v1.4.0 ✅, SIGNED-V1.4.0 ❌

Step 3: Tag Git Repository

# Example: Quarterly release
git tag -a signed-2025-q1 3289h3292 -m "Q1 2025 Release | Apps: 22,33,44"
git push origin signed-2025-q1

# Example: Semantic version
git tag -a signed-v1.4.0 3289h3292 -m "Release v1.4.0 | All apps snapshot"
git push origin signed-v1.4.0

Step 4: Tag Docker Images (Dual Tagging)

You must tag all deployed Docker images with the same signed-* tag.

Automated approach (recommended):

# Use the release tagger script
node scripts/release-tagger.js --tag signed-2025-q1 --docker-tags 22,33,44

# Or auto-discover and tag
node scripts/release-tagger.js --tag signed-2025-q1 --auto

The script will:

• Tag all specified Docker images in the container registry
• Create a release manifest JSON in /releases/signed-2025-q1.json
• Update the Release Ledger in /governance/ledger.md

Step 5: Trigger Release Pipeline

The Azure Release Pipeline should be configured to trigger on signed-* tags. This pipeline includes a manual approval gate (C3 control).

Logical flow:

1. Pipeline detects new signed-* tag in Git
2. Pipeline reads the tag to identify which Docker images to pull (from registry)
3. Manual Approval Gate — Approver reviews release manifest, ledger entry, and changes
4. After approval, pipeline pulls Docker images by signed-* tag
5. Pipeline deploys to beta or production environment

A.4Visual Workflow Diagram #

┌──────────────────────────────────────────────────────────────────┐
│  SNAPSHOT-BASED RELEASE: From Deployment to Production           │
└──────────────────────────────────────────────────────────────────┘

[Apps Running in Alpha Environment]
┌──────────────────────────────────────────────────┐
│ app1: /health → { commit: "43jdfd342", tag: 33 } │
│ app2: /health → { commit: "3289h3292", tag: 44 } │ ← HIGHEST TAG
│ app3: /health → { commit: "v04343432", tag: 22 } │
└──────────────────────────────────────────────────┘
                     ↓
         [Discovery: Query Apps]
         node scripts/release-tagger.js --discover
                     ↓
         Latest commit: 3289h3292 (docker tag 44)
                     ↓
         ┌─────────────────────────────────┐
         │  Dual Tagging Process           │
         └─────────────────────────────────┘
                     ↓
         ┌─────────────────────────────────┐
         │  Git: Tag Commit                │
         │  git tag signed-2025-q1         │
         │  → commit 3289h3292              │
         └─────────────────────────────────┘
                     ↓
         ┌─────────────────────────────────┐
         │  Docker: Tag Images             │
         │  duckbook.azurecr.io            │
         │  Tag 22,33,44 → signed-2025-q1  │
         └─────────────────────────────────┘
                     ↓
         ┌─────────────────────────────────┐
         │  Release Manifest Created       │
         │  /releases/signed-2025-q1.json  │
         └─────────────────────────────────┘
                     ↓
         ┌─────────────────────────────────┐
         │  Ledger Entry Added             │
         │  /governance/ledger.md          │
         └─────────────────────────────────┘
                     ↓
         ┌─────────────────────────────────┐
         │  Azure Release Pipeline         │
         │  Triggered by: signed-2025-q1   │
         └─────────────────────────────────┘
                     ↓
         ┌─────────────────────────────────┐
         │  Manual Approval Gate (C3)      │
         │  Approver: PM or CIO            │
         │  Reviews manifest & changes     │
         └─────────────────────────────────┘
                     ↓
         ┌─────────────────────────────────┐
         │  Deploy to Beta/Production      │
         │  Pull images: signed-2025-q1    │
         └─────────────────────────────────┘

Evidence Chain: 
Deployment State → Discovery → Git Tag → Docker Tags 
→ Manifest → Ledger → Pipeline → Approval → Production

A.5Integration with Existing Controls #

Snapshot releases comply with the Triple-Guardrail controls:

A.6Troubleshooting Common Issues #

A.7Example: Complete Release Flow #

Here's a complete example of creating a quarterly release:

# ────────────────────────────────────────────────────
# STEP 1: Discover current deployment
# ────────────────────────────────────────────────────
$ node scripts/release-tagger.js --discover

Querying apps...
✓ app1: commit 43jdfd342, docker tag 33
✓ app2: commit 3289h3292, docker tag 44  ← HIGHEST
✓ app3: commit v04343432, docker tag 22

Latest commit identified: 3289h3292 (docker tag 44)

# ────────────────────────────────────────────────────
# STEP 2: Verify commit in git
# ────────────────────────────────────────────────────
$ git log --oneline | grep 3289h3292
3289h3292 feat: add streaming data feed bet:market-data

$ git branch --contains 3289h3292
* main

# ────────────────────────────────────────────────────
# STEP 3: Create Git tag
# ────────────────────────────────────────────────────
$ git tag -a signed-2025-q1 3289h3292 -m "Q1 2025 Release | Apps: 22,33,44"
$ git push origin signed-2025-q1

# ────────────────────────────────────────────────────
# STEP 4: Tag Docker images (automated)
# ────────────────────────────────────────────────────
$ node scripts/release-tagger.js --tag signed-2025-q1 --auto

Connecting to duckbook.azurecr.io...
✓ Tagged duckbook.azurecr.io/app1:33 → signed-2025-q1
✓ Tagged duckbook.azurecr.io/app2:44 → signed-2025-q1
✓ Tagged duckbook.azurecr.io/app3:22 → signed-2025-q1

Release manifest saved to: /releases/signed-2025-q1.json
✓ Appended entry to /governance/ledger.md

# ────────────────────────────────────────────────────
# STEP 5: Trigger Release Pipeline & Verify
# ────────────────────────────────────────────────────
# Navigate to Azure DevOps → Pipelines → "Release Pipeline"
# [Manual Approval Gate] → Approver reviews and approves
# After approval → Deploy to Beta/Production

A.8Quick Reference Card #

# ═══════════════════════════════════════════════════
# DISCOVERY
# ═══════════════════════════════════════════════════

# Find what's deployed
node scripts/release-tagger.js --discover

# Check health endpoint (if implemented)
curl https://app1.company.com/health

# ═══════════════════════════════════════════════════
# GIT TAGGING
# ═══════════════════════════════════════════════════

# Tag the commit with highest Docker tag
git tag -a signed-<NAME> <COMMIT_HASH> -m "<DESCRIPTION>"
git push origin signed-<NAME>

# Examples:
git tag -a signed-v1.4.0 abc123 -m "Release v1.4.0"
git tag -a signed-2025-q1 abc123 -m "Q1 2025 Release"

# ═══════════════════════════════════════════════════
# DOCKER TAGGING
# ═══════════════════════════════════════════════════

# Automated (recommended)
node scripts/release-tagger.js --tag signed-<NAME> --auto

# Manual
az acr login --name duckbook
docker tag duckbook.azurecr.io/<app>:<BUILD> duckbook.azurecr.io/<app>:signed-<NAME>
docker push duckbook.azurecr.io/<app>:signed-<NAME>

# ═══════════════════════════════════════════════════
# VERIFICATION
# ═══════════════════════════════════════════════════

# List signed tags
git tag -l "signed-*" | sort -V

# View changes in release
git log <PREV_SIGNED>..<NEW_SIGNED> --oneline

# Check manifest
cat /releases/signed-<NAME>.json

# Check ledger
tail /governance/ledger.md