CascadeGuard Software Development Lifecycle

This document describes the software development lifecycle (SDLC) for the CascadeGuard project. It covers how features move from idea to production and how the project is maintained.

For contributor-specific guidelines (setup, code style, PR mechanics), see the Development guide and the CONTRIBUTING.md in the main repository.

1. Feature Lifecycle

Idea → Discussion → Backlog → Ready → In Progress → In Review → Done → Released

Idea

Features start as GitHub issues. Anyone can propose a feature or report a bug by opening an issue.

Discussion

Feature discussion happens in GitHub issue comments.
For significant features, a short proposal should be posted in the issue covering: scope, motivation, and trade-offs.
Maintainers and community members discuss until a decision is reached.
Small changes (bug fixes, typos, minor improvements) can skip this phase.

Backlog

An issue enters the backlog when it has:

A clear title and description (what, not how).
An assigned priority label (critical, high, medium, low).
Acceptance criteria or a definition of what “done” looks like.
Explicit delivery scope for feature/enhancement issues: one of full-stack, backend-only, frontend-only, infra, docs, or ci. Issues without explicit scope will be sent back during triage.

Ready

An issue is ready to build when:

The description answers: what are we building, why, and what does done look like?
Dependencies are identified and unblocked.
For non-trivial features: a design proposal or ADR exists (see Architecture Decisions).
A maintainer has approved it to start (labeled or assigned).

In Progress

The assignee creates a feature branch off main (see branch naming in CONTRIBUTING.md).
Work happens in focused commits with clear messages.
The assignee runs tests locally before opening a PR.

In Review

A pull request is opened against main.
All CI checks must pass (lint, type check, tests, security scan).
At least one maintainer reviews and approves the PR.
Feedback is addressed in new commits — no force-pushing during review.
See Pull Request Process for details.

In Review — Status Ownership

Only ICs move issues to in_review — this signals “I believe this is complete.”
Only the Product Owner moves issues to done — after verifying the Definition of Done checklist.
ICs MUST NOT move issues directly to done.

Done

A change is done when:

It is merged to main with all checks passing.
The Product Owner has verified the Definition of Done checklist.
The originating issue is closed with a comment that includes: PR link(s), preview/deployment links (if applicable), and a summary of what was delivered.

End-to-End Delivery

When a feature spans backend (API/database) and frontend (UI), the ticket should cover the full stack. A ticket is not done if only one layer is delivered unless the ticket explicitly scopes it to a single layer. For features that naturally span layers:

The ticket description should identify all layers involved.
PRs may be separate per layer, but ALL must be merged before the ticket moves to done.
Preview links should demonstrate the full user-facing flow, not just one component.

2. Issue Management

Creating Issues

Bug reports: Include steps to reproduce, expected vs. actual behavior, and environment details.
Feature requests: Describe the problem being solved, proposed solution, and alternatives considered.
Scope declaration (required for features/enhancements): State the delivery scope explicitly in the issue body:
- full-stack — requires both API/backend and frontend changes
- backend-only — API/backend changes only
- frontend-only — UI changes only
- infra / docs / ci — non-application changes
If omitted, the issue will be returned during triage with a request to clarify before it enters the backlog.
One concern per issue — don’t combine unrelated changes.

Labels

Label	Meaning
`bug`	Something isn’t working correctly
`feature`	New functionality
`enhancement`	Improvement to existing functionality
`docs`	Documentation only
`tech-debt`	Refactoring or cleanup with no user-facing change
`critical` / `high` / `medium` / `low`	Priority

Triage Labels

These labels track an issue’s progress through the triage pipeline:

Label	Meaning
`triaged`	Issue has been reviewed and categorized
`inscope`	Fits the current roadmap
`next`	Top prioritized items ready for CTO review
`cto-reviewed`	CTO has added technical assessment
`ready`	Board-approved, can be scheduled for implementation
`needs-info`	Awaiting clarification from the reporter

GitHub Issue Triage Lifecycle

GitHub is the source of truth for issue state. Issues stay in GitHub until approved for implementation. The full lifecycle is:

New Issue → Triaged → In Scope → Next → CTO Reviewed → Ready → Paperclip Issue → Implementation → PR Merged → GitHub Issue Closed

New issue filed — community member or maintainer opens a GitHub issue.
Triage — the daily triage process reviews new issues:
- Categorize (bug, feature, question, security, docs).
- If in scope: label triaged + inscope.
- If out of scope: move to GitHub Discussions with a comment explaining why.
- If unclear: label triaged + needs-info, comment asking for clarification.
Prioritization — inscope issues are ranked. Top items receive the next label.
CTO review — next items get a technical assessment comment and the cto-reviewed label.
Board approval — board reviews the daily summary and approves items. Approved items receive the ready label. Nothing proceeds without board sign-off.
Paperclip handoff — a Paperclip issue is created only for ready-labeled items, assigned to the relevant engineer.
Implementation — normal feature lifecycle (branch, code, tests, PR).
Closing — when the PR is merged, the corresponding GitHub issue is closed with a comment summarizing what was done and linking to the PR. This ensures the community sees the resolution.

