The Solo Orchestrator Journey

How a single person builds a real, production-ready application with an AI coding agent — from empty folder to shipped release, one step at a time. Each step below shows what you do on the left and what the framework and AI do on the right.

Setup Phase 0 · Discovery Phase 1 · Architecture Phase 2 · Construction Phase 3 · Validation Phase 4 · Release Phase Gate

What you do

  • Clone the repository and run ./init.sh.
  • Answer prompts (approve each tool install).
  • Optional: run ./init.sh --dry-run first to preview.
1

One-Command Setup

Installs everything the framework needs on your machine.

./init.sh
Produces: a project folder with all templates, pipelines, and a fresh git repo.

What the framework does

  • Checks prerequisites (Git, Node.js, jq, Docker) and offers to install any missing.
  • Resolves the tool matrix for your platform and offers to install the applicable security tools (Semgrep, gitleaks, Snyk for all projects; Lighthouse + OWASP ZAP for web).
  • Clones the Development Guardrails for Claude Code (git hooks + session rules).
  • Generates your project folder, CI + release pipelines, CLAUDE.md, and three state files: phase-state.json, .claude/process-state.json (build-loop/UAT/Phase 3 ledger), and .claude/manifest.json (host, deployment, poc_mode, enforcement level).
  • Initializes git, seeds .claude/bypass-audit.json, and runs a health check.

What you do

  • Run the intake wizard and answer plain-language questions.
  • Describe project name, what it does, who uses it, platform (web/desktop/mobile/etc), language, success criteria, and the four independent settings the framework tracks:
    • Deployment: personal or organizational.
    • Track: Light / Standard / Full (depth of Phase 3 rigor).
    • POC mode: production, Sponsored POC, or Private POC (Sponsored is org-only; Phase 4 is blocked in POC mode until scripts/upgrade-project.sh --to-production).
    • Enforcement level: strict / light / no (strict is default and forced for organizational Sponsored POC + Production).
  • Review the generated PROJECT_INTAKE.md before moving on.
2

Project Intake

Tell the framework exactly what you're building and why.

bash scripts/intake-wizard.sh
Produces: PROJECT_INTAKE.md — the AI's product brief. Also seeds data_classification + ZDR attestation for the Phase 1 → 2 gate.

What the framework does

  • Walks you through a structured Q&A tailored to your chosen platform.
  • Offers context-aware suggestions (e.g. auth options for web, notarization for macOS desktop).
  • Auto-fills the resolved tool matrix so the AI knows exactly which tools apply.
  • Captures data classification (public / internal / confidential / pii / financial / health / regulated) and ZDR attestation — enforced later at the Phase 1 → 2 gate.
  • Writes a complete intake document — no free-form guessing required later.

What you do

  • Start Claude Code (or your AI agent of choice).
  • Paste the context-loading prompt from the README.
  • Read the AI's summary. Correct any misunderstanding before it starts work.
3

Give the AI Its Context

The agent reads its instructions before it does anything.

claude
Produces: an AI that understands your project, its phase, and its constraints.

What the framework does

  • The AI reads five files in order: CLAUDE.md (its rules), PROJECT_INTAKE.md (what to build), the Builder's Guide (how to build), the Platform Module (platform know-how), and phase-state.json (current stage).
  • Summarizes the goal, constraints, current phase, and available tools.
  • Asks you clarifying questions — it does not start coding blind.

What you do (organizational only)

  • Record six blocking pre-conditions as dated rows in APPROVAL_LOG.md before Phase 0 can advance.
  • Personal projects and Private POCs skip this row entirely; Sponsored POCs need rows 1 & 4 up front and may defer the rest.
0

Pre-Phase 0 · Organizational Pre-Conditions

Six governance rows before Day 1 for organizational deployments. See docs/governance-framework.md §V & §IX.4.

check-phase-gate.sh (Pre-Phase 0)

