Skip to main content
>_ supraj.dev

Module 7: Enterprise Production & Capstone · 4.25h

01 · UNDERSTAND

Day 41 Theory — Capstone Freeze: Requirements, Architecture and Unseen Acceptance Tests

Why we freeze requirements now

The capstone is where the course stops behaving like a guided tutorial and starts behaving like an engineering delivery.

If requirements keep changing while implementation continues, it becomes impossible to judge whether the system is complete. Today we freeze the problem, architecture boundaries, and acceptance criteria before writing more code.

Requirements are testable statements

A weak requirement says:

“The agent should be secure and reliable.”

A stronger requirement says what observable behavior must hold:

  • unauthorized users cannot execute privileged reset tools,
  • retrieval answers cite approved sources,
  • agent loops terminate within configured limits,
  • failed side effects do not create duplicates,
  • sensitive fields are not emitted in public logs.

Good requirements tell us what evidence will prove completion.

Functional and non-functional requirements

Functional requirements describe what the system does.

Non-functional requirements describe qualities such as:

  • security,
  • reliability,
  • performance,
  • observability,
  • cost,
  • maintainability.

AI products need both. A correct answer produced through an unsafe tool path is not a successful system.

Architecture freeze

Draw the current system and identify ownership boundaries:

client
  ↓
API/auth
  ↓
agent runtime
  ├─ model provider
  ├─ retrieval
  ├─ tools/MCP
  ├─ state/checkpoints
  └─ tracing/evals

For each boundary, define trust, data flow and failure behavior.

Unseen acceptance tests

Students should expect tests that are not copied from the exact examples they practiced.

This evaluates whether the implementation satisfies the contract rather than only memorizing visible test cases.

Design for the requirement, not for the test fixture.

Change control

After freeze, changes should be classified:

  • bug fix required to meet frozen requirement,
  • clarification of ambiguity,
  • optional enhancement.

Do not destabilize the capstone by adding new technologies for novelty.

Service Desk connection

Today the evolving Service Desk becomes the final product candidate. We stop adding curriculum features and define what “production-ready enough for this capstone” means in observable terms.

The principle is:

Freeze the problem before the final build, express requirements as testable behavior, and make architecture/trust boundaries explicit enough that unseen tests cannot surprise the design.

02 · APPLY

Lesson Overview

This is the applied companion for Day 41. Read DAY_41_THEORY.md first for the beginner-first teaching of Capstone Freeze: Requirements, Architecture and Unseen Acceptance Tests. Then use the real service-desk-day-41/ project to trace, run, debug, and explain the concept.

Service Desk Alignment

Day 41 adds Capstone Freeze: Requirements, Architecture and Unseen Acceptance Tests to the running Service Desk. Start with freeze_validator.py, then follow imports and tests to identify the actual runtime path.

Why This Topic Matters

The theory chapter explains why Capstone Freeze: Requirements, Architecture and Unseen Acceptance Tests is needed. Here the goal is evidence: identify where the capability is implemented, what observable behavior changes, and how the repository proves both success and failure behavior.

System Architecture

This is a repository surface map, not a claim that modules call each other in the displayed order. The modules are ranked by relevance to today's theory.

graph LR
    T[Day 41: Capstone Freeze - Requirements, Architecture and Unseen Acceptance Tests]
    T --> M1[freeze_validator.py]

Follow imports and tests to discover the actual runtime flow.

Repository Implementation Map

Use the real Day 41 repository, not a fabricated sample, to connect theory to implementation.

Theory concepts to locate:

  • Why we freeze requirements now
  • Requirements are testable statements
  • Functional and non-functional requirements
  • Architecture freeze

Most relevant implementation modules first:

  • service_desk/freeze_validator.py

Follow imports/calls from the relevant module and confirm behavior in tests. Record input → mechanism → observable output/state → failure evidence.

Code Walkthrough & Mechanics

Read freeze_validator.py with these theory sections beside you:

  • Why we freeze requirements now — locate its implementation and evidence.
  • Requirements are testable statements — locate its implementation and evidence.
  • Functional and non-functional requirements — locate its implementation and evidence.
  • Architecture freeze — locate its implementation and evidence.
  • Unseen acceptance tests — locate its implementation and evidence.

For each concept identify the real function/class/protocol boundary, its input/state, its observable result, and the assertion in tests/test_capstone_freeze.py that proves the behavior. If a concept has no implementation or evidence, record that as a gap rather than inventing one.

Common Mistakes & Debugging Guidance

Use the theory—not generic timeout or .env advice—to decide what can fail today.

Failure lens: revisit Architecture freeze, Unseen acceptance tests.

  • Reproduce the smallest case that violates one of those expectations.
  • Trace the real Day 41 modules until you find the first incorrect state/output/decision.
  • Use tests/test_capstone_freeze.py as executable evidence.
  • Add a regression test if the failure is not already represented.
  • Fix the smallest responsible boundary and rerun the relevant test before the full suite.

Your debugging explanation must name the topic-specific invariant that failed, not merely say “an exception occurred.”

Practical Lab Instructions

  1. Summarize these theory ideas before opening the implementation:
    • Why we freeze requirements now
    • Requirements are testable statements
    • Functional and non-functional requirements
    • Architecture freeze
  2. Inspect the most relevant real Day 41 modules first:
    • service_desk/freeze_validator.py
  3. Inspect the automated evidence:
    • tests/test_capstone_freeze.py
  4. Establish the baseline:
    cd service-desk-day-41
PYTHONPATH=. pytest tests/test_capstone_freeze.py -q
  5. Trace one theory concept through the actual nested modules and tests.
  6. Run one success case and record input → mechanism → observable result.
  7. Exercise one topic-specific failure/boundary case and name the invariant that protects the system.
  8. Re-run the relevant tests and explain theory → implementation → evidence.

Done when: another student can reproduce your trace without relying on an invented sample.

Key Takeaways

  1. Be able to explain Why we freeze requirements now and point to its implementation/evidence in Day 41.
  2. Be able to explain Requirements are testable statements and point to its implementation/evidence in Day 41.
  3. Be able to explain Functional and non-functional requirements and point to its implementation/evidence in Day 41.

Knowledge Check & Scenario Questions

  1. Concept: Using Why we freeze requirements now, explain the engineering problem Day 41 is solving without naming a framework as the answer.
  2. Mechanism: How does Requirements are testable statements appear in the real project? Start from service_desk/freeze_validator.py and name the observable state/output/event that changes.
  3. Failure: For Functional and non-functional requirements, describe one incorrect implementation or boundary condition and the evidence you would expect in tests/test_capstone_freeze.py.
  4. Design review: Which assumption in today's design would you verify before reusing this implementation in a different production system?

Official References

03 · EXPLAIN

Interview checkpoint

Explain one design decision from this lesson, the alternative you rejected, and the failure mode or evidence that justified your choice.