Metadata-Version: 2.4
Name: sdlckit
Version: 0.8.6
Summary: SDLCKit — AI-governed SDLC lifecycle engine with SAGE loop
Author: SDLCKit Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/atishio/sdlckit
Project-URL: Documentation, https://github.com/atishio/sdlckit#readme
Project-URL: Repository, https://github.com/atishio/sdlckit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: ==3.11.*
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: jsonschema<5.0,>=4.0
Requires-Dist: referencing>=0.30.0
Requires-Dist: python-frontmatter>=1.0
Requires-Dist: filelock>=3.0
Requires-Dist: mcp<2,>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# SDLCKit

**Governed AI quality loops for every SDLC phase.**

![Beta](https://img.shields.io/badge/status-beta-blue)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green)

SDLCKit wraps each phase of the software development lifecycle in a **SAGE loop** — a governed cycle where humans declare intent, AI produces artifacts, and independent scorers review against quality dimensions using min-score confidence. The result: measurable confidence in AI-generated artifacts before they reach production.

SDLCKit is a governance layer, not an SDLC. You keep your existing process and add SDLCKit on top.

---

## Why Governance?

AI agents can produce code, specs, and designs — but without governance, there is no measurable quality signal. SDLCKit provides that signal through four properties:

| Property | What It Means |
|----------|---------------|
| **Independent Scoring** | Scorer agent is sandboxed (read-only tools). Cannot collude with producer. |
| **Dimensional Confidence** | Not pass/fail. N dimensions scored independently 0-100. Overall confidence = min(all scores) — weakest dimension determines the outcome. |
| **Bounded Fix Loops** | Max N automated iterations. Oscillation detection stops thrashing. |
| **Human Gates** | Two-pass: (1) deterministic structural check, (2) human quality review with scorecard. |

---

## The SAGE Loop

Every phase — refine, architect, build, review — runs the same governed cycle:

```
  SCOPE                           SAGE LOOP
  +------------------+            +------------+
  | User input       |       +--->|  ANALYZE   |
  | Discovery output |       |    |  Frame goal + constraints   |
  | Feedback signals |------>+    +-----+------+
  | Prior state      |       |          |
  +------------------+       |          v
                             |    +------------+
                             |    | GENERATE   |
                             |    |  AI produces artifacts      |
                             |    +-----+------+
                             |          |
                             |          v
                             |    +------------+
                             |    | EVALUATE   |
                             |    |  Independent scorer scores  |
                             |    |  N dimensions (min-gate)    |
                             |    +-----+------+
                             |          |
                             |     confidence < threshold?
                             |          |
                             |     YES: Fix Loop (target weakest dim)
                             |          |
                             |     NO:  Human Gate
                             |          |
                             |    [Approve] -> advance
                             |    [Revise]  -> feedback
                             +----[Pause]   -> save state
```

---

## Quick Start

### Prerequisites

- Python 3.11+
- An AI coding assistant: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), GitHub Copilot CLI, Cursor, or Windsurf

### Install

```bash
pip install sdlckit
```

### Initialize a Project

```bash
sdlckit init
```

Scaffolds your project with `sdlc.yaml`, skills, templates, schemas, and the `/sdlc` slash command.

### Customize

After init, update these for your team:

- **`sdlc.yaml`** — lifecycle phases, scoring dimensions, thresholds, extension config
- **`sdlckit/memory/conventions/`** — layered convention files loaded in sorted order:
  - `00-architecture.md` — diagram standards, contract registry format, component identity (built-in)
  - `01-security-architecture.md` — trust zones, data classification (built-in)
  - `10-your-team.md`, `11-your-domain.md` — add your own with `10+` prefix

### Run a Phase

```bash
# In your AI coding assistant:
/sdlc refine "user onboarding feature"
```

The SAGE engine produces `REFINE.md`, scores it across dimensions (min-gate confidence), runs fix loops if below threshold, then presents the human gate.

### Check Status

```bash
/sdlc status
```

---

## Commands

**Slash commands** (in your AI coding assistant):

| Command | What It Does |
|---------|-------------|
| `/sdlc <phase> "input"` | Run a phase with direct input |
| `/sdlc <phase>` | Run a phase (inputs auto-resolved from upstream) |
| `/sdlc <phase> amend "feedback"` | Re-enter a completed phase with feedback |
| `/sdlc status` | Lifecycle dashboard |
| `/sdlc reconcile` | Re-run stale phases after an amendment |
| `/sdlc signal list\|show\|dismiss\|inject` | Manage feedback signals |

**CLI commands:**