What the framework checks

  • Six named rows each with an ISO-dated approval (per templates/generated/approval-log-org.tmpl lines 16–28):
    1. AI deployment path — IT Security approval.
    2. Insurance clearance / broker confirmation.
    3. Liability entity designation.
    4. Named Project Sponsor.
    5. Backup maintainer designation.
    6. ITSM registration.
  • Sponsored POC: rows 1 & 4 required, rows 2/3/5/6 deferred (verified later by scripts/upgrade-project.sh --to-production).
  • Private POC: all six deferred.
  • Governance mode is forced strict for organizational Sponsored POC + Production.

What you do

  • Answer the AI's discovery questions about goals and users.
  • Review the draft Product Manifesto.
  • Approve it in APPROVAL_LOG.md (or request revisions).
4

Phase 0 · Product Discovery

Turn the idea into a written product agreement.

Produces: Product Manifesto (goals, users, MVP scope, non-goals).

What the framework does

  • AI walks the seven Phase 0 sub-steps: 0.1 FRD, 0.2 User Journey (Skeptical PM persona), 0.3 Data Contract, 0.4 Product Manifesto & MVP Cutline, 0.5 Revenue Model (Std+), 0.6 Competency Matrix (drives mandatory CI tooling for any "No" domain), 0.7 Trademark & Legal (Std+).
  • Generates supporting artifacts: user journey, data contract.
  • Organizational deployments: sponsor reviews the Compliance Screening Matrix (SOX / PCI / GDPR / HIPAA / GLBA / SEC / records-retention / EU-AI-Act) — see governance-framework.md §VIII.11.
  • Cannot proceed to Phase 1 until the phase gate is approved. (STRIDE threat model is Phase 1.3, not here.)

Your approval unlocks the next phase

  • Personal deployments: self-review recorded in APPROVAL_LOG.md with name and date.
  • Organizational deployments: Project Sponsor is the sole named approver for business justification + compliance screening. The Sponsor (not you) must author the git commit that adds their signature.
✓

Phase Gate 0 → 1

Framework refuses to advance without written sign-off. On success, a snapshot is copied to docs/snapshots/phase-0-to-1_YYYY-MM-DD/.

scripts/check-phase-gate.sh

What the framework checks

  • Reads APPROVAL_LOG.md and (organizational) runs git blame --line-porcelain on the Approver row itself — the git-commit author of that specific line must not equal the approver's name (anti-self-approval FAIL). Personal deployments skip this check.
  • Confirms PRODUCT_MANIFESTO.md has all 8 numbered sections filled with content (no placeholders), and NO Status: Open lines remain — either causes a FAIL.
  • Compares the dated Phase 0 → 1 entry against phase-state.json::gates.phase_0_to_1. (Note: the gate script reads both dates; the JSON value itself is populated by scripts/upgrade-project.sh or edited by the approver during the sign-off commit — the gate does not auto-write it.)
  • On PASS, check-phase-gate.sh creates a point-in-time snapshot at docs/snapshots/phase-0-to-1_YYYY-MM-DD/.

What you do

  • Review architecture options with tradeoffs (usually 2–3 candidates).
  • Pick the architecture. Read the test plan.
  • Approve at the Phase 1 → 2 gate.
5

Phase 1 · Architecture & Planning

Design the system on paper before writing any code.

Produces: Project Bible (architecture, ADRs, data contract, threat model, test plan).

What the framework does

  • AI walks the Phase 1 sub-steps: 1.1 Business Strategy Gateway (Std+ Go/No-Go), 1.1.5 Market Signal Validation, 1.2 Architecture & Stack Selection (3 candidates, 10 first-class decisions, Competency Matrix as required input), 1.3 STRIDE Threat Model (Penetration Tester persona), 1.4 Data Model, 1.4.5 Data Migration Plan (only if replacing an existing system), 1.5 UI/UX Scaffolding (four-state Empty/Loading/Error/Success), 1.6 Project Bible (16 sections), 1.7 Data Classification & ZDR Attestation.
  • Writes Architecture Decision Records (ADRs) explaining why each big choice was made, and rejected alternatives.
  • Configures branch protection against the real git-host API (GitHub/GitLab/Bitbucket) via scripts/lib/host.sh — free-tier limitations use an attestation escape hatch (github_free_tier, gitlab_free_tier_approvals).
  • Produces a test plan mapped to intake acceptance criteria.

