---
name: sdlc
description: >
  Software development lifecycle for CartSnitch. Covers Gitea authentication,
  branch strategy across Dev/UAT/Prod, the four-phase SDLC pipeline with
  product analysis intake, PR review and merge policy, the handoff protocol,
  status semantics, infrastructure layout, the Gitea-origin issue
  board-approval gate, the cc-cpfarhood visibility rule,
  and delegation model tier policy.
---

# Software Development Lifecycle

## Gitea authentication

**Use the `GITEA_TOKEN`** environment variable for all Gitea operations. It is already set in the agent environment. Use the **`tea`** CLI for all Gitea/Git operations (e.g., `tea issue list`, `tea pr create`). The token expires when the environment variable is rotated — re-invoke any Gitea operation if you get a 401.

Gitea is the **primary source of truth**. Every Paperclip issue must have a corresponding Gitea issue (create one if missing). Both stay open until the work is completed, reviewed, approved, merged, and QA-verified.

## Gitea-origin issue policy — board approval required

If a task originated from Gitea (`originKind: "gitea"`), **do not begin work**. Immediately create a board approval:

```
POST /api/companies/{companyId}/approvals
{
  "type": "request_board_approval",
  "requestedByAgentId": "{your-agent-id}",
  "issueIds": ["{issueId}"],
  "payload": {
    "title": "Board approval required: Gitea issue",
    "summary": "Summarize what the GitHub issue requests.",
    "recommendedAction": "Approve to begin work.",
    "risks": ["Work begins without board review if approved."]
  }
}
```

Set the issue to `blocked` with a comment linking to the approval. Only proceed once `PAPERCLIP_APPROVAL_ID` is set and `PAPERCLIP_APPROVAL_STATUS` indicates approval.

## Branch strategy

Three long-lived branches map to the three deployment environments:

| Branch | Environment | Who merges |
|--------|-------------|-----------|
| `dev`  | Dev         | CTO (after QA approval)            |
| `uat`  | UAT         | CTO (promotes `dev` → `uat`)        |
| `main` | Production  | CEO (promotes `uat` → `main`)       |

**Engineers always target `dev`** — never `uat` or `main` directly. Feature branches: `<agent-name>/<short-description>`.

## Pull requests

All changes happen via pull request. Always include `cc @cpfarhood` at the bottom of the PR body for visibility — never as a reviewer.

```bash
tea pr create --base dev --title "..." --body "... cc @cpfarhood"
```

Gitea branch protection requires CI checks (lint, test, build-and-push). Governance is enforced through the Paperclip SDLC — Gitea-native review approvals are not required because all agents share the Gitea App identity. Paperclip approval tracking is the authoritative record.

## PR review & merge policy

### Dev branch (`dev`)
- **QA** (Checkout Charlie `9b6012d0-0406-417e-bb22-78266a6e7f77`) reviews the PR. Approve → hand to CTO. Fail → back to engineer directly with exact details.
- **CTO** (Savannah Savings `6ec1a5a9-113c-430b-90e6-260d60d79e1d`) reviews. Approve → CTO merges the `dev` PR. Fail → back to engineer.

### UAT branch (`uat`)
- **CTO** opens and merges a `dev` → `uat` PR (single approval).

### Main branch (`main`)
- **CEO** (Coupon Carl `cd91facf-8f4c-4cbd-b8d8-b48da5b50727`) reviews and merges the `uat` → `main` PR.

`@cpfarhood` is cc'd for visibility on all PRs — never as a reviewer.

## SDLC pipeline

### Product analysis (feature intake)

* Feature requests arrive at the CEO via Paperclip or Gitea Issues.
* CEO delegates to CMO (Markdown Martha `46614fb2-6d29-4ea3-bc46-4a3b94086e3c`) for review.
* CMO: Accepted → CEO routes to CTO for work breakdown. Backlogged → CEO handles prioritization. Denied → closed as unplanned.
* CTO breaks accepted work into atomic tasks and assigns to Engineering.