Closing GitHub Issues

When closing a GitHub issue after implementation:

Always add a closing comment before or alongside closing the issue.
The comment should reference the PR that resolved it (e.g., “Resolved in PR #27”).
Briefly describe what changed and any follow-up actions for users.
Use state_reason: completed when the issue is resolved, or not_planned when moved to Discussions.

Milestones

Milestones group issues for release planning. Each milestone corresponds to a planned release version.

3. Pull Request Process

Branch Strategy

Feature branches off main. One branch per issue.

Branch naming: <identifier>/<short-description> (e.g., 42/add-vulnerability-scanner).

PR Creation

Push your feature branch.
Open a PR against main with:
- Title: Short description of the change.
- Body: Summary of what changed and why, a test plan, and a link to the related issue.
Ensure all CI checks pass.

Review

Automated checks run first: lint, type check, unit tests, integration tests, security scan.
A maintainer reviews for correctness, architecture, and code quality.
Test adequacy review — the reviewer verifies that the PR tests the right things, not just that tests exist. Check for edge cases, error paths, and that acceptance criteria are covered by tests.
The reviewer comments on the PR. Author addresses feedback in new commits.
Once approved, a maintainer merges to main. Contributors do not merge their own PRs.

PR Rules

No direct commits to main.
All CI checks must pass before review.
Squash merge preferred for clean history.
Delete branch after merge.

4. Testing Pyramid

         /    E2E    \          ← Few, slow, high confidence
        / Integration  \        ← Moderate, test boundaries
       /   Unit Tests    \      ← Many, fast, isolated
      / Static Analysis    \    ← Lint, type check, security

Layer Details

Layer	What	Tools	Target
Static analysis	Linting, type checking, secret scanning	Per-language linters, type checkers, gitleaks	100% of code
Unit tests	Pure functions, business logic, utilities	pytest / vitest	80%+ line coverage
Integration tests	Service boundaries, deployment validation	pytest / vitest	Key paths covered
E2E tests	Critical user flows, deployment smoke tests	Deployment-level flows	Top 5 user journeys

Testing Requirements

Every PR must include tests for new or changed behavior.
Run tests locally before opening a PR:
```
task test:all
```
CI runs the full pyramid on every PR.
Test failures block merge. No exceptions.

5. Definition of Done

A change is complete when all of the following are true:

6. Release Process

Versioning

CascadeGuard follows Semantic Versioning:

MAJOR: Breaking changes to public interfaces or behavior.
MINOR: New functionality, backwards-compatible.
PATCH: Bug fixes, backwards-compatible.

Release Steps

A maintainer creates a release branch or tags main at the release point.
The changelog is updated with a summary of changes since the last release.
CI builds and publishes release artifacts (container images, packages).
A GitHub Release is created with release notes.

Hotfix Process

Critical production bugs skip the normal backlog queue.
A maintainer creates a critical priority issue — immediate todo.
The same PR and review process applies, but review is expedited.
Hotfix releases are patch version bumps.

7. Architecture Decisions

Significant technical decisions are recorded as Architecture Decision Records (ADRs).

When to Write an ADR

Introducing a new dependency or technology.
Changing the data model or public interfaces.
Choosing between multiple viable approaches.
Any decision that would be hard to reverse later.

ADR Format

ADRs are stored in docs/adr/ and follow the MADR template:

# NNN - Title

## Status
Proposed / Accepted / Deprecated / Superseded by [NNN]

## Context
What is the issue that we're seeing that is motivating this decision?

## Decision
What is the change that we're proposing and/or doing?

## Consequences
What becomes easier or more difficult to do because of this change?

ADRs are immutable once accepted. New decisions supersede old ones.

8. Security

Never commit secrets, credentials, or environment-specific configuration.
Security vulnerabilities in dependencies should be addressed promptly.
Report security issues responsibly — see the project’s security policy.
All code changes go through review; no exceptions for security-sensitive areas.

9. Tech Debt

Tech debt issues are tracked like any other issue with the tech-debt label.
Approximately 20% of development capacity is reserved for tech debt reduction.
Tech debt follows the same approval and review flow as features.

10. Continuous Integration

CI runs automatically on every PR and push to main:

Static analysis: Linting, type checking, secret scanning.
Unit tests: Fast, isolated tests for business logic.
Integration tests: Service boundary and deployment validation tests.
Build verification: Ensure the application builds and container images are valid.

All checks must pass for a PR to be merge-eligible.

11. Environments & Preview Deployments

Environment Strategy

All changes must be testable in an environment that mirrors production before merging.

Environment	Purpose	Web URL	API URL
Preview	Per-PR ephemeral deployment for review and testing	`<pr-id>.preview.cascadeguard.com`	`<pr-id>.preview.api.cascadeguard.com`
Staging	Pre-release validation, integration testing	`staging.cascadeguard.com`	`staging.api.cascadeguard.com`
Production	Live environment	`cascadeguard.com`	`api.cascadeguard.com`

Preview Deployment Requirements

Any PR that changes web frontend or API backend code must deploy both components to a preview environment. A single preview link is insufficient when the change touches either layer, because the web and API are coupled.
Preview links must be posted as a PR comment before requesting review.
Reviewers must not approve PRs with missing preview links for web/API changes.
Preview environments are automatically torn down when the PR is merged or closed.

Promotion Path

Preview → Staging → Production

PRs are tested in preview before merge.
main is deployed to staging automatically after merge.
Production releases are promoted from staging after validation (see Release Process).

12. Engineering Operations & Oversight

This section defines who is responsible for keeping engineering work flowing without requiring board intervention on routine operational matters.

Roles

Role	Operational Responsibility
IC Engineer	Pull work from backlog, own CI green status, merge conflict resolution, status updates
CTO	Backlog prioritisation, PR review (1h SLA), blocker triage (<30min), hourly health scans
Product Owner	Acceptance validation for user-facing changes (<2h), backlog health (weekly)
Board	Strategic review only — async daily summary + weekly sync

Event-Driven Response (Tier 1)

These status transitions require prompt action:

Event	Who Acts	Target Response Time
Issue moves to blocked	CTO	<30min — assess blocker, provide guidance or reassign
PR marked ready for review (CI green)	CTO	<30min to begin review, <1h to complete
Issue moves to done (user-facing)	PO	<1h — validate acceptance criteria
Issue moves to done (technical)	CTO	Next hourly scan

Scheduled Scans (Tier 2 — Hourly)

Check	Owner	Action
Issues `in_progress` with no activity >1h	CTO	Request status update from assignee
Issues `in_progress` with no activity >2h	CTO	Escalate or reassign
Issues in `todo` with no assignee >2h	CTO	Verify backlog priority is clear; escalate to board if ambiguous
PRs open >1h with merge conflicts	CTO	Comment asking engineer to rebase
PRs open >4h with no review activity	CTO	Review or close with note to reopen when ready
Issues `blocked` >2h	CTO	Escalate to CEO if unresolvable

Work Assignment — Pull Model

Engineers pull work from the prioritised backlog rather than receiving assignments from the CTO. This prevents over-assignment and gives engineers ownership of their capacity.

How it works:

CTO and PO maintain backlog priority. Issues in todo are ordered by priority. The CTO ensures technical context and scope are clear before an issue is ready for pickup.
Engineers pull when they have capacity. When an engineer finishes work or has fewer than 3 active issues (todo + in_progress), they pick the highest-priority unassigned todo item that matches their skills.
WIP limit: max 3 active issues per engineer. Engineers must not pull new work if they already have 3 active issues.
No duplicate tasks. If an existing task covers the work, reopen/unblock it instead of creating a new one.
Blocked task hygiene. When a task is blocked, either unblock it or escalate within 1 heartbeat. Do not leave blocked tasks accumulating.

CTO may still assign directly when:

A critical/urgent issue needs a specific engineer’s expertise
An engineer is idle and hasn’t pulled work (escalation path)
Cross-team coordination requires explicit routing

Engineer Responsibilities

Engineers are expected to:

Pull work from the backlog — when you have capacity (fewer than 3 active issues), pick the highest-priority unassigned todo item that matches your skills.
Keep CI green — do not request review until all checks pass.
Resolve merge conflicts — the PR author owns keeping their branch up to date with main.
Update issue status — move issues to blocked with a comment explaining the blocker. Do not leave issues silently stalled.
Respond to review feedback — address reviewer comments within 1h.
Use clickable links for external references — when referencing GitHub issues, PRs, external services, or any resource outside the current system, always use full clickable Markdown links (e.g. [PR #46](https://github.com/cascadeguard/cascadeguard/pull/46)). Never leave bare identifiers or plain-text URLs that readers cannot click to navigate to. Where the platform supports it, links to external systems should open in a new tab (use HTML <a href="..." target="_blank"> when Markdown target control is unavailable).

Board Cadence

Frequency	Activity
Daily (async, ~5 min)	Read CTO summary: what shipped, what’s blocked, any escalations
Weekly (30 min)	Roadmap review, approve `ready` items, discuss strategic risks
On demand	CTO escalates items needing board input (budget, hiring, partnerships)

RACI Matrix

Activity	Engineer	PO	CTO	Board
Keep CI green	R	—	I	—
Resolve merge conflicts	R	—	I	—
Update issue status when blocked	R	I	A	—
Review PRs (technical)	C	—	R/A	—
Acceptance validation (user-facing)	I	R/A	—	—
Daily stuck-issue scan	—	—	R	I
Pull work from prioritised backlog	R	—	I	—
Maintain backlog priority	—	C	R	I
Escalate strategic blockers	—	—	R	A
Weekly roadmap review	—	C	R	A

R = Responsible, A = Accountable, C = Consulted, I = Informed

Techcle Wiki

Explorer

Sdlc