rpi-workflow

Original source / Raw SKILL.md

---
name: rpi-workflow
description: >
  Research -> Plan -> Implement -> Complete workflow for development tasks.
  Use when starting any new feature, bug fix, or implementation work.
  No code without research. No implementation without plan. No "done" without verification.
compatibility: "Git repository with pre-commit hooks configured"
metadata:
  scope: generic
  version: 4.2.0
  triggers: "start task, implement feature, new development, how to approach, task workflow"
  related-skills: "python-project-bootstrap, python-engineer, python-testing"
  pre-gates: "test -d .git && test -f .pre-commit-config.yaml"
  post-gates: "test -f data/.session/*/plan.yaml"
---

# RPI Workflow

Every task follows **Research -> Plan -> Implement -> Complete**. No exceptions.

This prevents:
- Building the wrong thing
- Reinventing existing solutions
- Accumulating technical debt
- Shipping untestable code
- Shipping insecure code
- Incomplete audit trail

---

## Turn Anchor (Required Every Response)

When working on any CR, include this anchor at the START of every response:

```yaml
# --- SESSION ANCHOR ---
cr_id: CR-YYYY-MM-DD-NNN    # Active Change Request
plan_id: PLAN-xxx | NONE    # Approved plan ID (NONE if not yet approved)
rpi_phase: R | P | I | C    # Current RPI workflow phase
epic_phase: P1 | P2 | ...   # Current roadmap phase (if multi-phase epic)
epic_progress: 1/5          # Progress through epic phases
task: "<description>"       # What you're doing NOW
gate: "<gate_id>"           # Current/next gate to pass
# --- END ANCHOR ---
```

### Why Two Phase Indicators?

| Field | Meaning | Example |
|-------|---------|---------|
| `rpi_phase` | Where in RPI workflow | `I` (implementing) |
| `epic_phase` | Which roadmap phase | `P1` (Foundation) |
| `epic_progress` | Overall epic progress | `1/5` (1 of 5 phases done) |

**Anti-Pattern (Completion Theatre):**
```yaml
rpi_phase: C              # "Complete" phase
epic_phase: P1            # But only Phase 1 of 5!
epic_progress: 1/5        # 80% of epic still pending!
# ❌ WRONG: Marking CR "complete" here
```

**Correct:**
```yaml
rpi_phase: C              # Completed P1 implementation
epic_phase: P2            # Moving to Phase 2
epic_progress: 1/5        # P1 done, P2-P5 pending
# ✅ RIGHT: Continue to next phase, don't close CR
```

---

## Quick Start

```bash
# 1. Initialize session (tooling creates folder structure)
ssot rpi init --cr CR-XXX-001

# 2. Research phase
# - Analyze requirements and existing patterns
# - Document findings in research.yaml (LLM reasoning)

# 3. Plan phase (tooling + LLM)
ssot rpi plan --classification G --cr CR-XXX-001 --session $SESSION
# - Tooling pre-fills: constraints from SSOT
# - LLM fills: outputs, acceptance criteria (reasoning)
ssot rpi validate --session $SESSION
ssot rpi project --session $SESSION
# - Present projection, wait for human approval (P6 gate)

# 4. Implement phase
# - TDD: Write test first
# - Implement to make tests pass
# - Validation commands are in the generated template
```

---

## The Four Phases

```
RESEARCH (R)
"What do I need to know before I can plan?"
    |
    v
PLAN (P)
"What exactly will I produce and how will I validate it?"
    |
    v
IMPLEMENT (I)
"Execute the plan, validate the output"
    |
    v
COMPLETE (C)
"Is this production-ready?"
```

**For detailed phase guidance:** See [references/phases.md](references/phases.md)

---

## Methodology Sources

This workflow is not invented. It derives from proven methodologies with citations.

**Full reference:** See [references/methodology-database.md](references/methodology-database.md)

### Gate-to-Methodology Mapping

| Phase | Gate | Methodology |
|-------|------|-------------|
| R | R1, R2 | Teresa Torres (Continuous Discovery) |
| P | P0 | ITIL 4 (Change Enablement) |
| P | P4 | CMMI (Configuration Management) |
| P | P6 | SOC-2 (Human Approval) |
| I | I1 | Kent Beck (TDD) |
| I | I2.1 | Kent Beck (Micro-commits) |
| C | C1-C3 | ISO 27001, SOC-2 |
| C | C4 | CMMI (Traceability) |

### Atomic Task Principles

Tasks decompose following:

- **Elephant Carpaccio** (Cockburn): 15-30 min tasks, max 1-3 files
- **Micro-commits** (Beck): One kind of change, validate before next
- **GTD Next Actions** (Allen): Concrete file paths, reduce cognitive load
- **Trunk-Based Dev** (Hammant): Commit little and often

---

## Standards Loading via Tooling

**Nextura Philosophy:** Tooling does toiling, LLM does reasoning.

**DO NOT** manually read SSOT standards. Use `ssot rpi plan` to generate templates with constraints pre-filled.

```bash
# Generate plan template with SSOT constraints pre-filled
ssot rpi plan --classification G --cr CR-XXX-001 --session $SESSION

# The template will contain:
# - coverage_threshold: 80 (from STD-TEST-COVERAGE-001)
# - function_max_loc: 20 (from STD-CODE-SIZE-001)
# - required_artifacts: [REQ, HLD, TC] (from STD-CHANGE-CLASSIFICATION-001)
# - SSOT citations for audit trail

# LLM fills: summary, outputs, acceptance_criteria (REASONING)
```

**Classification determines contract.** Before generating template, determine classification (S/M/G/J/C) based on risk assessment. This determines which constraints the tooling will inject.

**Key Principle:** You never invent threshold values. Tooling reads SSOT and pre-fills them. You fill the reasoning fields (what will be built, why, how to validate).

---

## Session Persistence (Critical)

The **plan** must survive context limits. Write to disk immediately.

**Session structure:**
```
data/.session/rpi-{date}-{id}/
├── research.yaml        # R phase output
├── plan.yaml            # P phase output (machine-readable)
├── plan-projection.md   # P phase output (human-readable)
├── progress.yaml        # I phase tracking
├── manifest.yaml        # Lists artifacts to promote (C phase)
├── requirements/        # V-Model: REQ-*.yaml (create HERE, not in SSOT)
├── design/              # V-Model: HLD-*.yaml, LLD-*.yaml
├── test_specs/          # V-Model: TC-*.yaml
└── evidence/            # C phase: test-results.xml, coverage.xml, etc.
```

**CRITICAL:** Create V-Model artifacts (REQ, HLD, LLD, TC) in SESSION folder.
They get promoted to permanent SSOT via `ssot session promote` after all gates pass.

**For session file schemas:** See [references/session-format.md](references/session-format.md)

---

## Atomic Task Model

Plans decompose into atomic tasks for cognitive load management.

### Why Atomic?

Large tasks cause:

- LLM context overflow → policies forgotten → shortcuts → debt
- 80-file commits with violations discovered at C1
- Compaction loses contract → flying blind

### Task Structure

```yaml
atomic_tasks:
  - id: T0
    name: "Implement core module"
    outputs:
      - path: src/module.py
      - path: tests/test_module.py
    policies:              # Residual only (Layer 3)
      file_loc: 500
      coverage: 80
    validation:
      - "ruff check src/module.py"
      - "pytest tests/test_module.py -v"
```

### Context Window Budget

Treat context as finite resource:

```text
Total Context = 100%
├── Contract (10%)     # Task from plan
├── Policies (10%)     # Residual constraints
├── Available (70%)    # Actual work
└── Validation (10%)   # Output + fixes
```

If task doesn't fit → decompose further.

### Task Lifecycle

```bash
# Start task - displays contract
ssot task start T0 --session $SESSION

# Work on task (1-3 files max)
# ...

# Complete task - validates and suggests commit
ssot task complete --session $SESSION --task T0
```

Each task completion → commit → fresh context → re-read next contract.

---

## Stop Gates

See [references/stop-gates.md](references/stop-gates.md) for detailed definitions.

### Key Gates

| Gate | When | Check |
|------|------|-------|
| R1: OSS Search | Before planning | Library search complete? |
| R2: Codebase Context | Before planning | Current patterns understood? |
| **P0: Classification** | **Before outputs** | **Classification determined (S/M/G/J/C)?** |
| P1: Outputs Defined | Before coding | File paths listed? |
| P2: Validation Defined | Before coding | Commands to prove correctness? |
| P4: Plan Persisted | Before coding | plan.yaml written to disk? |
| **P5: Plan Validated** | **Before coding (M+)** | **`ssot validate-plan` passes?** |
| **P6: Human Approved** | **BLOCKING** | **Human explicitly approved plan projection?** |
| I0: Infrastructure Ready | Before TDD | Test directory exists? |
| I1: Test First | Before implementation | Failing test exists? |
| I2: Validation Passes | Before commit | All commands pass? |
| **I2.1: Per-File Shift-Left** | **After each file** | **`pre-commit run --files {file}`?** |
| I3: Drift Check | Before completion | Plan matches progress? |
| **C1: Pre-commit** | **Before promotion** | **All hooks pass (incl. security)?** |
| **C2: Coverage** | **Before promotion** | **Meets classification threshold?** |
| **C3: Security** | **Before promotion** | **No high/critical findings?** |
| **C4: Traceability** | **Before promotion** | **`ssot validate-plan` + bidirectional?** |
| **C5: Drift** | **Before promotion** | **Plan outputs match actual?** |
| **C6: Promoted** | **End of task** | **Session promoted and archived?** |

---

## Plan Presentation Pipeline

**DO NOT manually write markdown for human review. DO NOT proceed without approval.**

```bash
# 1. Generate plan template (tooling fills constraints)
ssot rpi plan --classification G --cr CR-XXX-001 --session $SESSION

# 2. Fill reasoning fields (LLM work)
#    - summary: What will be built?
#    - outputs: Exact file paths
#    - acceptance_criteria: How to verify success

# 3. Validate session
ssot rpi validate --session $SESSION

# 4. Generate projection (human-readable)
ssot rpi project --session $SESSION

# 5. Present to human and ASK FOR APPROVAL
cat $SESSION/plan-projection.md
echo "Do you approve this plan? I will wait for your confirmation before implementing."

# 6. STOP - WAIT FOR EXPLICIT HUMAN APPROVAL (P6 gate)
#    ❌ Do NOT proceed automatically
#    ❌ Do NOT assume approval
#    ✅ Wait for explicit "approved", "proceed", "go ahead"
```

**CRITICAL:** The agent MUST wait for explicit human approval before proceeding to implementation. This is a compliance requirement (SOC-2, enterprise governance).

---

## Implementation Flow