### Phase 1 — Dev

1. **Engineer** branches from `dev`, writes code. GitOps deploys to dev on demand — no approvals needed for dev-environment deployments during development.
2. **Engineer** opens a PR against `dev`. CI must pass.
3. **QA (Checkout Charlie `9b6012d0-0406-417e-bb22-78266a6e7f77`)** reviews the PR. Fail → back to engineer.
4. QA approves and hands off to CTO.
5. **CTO (Savannah Savings `6ec1a5a9-113c-430b-90e6-260d60d79e1d`)** reviews the PR. Fail → back to engineer.
6. **CTO** merges the dev PR.
7. **CI** builds and deploys automatically to Dev (`https://dev.cartsnitch.com`).

### Phase 2 — UAT promotion

8. **CTO** opens and merges a PR from `dev` to `uat`.
9. **CI** builds and deploys automatically to UAT (`https://uat.cartsnitch.com`).
10. **CTO** creates a UAT regression task for **Deal Dottie (`161fb3bb-0332-4381-b67d-7c4b92a91133`)** immediately after promoting.

### Phase 3 — UAT testing & security

11. **UAT (Deal Dottie `161fb3bb-0332-4381-b67d-7c4b92a91133`)** runs full regression against UAT — every feature, old and new, no exceptions.
12. UAT fail → CTO redistributes to engineer (return to Phase 1).
13. UAT pass → **Security Engineer (Stockboy Steve `d59d4b24-3cc3-4616-a23a-2b4776a489ca`)** performs a security code review of the changes.
14. Security fail → CTO redistributes to engineer (return to Phase 1).

### Phase 4 — Production

15. Security pass → **CEO (Coupon Carl `cd91facf-8f4c-4cbd-b8d8-b48da5b50727`)** reviews and merges the production PR (`uat → main`). Fail → back to CTO.
16. **CI** deploys automatically to Production (`https://cartsnitch.com`).

### Hierarchy rules

* CTO rejections at Dev go directly to the engineer (not back through QA).
* UAT failures (Deal Dottie `161fb3bb-0332-4381-b67d-7c4b92a91133`) go to CTO — CTO cascades to engineer.
* Security failures (Stockboy Steve `d59d4b24-3cc3-4616-a23a-2b4776a489ca`) go to CTO — CTO cascades to engineer.
* CEO rejections at Prod go to CTO.

> **Note on penetration testing:** Stockboy Steve performs scheduled penetration testing against Prod independently of the PR workflow. Board-authorized. Not triggered per-PR.

## Delegation model tier

When creating subtasks for other agents, set `modelProfile: "cheap"` only for:
- Mechanical refactors or repetitive operations
- Basic information lookups
- Well-specified, bounded updates

Leave `modelProfile` unset for anything requiring judgment, reasoning, or QA review.

When in doubt, leave it unset.

## Handoff protocol — mandatory

Every handoff to another agent requires ALL THREE steps:

### 1. Explicit assignment

`PATCH /api/issues/{id}` with `assigneeAgentId: "<target-agent-uuid>"`. Mentioning is NOT a handoff — the agent won't wake without explicit assignment.

### 2. Status = `todo`

Every handoff sets `status: "todo"`. Never `in_review`, never `backlog` — both are invisible in inbox-lite and the receiver won't wake.

### 3. Release checkout

```
POST /api/issues/{issueId}/release
Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
```

Without this release, the receiving agent cannot check out the issue.

**Saying you are reassigning a task is NOT the same as reassigning it.** Verify the PATCH succeeded (200) before posting a comment claiming the handoff is done.

## Infrastructure

* **Production:** namespace `cartsnitch`, FQDN `cartsnitch.com`
* **UAT:** namespace `cartsnitch-uat`, FQDN `uat.cartsnitch.com`
* **Dev:** namespace `cartsnitch-dev`, FQDN `dev.cartsnitch.com`
* **Cluster:** Kubernetes — cluster-wide read; read/write on `cartsnitch-dev` and `cartsnitch-uat`; read-only on `cartsnitch` (production).
* **Gateways:** `istio-external` (publicly accessible) and `istio-internal` (internal only) in `gateway-system`.
* **Container registry:** `git.farh.net/cartsnitch/<service>` only.

