Metadata-Version: 2.4
Name: sdlc-framework
Version: 0.17.0
Summary: Local-only multi-AI SDLC framework with auto-detect engine, tier-aware DoD, and GitHub integration
Project-URL: Homepage, https://github.com/vuonglq01685/SDLC
Project-URL: Source, https://github.com/vuonglq01685/SDLC
Project-URL: Issues, https://github.com/vuonglq01685/SDLC/issues
Author-email: Lam Vuong <vuonglq01685@gmail.com>
License-Expression: MIT
Keywords: ai-agent,claude,codex,cursor,github,sdlc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# SDLC Framework

> A local-only, multi-AI SDLC framework. One `sdlc` CLI scaffolds a 5-phase
> project, auto-detects DoD evidence, dispatches the right specialist subagent
> for each stage, and tracks per-feature task progress with strict sequential
> TDD.

[![PyPI](https://img.shields.io/pypi/v/sdlc-framework.svg)](https://pypi.org/project/sdlc-framework/)
[![Python](https://img.shields.io/pypi/pyversions/sdlc-framework.svg)](https://pypi.org/project/sdlc-framework/)

Works with **8 AI coding tools**: Claude Code · GitHub Copilot · Cursor ·
OpenAI Codex · Aider · Windsurf · Cline · Continue.

---

## Table of contents

1. [What it does](#what-it-does)
2. [Install + first project](#install--first-project)
3. [Adopt an existing project](#adopt-an-existing-project)
4. [Workflow guideline (6 approaches)](GUIDELINE.md)
5. [Daily commands](#daily-commands)
6. [Concepts](#concepts)
7. [AI tool support](#ai-tool-support)
8. [Specialist subagents](#specialist-subagents)
9. [Repo layout](#repo-layout)
10. [Advanced](#advanced)
11. [Contributing](#contributing)

---

## What's new

### 0.17.0 — 2026-05-02

**Multi-tool slash command parity.** Slash commands and subagents now ship to 5 additional AI tools beyond Claude Code, with capability-aware tiering.

| Tier | Tools | Surface | Phase 3 strict TDD |
|---|---|---|---|
| 1 — full | Claude Code, **Cursor**, **GitHub Copilot** | 13 commands + 12 subagents | ✅ fresh-context per stage |
| 2 — autopilot, role-by-prompt | **Cline**, **Windsurf** | 13 workflows + warning rules | ⚠️ same-context, role re-read each stage |
| 3 — guided prompts | **Continue.dev** | 5-prompt subset (`sdlc-next`/`-resume`/`-scan`/`-tasks`/`-verify`) | ❌ runs in terminal |
| 4 — terminal only | Aider, Codex | docs in `CONVENTIONS.md` / `AGENTS.md` | ❌ runs in terminal |

Highlights:

- **Generator approach** — single canonical (`.claude/commands/` + `agents/`); per-tool surfaces re-render idempotently with `<!-- generated-from: <canonical-path> -->` markers. User-edited files (no marker) are never clobbered.
- **`sdlc upgrade`** auto-detects existing surfaces (`.cursor/`, `.github/prompts/`, etc.) and re-renders them. New flag: `sdlc upgrade --add-tool=<name>` adds a surface to a project that doesn't have it yet.
- **`sdlc init --ai-tools=cursor,copilot,...`** — opt-in to per-tool surfaces at scaffold time.
- **`sdlc adopt`** auto-renders detected tool surfaces during retrofit.

Try it:
```bash
sdlc init --ai-tools=cursor,copilot,cline,windsurf,continue
# or, on an existing project:
sdlc upgrade --add-tool=cursor
```

### 0.16.1 — 2026-05-02

**`sdlc upgrade` — bring an existing project in sync with new scaffold files after `pip install --upgrade`.**

When you upgrade the framework, runtime logic (engine, dispatch, agent context bundles) updates automatically. But scaffold files copied at `sdlc init` time — `automation/rules.json`, design templates, agent prompts, AI-tool docs — are frozen in your project from the day it was first scaffolded. New DoD items, new templates, and updated agent prompts shipped in later versions don't reach your project on their own. `sdlc upgrade` closes that gap:

- **Adds** new scaffold files that didn't exist when your project was scaffolded (e.g. `02-Design/templates/00-Code-Structure.md` from 0.16.0).
- **Skips** files identical to scaffold (already in sync).
- **Reports** files where your project differs from scaffold — does NOT overwrite by default. Review the diff, then opt into overwrite with `--force` or keep your customizations.
- **Structurally merges** `automation/rules.json`: missing engine items are inserted at the correct phase position; user-added custom items are preserved untouched.
- **Never touches** user-owned files (state.json, tasks/, clarifications/, signoffs/, your actual PRD/architecture/code) — they're outside the scaffold tree, so the walk doesn't even see them.
- `--dry-run` makes zero writes; useful for previewing.

Recommended one-liner after every framework upgrade:
```bash
pip install --upgrade sdlc-framework
sdlc upgrade --dry-run    # preview
sdlc upgrade              # apply
```

### 0.16.0 — 2026-05-02

**Phase 2 → Phase 3 architecture-to-code bridge + activity-based stage labels.**

#### Architecture-to-code bridge

Closes the defect where bootstrap created `src/<user-story-slug>/` folders regardless of architecture, producing parallel "code-soup" islands that the user had to manually rewire (observed across Cursor, Copilot, and Claude). Cursor / Copilot / Claude were *following the rails correctly* — the rails were laid in the wrong direction.

- New Phase 2 DoD item `code-structure-mapped` (architecture sub-track). Architect-agent must produce `02-Design/00-Code-Structure.md` mapping each C4-L2 container to a `src/<folder>/` and each user story to its primary container.
- Scaffold template `02-Design/templates/00-Code-Structure.md` with §1 container → folder, §2 user-story → container, §3 dependency rules.
- `sdlc tasks bootstrap` now consults `02-Design/*Code-Structure*.md`. Each task yaml gains a `container:` field; `code_glob` becomes `src/<container>/<module-hint>*` instead of `src/<slug>/**`. Unmapped stories surface a warning per story so the user can fill them in. When the file is absent, the legacy slug behavior is preserved with a one-line deprecation warning.
- `developer-agent`, `phase-3-developer`, `test-author`, `code-reviewer`, `security-reviewer` brief slices now include the §1 container → folder map and §3 dependency rules. Code-writing agents finally see the architectural anchor instead of inferring layout from the task glob alone.
- `phase-2-architect.md` mandate updated: Code Structure is now listed as a non-negotiable Phase 2 deliverable for tier 1/2 projects.

#### Phase 3 stage labels — activity-based

Closes the lag where the dashboard / state.json named stages after the *deliverable already produced* instead of the *activity in flight*. Symptom: while developer-agent was actively writing code, the stage still showed `write-tests` because tests existed and code did not — one nhịp behind reality. Same lag at every transition.

- Stages renamed to label the activity happening NOW. Old: `pending → write-tests → write-code → review → done`. New (6 stages): `pending → write-tests → write-code → review → await-merge → done`.
- `pending` is now narrowed to *queued behind the Phase 3 serial lock* (inactive groups). Active tasks with no deliverables go straight to `write-tests` — that is the activity test-author is performing.
- `await-merge` is new — distinguishes "code-reviewer is doing its local job" (`review`) from "PR open, waiting for human merge" (`await-merge`).
- `auto-mad-step` behavior preserved exactly: at stage `review` (both files, no PR) it auto-opens the PR; at stage `await-merge` it parses the verdict block and auto squash-merges on PASS + critical=0.
- `stage_to_subagent` mapping shifted accordingly: `write-tests` → `test-author`, `write-code` → `developer-agent`, `review` → `code-reviewer` (or `security-reviewer` for sensitive areas), `await-merge` → none, `pending` → none.

### 0.15.0 — 2026-05-02

**Phase 3 serial lock + mad-mode auto-PR-merge.**

- Phase 3 now runs strictly serial: only one `feature_id` group is "active" at a time. Inactive tasks always show `stage: pending` regardless of filesystem state. Fixes the bug where one task's commit advanced every task to `write-code` simultaneously (most visible on GitHub Copilot).
- `auto-mad-step` now auto-opens PRs after `write-code` and auto squash-merges after `review` when the code-reviewer verdict block is `PASS` with zero `critical` findings. New stop reasons: `code_review_failed`, `pr_open_failed`, `merge_failed`.
- New CLI: `sdlc tasks activate <id>`, `sdlc tasks active`, `sdlc tasks unlock`, `sdlc tasks force-merge <id> --i-accept-the-risk`.
- Code-reviewer agent prompt now mandates a `<!-- sdlc:review-verdict ... -->` block at the end of every review file. Missing/malformed → fail-safe to BLOCK.
- AI-tool prompts (Copilot, Cursor, Cline, Continue, Windsurf, Aider, Codex) now include a CONTRACT section forbidding direct state mutation and cross-phase drift.
- Schema migration `state.json` v2 → v3 (idempotent, automatic on first scan after upgrade). Adds `phase3` block.

---

## What it does

```mermaid
flowchart LR
  Idea[Idea / brief] --> P1[1. Planning]
  P1 --> P2[2. Design]
  P2 --> P3[3. Development]
  P3 --> P4[4. E2E & Integration]
  P4 --> P5[5. Deploy & Monitor]
  P5 -. metrics & feedback .-> P1
```

| Phase | Focus | Sub-tracks | Subagent(s) |
|-------|-------|------------|-------------|
| 1 — Planning | PRD, user stories, NFRs, RACI, risks | — | `pm-agent`, `security-reviewer` (risks) |
| 2 — Design | C4 architecture + UI/UX | Architecture · UI/UX | `architect-agent`, `ux-designer`, `security-reviewer` |
| 3 — Development | Setup + per-task Kanban with sequential TDD | Setup · Tasks | `test-author` → `developer-agent` → `code-reviewer` |
| 4 — Testing | E2E, integration, smoke, regression, load | — | `qa-engineer` |
| 5 — Deploy & Monitor | CI/CD, runbook, SLOs, incident response | — | `sre-agent` |

The engine scans your repo (`sdlc scan` or `sdlc scan --watch`), evaluates DoD
rules from `automation/rules.json`, writes `state.json`, and the dashboard
renders it. AI agents read the same rules to know what evidence to produce
next.

---

## Install + first project

```bash
pip install --upgrade sdlc-framework

mkdir my-app && cd my-app
sdlc setup                                      # interactive: pick AI tools, scaffold
sdlc start "Mobile task app for 5-person team"  # save your idea
```

Then in **Claude Code** (or your AI tool of choice):

```
/sdlc-start "Mobile task app for 5-person team"
```

The slash command invokes `pm-agent`, drafts `01-Planning/01-PRD.md` from
`01-Planning/IDEA.md`, and reports progress. Run `/sdlc-next` to advance.

Prefer the terminal? Same loop:

```bash
sdlc next                  # paste-ready prompt for the next pending item
sdlc scan --print          # progress summary
sdlc resume                # "where am I?"
sdlc dashboard --port 8765 # live UI
```

---

## Adopt an existing project

For a project already mid-development or in production:

```bash
cd ~/Projects/existing-app
sdlc adopt
```

`sdlc adopt` is **idempotent** and **non-destructive**: it scans for existing
assets (`docs/PRD.md`, `docs/ARCHITECTURE.md`, runbooks, SLO docs, CI
workflows…), creates symlinks (or copies on Windows) into the canonical SDLC
paths, and auto-verifies them with the marker `imported-from-existing`. Your
existing files stay where they are.

For Phase 3 you choose:
- **Legacy mode** — existing `src/` is grandfathered (no TDD enforcement);
  only new features go through tasks.
- **Skip mode** — manage tasks manually.

After adopt, `sdlc resume` shows your starting point.

> **Not sure which workflow fits your situation?** See [GUIDELINE.md](GUIDELINE.md)
> for 6 approaches (greenfield, new feature, replan, auto-adopt, manual adopt,
> legacy reconstruct) with a decision table, command sequences, and the
> file-path ↔ DoD item-id mapping used by `sdlc verify`.

---

## Daily commands

```text
# day-to-day
sdlc resume                              "where am I?" (aliases: status, where)
sdlc next [--json]                       paste-ready prompt for next pending item
sdlc verify <item-id> [--name=<who>]     mark a Phase 1/2/4 artifact verified
sdlc tasks bootstrap                     auto-create tasks from user stories
sdlc tasks list | new <id> | rm <id>     manage Phase 3 tasks

# engine
sdlc scan [--watch] [--print]            run engine, write state.json
sdlc dispatch [--json]                   inspect next-agent decision
sdlc dashboard [--port N]                serve the live UI

# autopilot
sdlc auto-step                           one iteration of /sdlc-auto
sdlc auto-mad-step                       one iteration of /sdlc-auto-mad (YOLO)

# adjustments
sdlc replan [--scope=...] [--clear]      mark items dirty after a major change

# integrations (low-level; agents call these automatically)
sdlc agent-log start|done|fail ...
sdlc notify <kind> <id> <title> <body>
sdlc gh-issue --clarification PATH | --gate ID
sdlc gh-pr [--ready] [--base BRANCH]
sdlc build-ai-configs                    regenerate the 8 AI tool configs

# migrations
sdlc migrate-v2                          v0.6.x → v2 (3-phase → 5-phase)
sdlc migrate-v3                          v0.7/v0.8 → v3 (rename + reorder)

sdlc --version
```

---

## Concepts

### `project.yaml` — tier-aware DoD strictness

The engine reads `project.yaml` and adjusts evidence strictness per tier:

| Rule | Tier 1 (critical) | Tier 2 (standard) | Tier 3 (experiment) |
|------|---|---|---|
| `nfr-targets` | `p99` AND (`RTO` or `RPO`) | `p95` / `p99` | optional |
| `security-threat-model` | STRIDE + `Mitigation` per asset | STRIDE only | optional |
| `tdd-coverage-active` | strict 1:1 | strict 1:1 | strict 1:1 |
| `phase5-signoff` | sponsor + eng_lead + sre + security | sponsor + eng_lead + sre | eng_lead only |
| `owners-defined` | sponsor + eng_lead + security + sre | sponsor + eng_lead + sre | sponsor + eng_lead |

Minimal schema:

```yaml
schema_version: 3
name: my-app
team: platform
stack: node
tier: 2
phase_target: 3
repo_url: https://github.com/your-org/my-app
owners:
  sponsor: alice@org.com
  eng_lead: bob@org.com
  sre: dave@org.com
flags:
  ai_disclosure_required: true
  signoffs_strict: auto
legacy_code_globs: []     # for retrofits — exclude from TDD coverage
```

### Per-artifact verify (Phase 1, 2, 4)

Each artifact has two states: `drafted` (file exists with content) and
`verified` (file ends with `<!-- sdlc:verified-by: <name> <iso-date> -->`).
Both required for `done`.

```bash
sdlc verify prd-drafted --name="alice"
# records to automation/.verifications.json + appends marker
```

For retrofits, `sdlc adopt --auto` writes the marker as
`imported-from-existing` so the audit trail honestly reflects provenance.

### Phase 3 task lifecycle (sequential TDD strict)

Tasks live in `automation/tasks/<id>.yaml`. Each progresses through 5 stages
sequentially:

```
pending → write-tests → write-code → review → done
```

Stage detection is automatic (filesystem + `gh pr view`):

| Stage | Detection | Subagent invoked |
|---|---|---|
| `pending` | no code, no tests | `test-author` |
| `write-tests` | tests exist, no code | `developer-agent` |
| `write-code` | tests ≥ code, no PR | `code-reviewer` (or `security-reviewer` if sensitive) |
| `review` | PR open | (waits for human merge) |
| `done` | PR merged | (terminal) |

Each subagent runs in a **fresh context** — no memory leakage between stages.
Bootstrap from user stories:

```bash
sdlc tasks bootstrap   # one task per `## Story:` heading in 01-Planning/02-User-Stories.md
```

Or manual:

```bash
sdlc tasks new feature-billing --label="Billing — Stripe" \
  --code-glob="src/billing/**/*.ts" \
  --test-glob="src/billing/**/*.test.ts"
```

### Autopilot

Two modes — same loop, different stop policy.

| Stop reason       | `/sdlc-auto`   | `/sdlc-auto-mad`                       |
|-------------------|----------------|----------------------------------------|
| `verify_needed`   | stop           | **auto-verify** (marker `ai-mad-mode`) |
| `gate`            | stop           | **auto-sign** (`approved_by: ai-mad-mode`) |
| `clarification`   | stop           | stop                                   |
| `high_risk`       | stop           | stop (auth / crypto / payment)         |
| `review_pending`  | stop           | stop (PR is external)                  |

`/sdlc-auto-mad` is **opt-in YOLO** for prototypes / hackathons /
throwaway projects. Every auto-signed yaml is clearly marked with an
`unsign_command`. To revert ALL ai-mad-mode signoffs:

```bash
grep -l "approved_by: ai-mad-mode" automation/signoffs/*.yaml | xargs rm
sdlc scan
```

### Smart dispatcher

`sdlc dispatch` returns:

- The **primary agent** for the next pending item (resolved as: stage-specific
  for tasks > item override > phase default).
- A **`parallel_agents`** list — cross-cutting agents to invoke alongside
  (e.g., `risks-identified` invites `pm-agent` + `security-reviewer`).
- A **`blocked_by`** field — names the earlier-phase blocker when
  `phase_target` can't be honored.

### Replan workflow

Requirements changed? Tech-stack pivot?

```bash
sdlc replan
# Interactive: pick scope (requirements / ui-ux / tech-stack / scale-nfr / custom)
# Affected items go red until you redo them.
# Audit clarification written to automation/clarifications/replan-<ts>.md
sdlc replan --clear   # drop dirty markers when done
```

### STOP triggers (autonomous loop)

When operating without a human, agents follow `automation/AGENT-LOOP.md` and
stop on:

- 🔍 **Ambiguity** — insufficient information
- ⚔️ **Conflict** — sources disagree
- 🚪 **Gate** — sign-off needed
- 🛑 **High-risk path** — auth / crypto / payment / migrations / secrets

Resolve a clarification: edit the file, change `STATUS: open` → `resolved`.
Approve a gate: write `automation/signoffs/<gate-id>.yaml` with
`approved: true`.

---

## AI tool support

Single shared source in `ai-tools/shared-prompts/standards.md` plus a per-tool
header. `sdlc setup` (or `sdlc build-ai-configs`) generates 8 configs:

| Tool | Output path | Native commands |
|------|-------------|-----------------|
| Claude Code | `CLAUDE.md` + `.claude/agents/*.md` + `.claude/commands/sdlc-*.md` + `.claude/skills/sdlc/SKILL.md` | `/sdlc-init` `/sdlc-start` `/sdlc-next` `/sdlc-scan` `/sdlc-dispatch` `/sdlc-dashboard` `/sdlc-auto` `/sdlc-auto-mad` |
| Cursor | `.cursorrules` + `.cursor/rules/sdlc.mdc` | (auto-loaded rules) |
| GitHub Copilot Chat | `.github/copilot-instructions.md` + `.github/prompts/sdlc-*.prompt.md` | (prompt files) |
| OpenAI Codex | `AGENTS.md` | (text rules) |
| Aider | `.aider.conf.yml` + `CONVENTIONS.md` | (text rules + CLI) |
| Windsurf | `.windsurfrules` | (text rules) |
| Cline | `.clinerules` | (text rules) |
| Continue | `.continuerules` + `.continue/config.json` | (text rules) |

Edit `ai-tools/shared-prompts/standards.md`, run `sdlc build-ai-configs`, all
8 files regenerate. Each carries a `<!-- AUTO-GENERATED -->` header so devs
don't hand-edit.

---

## Specialist subagents

11 role specs that any AI tool can read.

| Subagent | Phase / stage | Role |
|----------|---------------|------|
| `pm-agent` | Phase 1 | PRDs, user stories with G/W/T, quantified NFRs, stakeholders, risks |
| `architect-agent` | Phase 2 (Architecture) | C4, API spec, DB schema, ADRs |
| `ux-designer` | Phase 2 (UI/UX) | UI specs, wireframes, design system, accessibility |
| `security-reviewer` | Phase 1/2/3 | AppSec — risks, threat model, sensitive code review |
| `test-author` | Phase 3 `pending → write-tests` | Tests-first (TDD red phase) |
| `developer-agent` | Phase 3 `write-tests → write-code` | Production code (TDD green phase) |
| `code-reviewer` | Phase 3 `write-code → review` | Code quality review |
| `qa-engineer` | Phase 4 | E2E, integration, smoke, regression, load |
| `sre-agent` | Phase 5 | CI/CD, runbook, SLOs, incident response |
| `doc-keeper` | cross-cutting | Sync docs after behavior changes |
| `clarification-triager` | cross-cutting | Resolve STOP triggers |

Same files in `.claude/agents/` (Claude Code subagent format with
frontmatter — opt-in, bypasses plugin skills).

---

## Repo layout

```
your-repo/
├── project.yaml                       # metadata (engine reads this)
├── automation/
│   ├── rules.json                     # DoD rules (5 phases, sub-tracks)
│   ├── state.json                     # AUTO-GENERATED snapshot (gitignored)
│   ├── tasks/<id>.yaml                # Phase 3 task definitions
│   ├── clarifications/*.md            # STOP triggers; user resolves
│   ├── signoffs/<gate-id>.yaml        # gate approvals
│   ├── reviews/<task-id>-<ts>.md      # code-reviewer findings
│   ├── agent-runs.jsonl               # AUTO-GENERATED activity log (gitignored)
│   ├── notifications.log              # AUTO-GENERATED (gitignored)
│   ├── .verifications.json            # AUTO-GENERATED verify audit (gitignored)
│   └── .replan.json                   # AUTO-GENERATED dirty markers (gitignored)
├── 01-Planning/                       # Phase 1 templates + filled artifacts
├── 02-Design/                         # Phase 2 (architecture + UI/UX)
├── 03-Development/                    # Phase 3 standards + AI configs
├── 04-Testing-Deploy/                 # Phase 4 + 5 templates + filled artifacts
├── agents/                            # 11 role specs (English)
├── .claude/
│   ├── agents/                        # Claude Code subagent format
│   ├── commands/sdlc-*.md             # slash commands
│   └── skills/sdlc/SKILL.md           # auto-trigger skill
├── ai-tools/<tool>/<file>             # 8 AI tool configs (auto-generated)
├── .cursor/rules/sdlc.mdc             # Cursor rules
├── .github/
│   ├── workflows/ci.yml               # selected CI template
│   ├── copilot-instructions.md        # Copilot
│   └── prompts/sdlc-*.prompt.md       # Copilot Chat prompts
├── dashboard/
│   ├── index.html                     # ops-console UI
│   └── state.json                     # mirror of automation/state.json
└── CLAUDE.md / .cursorrules / AGENTS.md / ...    # 8 root-level configs
```

State flow: AI agent writes file → engine scans → `state.json` updated →
dashboard refreshes → dispatcher decides → next agent.

---

## Advanced

### Dashboard

A compact ops-console (single viewport, no scroll). Auto-fetches
`dashboard/state.json` every 3 seconds.

- **Top header** — live status dot, project meta, overall %.
- **Alert banners** — STOP triggers, gates, replan-dirty, unverified drafts
  (each with a `[Copy path]` button).
- **"You are here" card** — current phase + active item + paste-ready
  `/sdlc-next` prompt. Phase 3 tasks show stage pills
  `[pending][write-tests][write-code][review][done]`.
- **Phase tracker** — 5 phase rows with sub-track columns.
- **Side panel** — Resume card, project info, activity timeline, quick links.

```bash
sdlc scan --watch                # re-scan every 3s; fires desktop notifications
sdlc dashboard --port 8765       # http://localhost:8765/dashboard/
```

The state file is rewritten **only when the engine runs** (`sdlc dashboard`
itself just serves static files). Agents call `sdlc scan` after every
artifact write to a phase-owned path so the UI stays live without a watch
loop.

### Project memory bundle

Every `sdlc scan` regenerates `automation/.context-bundle.md` (mirrored to
`dashboard/.context-bundle.md`) with:

- Project name + stack + current phase
- Top 3 PRD goals
- Last 8 ADRs
- Active DoD item, recent agent runs, open clarifications, pending gates
- Anything in `automation/CONTEXT-PINS.md`

Sub-agents read this bundle (or a role-tailored slice) instead of re-reading
PRD + stories + architecture every invocation. Cap is 12 KB; sections truncate
before the cap.

### `automation/CONTEXT-PINS.md` — your override file

For facts the engine cannot infer (verbal decisions, gotchas, deprecations
in flight):

```markdown
# Context Pins
## Tech decisions
- Auth: VNPay (NOT Stripe — switched 2026-04-15 due to VN customer base)

## Gotchas
- Postgres users.email — always wrap in LOWER(); legacy rows mixed-case.
```

Plain markdown — no DB, no service. Edit, save, run `sdlc scan`. The engine
concatenates its contents under `## User pins` in the bundle.

### Desktop notifications

In `--watch` mode, every newly appearing clarification or pending gate fires:

- macOS — `osascript display notification` (sound on gate)
- Linux — `notify-send -u critical|normal --app-name=SDLC`
- elsewhere — silent fallback (log line in `automation/notifications.log`)

Transition-only: items that stay pending across many scans only fire once.

### GitHub integration

```bash
sdlc gh-issue --clarification automation/clarifications/001-foo.md
# → creates a GitHub Issue, writes issue_url back into the file (idempotent)

sdlc gh-issue --gate phase5-signoff
# → creates "Gate pending: <label>" issue

sdlc gh-pr [--ready] [--base main]
# → opens a Draft PR (or reuses existing)
```

All three exit 0 when `gh` is missing/unauthenticated. The engine reads
`issue_url` back into `state.json` and the dashboard shows ↗ icons.

### TDD coverage rule

The built-in `tdd-coverage` rule (Phase 3 Setup sub-track) enforces strict
1:1 source-to-test pairing across all tiers. Paths in `legacy_code_globs`
are excluded — retrofit projects don't get punished for old code.

---

## Contributing

```bash
git clone https://github.com/vuonglq01685/SDLC.git
cd SDLC
python3 -m pip install --user -e .
python3 -m pip install --user -r automation/requirements-dev.txt

python3 -m pytest automation/tests/ -v
bash scripts/tests/test_setup.sh
bash scripts/tests/test_agent_log.sh
bash scripts/tests/test_notify.sh
bash scripts/tests/test_gh_wrappers.sh

bash scripts/sync-scaffold.sh     # refresh package scaffold from repo content
python3 -m build                  # build wheel + sdist
```

The framework eats its own dog food: it has its own `project.yaml`, runs its
own engine on itself, and the `owners-defined` rule is intentionally red here
so you can see it work in the dashboard.

---

## License & links

MIT.

- [PyPI](https://pypi.org/project/sdlc-framework/)
- [GitHub](https://github.com/vuonglq01685/SDLC)
- [C4 model](https://c4model.com)
- [OWASP ASVS](https://owasp.org/www-project-application-security-verification-standard/)
- [Conventional Commits](https://www.conventionalcommits.org)