Your approval unlocks Phase 2

  • Personal: self-review recorded in APPROVAL_LOG.md.
  • Organizational: Senior Technical Authority approves architecture, security posture, and data classification.
✓

Phase Gate 1 → 2

Includes the mandatory Zero Data Retention gate (Invariant #16). Snapshot: docs/snapshots/phase-1-to-2_YYYY-MM-DD/.

scripts/check-phase-gate.sh

What the framework checks

  • Dated "Phase 1 → Phase 2" entry in APPROVAL_LOG.md; organizational adds a per-line git-blame check on the STA row.
  • PROJECT_BIBLE.md exists with ≥14 numbered sections and no YYYY-MM-DD placeholder dates remaining.
  • Mandatory ZDR gate (Invariant #16): phase1_artifacts.data_classification must be one of public / internal / confidential / pii / financial / health / regulated. Anything above public requires zdr_attested=true OR a written zdr_attestation_reason. FAIL otherwise.
  • Branch protection backstop: real API call verifies force-push disabled + (org) 1+ PR approver + CI status checks. Free-tier attestation limits are accepted only if recorded in process-state.json.
  • Personal → organizational upgrades: recurring WARN until the Retroactive Phase 1 → 2 STA Approval row is filled.

What you do

  • Answer clarifying questions when the AI asks.
  • Review test assertions and code diffs for each feature.
  • Every ~2 features: run a UAT session and triage any bugs found.
  • Mark bugs Fix Now / Defer / Won't Fix / Post-MVP.
6

Phase 2 · Construction (Build Loop)

Build features one at a time, TDD-first, with security review baked in. Full sub-loop shown below.

Produces: working codebase + passing tests + docs + audit trail.

What the framework does

  • Runs the Feature Build Loop for every feature (detailed diagram below).
  • Enforces the Build Loop checklist on feat: commits: process-checklist.sh requires the first five steps (tests_written → documentation_updated) done before allowing the commit. Non-feat: prefixes (chore:, fix:, refactor:, etc.) bypass this check — this is a scope-limited, not universal, gate. The TDD file-ordering check is warning-only (per README §Enforcement).
  • Runs gitleaks + Semgrep (staged-files) on every commit; blocks --no-verify and captures any that get through in .claude/bypass-audit.json.
  • Blocks gh pr create when UAT is in progress with < 9 steps completed, or Build Loop steps 1–4 done but not step 5.
  • Test-gate reminds you when features_since_last_test reaches the interval; you invoke scripts/test-gate.sh --check-batch to trigger the UAT.
  • Blocks Phase 2 → 3 on any open SEV-1 OR any SEV-2 (open OR deferred — deferred SEV-2 must be resolved or the feature removed; no third option).
  • Organizational: biweekly Mid-Phase 2 Governance Checkpoint with the Senior Technical Authority (30-min status review, escalation on ADR-less architecture deviation, test pass < 80%, unresolved security findings, AI quality degradation).

Your approval unlocks Phase 3

  • Personal: self-review in APPROVAL_LOG.md.
  • Organizational: Senior Technical Authority signs.
  • Reconcile FEATURES.md vs the Manifesto MVP Cutline — any additions require documented orchestrator approval.
✓

Phase Gate 2 → 3

Bug gate blocks; MVP-Cutline reconciliation required. Snapshot: docs/snapshots/phase-2-to-3_YYYY-MM-DD/.

check-phase-gate.sh → test-gate.sh --check-phase-gate

What the framework checks

  • Dated "Phase 2 → Phase 3" entry in APPROVAL_LOG.md.
  • FEATURES.md and CHANGELOG.md exist and are non-empty.
  • Bug gate via test-gate.sh --check-phase-gate: SEV-1 open > 0 → BLOCKED; SEV-2 open > 0 → BLOCKED; SEV-2 Deferred > 0 → BLOCKED (must resolve or remove feature); SEV-3 open → WARN.

What you do

  • Walk the mechanically-enforced 9-step Phase 3 checklist (process-checklist.sh --start-phase3): integration testing, security hardening, chaos testing, accessibility audit, performance audit, contract testing, results archived, pre-launch preparation, legal review.
  • Run evaluation-prompts/Projects/run-reviews.sh <module> to produce the six adversarial reviewer reports (Standard: recommended; Full: Security + Red Team REQUIRED). Address all Critical / High findings.
  • Personal: self-review recorded. Organizational: gather written sign-offs from both Application Owner AND IT Security — see the Gate 3 → 4 row below.
  • Security-domain "No" or "Partially" on the Competency Matrix → mandatory Security Peer Review before go-live, regardless of track (governance-framework.md §V.C).
7

Phase 3 · Validation & Security

Nine substeps + adversarial reviews + track-specific pen test + attorney legal review. Exit rule: zero Critical or High-severity findings.

Produces: docs/test-results/ archive, sbom.json, HANDOFF.md, INCIDENT_RESPONSE.md, SECURITY.md, review manifest, penetration test report (Std+).

What the framework does

  • 3.1 Integration Testing — Platform Module E2E suite over the full User Journey.
  • 3.2 Security Hardening — you run Semgrep (--config=p/owasp-top-ten --config=p/security-audit) + Snyk + gitleaks + license check + SBOM (CycloneDX/syft) + threat-model validation. Web: OWASP ZAP baseline (all tracks) / active (Full). Framework archives artifacts to docs/test-results/[date]_[scan-type]_[pass|fail].[ext].
  • 3.3 Chaos & Edge-Case Testing — input abuse defenses, error recovery, concurrency, global error boundaries.
  • 3.4 UX & Accessibility Audit — WCAG AA baseline; Lighthouse ≥ 90 for web; Full Track requires explicit screen-reader testing.
  • 3.5 Performance Audit — latency vs data contract, memory stability, minimum-supported-hardware validation.
  • 3.5.5 Contract Testing (Std+ for APIs/IPC/file formats); 3.5.7 Load/Stress Testing (Full).
  • 3.5.9 Test Results Archive — docs/test-results/ is referenced from the Phase 3 → 4 APPROVAL_LOG entry and folded into HANDOFF.md.
  • 3.6 Pre-Launch Preparation (Std+) — Final UAT with formal acceptance sign-off (Sponsored POC / Production); MANDATORY attorney review of Privacy Policy AND Terms of Service recorded in APPROVAL_LOG (builders-guide.md §Phase 3.6); license audit passing; trademark search.
  • Six evaluation prompts are operator-invoked via run-reviews.sh; check-phase-gate.sh only WARNs (not FAILs) when docs/eval-results/review-manifest.json is missing. Personas: Senior Engineer (01), CIO (02), SVP IT Security (03), Corporate Legal (04), Technical User (05), Red Team (06).

The heaviest gate — governance sign-offs required

  • Personal: self-review recorded in APPROVAL_LOG.md (single approver).
  • Organizational — dual approval: BOTH Application Owner Approval AND IT Security Approval subsections in APPROVAL_LOG.md must have populated Date rows.
    • Application Owner: accepts operational risk + go-live readiness.
    • IT Security: reviews scan results, penetration test, threat-model validation, risk acceptance.
    • Each subsection is verified independently by validate_approval_section_dated — header presence alone does not satisfy the gate.
    • Approvers must author their own commit (anti-self-approval via per-line git blame; org projects FAIL on self-approval).
  • Attorney/Legal review recorded for Privacy Policy + ToS if applicable (external users).
  • ITSM deployment change ticket referenced in the Phase 4 Completion row.
  • Sponsored POC / Production Full UAT: formal acceptance sign-off by product sponsor or designated tester.
  • See governance-framework.md §V Approval Authority row for Phase 3 → 4.
✓

Phase Gate 3 → 4

Two written signatures (org), pen test on Std+, artifact roster, hard-block for POC. Snapshot: docs/snapshots/phase-3-to-4_YYYY-MM-DD/ — the point-in-time audit record.

scripts/check-phase-gate.sh

What the framework checks (check-phase-gate.sh:901–1056)

  • Dated "Phase 3 → Phase 4" entry within 15 lines of the header.
  • Organizational: BOTH Application Owner AND IT Security Date rows populated — either missing → FAIL.
  • Required artifacts: HANDOFF.md, docs/INCIDENT_RESPONSE.md, sbom.json, non-empty docs/test-results/ (empty → FAIL), SECURITY.md (missing → WARN), docs/eval-results/review-manifest.json.
  • Penetration test: Standard track requires *pen-test*|*pentest*|*penetration* files in docs/test-results/ or an IT Security exemption recorded in APPROVAL_LOG.md. Full track has NO exemption path.
  • POC hard-block: if poc_mode is set in phase-state.json, Phase 4 is BLOCKED with ::error::. Points at scripts/upgrade-project.sh --to-production, which verifies each of the six deferred Pre-Phase 0 rows (or requires --ack-preconditions=<N1,N2,…>, recorded in .claude/bypass-audit.json).
  • Release pipeline TODO check: .github/workflows/release.yml unconfigured TODOs → WARN.
  • Bug gate (via test-gate.sh --check-phase-gate) must pass.
  • On PASS: point-in-time snapshot copied to docs/snapshots/phase-3-to-4_YYYY-MM-DD/ containing gate-checked artifacts plus PRODUCT_MANIFESTO / PROJECT_BIBLE / FEATURES / CHANGELOG / BUGS / USER_GUIDE / RELEASE_NOTES / APPROVAL_LOG / HANDOFF / INCIDENT_RESPONSE / sbom (see builders-guide.md §Phase 3 → 4 Snapshot Mechanism).
  • Every enforcement decision (proposal, block, pass, out-of-band commit, escalation) is appended to .claude/bypass-audit.json — the durable audit ledger.

What you do

  • POC → Production upgrade first: Phase 4 is hard-blocked for poc_mode projects at BOTH check-phase-gate.sh AND process-checklist.sh --start-phase4. Run scripts/upgrade-project.sh --to-production BEFORE Phase 4 can start.
  • Walk the 6-step Phase 4 checklist: production build, rollback tested, go-live verified, monitoring configured, handoff written, handoff tested.
  • Kick off the release (signing keys, store credentials, deploy) using your chosen strategy: cut-over (Light), blue/green (Std+ web), rolling/canary (Std+ >1000 users), feature flags (any track, high-risk).
  • Update RELEASE_NOTES.md and hand off to users.
  • Organizational: file the ITSM deployment change ticket (ID recorded in the APPROVAL_LOG Phase 4 Completion row); the backup maintainer validates HANDOFF.md — must be able to build, test, deploy, and run scans from the doc alone.
8

Phase 4 · Release & Maintenance

Ship the MVP with a tested rollback and verified monitoring. Then maintain on a four-cadence schedule.

Produces: signed release, CHANGELOG.md, RELEASE_NOTES.md, HANDOFF.md, docs/INCIDENT_RESPONSE.md (SEV-1..SEV-4 severity matrix + notification chains), monitoring configuration, Phase 4 Completion row in APPROVAL_LOG.md.

What the framework does

  • Runs the release pipeline (.github/workflows/release.yml) for your platform: build, sign, package, distribute.
  • MANDATORY rollback test BEFORE go-live (Step 4.1.5): deploy candidate → execute documented rollback → verify data integrity + revert. "A rollback procedure that has never been tested is not a rollback procedure — it is a hope."
  • MANDATORY monitoring verification (Step 4.3): trigger a test error, confirm the alert was received. "Configured is not verified."
  • PLATFORM MODULE MANDATORY go-live checklist (Step 4.2): SSL/security headers (web), code signing/auto-updater (desktop), app-store metadata & certificates (mobile). Failure may result in deployment rejection.
  • Updates CHANGELOG + RELEASE_NOTES with what shipped.
  • Turns on the maintenance cadence — actual cadences are monthly (CHANGELOG + SBOM, 35d), quarterly (dependency audit, 95d), biannually (full Phase 3 security+perf re-run + AI provider terms re-verification, 185d). Verified on demand by scripts/check-maintenance.sh.
  • Records the release + all post-launch changes in the APPROVAL_LOG "Approval History" table; the point-in-time docs/snapshots/phase-3-to-4_YYYY-MM-DD/ stays immutable.

Zoom in: The Feature Build Loop (inside Phase 2)

This is the sub-loop that runs for every single feature. It's the heartbeat of Phase 2 — a disciplined cycle that guarantees each feature ships with current library knowledge, a passing test, a security review, and a red-team review before it's marked complete. If any review flags an issue, the loop restarts at the fix step; nothing is approved on the first try if it isn't ready.

STEP 1

Context7 Docs Review

AI queries Context7 for current documentation on any libraries in play. Prevents "I remember the API from training data" errors on stale libraries.

STEP 2

Write the Test First

AI writes the test that describes what "working" means for this feature. Runs it — confirms it FAILS (Red). This proves the test actually tests something.

STEP 3

Write the Code

AI writes the minimum implementation needed to make the test pass (Green). No over-building.

STEP 4

Refactor

Clean up the implementation now that it works: better naming, remove duplication, tighten boundaries. Tests stay green throughout.

STEP 5

Pre-commit Gate

Automatic hooks run: gitleaks (blocks on hit), Semgrep on staged files (blocks on hit), framework-hygiene lints, TDD file-ordering check (warning-only, per README §Enforcement).

STEP 6

Security Audit

Senior Security Engineer persona reviews the change: injection, authz, secrets, data isolation, N+1, structured logging. Findings marked in process-state.json.build_loop.steps_completed[security_audit].

STEP 7

Documentation Updated

Parallel doc updates: CHANGELOG.md, FEATURES.md, interface docs, ADR (if applicable), Bible update. Enforced as a mandatory Build Loop step.

STEP 8

Iterate If Needed

If steps 5–7 raised issues: back to Step 3 to fix, then re-run 4–7. Loop continues until reviews are clean. (Refactor, Red Team, and Iterate are AI conventions — not framework-enforced Build Loop steps.)

STEP 9

Feature Recorded

Feature is added to FEATURES.md; build progress is recorded in build-progress.json; test-gate.sh --record-feature bumps the UAT counter. Marked complete in process-state.json.

Enforced vs documented: process-checklist.sh mechanically enforces six Build Loop steps: tests_written → tests_verified_failing → implemented → security_audit → documentation_updated → feature_recorded. The Context7 lookup, Refactor, Red Team Review, and Iterate steps above are AI conventions the Builder's Guide describes but that are not gate-blocking on their own. The feat:-commit gate blocks a commit until the first five enforced steps are complete; non-feat: prefixes bypass this check.
Every ~2 features (configurable): the loop pauses for a UAT session driven by scripts/test-gate.sh --check-batch. Parallel AI agents (automated testing, malicious user, cross-platform) test the app alongside you. Bugs get triaged into SEV-1 (must fix before release) through SEV-4 (nice to have) and assigned a disposition (Fix Now / Defer / Won't Fix / Post-MVP). Fix-Now bugs re-enter the Build Loop. The framework will refuse to advance Phase 2 → 3 while any SEV-1 is open OR any SEV-2 is open OR deferred (SEV-2 must be resolved or the feature removed; no third option).

Always Running in the Background

These aren't steps — they're guardrails that run automatically no matter which phase you're in. You never have to remember to invoke them; the framework does it for you and refuses to proceed if something is off.

Phase Gate Enforcement

Every phase-to-phase transition requires a written approval in APPROVAL_LOG.md plus green tests plus completed gate criteria. Enforced by check-phase-gate.sh. On PASS, an immutable point-in-time snapshot is written to docs/snapshots/phase-N-to-M_YYYY-MM-DD/.

Enforcement Level (strict / light / no)

Recorded in .claude/manifest.json::enforcement_level. Strict is the default and is forced for organizational Sponsored POC + Production; it installs .git/hooks/framework-gate.sh which blocks user-terminal commits that violate the classifier. Light and No relax coverage. Every transition is recorded as an enforcement_level_set row in the audit ledger.

Bypass Audit Ledger

.claude/bypass-audit.json is the append-only, git-tracked audit trail. Records seven row types: claude_bypass_proposal, terminal_commit_blocked/passed, out_of_band_commit, enforcement_level_set, escalation, detector_error. SessionStart runs detect-out-of-band-commits.sh against the last-checked-commit baseline. Guarantee: "you can route around the block, you cannot route around the audit." See docs/audit-log-lifecycle.md.

Pending-Approval Sentinel

.claude/pending-approval.json signals a structured A/B/C decision to the operator. While present, the pre-commit gate blocks git commit and gh pr create — the agent cannot rationalize a unilateral commit while you are still deliberating.

Session Hooks

Every time you start the AI, hooks run: version check, test-gate, out-of-band commit detector, MCP-usage gate. If the Development Guardrails are out of date or the test-gate is red, you're told before any work begins. Qdrant / Context7 requirements only fire when you have those MCP servers configured — the gate expects one call per session, not per library.

Live Docs (Context7)

When Context7 is configured as an MCP server, the framework requires at least one lookup per session before allowing commits (session-mcp-gate). The Build Loop's first step invokes Context7 to prevent "API remembered from training data" errors on library-touching features.

Persistent Memory (Qdrant)

When Qdrant is configured as an MCP server, the framework requires at least one qdrant-store/qdrant-find call per session. Decisions, review findings, and context notes are stored in a local semantic memory the AI can search across sessions — so the AI remembers why something was done, not just what.

Audit Trail

Every phase gate, every UAT session, every bug disposition, every release — all recorded in APPROVAL_LOG.md, docs/snapshots/, docs/test-results/, sbom.json, and .claude/bypass-audit.json. Six canonical jq recipes in docs/audit-log-lifecycle.md support cold-pickup successor handoff (W7 use case).

Organizational Governance (opt-in)

If you selected "organizational" deployment: Project Sponsor (Phase 0 → 1), Senior Technical Authority (Phase 1 → 2 & 2 → 3), Application Owner + IT Security (Phase 3 → 4), Attorney (Phase 3.6 for Privacy Policy + ToS), ITSM ticket linkage (Phase 4 Completion row). Each sign-off is verified with per-line git blame; anti-self-approval is a FAIL. The Pre-Phase 0 organizational roster (six named rows) must be dated before Day 1. POC modes let you defer parts of that roster; upgrade-project.sh --to-production is the only way to unlock Phase 4 from a POC.

Gate Denial Path

When an approver denies a gate: written findings required, rework limited to cited deficiencies, maximum 2 rework cycles before escalation to the Project Sponsor. Every denial and re-submission is recorded in APPROVAL_LOG.md. See governance-framework.md §V Gate Denial.

Plain-English Glossary

TDD (Test-Driven Development)
Write the test first (it fails), then write just enough code to make it pass, then clean up. Guarantees the code does what the test says it does.
SAST
Static Application Security Testing — automated tools that read your code (without running it) and look for known unsafe patterns.
DAST
Dynamic Application Security Testing — attacks a running copy of your app to find real vulnerabilities from the outside.
UAT (User Acceptance Testing)
Sessions where a human — plus AI agents in this framework — actually use the app and try to break it or confirm it does what users need.
Phase Gate
A checkpoint between phases. The framework refuses to advance until specific artifacts exist, specific tests pass, and (for organizational Phase 3 → 4) BOTH Application Owner and IT Security have written signed approvals in the log.
MVP
Minimum Viable Product — the smallest useful version worth releasing. The framework's target for a first release.
Sponsored POC
Organizational-only POC mode: the organization knows and has approved. Requires AI-deployment-path approval + named sponsor up front; defers insurance, liability, ITSM, exit criteria, and backup maintainer. Phase 4 hard-blocked until upgrade-project.sh --to-production.
Private POC
Personal-only POC mode: all six Pre-Phase 0 pre-conditions deferred. Same technical rigor as Production Build; NO real user data, NO external users, NO production deployment until upgraded.
Track (Light / Standard / Full)
Depth of Phase 3 rigor. Light skips Business Strategy Gateway, Market Signal Validation, Revenue Model, contract testing, load/stress testing, and Std+ pre-launch preparation. Standard adds them; Full also requires screen-reader accessibility testing and has no penetration-test exemption.
Enforcement Level (strict / light / no)
Field in .claude/manifest.json. Strict installs a filesystem-gate hook that blocks user-terminal commits violating the classifier; light logs but allows; no does not enforce. Forced strict for organizational Sponsored POC + Production.
ZDR (Zero Data Retention)
Mandatory Phase 1 → 2 gate (Invariant #16). Projects with data classification of internal or higher must attest ZDR (or record a written exception). Enforced by check-phase-gate.sh as a FAIL. Public projects are exempt.
APPROVAL_LOG.md
Append-only audit trail of every phase-gate approval. Tamper-evident via git history; anti-self-approval enforced via per-line git blame. Includes an Approval History table for post-launch changes.
Phase Gate Snapshot
Point-in-time immutable copy of key documents at each phase transition. Auto-created by check-phase-gate.sh at docs/snapshots/phase-N-to-M_YYYY-MM-DD/. Preserves whatever state Manifesto, Bible, FEATURES, CHANGELOG, BUGS, USER_GUIDE, RELEASE_NOTES, APPROVAL_LOG, HANDOFF, INCIDENT_RESPONSE, and sbom are in at gate time.
Bypass Audit Ledger
.claude/bypass-audit.json — append-only, git-tracked, atomic-write JSON ledger recording every enforcement decision, bypass attempt, and out-of-band commit. The framework's guarantee: "you can route around the block, you cannot route around the audit."
Product Manifesto
The one-page product agreement produced at the end of Phase 0. What we're building, for whom, and what's out of scope.
Project Bible
The architecture + planning document produced at the end of Phase 1. Decisions, diagrams, threat model, and test plan.
ADR (Architecture Decision Record)
A short note explaining why a specific architectural choice was made (and what alternatives were rejected). Written when the decision is made, not months later.
Threat Model
A structured list of "what could an attacker do?" scenarios, plus what mitigation exists for each. Verified in Phase 3.
Red Team Review
An adversarial review that assumes the worst and tries to find failure modes: edge cases, hostile inputs, misuse. Runs on every feature and again in Phase 3.
Context7
An MCP tool that fetches current library documentation on demand. Prevents the AI from using outdated API knowledge.
MCP (Model Context Protocol)
A standard way for AI agents to talk to external tools and services (documentation lookups, memory stores, code search, etc).
Development Guardrails for Claude Code
The git-hook-based guardrail layer (sometimes called CDF / Claude Dev Framework) that gets installed alongside your project. Clones from kraulerson/claude-dev-framework. Provides pre-commit hooks, SessionStart hooks, and the framework-gate that (in strict mode) refuses to accept commits which break the rules.
Anti-Self-Approval Check
For organizational deployments only, check-phase-gate.sh runs git blame --line-porcelain on the specific Approver row and FAILs if the committer of that line matches the approver's name. Personal deployments skip this check.
SEV-1 / SEV-2 / SEV-3 / SEV-4
Bug severity levels. SEV-1 = blocks basic use; SEV-2 = major broken feature; SEV-3 = noticeable but livable; SEV-4 = polish. Phase 2 can't finish while any SEV-1 or SEV-2 is open.