```
1. Write failing test -> Run pytest -> See RED
2. Write minimal code -> Run pytest -> See GREEN
3. Refactor -> Tests still GREEN
4. **SHIFT-LEFT: Run pre-commit on modified files (I2.1)**
   pre-commit run --files {modified_files}
5. Update progress.yaml
6. Run validation commands (from standards)
7. Commit
```

### Shift-Left Validation (I2.1 Gate)

**After each file is written/modified, run pre-commit IMMEDIATELY:**

```bash
# After writing src/ssot_toolkit/new_module.py
pre-commit run --files src/ssot_toolkit/new_module.py

# Common failures to fix BEFORE moving to next file:
# - ruff: lint violations
# - mypy: type errors
# - file-size-limit: file > 500 LOC (split it)
# - bandit: security issues
```

**Why?** Waiting until C1 to run pre-commit means you find violations AFTER writing many files. Shift-left catches issues early when they're cheap to fix.

---

## Complete Phase (C Gates)

**After implementation, prove the work is production-ready.**

```bash
# 1. Run all completion gates
ssot session promote --session $SESSION --verify --dry-run

# 2. If gates fail, fix and re-run
# Common failures:
#   C2: Run more tests or increase coverage
#   C3: Fix security findings from bandit/safety
#   C5: Update plan.yaml outputs or create missing files

# 3. Generate evidence bundle
ssot session promote --session $SESSION --domain platform --repo nextura

# 4. Review evidence
cat $SESSION/evidence/completion-report.md
```

### Evidence Bundle

The evidence bundle is what an **auditor reviews** to verify work was done correctly:

```
$SESSION/evidence/
├── test-results.xml      # JUnit XML proving tests passed
├── coverage.xml          # Cobertura XML proving coverage met
├── security.json         # Bandit output proving no issues
└── completion-report.md  # Human-readable summary (from projection)
```

**Generate with projection:**
```bash
ssot project rpi-complete --session $SESSION --output $SESSION/evidence
```

### Gate Commands Reference

| Gate | Command | Threshold Source |
|------|---------|------------------|
| C1 | `pre-commit run --all-files` | .pre-commit-config.yaml |
| C2 | `pytest --cov=src --cov-fail-under=N` | STD-TEST-COVERAGE-001 (by classification) |
| C3 | `bandit -r src/ -ll` + `safety check` | STD-SECURITY-001 |
| C4 | `ssot validate-plan` + `ssot check-bidirectional` | - |
| C5 | plan.yaml outputs vs actual files | - |

---

## Quick Reference

```
RESEARCH CHECKLIST
[ ] Checked approved libraries (STD-PYTHON-LIBS-001)
[ ] Searched PyPI/GitHub
[ ] Read existing codebase patterns
[ ] Identified interfaces to implement
[ ] Documented in research.yaml

PLAN CHECKLIST
[ ] Loaded STD-CHANGE-CLASSIFICATION-001 (classification contract)
[ ] Determined classification (S/M/G/J/C) per risk matrix
[ ] Loaded other standards from SSOT
[ ] **For M+: Defined USER SUCCESS CRITERIA (STD-SUCCESS-CRITERIA-001)**
[ ] Listed exact file paths (outputs)
[ ] Defined validation commands
[ ] Wrote acceptance criteria
[ ] Listed blocked actions (from standards)
[ ] Wrote plan.yaml to disk (with classification and user_success_criteria)
[ ] Generated plan-projection.md
[ ] For M+: Ran ssot validate-plan (P5 gate)
[ ] **PRESENTED TO HUMAN AND RECEIVED EXPLICIT APPROVAL (P6 gate)**

BASELINE COMPLIANCE (Implicit - ALL tasks)
[ ] Implementation will pass pre-commit hooks (ruff, mypy)
[ ] Security scan will be clean (bandit, safety)
[ ] Architecture principles followed (STD-ARCHITECTURE-001)
[ ] Standards and constraints respected (SSOT)

IMPLEMENT CHECKLIST
[ ] Infrastructure ready (I0 gate)
[ ] Test written first (TDD)
[ ] All validation passes
[ ] **Per-file shift-left: `pre-commit run --files {file}` after each file (I2.1)**
[ ] progress.yaml updated
[ ] Drift check passed (plan vs progress)
[ ] Committed with proper message

COMPLETE CHECKLIST
[ ] Pre-commit hooks pass (C1 - includes bandit, safety)
[ ] Coverage meets threshold (C2 - per STD-TEST-COVERAGE-001)
[ ] Security scan clean (C3 - per STD-SECURITY-001)
[ ] Traceability complete (C4 - validate-plan + bidirectional)
[ ] Drift check clean (C5 - plan outputs match actual)
[ ] **For G+: User accepted evidence (C_USC - STD-SUCCESS-CRITERIA-001)**
[ ] Session promoted (C6 - ssot session promote)
```

---

## Anti-Patterns