| Command | What It Does |
|---------|-------------|
| `sdlckit init [--type component\|initiative]` | Scaffold a project |
| `sdlckit assign <path>` | Import an assignment into a component repo |
| `sdlckit observe <title> --components <names>` | Record an operational observation |
| `sdlckit archive <name>` | Pre-merge cleanup (manifests, state) |
| `sdlckit update [--migrate-config] [--dry-run]` | Update framework files; optionally migrate config |
| `sdlckit claim list` | Show active phase claims (shared store) |
| `sdlckit claim break <phase>` | Force-release a phase claim |
| `sdlckit --version` | Show installed version |

---

## Project Layout

After `sdlckit init`, your project has a single MemoryBus-managed state root:

```
my-project/
├── sdlc.yaml                          # Lifecycle config
├── sdlckit/memory/                    # Persistent state (git-committed)
│   ├── conventions/                   #   Team conventions (customizable)
│   ├── contracts/                     #   Contract registry + spec files
│   │   └── registry.yaml             #   Components, contracts, interfaces
│   ├── knowledge/                     #   Patterns and anti-patterns (YAML)
│   ├── components/                    #   Component profiles (YAML)
│   ├── observations/                  #   Operational observations
│   └── work/                          #   Per-initiative work artifacts
├── sdlckit/                           # State root (MemoryBus-managed)
│   ├── runtime/                       #   Runtime state (gitignored)
│   │   ├── phase/{name}/state.yaml    #     Phase state (via PhaseManager)
│   │   ├── digest/{phase}.yaml        #     Materialized digests
│   │   ├── gate/{phase}/              #     Gate verdict audit trail
│   │   └── extensions/{name}/         #     Extension state
│   └── memory/                        #   Persistent state (git-committed)
│       ├── conventions/               #     Team conventions
│       ├── contracts/                 #     Contract registry
│       ├── knowledge/                 #     Patterns, anti-patterns
│       └── components/                #     Component profiles
└── .claude/                           # AI harness files
    ├── skills/sdlc-*                  #   Phase and CLI skill wrappers
    ├── commands/sdlc.md               #   /sdlc slash command
    └── sdlckit/                       #   SAGE engine core + templates
```

### Shared Store (Optional)

For multi-user coordination, SDLCKit can use PostgreSQL as a shared backend. Set `$SDLCKIT_DB_URL` or add `state.shared.connection` to `sdlc.yaml`. Phase state and knowledge are stored in PostgreSQL with the local filesystem as a write-through cache. Phase claims prevent concurrent modification by different users. Install the optional dependency: `pip install sdlckit[shared]`.

See [State Management](docs/architecture/state-management.md) for details.

---

## Two Modes

**Component mode** (`sdlc.yaml`) — single project, linear phase sequence: refine -> architect -> build -> review.

**Initiative mode** (`sdlc-initiative.yaml`) — multi-component, multi-repo projects. Discovery and Delivery stages with per-component SAGE loops, stage reviews, knowledge extraction, and assignment handoffs.

---

## Extending with Extensions

SDLCKit supports three extension roles:

**Phase Override** — replace the engine for any phase. Your extension provides the scanning/design logic; the built-in skill assembles output. Declare `provides[]` in your `sdlcext.yaml`.

**Extension** — augment a built-in skill with pre/post hooks at any SAGE step boundary. Declare `hooks[]` with the naming pattern `<pre|post>_<step>__<action>`. Blocking hooks gate the step; non-blocking hooks run alongside.

**Connector** — bridge SDLCKit to external systems (CI/CD, issue trackers, chat). Connectors subscribe to lifecycle events (`gate_passed`, `gate_failed`, etc.) and fire non-blocking. Declare `subscribes_to[]`.

### Install an Extension

```bash
sdlckit install ./extensions/my-extension
```

This reads the extension manifest, validates it, and binds it to `sdlc.yaml` automatically.

### Extension Manifest

Extensions are skill bundles — markdown skills, agent files, and templates. No compiled code. See `engine/data/schemas/sdlcext.schema.yaml` for the full manifest schema (v3.0).

### Extension Status

```bash
sdlckit status extensions
```

Shows all loaded extensions, their roles, bound phases, hooks, and subscriptions.

See `docs/developer-guide.md` for the full extension development guide.

---

## Documentation

- **[Consumer Guide](docs/consumer-guide.md)** — installation, configuration, daily usage
- **[Contributor Guide](docs/contributor-guide.md)** — engine internals, testing
- **[Developer Guide](docs/developer-guide.md)** — building extensions, skills, agents, schemas
- **[AGENTS.md](AGENTS.md)** — AI assistant rules (MUST/SHOULD for Claude, Copilot, Cursor, etc.)
- **[Architecture Reference](docs/architecture/)** — SAGE engine, state management, extension model, agent model
- **[Reverse Architect Quickstart](docs/quickstart-reverse-architect.md)** — scan existing codebases

---

## License

Apache License 2.0
