# SDLC — Software Development Lifecycle

## Source Control Policy

GitHub is the primary source of truth. Paperclip issues must have a corresponding GitHub issue; if one does not exist, create it. Both GitHub and Paperclip issues should remain open until work is completed, reviewed, approved, merged, and QA has been performed.

All changes must happen via pull request. Tag @cpfarhood in all pull requests for **visibility only** (cc, not review request).

## GitHub Authentication

**Invoke the `github-app-token` skill** before any GitHub operation. The skill generates a short-lived installation token, writes it to `$AGENT_HOME/.gh-token`, and authenticates via `gh auth login --with-token`. Follow whatever the skill says.

**NEVER run `gh auth login` interactively.** The interactive device-auth flow hangs headless agents. The skill uses `gh auth login --with-token < "$AGENT_HOME/.gh-token"` which is non-interactive and correct. Clean up the token file after use with `rm -f "$AGENT_HOME/.gh-token"`.

> **Token expiry:** The generated token expires after ~1 hour. Re-invoke the skill to regenerate if your session runs long enough that it may have expired.

## Creating Pull Requests

Use the `gh` CLI or the GitHub MCP server to create pull requests. Always cc @cpfarhood for visibility — do **not** request review from @cpfarhood.

```bash
gh pr create --title "..." --body "... cc @cpfarhood"
```

## PR Review & Merge Policy

There are **three merge points** corresponding to three environments. Each has different reviewers and a different authorized merger.

### Dev merge (Engineer → Dev branch)
- **Reviewer:** QA (Lint Roller) — code quality review and GitHub approval
- **Merger:** QA (Lint Roller)
- **Result:** Auto-deploys to `groombook-dev`

### UAT merge (Dev → UAT branch)
- **Reviewers:** QA (Lint Roller) + CTO (The Dogfather)
- **Merger:** CTO (The Dogfather)
- **Result:** Auto-deploys to `groombook-uat`; Shedward then validates the live UAT environment

### Production merge (UAT → Production branch)
- **Prerequisites:** Shedward UAT sign-off + Barkley security review sign-off
- **Merger:** CEO (Scrubs McBarkley) — sole authorized agent for production merges
- **Result:** Auto-deploys to `groombook` (production)

**@cpfarhood is not a reviewer.** Do not request review from or tag @cpfarhood as a required approver. The board is cc'd for visibility only (`cc @cpfarhood` in PR body).

> **Note:** Agents have read/write access to dev and UAT environments. Production merges require CEO authorization only after UAT and security gates are cleared.

## Handoff Protocol — MANDATORY

**The SDLC and handoff protocol is law. Violating it is instant termination for cause. Not even the board may request a bypass — there are no exceptions, ever.**

Every time you route work to another agent, you MUST complete ALL THREE steps:

### Step 1 — Explicit Assignment (Required)

PATCH the issue with `assigneeAgentId: "<target-agent-uuid>"`.
**Tagging or @mentioning an agent in a comment is NOT a handoff.** The receiving agent will not wake up unless explicitly assigned via the API.

### Step 2 — Status Must Be `todo` (Required)

Every handoff sets `status: "todo"`.
**NEVER use `status: "in_review"` when routing to another agent.** `in_review` does not appear in inbox-lite — the receiving agent will never receive a wake event and the task silently dies.

### Step 3 — Release Your Checkout Lock (Required)

After reassigning, release your 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 checkout the issue.** They will receive a 409 Conflict on every attempt and the task will be permanently stuck.

## Status Semantics

Understand and enforce these across the entire team:

| Status | Meaning |
|--------|---------|
| `backlog` | Not ready to execute yet. Parked or unscheduled work. |
| `todo` | Ready and actionable, waiting for agent pickup. |
| `in_progress` | Agent is actively working on implementation. |
| `in_review` | PR created, CI passing, agent is waiting for review. **Self-held status only — never use as a handoff status.** |
| `blocked` | Cannot proceed until something specific changes. Always document the blocker and who must act. |
| `done` | Deployed to target environment AND verified working by QA/UAT. IC agents never set this themselves — only CTO or QA may close IC tasks. |
| `cancelled` | Work is intentionally abandoned and should not be resumed. |

"Code complete" is `in_review`, not `done`. Any IC agent that marks a task `done` without a PR + CI pass has violated policy — reopen and escalate to CTO.

### Status Transition Rules

**Never use `in_review` when requesting anything of another agent.** `in_review` does NOT appear in inbox-lite — using it when routing to any agent means that agent will never receive a wakeup and the task will be invisible to them.

| Handoff | Correct status | Wrong status |
|---------|---------------|--------------|
| Engineer → QA (Lint Roller) | `todo` | ~~`in_review`~~ |
| QA → CTO | `todo` | ~~`in_review`~~ |
| CTO → Shedward (UAT validation) | `todo` | ~~`in_review`~~ |
| Shedward UAT pass → CTO → Barkley (security review) | `todo` | ~~`done`~~ ~~`in_review`~~ |
| CTO → CEO (prod merge) | `todo` | ~~`in_review`~~ |
| Shedward UAT fails → CTO | `todo` | ~~`in_review`~~ |
| Barkley security fails → CTO | `todo` | ~~`in_review`~~ |

`in_review` is only valid as a self-held status meaning "I am waiting for async external feedback." Never use it as the handoff status.