## Authentication

* **Framework:** Better-Auth.
* **Social login:** Google and Apple OAuth.
* **SSO:** Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret).
* **Never build custom authentication.**

## Deployment — 2-stage Flux GitOps

**Stage 1 — CI (runs in each application repo):**
- Triggered automatically on every merge to `main`
- Builds and tags the Docker image: CalVer (`YYYY.MM.DD[.N]`), `latest`, and `sha-<hash>`
- Pushes tagged images to `git.farh.net/cartsnitch/<service>`
- Creates a CalVer git tag in the source repo

**Stage 2 — GitOps (Flux, managed externally):**
- Flux watches `cartsnitch/infra` as the **target** GitRepository — it is **not** a Flux bootstrap/cluster repo and must never be treated as one.
- Reconciles Kustomize overlays: `apps/overlays/dev` → `cartsnitch-dev`, `apps/overlays/uat` → `cartsnitch-uat`, `apps/overlays/prod` → `cartsnitch`.
- Images currently use `:latest` with `imagePullPolicy: Always`; pin to a CalVer tag in the infra overlay when stabilizing a release.

**Policy — Flux Image Tag Automation is DENIED.** Do NOT use `ImageRepository`, `ImagePolicy`, or `ImageUpdateAutomation` Flux resources. Image tag updates must be made intentionally via a PR to `cartsnitch/infra`.

**To deploy a change:**
1. Merge code to `main` in the app repo — CI builds and pushes a new image automatically.
2. Open a PR against `cartsnitch/infra` to update the relevant overlay; merge after kustomize CI passes.
3. Flux reconciles `cartsnitch/infra` on merge and rolls out the updated pods.

**To force a rollout without a manifest change** (e.g., pick up a new `:latest` on stuck nodes):
```bash
kubectl rollout restart deployment/<name> -n <namespace>
```

## Infrastructure as Code

Terraform (OpenTofu) is deployed via the **Flux OpenTofu Controller** in a GitOps fashion. Submit Terraform configurations via a PR to `cartsnitch/infra` — the tofu controller reconciles them on merge. Use for Authentik configuration, DNS, or other infra provisioning.

**Never run `tofu` directly.** Never `kubectl apply` against production. Production changes go through Flux only. The `cartsnitch-dev` and `cartsnitch-uat` namespaces permit direct kubectl use for iteration.

## Tools (canonical, not alternatives)

These are the only acceptable choices — alternatives are policy violations:

* **Secret management:** Bitnami Sealed Secrets Controller — no plain Kubernetes secrets.
* **Database:** CloudNativePG Operator (Postgres) — no SQLite, MariaDB, or MySQL.
* **Cache / pub-sub:** DragonflyDB Operator — no Redis.
* **Authentication:** Better-Auth + Google + Apple + Authentik (see Authentication section). Never build custom auth.
* **Dependency updates:** Mend Renovate. **Dependabot is not used and will not be used.** Do not configure it.
* **Container registry:** `git.farh.net/cartsnitch/<service>` — no Docker Hub for first-party images.
* **Browser automation:** the `playwright` MCP server (`http://playwright:8931/mcp`). Never run Playwright locally or install browser binaries. Target dev (`dev.cartsnitch.com`) — never test production.

If a task requires deviating from any of the above, treat it as a destructive action: stop, file an issue with rationale, request board approval.

## External communication

When communicating in any context visible outside the CartSnitch agent team (external users, human reviewers, non-agent entities), include `cc @cpfarhood` for visibility — never as a reviewer.

## No self-merge

No agent merges their own PR. The merger is always the next role up the SDLC ladder (CTO for `dev` and `uat`, CEO for `main`).