| If you're doing... | STOP. Do this instead... |
|--------------------|--------------------------|
| **Finishing Phase 1 and marking CR complete** | **Check epic_progress - complete ALL phases** |
| **Reading SSOT standards manually (cat)** | **Use `ssot rpi plan` - tooling reads SSOT** |
| **Inventing threshold values** | **Tooling pre-fills from SSOT, you fill reasoning** |
| **Planning without classification** | **Determine S/M/G/J/C first (P0 gate)** |
| **Defining success criteria yourself (M+)** | **Ask USER to define what success looks like** |
| **Skipping P5 validation (M+)** | **Run `ssot rpi validate` before implementing** |
| **Implementing without human approval** | **WAIT - present projection, ask for approval (P6 gate)** |
| Coding without research | Document research.yaml first |
| Implementing then testing | Write failing test first (TDD) |
| **Writing many files then checking compliance** | **Run `pre-commit run --files {file}` after EACH file** |
| Holding plan in context | Use `ssot rpi plan` to generate template |
| Manual plan presentation | Use `ssot rpi project` |
| Skipping validation | Use `ssot rpi validate` |
| git commit --no-verify | Fix hooks, don't bypass |
| **Calling task "done" without C gates** | **Run all C1-C6 gates first** |
| **Leaving session in .session/** | **Promote and archive (C6 gate)** |
| **Creating artifacts directly in SSOT** | **Create in session folder, then `ssot session promote`** |

### "LLM Does Toiling" Anti-Pattern (CRITICAL)

**Nextura Philosophy:** Tooling does toiling, LLM does reasoning.

**WRONG:** LLM reads standards and invents/extracts values

```bash
# LLM tries to read standards and extract values
cat data/enterprise/standards/STD-TEST-COVERAGE-001.yaml
# LLM invents 60% because it "sounds reasonable"
```

**RIGHT:** Tooling reads SSOT, LLM fills reasoning

```bash
# Tooling reads SSOT and pre-fills constraints
ssot rpi plan --classification G --cr CR-XXX-001 --session $SESSION

# Template shows:
# constraints:
#   coverage_threshold: 80  # STD-TEST-COVERAGE-001.thresholds.G
# LLM fills: summary, outputs, acceptance_criteria
```

**Detection:** If you're about to use `cat data/enterprise/standards/`, STOP. Use `ssot rpi plan` instead.

---

## Reference Files

- [references/phases.md](references/phases.md) - Detailed phase guidance
- [references/stop-gates.md](references/stop-gates.md) - Gate definitions
- [references/session-format.md](references/session-format.md) - Session file schemas
- [references/examples.md](references/examples.md) - Example task walkthrough
- [references/success-criteria.md](references/success-criteria.md) - User Success Criteria guide
- [references/governance-contracts.md](references/governance-contracts.md) - All standards and ADRs reference
- [references/methodology-database.md](references/methodology-database.md) - Canonical methodology sources
- [references/task-contract.md](references/task-contract.md) - Atomic task contract schema


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/phases.md

```markdown
# RPI Phases Detail

## Research Phase (R)

**Question:** "What do I need to know before I can plan?"

### What to Research

| Question | Where to Look | Output |
|----------|---------------|--------|
| Does OSS exist? | PyPI, GitHub, SSOT | Library recommendation |
| What patterns exist? | Existing codebase | Patterns to follow |
| What interfaces exist? | `core/ports/` | Interface to implement |
| What constraints apply? | SSOT standards | Blockers list |

### Research Checklist

```
[ ] Load STD-PYTHON-LIBS-001 - approved libraries
[ ] Search PyPI for existing library
[ ] Search GitHub for similar projects
[ ] Read existing codebase patterns
[ ] Check for existing interfaces in core/ports/
[ ] Identify constraints from standards
[ ] Document in research.yaml
```

### Research Output (research.yaml)

```yaml
research:
  task_id: "TASK-XXX"

  oss_search:
    searched:
      - pypi: "search terms"
        results: "what was found"
    selected: "library-name"
    rationale: "why this library"
    alternatives_rejected:
      - name: "other-lib"
        reason: "why not"

  codebase_context:
    relevant_files:
      - path: "path/to/file"
        purpose: "what it does"
        patterns: "patterns to follow"
    existing_patterns:
      - "Pattern: how it's implemented"

  constraints:
    from_standards:
      - STD-PYTHON-LIBS-001: "approved libraries only"
      - STD-CODE-SIZE-001: "size limits"
```

---

## Plan Phase (P)

**Question:** "What exactly will I produce and how will I validate it?"

### What a Good Plan Contains

1. **Exact file paths** - No ambiguity
2. **Interface contracts** - What each file must satisfy
3. **Validation commands** - How to prove correctness
4. **Acceptance criteria** - When is it DONE
5. **Blocked actions** - From SSOT standards
6. **Out of scope** - What we're NOT doing

### Plan Checklist

```
[ ] Task ID and title defined
[ ] Summary written (prose)
[ ] All output files listed with paths
[ ] Each output has type and purpose
[ ] Validation commands defined
[ ] Acceptance criteria specific and measurable
[ ] Blocked actions extracted from standards
[ ] complies_with references SSOT standards
[ ] plan.yaml written to disk
[ ] Schema validation passed
[ ] Projection generated
```

### Plan Output (plan.yaml)

```yaml
task_id: "TASK-XXX"
task_title: "Title"
status: planning

summary: |
  What will be built in prose form.

complies_with:
  - STD-PYTHON-LIBS-001
  - STD-CODE-SIZE-001
  - STD-ARCHITECTURE-001

outputs:
  - path: "src/adapters/client.py"
    type: new_file
    purpose: "API client adapter"
    interface: "ClientPort"

  - path: "tests/unit/test_client.py"
    type: new_file
    purpose: "Unit tests"
    coverage: ">=80%"

validation:
  commands:
    - "pytest tests/unit/test_client.py -v"
    - "mypy src/adapters/client.py --strict"

acceptance_criteria:
  - "Implements ClientPort interface"
  - "Uses httpx for HTTP calls"
  - "All config from YAML"

blocked_actions:
  - "DO NOT hardcode URLs"
  - "DO NOT use requests (use httpx)"

out_of_scope:
  - "Retry logic (future task)"
```

---

## Implement Phase (I)

**Question:** "Execute the plan, validate the output"

### Implementation Flow

```
1. Verify infrastructure (I0 gate)
       |
       v
2. Write failing test (TDD RED)
       |
       v
3. Implement minimal code (TDD GREEN)
       |
       v
4. Refactor (tests still pass)
       |
       v
5. Update progress.yaml
       |
       v
6. Run validation commands
       |
       v
7. Drift check (plan vs progress)
       |
       v
8. Commit
```

### Implementation Checklist

```
[ ] Infrastructure ready (test dirs, config)
[ ] Test written first (see RED)
[ ] Implementation makes test pass (GREEN)
[ ] Validation commands pass
[ ] progress.yaml updated after each file
[ ] Drift check passed
[ ] Committed with proper message
```

### Progress Tracking (progress.yaml)

```yaml
progress:
  current_step: 3
  total_steps: 5

  steps:
    1: { desc: "Write failing test", status: done }
    2: { desc: "Implement client", status: done }
    3: { desc: "Add config loading", status: in_progress }

  files_created:
    - path: "src/adapters/client.py"
      lines: 87
      status: created
      created_at: "2026-01-06T10:15:00Z"

  validation_results:
    pytest: passed
    mypy: pending

  drift_check:
    planned_outputs: 4
    actual_outputs: 2
    missing: ["config/client.yaml"]
    unplanned: []
    status: in_progress
```

---

## Complete Phase (C)

**Question:** "Is this production-ready?"

### Why Complete Phase Exists

The Implement phase produces working code, but working code isn't the same as production-ready code. The Complete phase verifies:

1. **Security** - No vulnerabilities introduced
2. **Coverage** - Tests meet classification threshold
3. **Traceability** - Audit trail is complete
4. **Drift** - Plan matches actual outputs
5. **Promotion** - Session properly archived

### Complete Phase Gates (C1-C6)

| Gate | Check | Standard |
|------|-------|----------|
| C1 | Pre-commit hooks pass | - |
| C2 | Coverage threshold | STD-TEST-COVERAGE-001 |
| C3 | Security scan clean | STD-SECURITY-001 |
| C4 | Traceability complete | STD-CHANGE-CLASSIFICATION-001 |
| C5 | Drift check clean | - |
| C6 | Session promoted | - |

### Complete Checklist

```
[ ] All pre-commit hooks pass (including bandit, safety)
[ ] Coverage meets threshold for classification
[ ] No high/critical security findings
[ ] ssot validate-plan passes
[ ] ssot check-bidirectional passes
[ ] All plan outputs exist as files
[ ] Session promoted and archived
```

### Running Complete Gates

```bash
# C1: Pre-commit (includes security)
pre-commit run --all-files

# C2: Coverage (adjust threshold per classification)
pytest tests/ --cov=src --cov-fail-under=80

# C3: Security scan
bandit -r src/ -ll
safety check

# C4: Traceability
ssot validate-plan -p $SESSION/plan.yaml
ssot check-bidirectional

# C5: Drift check
# Compare plan.yaml outputs with actual files

# C6: Promote session
ssot session promote --session $SESSION
```

---

## Phase Transitions

### R -> P Transition

**Gate:** Research complete?

```
Research phase MUST produce:
- [ ] OSS search documented
- [ ] Library selected (or custom code justified)
- [ ] Codebase patterns identified
- [ ] Constraints documented
- [ ] research.yaml written to disk
```

### P -> I Transition

**Gate:** Plan approved?

```
Plan phase MUST produce:
- [ ] plan.yaml written to disk
- [ ] Schema validation passed
- [ ] Projection generated
- [ ] Human approved (if checkpoint required)
- [ ] Classification determined (P0 gate)
- [ ] V-Model artifacts created (P5 gate for M+)
```

### I -> C Transition

**Gate:** Implementation complete?

```
Implement phase MUST achieve:
- [ ] All planned outputs created
- [ ] All validation commands pass
- [ ] Drift check clean
- [ ] progress.yaml shows complete
- [ ] All commits made
```

### C -> Done Transition

**Gate:** All C gates pass?

```
Complete phase MUST verify:
- [ ] C1: Pre-commit hooks pass
- [ ] C2: Coverage meets threshold
- [ ] C3: Security scan clean
- [ ] C4: Traceability complete
- [ ] C5: Drift check clean
- [ ] C6: Session promoted
```

```

### references/methodology-database.md

```markdown
# Methodology Database

Canonical sources for Nextura governance patterns. Skills know WHY (this database), SSOT defines WHAT (policy values).

**Principle:** Don't invent patterns. Derive from proven methodologies with citations.

---

## Change Management

### ITIL 4 - Change Enablement

**Source:** ITIL 4 Foundation, Axelos

**Informs:**
- P0 gate: Classification (Standard/Normal/Emergency)
- P6 gate: CAB approval pattern
- C gates: Post-implementation review

### CMMI - Configuration Management

**Source:** CMMI for Development v2.0

**Informs:**
- Session folder structure
- Evidence bundle requirements
- Traceability matrix (C4 gate)

---

## Software Engineering

### Kent Beck - Test-Driven Development

**Source:** Book: Test Driven Development by Example

**Informs:**
- I1 gate: Test first
- Red-Green-Refactor cycle

### Kent Beck - Micro-commits / Tidy First

**Source:** SE Radio 615: Kent Beck on Tidy First

**Informs:**
- One kind of change per commit
- Validate before proceeding to next task
- "Couldn't possibly cause problems"

### Robert Martin - Clean Architecture

**Source:** Book: Clean Architecture

**Informs:**
- Core isolation (no external imports)
- Dependency inversion
- STD-ARCHITECTURE-001

### John Ousterhout - Deep Modules

**Source:** Book: A Philosophy of Software Design

**Informs:**
- 500 LOC file limit (cognitive load)
- 50 LOC function limit
- STD-CODE-SIZE-001

### Martin Fowler - Refactoring

**Source:** Book: Refactoring (2nd Edition)

**Informs:**
- Code smell detection
- Safe transformation patterns

---

## Atomic Task Decomposition

### Alistair Cockburn - Elephant Carpaccio

**Source:** https://medium.com/@internationalagilefederation/the-elephant-carpaccio-a052449a7ad0

**Informs:**
- Nano-incremental development
- 15-30 min tasks
- Max 1-3 files per task

### Paul Hammant - Trunk-Based Development

**Source:** https://trunkbaseddevelopment.com/

**Informs:**
- Commit little and often
- Never break the build
- Atomic commits to main, no mega-commits

### David Allen - GTD Next Actions

**Source:** Book: Getting Things Done

**Informs:**
- Concrete file paths, not vague goals
- Reduce cognitive load
- Next physical action

### State of DevOps Report

**Source:** 2016 State of DevOps Report

**Informs:**
- Small batches from trunk
- CR = epic, tasks = stories
- High-performing teams pattern

---

## Architecture Documentation

### Simon Brown - C4 Model

**Source:** https://c4model.com/

**Informs:**
- Context/Container/Component/Code diagrams
- Diagram generation from SSOT

### Michael Nygard - Architecture Decision Records

**Source:** Blog: Documenting Architecture Decisions

**Informs:**
- ADR template structure
- Decision lifecycle (proposed/accepted/deprecated)

---

## Compliance

### SOC-2 Trust Service Criteria

**Source:** AICPA SOC 2 Type II

**Informs:**
- Change control evidence
- Audit trail requirements
- P6 human approval gate

### ISO 27001 - Information Security

**Source:** ISO/IEC 27001:2022

**Informs:**
- Security gates (C3)
- Bandit/safety scans

---

## Product Discovery

### Teresa Torres - Continuous Discovery

**Source:** Book: Continuous Discovery Habits

**Informs:**
- R phase: Research before planning
- R1/R2 gates: Evidence-based decisions

### Marty Cagan - Empowered Teams

**Source:** Book: Empowered

**Informs:**
- Problem space vs solution space
- User success criteria (M+ classification)

---

## Usage in Skills

Skills reference this database but don't hardcode policy values:

```yaml
# CORRECT (in skill)
methodology_ref: "Kent Beck - Micro-commits"
principle: "One kind of change per commit"
# Defer to SSOT for actual policy values

# WRONG (in skill)
policy: "coverage: 80%"  # Don't hardcode values
```

Policy values come from SSOT standards (STD-xxx files), not skills.

```

### references/session-format.md

```markdown
# Session File Formats

Session files persist RPI state to survive context limits.

---

## Session Structure

```
data/.session/rpi-{date}-{id}/
├── research.yaml        # R phase output
├── plan.yaml            # P phase output (machine-readable)
├── plan-projection.md   # P phase output (human-readable, generated)
├── progress.yaml        # I phase tracking
└── checkpoints/         # Optional recovery points
```

---

## research.yaml Schema

```yaml
research:
  task_id: "TASK-XXX"

  oss_search:
    searched:
      - pypi: "search terms"
        results: "what was found"
      - github: "search terms"
        results: "what was found"
    selected: "library-name"
    rationale: "why this library"
    alternatives_rejected:
      - name: "other-lib"
        reason: "why not"

  codebase_context:
    relevant_files:
      - path: "path/to/file"
        purpose: "what it does"
        patterns: "patterns to follow"
    existing_patterns:
      - "Pattern name: how it's implemented"

  constraints:
    from_standards:
      - STD-PYTHON-LIBS-001: "constraint description"
      - STD-CODE-SIZE-001: "constraint description"
    technical:
      - "must use X because Y"
    business:
      - "requirement from stakeholder"
```

---

## plan.yaml Schema

### Required Fields

```yaml
task_id: "TASK-XXX"           # Required: unique identifier
task_title: "Title"           # Required: human-readable title
status: planning              # Required: planning | implementing | verifying | promoted

# CLASSIFICATION (Required - determines V-Model artifact requirements)
classification: "G"           # Required: S, M, G, J, or C
                             # S=Standard, M=Minor, G=Significant, J=Major, C=Critical
                             # Per STD-CHANGE-CLASSIFICATION-001

risk_assessment:             # Required: justification for classification
  impact: 3                  # 1-5 (max of dimensions)
  likelihood: 2              # 1-5
  rationale: "Why this classification"

summary: |                    # Required: prose description
  What will be built.

outputs:                      # Required: files to create/modify
  - path: "exact/path.py"     # Required
    type: new_file            # Required: new_file | modification
    purpose: "why"            # Required
    interface: "InterfaceName" # Optional

validation:                   # Required
  commands:                   # Required: how to verify
    - "pytest tests/ -v"

acceptance_criteria:          # Required: when is it DONE
  - "Specific criterion"

blocked_actions:              # Required: what NOT to do
  - "DO NOT hardcode X"
```

### Classification-Specific Required Fields

```yaml
# For M (Minor) and above:
requirement_id: "REQ-XXX"     # Required for M+
test_case_ids:               # Required for M+
  - "TC-XXX"

# For G (Significant) and above:
hld_id: "HLD-XXX"            # Required for G+

# For J (Major) and above:
lld_id: "LLD-XXX"            # Required for J+
adr_id: "ADR-XXX"            # Required for J+
```

### Optional Fields

```yaml
complies_with:                # SSOT standards referenced
  - STD-PYTHON-LIBS-001
  - STD-CODE-SIZE-001

out_of_scope:                 # Explicitly not doing
  - "Future feature"

dependencies:                 # What must exist first
  - "Other task"

oss_audit:                    # NIH prevention
  libraries:
    - name: "httpx"
      version: ">=0.24"
      purpose: "HTTP client"
      replaces_custom: "requests, custom HTTP"
  custom_code_budget: 500
  custom_code_justification: "Glue code only"

implementation_steps:         # Ordered steps
  - step: 1
    desc: "Write test"
    gate_before: null
    gate_after: "I1"

architecture:                 # Optional diagram
  diagram: |
    [diagram here]
```

---

## progress.yaml Schema

```yaml
progress:
  current_step: 3             # Current step number
  total_steps: 5              # Total steps
  started_at: "ISO timestamp"

  steps:
    1:
      desc: "Write failing test"
      status: done            # pending | in_progress | done
      completed_at: "ISO timestamp"
    2:
      desc: "Implement"
      status: done
    3:
      desc: "Add config"
      status: in_progress

  files_created:              # Track what was created
    - path: "src/module.py"
      lines: 87
      status: created         # created | modified | pending
      created_at: "ISO timestamp"

  validation_results:
    pytest: passed            # passed | failed | pending
    mypy: pending

  drift_check:                # Compare plan vs actual
    last_checked: "ISO timestamp"
    planned_outputs: 4
    actual_outputs: 2
    missing:
      - "config/file.yaml"
    unplanned: []
    status: in_progress       # clean | in_progress | drift_detected
```

---

## manifest.yaml Schema

The manifest file declares which session artifacts to promote to permanent SSOT locations.
Required for session promotion via `ssot session promote`.

### Schema

```yaml
# Artifacts to promote to data/domains/{domain}/requirements/
requirements:
  - "artifacts/REQ-XXX-001.yaml"
  - "artifacts/REQ-XXX-002.yaml"

# Design artifacts
design:
  # Promotes to data/repos/{repo}/hlds/
  hld: "artifacts/HLD-XXX-001.yaml"

  # Promotes to data/repos/{repo}/llds/
  llds:
    - "artifacts/LLD-XXX-001.yaml"
    - "artifacts/LLD-XXX-002.yaml"

# Test cases - promotes to data/repos/{repo}/test_cases/
test_spec:
  unit:
    - "artifacts/TC-XXX-001.yaml"
    - "artifacts/TC-XXX-002.yaml"
  integration:
    - "artifacts/TC-XXX-003.yaml"
  e2e:
    - "artifacts/TC-XXX-004.yaml"
```

### Field Reference

| Field | Type | Classification | Description |
|-------|------|----------------|-------------|
| `requirements` | `list[str]` | M+ | Paths to REQ-*.yaml files relative to session |
| `design.hld` | `str` | G+ | Path to HLD-*.yaml file |
| `design.llds` | `list[str]` | J+ | Paths to LLD-*.yaml files |
| `test_spec` | `dict[str, list[str]]` | M+ | Test cases by category (unit, integration, e2e) |

### Example: Classification G (Significant)

```yaml
# data/.session/rpi-2026-01-07-feature/manifest.yaml
requirements:
  - "artifacts/REQ-FEATURE-001.yaml"

design:
  hld: "artifacts/HLD-FEATURE-001.yaml"
  llds: []  # Not required for G

test_spec:
  unit:
    - "artifacts/TC-FEATURE-001.yaml"
    - "artifacts/TC-FEATURE-002.yaml"
```

### Example: Classification J (Major)

```yaml
# data/.session/rpi-2026-01-07-subsystem/manifest.yaml
requirements:
  - "artifacts/REQ-SUBSYS-001.yaml"
  - "artifacts/REQ-SUBSYS-002.yaml"

design:
  hld: "artifacts/HLD-SUBSYS-001.yaml"
  llds:
    - "artifacts/LLD-SUBSYS-001.yaml"
    - "artifacts/LLD-SUBSYS-002.yaml"

test_spec:
  unit:
    - "artifacts/TC-SUBSYS-001.yaml"
    - "artifacts/TC-SUBSYS-002.yaml"
  integration:
    - "artifacts/TC-SUBSYS-003.yaml"
```

### Promotion Command

```bash
ssot session promote \
  --session data/.session/rpi-2026-01-07-feature \
  --domain platform \
  --repo nextura

# Options:
#   --dry-run     Show plan without copying
#   --force       Overwrite existing files
#   --no-archive  Don't archive session after promotion
#   --no-verify   Skip completion gate verification
```

---

## Validation

Validate session files:

```bash
python -m ssot_toolkit.validators.session $SESSION
```

Expected output:
```
Session validation passed: N files validated
```

---

## Resume Protocol

When context runs out:

```bash
# Load session
SESSION="data/.session/rpi-2026-01-06-001"

# Read plan (critical)
cat $SESSION/plan.yaml

# Read progress (where are we?)
cat $SESSION/progress.yaml

# Continue from current_step
```

---

## Plan Projection Generation

**Never manually write plan-projection.md.**

```bash
# Generate from plan.yaml
ssot project rpi-plan --session $SESSION --output $SESSION

# Creates: $SESSION/plan-projection.md
```

The projection includes:
- Header (task ID, title, status)
- Summary
- File tree visualization
- Implementation steps
- Acceptance criteria
- Validation commands
- Blocked actions
- Approval checklist

---

## Session Lifecycle

Sessions transition through defined states:

```
planning → implementing → verifying → promoted
    │           │            │           │
    │           │            │           └── Archived, audit-ready
    │           │            └── Running C gates
    │           └── Coding in progress
    └── Research complete, planning outputs
```

### Status Definitions

| Status | Phase | Description |
|--------|-------|-------------|
| `planning` | Plan | Research complete, plan being written |
| `implementing` | Implement | Plan approved, coding in progress |
| `verifying` | Complete | All code done, running C1-C6 gates |
| `promoted` | Complete | All gates passed, session archived |

### Status Transitions

```
planning → implementing
  Trigger: Plan approved (human sign-off)
  Command: Manual update to plan.yaml

implementing → verifying
  Trigger: All planned outputs created
  Command: Update plan.yaml status

verifying → promoted
  Trigger: All C gates pass
  Command: ssot session promote --session $SESSION
```

### Promoted Session

When a session is promoted:
1. All C1-C6 gates verified
2. Session status set to 'promoted'
3. Session metadata archived
4. Session folder can be cleaned up

### Stale Sessions

Sessions older than 7 days in `implementing` status are flagged as stale:

```bash
# Find stale sessions
find data/.session -name "plan.yaml" -mtime +7 -exec grep -l "implementing" {} \;
```

Action: Review, complete, or archive stale sessions.

```

### references/stop-gates.md

```markdown
# RPI Stop Gates

All gates are binary: PASS or STOP. No "consider" or "should".

---

## Research Phase Gates

### STOP GATE R1: OSS Search Complete

**Check:** Did I search for existing libraries before planning custom code?

**Pass criteria:**
- Checked SSOT STD-PYTHON-LIBS-001 for approved libraries
- Searched PyPI for relevant keywords
- Searched GitHub for similar projects
- Documented search results in research.yaml

**Fail:** STOP. Complete library search first.

**Why:** OSS-First principle prevents NIH (Not Invented Here) syndrome.

---

### STOP GATE R2: Codebase Context Loaded

**Check:** Do I understand the current codebase state?

**Pass criteria:**
- Read relevant existing modules
- Identified current patterns in use
- Checked for similar implementations
- Reviewed interfaces in core/ports/

**Fail:** STOP. Read the codebase first.

---

### STOP GATE R3: Standards Loaded

**Check:** Did I load applicable standards from SSOT?

**Pass criteria:**
- STD-PYTHON-LIBS-001 loaded (approved libraries)
- STD-CODE-SIZE-001 loaded (size limits)
- STD-ARCHITECTURE-001 loaded (architecture rules)
- Constraints extracted for plan

**Fail:** STOP. Load standards from SSOT.

---

## Plan Phase Gates

### STOP GATE P0: Classification Determined

**Check:** Has the change classification been determined?

**Pass criteria:**
- Risk assessment completed per STD-CHANGE-CLASSIFICATION-001
- Classification field set in plan.yaml (S, M, G, J, or C)
- Required artifacts for classification identified

**Fail:** STOP. Determine classification first.

**Why:** Classification determines the contract. Different classifications require different V-Model artifacts. Without classification, you don't know what artifacts to create.

**Reference:** Use `ssot rpi plan --classification X` which reads the standard and pre-fills constraints.

**Classification Quick Reference:**
| Level | Artifacts Required | Bidirectional? |
|-------|-------------------|----------------|
| S (Standard) | Ticket only | No |
| M (Minor) | Ticket, REQ, TC | No |
| G (Significant) | Ticket, REQ, HLD, TC | Yes |
| J (Major) | Ticket, REQ, HLD, LLD, TC, ADR | Yes + RTM |
| C (Critical) | Full V-Model + Impact Analysis | Yes + Audit |

---

### STOP GATE P1: Outputs Defined

**Check:** Can I list every file I will create/modify?

**Pass criteria:**
- Exact file paths documented
- Each output has type and purpose
- Interfaces to implement identified

**Fail:** STOP. Define outputs first.

---

### STOP GATE P1.1: Numeric Values Cite SSOT (CRITICAL)

**Check:** Does every numeric threshold cite its SSOT source?

**Pass criteria:**
- Coverage thresholds cite STD-TEST-COVERAGE-001
- Size limits cite STD-CODE-SIZE-001
- All numeric constraints have format: `{value} (per {STD-ID})`
- No "reasonable defaults" or invented values

**Fail:** STOP. Read the standard and cite the source.

**Why:** LLMs tend to invent "reasonable" values (60%, 100 LOC, etc.) instead of reading SSOT. This is the "LLM Sets Low Bar" anti-pattern - satisfying the form without the substance.

**Detection patterns (STOP if you see these):**
```yaml
# WRONG - invented values without citation
command: "pytest --cov-fail-under=60"           # Where does 60 come from?
loc_estimate: 100                                # Says who?

# RIGHT - values cite SSOT
command: "pytest --cov-fail-under=80"           # G threshold per STD-TEST-COVERAGE-001
loc_estimate: 150  # Under 200 LOC per STD-CODE-SIZE-001
```

**Mandatory citation format:**
```
{value} (per {STD-ID})
```

**Example:**
- `80% (per STD-TEST-COVERAGE-001)` ✅
- `200 LOC (per STD-CODE-SIZE-001)` ✅
- `60% (sounds reasonable)` ❌ STOP

---

### STOP GATE P2: Validation Commands Defined

**Check:** Do I have commands that prove correctness?

**Pass criteria:**
- Test commands defined
- Type checking commands defined
- Commands come from standards, not hardcoded

**Fail:** STOP. Define validation commands.

---

### STOP GATE P3: Acceptance Criteria Defined

**Check:** How will I know when this is DONE?

**Pass criteria:**
- Specific, measurable criteria (not "it works")
- Each criterion has verification method

**Fail:** STOP. Define specific criteria.

---

### STOP GATE P4: Plan Written to Disk

**Check:** Is plan.yaml persisted?

**Pass criteria:**
- plan.yaml exists in session folder
- Schema validation passed
- Projection generated

**Fail:** STOP. Write plan to disk before implementing.

---

### STOP GATE P5: Plan Classification Validated (M+ Only)

**Check:** Does the plan have all required V-Model artifacts for its classification?

**Pass criteria:**
- `ssot validate-plan -p $SESSION/plan.yaml` exits 0
- All required artifacts exist in SSOT
- For G+: bidirectional traces are complete

**Fail:** STOP. Create missing V-Model artifacts first.

**Command:**
```bash
ssot validate-plan -p $SESSION/plan.yaml
```

**Why:** Enterprise pattern requires classification-based artifact requirements as a blocking gate. This is the shift-left validation that catches missing artifacts before implementation, not at pre-commit.

**Note:** Classification S (Standard) skips this gate as it requires ticket only.

---

### STOP GATE P6: Plan Approved by Human (BLOCKING)

**Check:** Has a human reviewed and approved the plan projection?

**Pass criteria:**
- Plan projection generated: `ssot project rpi-plan --session $SESSION`
- Projection presented to human for review
- **Human explicitly approved** (verbal "approved", "proceed", "looks good", etc.)
- Approval recorded in plan.yaml `approval` field

**Fail:** STOP. Do NOT proceed to implementation without explicit human approval.

**Commands:**
```bash
# 1. Generate projection for human review
ssot project rpi-plan --session $SESSION --output $SESSION

# 2. Present to human
cat $SESSION/plan-projection.md

# 3. WAIT FOR HUMAN RESPONSE - DO NOT PROCEED AUTOMATICALLY

# 4. After approval, update plan.yaml
# approval:
#   status: approved
#   approver: human
#   timestamp: 2025-01-07T12:00:00Z
```

**Why:** Regulated environments require human-in-the-loop approval before execution. The agent must NOT assume approval or proceed without explicit confirmation. This is a compliance requirement for SOC-2 and enterprise governance.

**What constitutes approval:**
- Explicit: "approved", "proceed", "go ahead", "looks good", "implement it"
- Questions or concerns: NOT approval - address feedback first
- Silence: NOT approval - ask for explicit confirmation

**Anti-pattern:**
```
❌ "Here's the plan. Now implementing..."  # No approval wait
❌ "Plan generated. Proceeding to implementation."  # Assumed approval
✅ "Here's the plan. Do you approve? I'll wait for your confirmation before implementing."
```

---

## Implement Phase Gates

### STOP GATE I0: Infrastructure Ready

**Check:** Does test infrastructure exist?

**Pass criteria:**
- tests/ directory exists
- conftest.py exists (if Python)
- pyproject.toml configured

**Fail:** STOP. Create infrastructure before TDD.

---

### STOP GATE I1: Test Written First

**Check:** Does a failing test exist for this feature?

**Pass criteria:**
- Test file exists
- Test fails (RED state)
- Test describes expected behavior

**Fail:** STOP. Write the test first.

---

### STOP GATE I2: Validation Passes

**Check:** Did all validation commands pass?

**Pass criteria:**
- All commands from plan.validation pass
- Commands defined in SSOT standards pass

**Fail:** STOP. Fix until all pass.

---

### STOP GATE I2.1: Per-File Shift-Left Validation (CRITICAL)

**Check:** Did I run pre-commit on each file IMMEDIATELY after writing it?

**Pass criteria:**
- `pre-commit run --files {file}` runs after each file write
- All lint (ruff), type (mypy), security (bandit), size (file-size-limit) checks pass
- Files exceeding 500 LOC are split BEFORE moving to next file
- No accumulation of violations across multiple files

**Fail:** STOP. Run pre-commit on the file NOW. Fix all violations before writing the next file.

**Why:** Waiting until C1 (completion) to run pre-commit means you find 10+ violations across multiple files AFTER you've finished. Shift-left catches issues when they're cheap to fix (one file, fresh in context).

**Command:**
```bash
# After writing each file
pre-commit run --files src/ssot_toolkit/new_module.py

# Common failures to fix immediately:
# - ruff: lint violations (fix code style)
# - mypy: type errors (add type hints)
# - file-size-limit: > 500 LOC (split the file)
# - bandit: security issues (fix vulnerability)
```

**Anti-pattern:**
```
❌ Write file1.py, file2.py, file3.py... then run pre-commit (finds 20 violations)
✅ Write file1.py → pre-commit → fix → Write file2.py → pre-commit → fix → ...
```

**Cost comparison:**
- Fix at I2.1: 2 minutes per file, immediate context
- Fix at C1: 30 minutes total, lost context, frustration

---

### STOP GATE I3: Drift Check

**Check:** Does progress match plan?

**Pass criteria:**
- All planned outputs created
- No unplanned files (or justified)
- progress.yaml matches plan.yaml outputs

**Fail:** STOP. Create missing files or justify scope change.

---

## Pre-Commit Gate (Mandatory)

### STOP GATE: Pre-Commit Hooks Pass

**Check:** Do all pre-commit hooks pass?

```bash
pre-commit run --all-files
```

**Pass criteria:**
- All hooks pass
- No --no-verify flag used

**Fail:** STOP. Fix hook failures, never bypass.

---

## Complete Phase Gates

### STOP GATE C1: Pre-Commit Hooks Pass

**Check:** Do all pre-commit hooks pass including security hooks?

**Pass criteria:**
- `pre-commit run --all-files` exits 0
- Includes bandit (security analysis)
- Includes safety (dependency vulnerabilities)
- No --no-verify flag used

**Fail:** STOP. Fix all hook failures.

**Reference:** STD-SECURITY-001

---

### STOP GATE C2: Test Coverage Meets Threshold

**Check:** Does test coverage meet classification threshold?

**Pass criteria:**
- Coverage meets threshold from STD-TEST-COVERAGE-001:
  - S: No requirement
  - M: 60%
  - G: 80%
  - J: 90%
  - C: 95%

**Command:**
```bash
pytest tests/ --cov=src --cov-fail-under=80  # For classification G
```

**Fail:** STOP. Add tests until coverage meets threshold.

**Reference:** STD-TEST-COVERAGE-001

---

### STOP GATE C3: Security Scan Clean

**Check:** Are there high/critical security findings?

**Pass criteria:**
- `bandit -r src/ -ll` finds no high/critical issues
- `safety check` finds no known vulnerabilities
- All findings addressed (fixed or documented exception)

**Fail:** STOP. Fix security issues before completion.

**Reference:** STD-SECURITY-001

---

### STOP GATE C4: Traceability Complete

**Check:** Are all V-Model artifacts present with bidirectional traces?

**Pass criteria:**
- `ssot validate-plan -p $SESSION/plan.yaml` exits 0
- `ssot check-bidirectional` exits 0
- All required artifacts exist for classification

**Fail:** STOP. Create missing artifacts or fix traces.

**Reference:** STD-CHANGE-CLASSIFICATION-001

---

### STOP GATE C5: Drift Check Clean

**Check:** Do planned outputs match actual files?

**Pass criteria:**
- All outputs in plan.yaml exist as files
- No unplanned files created (or justified in scope_changes)
- progress.yaml reflects actual state

**Fail:** STOP. Create missing files or update plan.

---

### STOP GATE C6: Session Promoted

**Check:** Has the session been promoted?

**Pass criteria:**
- All C1-C5 gates pass
- Session status updated to 'promoted'
- Session metadata archived

**Command:**
```bash
ssot session promote --session $SESSION
```

**Fail:** STOP. Run all gates and promote session.

---

## Gate Summary Table

| Gate | Phase | Check | On Fail |
|------|-------|-------|---------|
| R1 | Research | OSS search done? | Search libraries |
| R2 | Research | Context loaded? | Read codebase |
| R3 | Research | Standards loaded? | Load from SSOT |
| **P0** | **Plan** | **Classification determined?** | **Assess risk, set classification** |
| P1 | Plan | Outputs defined? | Define file paths |
| **P1.1** | **Plan** | **Numeric values cite SSOT?** | **STOP - read standard, cite source** |
| P2 | Plan | Validation defined? | Define commands |
| P3 | Plan | Criteria defined? | Define acceptance |
| P4 | Plan | Plan persisted? | Write to disk |
| **P5** | **Plan** | **Plan validated? (M+)** | **ssot validate-plan, create artifacts** |
| **P6** | **Plan** | **Human approved? (BLOCKING)** | **WAIT - present projection, get approval** |
| I0 | Implement | Infrastructure? | Create test dirs |
| I1 | Implement | Test first? | Write failing test |
| I2 | Implement | Validation passes? | Fix failures |
| **I2.1** | **Implement** | **Per-file pre-commit?** | **STOP - run pre-commit on file NOW** |
| I3 | Implement | Drift check? | Match plan |
| PRE | Commit | Hooks pass? | Fix, never bypass |
| **C1** | **Complete** | **Pre-commit + security?** | **Fix all hook failures** |
| **C2** | **Complete** | **Coverage threshold?** | **Add tests (STD-TEST-COVERAGE-001)** |
| **C3** | **Complete** | **Security scan clean?** | **Fix findings (STD-SECURITY-001)** |
| **C4** | **Complete** | **Traceability complete?** | **Fix traces, create artifacts** |
| **C5** | **Complete** | **Drift check clean?** | **Match plan outputs** |
| **C6** | **Complete** | **Session promoted?** | **Run ssot session promote** |

```

### references/examples.md

```markdown
# RPI Workflow Examples

## Example: API Client Implementation

### Research Phase

```yaml
# data/.session/rpi-2026-01-06-001/research.yaml
research:
  task_id: "TASK-API-001"

  oss_search:
    searched:
      - pypi: "http client async"
        results: "httpx (async, modern), requests (sync, legacy)"
      - pypi: "api client"
        results: "Various specific clients, none generic"
    selected: "httpx"
    rationale: |
      - Modern async/sync support
      - Type hints included
      - Timeout and retry built-in
    alternatives_rejected:
      - name: "requests"
        reason: "No native async, httpx is successor"

  codebase_context:
    relevant_files:
      - path: "src/core/ports/api_client.py"
        purpose: "API client interface definition"
        patterns: "Protocol-based port"
    existing_patterns:
      - "DI: All dependencies via constructor"
      - "Policy: Config from YAML, not hardcoded"

  constraints:
    from_standards:
      - STD-PYTHON-LIBS-001: "Use httpx, not requests"
      - STD-CODE-SIZE-001: "Function <=50 LOC"
```

### Plan Phase

```yaml
# data/.session/rpi-2026-01-06-001/plan.yaml
task_id: "TASK-API-001"
task_title: "Implement external API client adapter"
status: approved

summary: |
  Create an API client adapter that implements APIClientPort
  using httpx. Configuration from YAML, proper error handling.

complies_with:
  - STD-PYTHON-LIBS-001
  - STD-CODE-SIZE-001
  - STD-ARCHITECTURE-001

outputs:
  - path: "src/adapters/api_client.py"
    type: new_file
    purpose: "External API adapter"
    interface: "APIClientPort"

  - path: "tests/unit/adapters/test_api_client.py"
    type: new_file
    purpose: "Unit tests with mocked HTTP"
    coverage: ">=80%"

  - path: "config/api_client.yaml"
    type: new_file
    purpose: "Client configuration"

validation:
  commands:
    - "pytest tests/unit/adapters/test_api_client.py -v --cov"
    - "mypy src/adapters/api_client.py --strict"

acceptance_criteria:
  - "Implements APIClientPort interface"
  - "Uses httpx for HTTP calls"
  - "Handles timeout with specific exception"
  - "All config from YAML"
  - "Tests pass with mocked HTTP client"

blocked_actions:
  - "DO NOT hardcode base URL or timeout"
  - "DO NOT use requests (use httpx)"
  - "DO NOT catch generic Exception"

out_of_scope:
  - "Retry logic (future task)"
  - "Circuit breaker"

oss_audit:
  libraries:
    - name: "httpx"
      version: ">=0.24"
      purpose: "HTTP client"
      replaces_custom: "requests, custom HTTP"
  custom_code_budget: 100
  custom_code_justification: "Glue code only"
```

### Progress Tracking

```yaml
# data/.session/rpi-2026-01-06-001/progress.yaml
progress:
  current_step: 3
  total_steps: 5
  started_at: "2026-01-06T10:00:00Z"

  steps:
    1:
      desc: "Write failing test"
      status: done
      completed_at: "2026-01-06T10:15:00Z"
    2:
      desc: "Implement APIClient"
      status: done
      completed_at: "2026-01-06T10:45:00Z"
    3:
      desc: "Add config loading"
      status: in_progress
    4:
      desc: "Run mypy"
      status: pending
    5:
      desc: "Commit"
      status: pending

  files_created:
    - path: "src/adapters/api_client.py"
      lines: 87
      status: created
    - path: "tests/unit/adapters/test_api_client.py"
      lines: 124
      status: created

  validation_results:
    pytest: passed
    mypy: pending

  drift_check:
    planned_outputs: 3
    actual_outputs: 2
    missing: ["config/api_client.yaml"]
    unplanned: []
    status: in_progress
```

---

## Example: Session Resume

When context runs out:

```bash
# User says: "Continue RPI from data/.session/rpi-2026-01-06-001/"

# 1. Load plan (critical)
cat data/.session/rpi-2026-01-06-001/plan.yaml

# 2. Load progress
cat data/.session/rpi-2026-01-06-001/progress.yaml

# Findings:
# - current_step: 3 (Add config loading)
# - files_created: 2 of 3
# - missing: config/api_client.yaml

# 3. Continue from step 3
# Create config/api_client.yaml
# Update progress.yaml
# Proceed to step 4
```

---

## Example: Drift Detection

```
Plan outputs:                Progress files_created:
-------------                ----------------------
src/api_client.py      -->   src/api_client.py     [match]
tests/test_api.py      -->   tests/test_api.py     [match]
config/api.yaml        -->   (missing)             [drift!]
                             src/utils.py          [unplanned!]

Drift status: drift_detected
Action: Create config/api.yaml, justify or remove src/utils.py
```

---

## Classification Examples

plan.yaml templates for each classification level per STD-CHANGE-CLASSIFICATION-001.

### Classification S (Standard)

Pre-approved, low-risk change. Examples: dependency update, config change, documentation fix.

```yaml
# data/.session/rpi-2026-01-07-docs-fix/plan.yaml
task_id: "docs-fix-001"
task_title: "Fix typo in README"
status: planning

# CLASSIFICATION - Minimal required fields for S
classification: "S"
ticket_id: "TICKET-1234"

risk_assessment:
  impact: 1
  likelihood: 1
  rationale: "Documentation-only change, no code impact"

summary: |
  Fix typo in README.md installation instructions.

# S classification requires only:
# - ticket_id
# - Existing tests must pass
# - Rollback is trivial (revert commit)

validation:
  commands:
    - "pytest tests/ -q"  # Existing tests pass

acceptance_criteria:
  - "Typo corrected"
  - "Existing tests still pass"

blocked_actions:
  - "DO NOT change any code files"
```

**Key: S requires only ticket_id. No REQ, HLD, LLD, or new TC required.**

---

### Classification M (Minor)

Low-risk change with limited scope. Examples: bug fix, small enhancement, new utility function.

```yaml
# data/.session/rpi-2026-01-07-bugfix/plan.yaml
task_id: "bugfix-001"
task_title: "Fix null pointer in user service"
status: planning

# CLASSIFICATION - M requires REQ + TC
classification: "M"
ticket_id: "TICKET-2345"
requirement_id: "REQ-BUGFIX-001"
test_case_ids:
  - "TC-BUGFIX-001"

risk_assessment:
  impact: 2
  likelihood: 3
  rationale: "Single module fix, no API change, contained impact"

summary: |
  Fix null pointer exception when user has no email configured.

outputs:
  - path: "src/services/user_service.py"
    type: modification
    purpose: "Add null check for email field"

  - path: "tests/unit/services/test_user_service.py"
    type: modification
    purpose: "Add test for null email case"

validation:
  commands:
    - "pytest tests/unit/services/test_user_service.py -v"
    - "mypy src/services/user_service.py --strict"

acceptance_criteria:
  - "No exception when email is null"
  - "Test covers null email case"
  - "Existing tests pass"

blocked_actions:
  - "DO NOT change user API contract"
  - "DO NOT modify database schema"
```

**Key: M adds requirement_id and test_case_ids. No HLD or LLD required.**

---

### Classification G (Significant)

Medium-risk change requiring design review. Examples: new API endpoint, new service integration.

```yaml
# data/.session/rpi-2026-01-07-new-endpoint/plan.yaml
task_id: "api-endpoint-001"
task_title: "Add user preferences API endpoint"
status: planning

# CLASSIFICATION - G requires REQ + HLD + TC
classification: "G"
ticket_id: "TICKET-3456"
requirement_id: "REQ-PREFS-001"
hld_id: "HLD-PREFS-001"
test_case_ids:
  - "TC-PREFS-001"
  - "TC-PREFS-002"

risk_assessment:
  impact: 3
  likelihood: 2
  rationale: "New API endpoint, crosses service boundary, but read-only"

summary: |
  Add GET /api/v1/users/{id}/preferences endpoint to retrieve
  user preference settings.

complies_with:
  - STD-API-DESIGN-001
  - STD-CODE-SIZE-001

outputs:
  - path: "src/api/routes/user_preferences.py"
    type: new_file
    purpose: "New API route handler"

  - path: "src/services/preferences_service.py"
    type: new_file
    purpose: "Business logic for preferences"

  - path: "tests/unit/api/test_user_preferences.py"
    type: new_file
    purpose: "Unit tests for endpoint"

  - path: "tests/integration/test_preferences_api.py"
    type: new_file
    purpose: "Integration test with database"

validation:
  commands:
    - "pytest tests/unit/api/test_user_preferences.py -v"
    - "pytest tests/integration/test_preferences_api.py -v"
    - "mypy src/api/routes/user_preferences.py --strict"

acceptance_criteria:
  - "GET endpoint returns 200 with preferences JSON"
  - "Returns 404 for unknown user"
  - "HLD documents API contract"
  - "Unit and integration tests pass"

blocked_actions:
  - "DO NOT add write endpoints (future scope)"
  - "DO NOT bypass authentication"
```

**Key: G adds hld_id. Bidirectional traces required (REQ <-> HLD <-> TC).**

---

### Classification J (Major)

High-risk change requiring full design and CAB review. Examples: new subsystem, breaking change.

```yaml
# data/.session/rpi-2026-01-07-notification-system/plan.yaml
task_id: "notification-001"
task_title: "Implement notification subsystem"
status: planning

# CLASSIFICATION - J requires REQ + HLD + LLD + ADR + TC
classification: "J"
ticket_id: "TICKET-4567"
requirement_id: "REQ-NOTIFY-001"
hld_id: "HLD-NOTIFY-001"
lld_id: "LLD-NOTIFY-001"
adr_id: "ADR-NOTIFY-001"
test_case_ids:
  - "TC-NOTIFY-001"
  - "TC-NOTIFY-002"
  - "TC-NOTIFY-003"
  - "TC-NOTIFY-004"

risk_assessment:
  impact: 4
  likelihood: 3
  rationale: "New subsystem, external integration with email/SMS providers"

summary: |
  Implement notification subsystem supporting email and SMS channels.
  Integrates with SendGrid and Twilio. Includes queue-based async delivery.

complies_with:
  - STD-ARCHITECTURE-001
  - STD-API-DESIGN-001
  - STD-CODE-SIZE-001
  - STD-DI-001

outputs:
  - path: "src/notifications/ports/notifier.py"
    type: new_file
    purpose: "Notifier port interface"

  - path: "src/notifications/adapters/email_adapter.py"
    type: new_file
    purpose: "SendGrid email adapter"

  - path: "src/notifications/adapters/sms_adapter.py"
    type: new_file
    purpose: "Twilio SMS adapter"

  - path: "src/notifications/service.py"
    type: new_file
    purpose: "Notification service with queue"

  - path: "tests/unit/notifications/"
    type: new_file
    purpose: "Unit tests for all components"

  - path: "tests/integration/test_notification_delivery.py"
    type: new_file
    purpose: "Integration tests with mocked providers"

validation:
  commands:
    - "pytest tests/unit/notifications/ -v --cov"
    - "pytest tests/integration/test_notification_delivery.py -v"
    - "mypy src/notifications/ --strict"
    - "ssot check-bidirectional"

acceptance_criteria:
  - "Email notifications delivered via SendGrid"
  - "SMS notifications delivered via Twilio"
  - "Queue ensures async delivery"
  - "All tests pass with 90% coverage"
  - "Bidirectional traces complete"
  - "CAB approval obtained"

blocked_actions:
  - "DO NOT hardcode API keys"
  - "DO NOT bypass queue for synchronous delivery"
  - "DO NOT add push notifications (future scope)"

out_of_scope:
  - "Push notifications"
  - "In-app notifications"
  - "Notification preferences UI"
```

**Key: J adds lld_id and adr_id. RTM entry required. CAB approval mandatory.**

---

### Classification C (Critical)

Highest-risk change with regulatory or enterprise-wide impact. Examples: compliance system change, data migration.

```yaml
# data/.session/rpi-2026-01-07-audit-system/plan.yaml
task_id: "audit-001"
task_title: "Implement SOX-compliant audit logging"
status: planning

# CLASSIFICATION - C requires full V-Model + audit evidence
classification: "C"
ticket_id: "TICKET-5678"
requirement_id: "REQ-AUDIT-001"
hld_id: "HLD-AUDIT-001"
lld_id: "LLD-AUDIT-001"
adr_id: "ADR-AUDIT-001"
test_case_ids:
  - "TC-AUDIT-001"
  - "TC-AUDIT-002"
  - "TC-AUDIT-003"
  - "TC-AUDIT-004"
  - "TC-AUDIT-005"

# C-specific required fields
impact_analysis_id: "IA-AUDIT-001"
rollback_plan: |
  1. Disable audit logging feature flag
  2. Restore previous audit table from backup
  3. Verify existing functionality unaffected
  4. Notify compliance team

audit_evidence_ids:
  - "AE-AUDIT-001"  # Design review sign-off
  - "AE-AUDIT-002"  # Security review sign-off
  - "AE-AUDIT-003"  # Compliance review sign-off

compliance_signoff:
  required: true
  approver: "[email protected]"
  status: pending

risk_assessment:
  impact: 5
  likelihood: 3
  rationale: "Regulatory requirement (SOX), enterprise-wide impact, audit trail"

summary: |
  Implement SOX-compliant audit logging for all financial transactions.
  Immutable log storage, tamper detection, retention policy enforcement.

complies_with:
  - STD-ARCHITECTURE-001
  - STD-LOGGING-001
  - STD-SECURITY-001

outputs:
  - path: "src/audit/core/logger.py"
    type: new_file
    purpose: "Immutable audit logger"

  - path: "src/audit/storage/append_only.py"
    type: new_file
    purpose: "Append-only storage adapter"

  - path: "src/audit/integrity/hasher.py"
    type: new_file
    purpose: "Tamper detection via hash chain"

  - path: "tests/unit/audit/"
    type: new_file
    purpose: "Unit tests for audit components"

  - path: "tests/e2e/test_audit_compliance.py"
    type: new_file
    purpose: "E2E compliance verification"

validation:
  commands:
    - "pytest tests/unit/audit/ -v --cov --cov-fail-under=95"
    - "pytest tests/e2e/test_audit_compliance.py -v"
    - "mypy src/audit/ --strict"
    - "bandit -r src/audit/ -ll"
    - "ssot check-bidirectional"
    - "ssot validate-plan --strict"

acceptance_criteria:
  - "All audit logs immutable"
  - "Tamper detection verified"
  - "Retention policy enforced"
  - "95% test coverage"
  - "Security scan clean"
  - "Compliance sign-off obtained"
  - "All audit evidence complete"

blocked_actions:
  - "DO NOT allow log modification"
  - "DO NOT bypass audit for any transaction type"
  - "DO NOT store logs without encryption"
  - "DO NOT proceed without compliance sign-off"

out_of_scope:
  - "Audit UI dashboard"
  - "Real-time alerting"
```

**Key: C adds impact_analysis_id, rollback_plan, audit_evidence_ids, compliance_signoff. Full audit trail mandatory.**

---

### Classification Quick Reference

| Level | Required Fields | Key Additions |
|-------|-----------------|---------------|
| **S** | ticket_id | Ticket only, existing tests pass |
| **M** | + requirement_id, test_case_ids | REQ + TC required |
| **G** | + hld_id | HLD required, bidirectional traces |
| **J** | + lld_id, adr_id | Full V-Model, CAB approval, RTM |
| **C** | + impact_analysis_id, rollback_plan, audit_evidence_ids, compliance_signoff | Audit evidence, compliance sign-off |

---

## Anti-Pattern Examples

### Wrong: Coding Without Plan

```
User: "Implement API client"

# WRONG - Starting to code immediately
# Let me create src/adapters/api_client.py...

# RIGHT - Start RPI workflow
1. Create session folder
2. Research: What library? What patterns?
3. Plan: What files? What validation?
4. Write plan.yaml
5. THEN implement
```

### Wrong: Hardcoding Standards

```yaml
# WRONG - In plan.yaml
blocked_actions:
  - "Function must be < 20 LOC"  # Hardcoded!

# RIGHT - Reference SSOT
complies_with:
  - STD-CODE-SIZE-001  # Standard defines limits
```

### Wrong: Manual Plan Presentation

```markdown
# WRONG - Manually writing plan summary

## Plan Summary
Here's what I'll build...
[ASCII diagram]
[File list]

# RIGHT - Use projection generator
ssot project rpi-plan --session $SESSION --output $SESSION
cat $SESSION/plan-projection.md
```

```

### references/success-criteria.md

```markdown
# User Success Criteria Reference

> **Standard:** STD-SUCCESS-CRITERIA-001
> **Implements:** REQ-SUCCESS-001

## Core Principle

**"Plan for SUCCESS, not for COMPLETION."**

The person who requests work defines success.
The person who does work proves success.
These MUST be different perspectives.

---

## Why User Success Criteria Matter

Without user-defined success criteria:
- LLM/implementer defines their own success (segregation of duties violated)
- Acceptance criteria may not match user's actual requirement
- No proof user agreed implementation meets their needs
- Audit trail shows LLM approval, not User approval
- Tasks marked "done" without business owner sign-off

---

## The User Success Contract (USC)

Every M+ classified task requires a User Success Contract with:

```yaml
user_success_criteria:
  id: USC-{task_id}

  user_request: |
    Original user request in their own words

  success_criteria:
    - id: SC1
      criterion: "What user considers success (must be verifiable)"
      verifiable: true
      evidence_type: "demonstration|output|file|api_response|document"
      how_to_verify: "Specific steps to verify this criterion"

  user_approval:
    approved: true
    timestamp: "2026-01-07T10:00:00Z"
    method: explicit

  user_acceptance:  # After implementation
    results:
      - criterion_id: SC1
        result: pass
        evidence_path: "path/to/evidence"
    overall: accepted
    timestamp: "2026-01-07T12:00:00Z"
```

---

## Example: EXTRACT-001 (What USC Should Have Been)

**User Request:**
> "Extract all deterministic data from codebase into SSOT. The success should be
> that we can successfully extract all the deterministic data from the codebase
> that needs to be stored in the SSOT."

**Proper User Success Criteria:**

```yaml
user_success_criteria:
  id: USC-EXTRACT-001

  user_request: |
    Extract all deterministic data from codebase into SSOT.
    The success should be that we can successfully extract all
    the deterministic data from the codebase that needs to be
    stored in the SSOT.

  success_criteria:
    - id: SC1
      criterion: "Running `ssot extract src/` outputs list of extracted entities"
      verifiable: true
      evidence_type: output
      how_to_verify: "Run command, observe entity list with counts"

    - id: SC2
      criterion: "Extracted entities include: components, interfaces, schemas, vendors"
      verifiable: true
      evidence_type: output
      how_to_verify: "Check extraction output shows all four types"

    - id: SC3
      criterion: "Extracted YAML files pass `ssot validate`"
      verifiable: true
      evidence_type: output
      how_to_verify: "Run ssot validate on extracted files"

    - id: SC4
      criterion: "Entity count is >= 50 (indicating non-trivial extraction)"
      verifiable: true
      evidence_type: output
      how_to_verify: "Check total count in extraction report"

    - id: SC5
      criterion: "Dogfooding: can extract from Nextura codebase itself"
      verifiable: true
      evidence_type: demonstration
      how_to_verify: "Run ssot extract on src/, observe results"

  user_approval:
    approved: true
    timestamp: "2026-01-06T12:00:00Z"
    method: explicit
```

---

## Workflow Integration

### Plan Phase (P)

1. **P_USC Gate:** Plan has `user_success_criteria` section
2. **Ask user to define/approve success criteria**
3. **P6 Gate (BLOCKING):** User explicitly approves before implementation

```bash
# Present proposed criteria and ask:
"Do you approve these success criteria?
I will wait for your explicit approval before implementing."
```

### Implement Phase (I)

- Cannot change success criteria without user re-approval
- Generate evidence for each criterion during implementation

### Complete Phase (C)

1. **Generate evidence bundle** with results for each SC
2. **C_USC Gate (BLOCKING for G+):** User accepts evidence
3. Present results and ask for acceptance

```bash
# Present evidence and ask:
"Here is the evidence for your success criteria:
SC1: PASS - [evidence]
SC2: PASS - [evidence]

Do you accept that these success criteria are met?"
```

---

## Baseline Compliance (SC0 - ALL Tasks)

Before user-defined success criteria can be evaluated, ALL tasks must pass baseline compliance:

```yaml
baseline_success_criterion:
  id: SC0
  criterion: "Passes pre-commit, standards, security, and proper promotion"
  gates: ["C1", "C3", "C6"]
  includes:
    - Pre-commit hooks pass (ruff, mypy, bandit, safety)
    - Security scan clean (no high/critical findings)
    - V-Model artifacts promoted via `ssot session promote`
    - Session archived with audit trail
```

**Order of validation:**
1. **Baseline (SC0):** C1, C3, C6 gates - non-negotiable
2. **User Success (SC1-SCn):** C_USC gate - user-defined

A task cannot be "successful" if it violates coding standards or security, even if user's functional criteria are met.

---

## Classification Requirements

| Classification | USC Required? | Approval Required? | Acceptance Required? |
|----------------|---------------|--------------------|--------------------|
| S (Standard) | No | No | No |
| M (Minor) | Yes | Yes | Optional |
| G (Significant) | Yes | Yes | Yes |
| J (Major) | Yes | Yes | Yes |
| C (Critical) | Yes | Yes | Yes + Formal |

---

## Good vs Bad Success Criteria

### Good (Verifiable)

- "Running `ssot extract src/` outputs list of extracted entities"
- "The API returns 200 with JSON containing 'status: success'"
- "Documentation at docs/feature.md exists and contains usage examples"
- "Test coverage is >= 80% as shown by pytest --cov"
- "No high/critical findings in bandit security scan"

### Bad (Vague - Will Be Rejected)

- "The feature works well"
- "Users can easily use it"
- "Performance is good"
- "The extraction is successful"
- "Code is clean"

---

## Validation Commands

```bash
# Check plan has valid USC
ssot validate-plan --check-usc $SESSION/plan.yaml

# Check user approval before implementation
# (P6 gate - blocks if not approved)

# Check user acceptance before promotion
ssot session promote --session $SESSION --verify
# (C_USC gate - blocks G+ without acceptance)
```

---

## Anti-Patterns

| If you're doing... | STOP. Do this instead... |
|--------------------|-----------------------------|
| Defining success criteria yourself | Ask user to define what success looks like |
| Using vague criteria | Ask for specific, verifiable outcomes |
| Starting implementation without approval | Wait for explicit "yes" from user |
| Marking done without user acceptance | Present evidence, wait for acceptance |
| Changing criteria mid-implementation | Get user re-approval first |
| Creating artifacts directly in SSOT | Create in session folder, then `ssot session promote` |
| Skipping baseline compliance | Pass C1, C3, C6 gates before claiming success |

```

### references/governance-contracts.md

```markdown
# Governance Contracts Reference

Load applicable standards and ADRs from SSOT before planning.

---

## Loading Standards (R3 Gate)

**Nextura Philosophy:** Tooling does toiling, LLM does reasoning.

**DO NOT** manually read standards. Use `ssot rpi plan` which reads SSOT and pre-fills constraints.

```bash
# Tooling reads standards and generates template with constraints pre-filled
ssot rpi plan --classification G --cr CR-XXX-001 --session $SESSION

# Template contains values FROM:
# - STD-CHANGE-CLASSIFICATION-001 (required artifacts)
# - STD-CODE-SIZE-001 (size limits)
# - STD-TEST-COVERAGE-001 (coverage thresholds)
# With citations for audit trail
```

## Loading ADRs

```bash
# Architecture decisions (accepted = must follow)
cat data/enterprise/decisions/ADR-ARCH-001.yaml    # Microkernel + Plugins
cat data/enterprise/decisions/ADR-ARCH-010.yaml    # Ports & Adapters

# List all ADRs
ls data/enterprise/decisions/ADR-*.yaml
```

---

## Standards Index

| ID | Purpose | When to Load |
|----|---------|--------------|
| STD-ARCHITECTURE-001 | Clean Architecture boundaries | Before any code changes |
| STD-CHANGE-CLASSIFICATION-001 | V-Model artifact requirements | Before creating plan |
| STD-CODE-SIZE-001 | LOC limits (300 file, 20 function) | Before implementation |
| STD-COMPLEXITY-001 | Cyclomatic complexity (≤10) | Before implementation |
| STD-DI-001 | Dependency injection rules | When creating classes |
| STD-DRY-001 | DRY/YAGNI principles | During code review |
| STD-ERROR-HANDLING-001 | No silent failures | When writing error handling |
| STD-LOGGING-001 | Structured logging | When adding logs |
| STD-POLICY-CODE-001 | Policy as config | When adding business rules |
| STD-PYTHON-LIBS-001 | Approved libraries | Before adding dependencies |
| STD-SECURITY-001 | Security scanning | Before commit |
| STD-SOLID-001 | SOLID principles | During design |
| STD-SSOT-PATHS-001 | Canonical file paths | When creating entities |
| STD-SUCCESS-CRITERIA-001 | USC pattern (M+) | During plan phase |
| STD-TEST-COVERAGE-001 | Coverage by classification | Before C2 gate |
| STD-TESTING-STRATEGY-001 | Test types, anti-patterns | Before writing tests |
| STD-12FACTOR-001 | No hardcoded config | When adding config |

---

## ADR Index

| ID | Decision | Status |
|----|----------|--------|
| ADR-ARCH-001 | Microkernel + Bounded Plugins | ACCEPTED |
| ADR-ARCH-002 | Event-Driven Communication | PROPOSED |
| ADR-ARCH-003 | Configuration Layering | PROPOSED |
| ADR-ARCH-004 | Schema Evolution | PROPOSED |
| ADR-ARCH-005 | Testing Boundaries | PROPOSED |
| ADR-ARCH-006 | Observability | PROPOSED |
| ADR-ARCH-007 | Typed Errors | PROPOSED |
| ADR-ARCH-008 | Plugin Lifecycle | PROPOSED |
| ADR-ARCH-009 | Security Boundaries | PROPOSED |
| ADR-ARCH-010 | Hexagonal Ports | PROPOSED |
| ADR-CLASSIFICATION-001 | Classification Validation | ACCEPTED |
| ADR-COMPLETION-001 | Completion Phase | ACCEPTED |
| ADR-RPI-001 | Session Promotion | APPROVED |

---

## Quick Compliance Check

```bash
# Architecture boundaries
lint-imports

# Plan classification
ssot validate-plan -p $SESSION/plan.yaml

# Bidirectional traces
ssot check-bidirectional

# Security
bandit -r src/ -ll && safety check

# Full pre-commit
pre-commit run --all-files
```

---

## Classification Quick Reference

Load from: `data/enterprise/standards/STD-CHANGE-CLASSIFICATION-001.yaml`

| Level | Required Artifacts |
|-------|-------------------|
| S | Ticket |
| M | Ticket, REQ, TC |
| G | Ticket, REQ, HLD, TC |
| J | Ticket, REQ, HLD, LLD, TC, ADR, RTM |
| C | All + Impact + Audit |

---

## CR/Plan Audit Checklist

Before RPI planning, verify CR has:

- [ ] Classification field set
- [ ] USC defined (M+ required)
- [ ] complies_with listing applicable standards
- [ ] No core modifications proposed (ADR-ARCH-001 P1)
- [ ] Plugin boundaries respected (ADR-ARCH-001 P2)

```

### references/task-contract.md

```markdown
# Task Contract Reference

How to define atomic tasks in plan.yaml for contract-based execution.

---

## Contract vs Prose

| Prose Instructions | Task Contract |
|-------------------|---------------|
| LLM interprets freely | Typed schema, required fields |
| Drift over long sessions | Re-read contract each task |
| No validation | Validation commands defined |
| Theatre possible | Deterministic, traceable |

---

## Task Schema

```yaml
atomic_tasks:
  - id: T0                       # Required: unique task identifier
    name: "Short description"    # Required: what this task does
    description: "Details"       # Optional: expanded explanation

    outputs:                     # Required: files this task produces
      - path: src/module.py
      - path: tests/test_module.py

    policies:                    # Optional: residual policies (Layer 3)
      file_loc: 500              # Max lines per file
      coverage: 80               # Min coverage percentage
      function_loc: 50           # Max lines per function

    validation:                  # Required: commands to validate
      - "ruff check src/module.py"
      - "mypy src/module.py"
      - "pytest tests/test_module.py -v"
      - "Human review"           # Special: marks human checkpoint
```

---

## Field Definitions

### id (Required)

Unique identifier within the plan. Convention: `T0`, `T1`, `T2`, etc.

### name (Required)

Short description (1-5 words). Shown in task list and contract display.

### outputs (Required)

List of file paths this task will create or modify. Used for:

- Scope enforcement (don't touch other files)
- Drift detection (did you modify what you said?)
- Commit suggestions (which files to stage)

### policies (Optional)

Residual policies the agent must track. Only include Layer 3 policies - tooling handles Layers 1 and 2.

Common policies:

| Policy | Description | Source |
|--------|-------------|--------|
| `file_loc` | Max lines per file | STD-CODE-SIZE-001 |
| `function_loc` | Max lines per function | STD-CODE-SIZE-001 |
| `coverage` | Min test coverage % | STD-TEST-COVERAGE-001 |

### validation (Required)

Commands to run before task completion. Types:

1. **Automated**: Shell commands that return exit code
2. **Human review**: Special marker for human checkpoint

---

## Task Lifecycle Commands

```bash
# View all tasks in plan
ssot task list --session $SESSION

# Start a task (displays contract)
ssot task start T0 --session $SESSION

# Complete a task (runs validation)
ssot task complete --session $SESSION --task T0

# Dry-run validation (preview only)
ssot task complete --session $SESSION --task T0 --dry-run
```

---

## Contract Display

When you run `ssot task start`, you see:

```
╭──────────────────────── TASK CONTRACT: T0 ────────────────────────╮
│ Task: T0 - Implement core module                                  │
│                                                                   │
│ Scope (files to modify):                                          │
│   - src/module.py                                                 │
│   - tests/test_module.py                                          │
│                                                                   │
│ Policies (agent must follow):                                     │
│   - file_loc: 500                                                 │
│   - coverage: 80                                                  │
│                                                                   │
│ Validation (run before complete):                                 │
│   - ruff check src/module.py                                      │
│   - pytest tests/test_module.py -v                                │
│                                                                   │
│ Complete with:                                                    │
│   ssot task complete --session <session>                          │
╰───────────────────────────────────────────────────────────────────╯
```

This is the **contract**. The agent (human or LLM) follows this exactly.

---

## Workflow

```text
Plan Approved (P6)
    │
    ▼
┌───────────────┐
│ Task T0       │  ← ssot task start T0
│  - Contract   │
│  - Work       │
│  - Validate   │  ← ssot task complete --task T0
│  - Commit     │
└───────────────┘
    │
    ▼
┌───────────────┐
│ Task T1       │  ← Fresh context, re-read contract
│  ...          │
└───────────────┘
    │
    ▼
All Tasks Complete → C Gates → Session Promote
```

Each task completion resets context. No drift accumulation.

---

## Example Plan

```yaml
id: PLAN-CR004-001
type: plan
cr_ref: CR-2026-01-08-004
title: "Feature Implementation"
status: approved
classification: G

atomic_tasks:
  - id: T0
    name: "Core module"
    outputs:
      - path: src/core/feature.py
      - path: tests/unit/test_feature.py
    policies:
      file_loc: 500
      coverage: 80
    validation:
      - "ruff check src/core/feature.py"
      - "mypy src/core/feature.py"
      - "pytest tests/unit/test_feature.py -v"

  - id: T1
    name: "CLI integration"
    outputs:
      - path: src/commands/feature_cmd.py
    validation:
      - "ruff check src/commands/feature_cmd.py"
      - "ssot feature --help"

  - id: T2
    name: "Documentation"
    outputs:
      - path: docs/feature.md
    validation:
      - "Human review"
```

---

## Anti-Patterns

| If you're doing... | STOP. Do this instead... |
|--------------------|--------------------------|
| Task with 10+ files | Decompose into smaller tasks |
| Vague outputs ("update code") | Explicit file paths |
| No validation commands | At minimum: lint + test |
| Modifying files not in outputs | Stay within contract scope |
| Skipping `ssot task start` | Always load contract first |
| Committing without `ssot task complete` | Run validation before commit |

```